H261_PLAY(1)

NAME
h261_play - view and dump h261 files

SYNOPSIS
h261_play [ -b ] [ -C ] [ -c dither ] [ -D ] [ -d display ] [ -l ] [ -n ] [ -p ] [ -S ] [ -s ] [ -t ] [ -u script ] [ -V visual ] file

DESCRIPTION

H261_play is a quick-and-dirty diagnostic we hacked together for debugging our h261 decoder. The input file should be a raw h261 bit streams (i.e., the bit stream specified in ITU recommendation H.261 minus the framing and error correction coding from fig. 13 and sec. 5.4). H261_play will display this bit stream and, optionally, provide a detailed diagnostic dump of it to stdout. Keyboard commands are available to single step and get some interactive diagnostic output.

OPTIONS

-b  make the rendering window `big' (2 x CIF). Other window size flags are -s (small or QCIF) and -t (tiny or 1/8 CIF). If none of these flags is given, the window is made CIF size. The h261 image is scaled to to the window size.

-c  On a color-mapped display, use the algorithm indicated by dither to convert video (typically represented in 24-bit YUV color space) to the available color palette. For monochrome and truecolor displays, this argument is ignored. dither may be one of the following:
    	ed		error-diffusion (i.e., Floyd-Steinberg) dither
    	gray		32-levels of gray
    	od		a simple 4x4 ordered dither
    	quantize		straight quantization
    The ``od'' algorithms uses the standard 5x5x5 color cube. Since this color palette is used by several other applications (wb, nv, and gs), colors can be shared which avoids the use of a private color map.

-C  show changes. The macroblocks that changed in the current frame are display normally while the blocks that didn't change are diplayed in a washed-out gray. (This option is generally only useful when you are single stepping through the file.)

-d  Connect to the X server indicated by the display argument.

-D  debug - send a very verbose, block-by-block dump of the h.261 data stream to stdout. (See below for format.)

-l  `loop' - when the input file eof is reached, it is rewound and restarted.

-n  `no rendering' - the input file is read and decoded (and dumped if -D is specified) but nothing is output to the screen. This flag can be used to get an ascii dump of an h261 file or to time the decoder.

-p  Don't pause on startup. Normal behavior is to start up in pause mode so a space or carriage return is required to start decode and rendering.

-s  render into a `small' (QCIF) window.

-S  Don't use the X shared memory extension to convey video images to the X server.

-t  render into a `tiny' (1/8 CIF) window.

-u  Source script, in addition to the compiled-in script, to build the user interface. This is normally only useful during development.

-V  Use visual as the rendering window visual.

KEYBOARD COMMANDS
The following can be typed in the h261_play video window:

space
    toggles run/pause.

carriage return
    if paused, single steps one frame forward.

q   quit - exits the program.

d   dump - dumps the current frame as a PPM file to `t.ppm'

f   frame - writes the current frame number on stdout.

button 1
    writes the gob and macroblock number of the data under the cursor to stdout.

DEBUGGING OUTPUT
The debugging output consists of one line for each syntactic unit in the h.261 file. Most of the output should be self explanatory, given a copy of the H.261 spec. Two things might not be are:

•   Each line ends with a representation of the bits that make up this syntactic unit in the form `cnt/bstring' where cnt is the number of bits in the unit and bstring is the actual bit string in hex, right adjusted with 0 fill to a multiple of 4 bits on the left.

•   In image coef blocks (output lines that start with blk), all non-zero coefs are listed in the form `number:value' where number is the coef number in zig-zag order with 0 being DC and value is the dequantized coef value.

SEE ALSO
vic(1), ppmtolut(1), mkcube(1), histtolut(1)

McCanne, Steven and Jacobson, Van. ``vic: A Flexible Framework for Packet Video''. In proceedings of ACM Multimedia '95. November, 1995.

ACKNOWLEDGMENTS

Elan Amir (elan@cs.berkeley.edu) implemented the error diffusion dithering code and dynamic color allocation (median cut) algorithms. Chris Goodman (goodman@sgi.com) provided valuable advice on the error diffusion algorithm and helped debug the implementation.

Martin Vetterli (martin@diva.eecs.berkeley.edu) provided input on fast DCT implementations. He pointed out that Arai, Agui, and Nakajmia's 8pt 1D DCT can be used to compute scaled row and column DCTs leading to a 80 multiply 8x8 2D DCT.

Thanks to Robert Berger (rwb@J.GP.CS.CMU.EDU) for his excellent web page on monitor gamma and for his permission to redistribute the gamma calibration test image (gamma.gif).

This software is based in part on the work of the Independent JPEG Group and the Portable Video Research Group.

This work was co-sponsored by the the Lawrence Berkeley National Laboratory and the Tenet Group of the University of California Berkeley and of the International Computer Science Institute. Support was provided by (1) an AT&T Graduate Fellowship; (2) for Lawrence Berkeley National Laboratory: (i) the Director, Office of Energy Research, Scientific Computing Staff, of the U.S. Department of Energy, Contract No. DE-AC03-76SF00098, (ii) Sun Microsystems, (iii) Digital Equipment Corporation, and (iv) Silicon Graphics Inc.; and (3) for the Tenet Research Group: (i) the National Science Foundation and the Advanced Research Projects Agency (ARPA) under Cooperative Agreement NCR-8919038 with the Corporation for National Research Initiatives, (ii) Digital Equipment Corporation, and (iii) Silicon Graphics Inc.

AUTHOR
Steven McCanne (mccanne@ee.lbl.gov), University of California, Berkeley and Lawrence Berkeley National Laboratory, Berkeley, CA, and Van Jacobson (van@ee.lbl.gov), Lawrence Berkeley National Laboratory, Berkeley, CA.

BUGS
There are no contrast or brightness controls. The error-diffsuion dithering code needs more work. At low luminosities, strange pastel colors appear. Blue skies are often rendered green. It would be nice to single-step in smaller units than a frame.