Videoplayer is a program designed to allow the real time playback of raw,
header-less YUV files that are encountered in video processing and broadcast
applications.

The source data should be a single file of concatenated video frames.


Aims and Features
=================
  * Play video locked exactly to the display device refresh rate (VSYNC)

  * Play back uncompressed video in real time

  * Offload chrominance upconversion and colour matrixing to the GPU
    to permit high performance playback.

  * Play multiple video files concurrently, with synchronized presentation.


Source Formats
==============
Videoplayer provides compatibility with a wide range of YUV formats:

FourCC code     Description
-----------     -----------
   I420         8 bit planar, 4:2:0 chroma
   YV12         8 bit planar, 4:2:0 chroma
   420p         8 bit planar, 4:2:0 chroma
   422p         8 bit planar, 4:2:2 chroma
   444p         8 bit planar, 4:4:4 chroma
   UYVY         UYVY multiplexed 8 bit data
   V210         UYVY multiplexed 10 bit data, 3 components packed into 32 bits
   V216         UYVY multiplexed 8-16 bit data, little-endian, msb aligned
   16P0         16 bit, big-endian, 16 bit planar data, 4:2:0 chroma
   16P2         16 bit, big-endian, 16 bit planar data, 4:2:2 chroma
   16P4         16 bit, big-endian, 16 bit planar data, 4:4:4 chroma

   plst         Playlist file


Operating System Compatibility
==============================
Videoplayer has been developed using the Qt cross platform toolkit.

The software has been tested on:
 - Linux/X11 (with nVidia and Intel graphics drivers)
 - OSX 10.5  (with nVidia and ATI graphics drivers)
 - WindowsXP (with nVidia and Intel graphics drivers)

Primary development occurs on a Linux/X11 platform.

There is a known issue with playback on Windows systems with Intel graphics
drivers.  On these systems the WGL SwapBuffers call does not block, which is
required for moderating the playback speed.


Hardware Requirements
=====================
Playing uncompressed video sources requires significant read bandwidth from
a storage device:

            ||                   FourCC
  Standard  ||   I420   |   UYVY   |   V210   |   V216
  ----------++----------+----------+----------+----------
    576i25  ||  15 MB/s |  20 MB/s |  27 MB/s |  41 MB/s
   1080p25  ||  77 MB/s | 103 MB/s | 138 MB/s | 207 MB/s
   1080p50  || 155 MB/s | 207 MB/s | 276 MB/s | 414 MB/s
   3260p60  || 746 MB/s | 995 MB/s | 1.3 GB/s | 1.6 GB/s

The videoplayer will attempt to use a read ahead buffer to aid guaranteeing
average throughput.  The size of the buffer is customizable.  It should be
noted that the continuous read rate of an HDD varies between the inside and
outside platter edges.  Performance can be significantly lower near the end of
the disk.

Videoplayer uses OpenGL to accelerate playback. Development has been done with
NVidia QuadroFX3450, 6600GT, 8600GT and 8800GT cards. Recent PCIe graphics cards
are recommended, but no testing of other models has been done.


Usage
=====
The videoplayer is principally designed as a command-line program.  There is
a rudimentary file chooser if the player is started without any arguments,
but this does not expose most of the program features.

Full help text can be displayed using the --help option.

Input files
-----------
Input files may be either raw YUV files, or playlists.
It is recommended to use the fourcc as the file extension, allowing the player
to automatically detect the format.  If a different file extension is used,
eg ".yuv", then the fourcc must be specified using the -t option.

Display Rate
------------
The videoplayer is designed to present video at the frame rate of the VDU.
To enable correct playback of a source file at a different frame rate, specify
the following command-line options: --vdu-fps=N --fps=M, where N is the
frame-rate of the display device and N is the frame-rate of the video.

If the storage back-end cannot provide data in time for real-time display,
the player waits for the frame to become available.  No frame skipping occurs.
Similarly, any delays are not taken into account when performing frame duplication
for frame-rate interpolation.

Pixel mapping
-------------
By default, the video is rendered with a 1:1 pixel-mapping.  If the window size
is smaller than the source video, the video is cropped, preserving the lower-left
corner.  To disable the pixel-mapping, the option --pixelmapped=0 privides a
low-quality interpolator

Multiple files
--------------
If multiple files are specified on the command-line, they are played
synchronously and displayed in a Nx1 grid.  To use a different grid layout,
the option --gl.grid=NxM permits an arbitrary grid.

The displayed frames are advanced in lock-step and only when the storage back-ends
are able to provide a frame for each input file.  Ie, one video will not end up
a frame ahead/behind of another.

OSD
---
A rudimentary on-screen display is provided.  Pressing the 'O' key during
playback will cycle through the OSD modes.  The order is:
     "nothing" -> "frame number" -> "caption"

A caption may be specified on the command line as --caption=foobar
The OSD by default uses a 72pt font.  This may be overridden with --osdptsize=N

Playlists
---------
A playlist file (with file extension/fourcc "plst") can be used to specify a
sequence of video files to read.  The plain text file should contain a single
entry per line.  Lines beginning with '#' are ignored.  Records should
be in the format:
    <name> <type> <width> <height> <fps> <start> <end> [osd caption]

Where, <name>    is the filename -- nb, must not have spaces
       <type>    is the fourcc code for the file
       <width>   picture width
       <height>  picture height
       <fps>     video frame rate
       <start>   first frame to display (0 = first)
       <end>     last frame to display
       [caption] optional string containing caption text for the OSD

Diagnostics
-----------
Some diagnostics are rendered by pressing the '?' key.

Key bindings
------------
  Key         Action
  ---         ------
   o          Toggle OSD state
   ?          Toggle display of statistics on/off
   f          Toggle full screen mode
   m          Switch to output levels from user flags out-range and out-black
   n          Switch to video output levels, out-range=220 out-black=16
   b          Switch to computer output levels, out-range=256, out-black=0
   Esc        Return from full screen mode to windowed
   a          Toggle aspect ratio lock
   i          Toggle deinterlacing of an interlaced source
   Space      Play/Pause
   s          Stop
   1-7        Play forward at 1,2,5,10,20,50,100x rate
   CTRL+1-7   Play backward at 1,2,5,10,20,50,100x rate
   >          Jog one frame forward when paused
   <          Jog one frame backward when paused
   y          Toggle display of luma on/off
   c          Toggle display of chroma on/off
   h          Switch to HDTV colour matrix kr=0.2126 kg=0.7152 kb=0.0722
   j          Switch to SDTV colour matrix kr=0.2990 kg=0.5870 kb=0.1140
   k          Switch to colour matrix kr, kg, kb from user flags
   q          Quit