PARALLAX GRAPHICS
Technical Tips

The MovieTool JPEG Movie File Structure

Overview

The MovieTool movie file format allows full-motion digital movies
to be played back on any workstation with a Parallax video card.

Based on the Joint Photographics Experts Group (JPEG) image 
compression standard, the file format provides a simple, flexible, and
linear stream of audio/video (AV) information.  The AV information is
interleaved within the file, offering self-synchronized playback with a
minimum requirement for real-time services from the UNIX environment.

The file format is designed to focus on the delivery of a single AV clip
and is not intended to grow into a complex or compound document
format for general-purpose multimedia.  We offer this movie file
format as a potential subset to compound multimedia file formats that
are currently under discussion for standardization by such groups as
the Interactive Multimedia Association (IMA).

The basic features of the JPEG Movie file format are as follows:

  Time-synchronized JPEG video delivered at up to 30 frames per second

  Multiple tracks of audio are supported (up to 4) for multilingual support

  Index table for random access to frames

  Limited ability to change playback parameters within the movie
      (for example, to adjust the playback speed)

Updated Movie File Structure

Sun Solaris 2.5 and HP version 9.3 and 10.10: We have updated the file
structure for MovieTool movie files. The new movie structure versions are
JPEG_VERSION_3 and JPEG_VERSION_4.

The current version of MovieTool (Sun Solaris 2.5 and HP version 9.3 and
10.10) captures movies in JPEG_VERSION_2 and then converts them to
JPEG_VERSION_3 if you use MovieTool to trim frames off the beginning or end
of the movie. MovieTool does not implement JPEG_VERSION_4, so there is no
example code for the JPEG_VERSION_4 enhancements.

MovieTool uses the lowest common version of the movie file structure to
ensure cross-platform compatibility with older versions of Parallax
MovieTool and videotool, and for playback by Sun XView. XView plays back
JPEG_VERSION_2 movie files.

The changes to the MovieTool movie file structure are indicated by the
updated "movie.h" file with new operands, and by new attributes in the
movie file header. Most of these changes (JPEG_VERSION_4) are not
implemented in MovieTool at this point, so you will have to work without
example code. The new capabilities include:

  Trimming frames off the beginning and end of a movie. The "trimmed"
      frames are not played back, but remain in the movie file to
      eliminate the need to re-record the movie. See attributes
      "firstValidFrame" and "lastValidFrame" and example code in MovieTool.

  Changing the baseline audio volume control in a movie file. See
      attribute "volbase".

  Changing the Q factor within a movie file (changing one time,
      several times, or every frame). Varying the Q factor can be useful
      for some methods of synchronization and bandwidth-management. 
      See operand "NEW_QFACTOR".

  Storing application-specific data. See operands "APP_DATA_0" to
      "APP_DATA_3".

  Using compressed audio data. See operands "LOAD_COMPRESSED_AUDIO_0"
      to "LOAD_COMPRESSED_AUDIO_3".

NOTE: There is another new attribute that is not currently
      supported, which would select frame mode (default) or field mode
      for movie capture and playback (a frame consists of two interlaced
      fields). The attribute ("options") is marked to show that only
      frame mode is currently supported.

For details about the revised movie file header, new attributes, and
operands, please read the rest of this Appendix.

Movie File Structure

A movie file is structured as a linear stream of bytes:



  
 Fixed-length jp_header record 
  
 Movie Frame 
  
 Movie Frame 
  
 ... 
  
 Movie Frame 
  
 Index (Frame Offset Array) 


  
 indexbuf=offset 
  
 offset(0) 
  
 offset(1) 
  
 ... 
  
 offset(n) 
  
 offset(0)...offset(n) 




Movie File Header

Each movie file starts with this fixed length record (data structure)
that describes the attributes of the movie, the "movie file header".


Original Movie File Header

Below is the original Parallax movie file header for Parallax software for
Sun framebuffer cards with Solaris 2.4 or earlier, or HP version 9.2 or
earlier. This movie file header can also be used for more recent Parallax
releases (Sun framebuffer and overlay with Solaris 2.5 and HP version 9.3
or later) and for cross-platform support.

typedef struct
{
        char    magic[8];       /* Defined as "j_movie" */
        int     version;        /* Version number       */
        int     fps;            /* Desired frames per second executed during playback   */
        int     frames;         /* Total number of frames in the movie file     */
        int     width;          /* Width of image in any frame  */
        int     height;         /* Height of image in any frame */
        int     bandwidth;      /* Bandwidth required for playback      */
        int     qfactor;        /* Quantization factor used in compression */
        int     mapsize;        /* Number of unique colors used in colormap */
        int     indexbuf;       /* Offset in file of frame indexes      */
        int     tracks;         /* Number of audio tracks used  */
        int     unused;         /* An unspecified field */
        int     audioslice;     /* Number of audio bytes per frame      */
        Audio_hdr       audio;  /* Audio header needed to initialize audio device       */
        char    filler[48];     /* Pad out this record to 128 bytes     */
} jpheader;

New Movie File Header

In Parallax software for Solaris 2.5 (Sun framebuffer and overlay) and HP
version 9.3 or later, the movie header file can contain additional
information (see firstValidFrame, lastValidFrame, options, and volbase
below). If you use this movie file header format, it will work
cross-platform between all Parallax releases, but it will not support the
new features during playback on earlier Parallax software releases.

typedef struct
{
        char    magic[8];       /* Defined as "j_movie" */
        int     version;        /* Version number       */
        int     fps;            /* Desired frames per second executed during playback   */
        int     frames;         /* Total number of frames in the movie file     */
        int     width;          /* Width of image in any frame  */
        int     height;         /* Height of image in any frame         */
        int     bandwidth;      /* Bandwidth required for playback      */
        int     qfactor;        /* Quantization factor used in compression */
        int     mapsize;        /* Number of unique colors used in colormap */
        int     indexbuf;       /* Offset in file of frame indexes      */
        int     tracks;         /* Number of audio tracks used  */
        int     volbase;        /* Baseline for volume control (not used by Parallax)   */
        int     audioslice;     /* Number of audio bytes per frame      */
        PlxAudioHeader  audio;  /* Audio header needed to initialize audio device       */
        int     firstValidFrame; /* First & last frames of the movie to be played, ...   */
        int     lastValidFrame; /* ...useful for trimming a few frames off the ends of  */
                                /* movies w/o having to save the whole movie again.  */
        PlxMovieOptions options;        /* Describes special options (frames vs. fields)        */
        char    filler[FILLER]; /* Pad out this record to 128 bytes     */
} jpheader;

Below is some information on the new PlxMovieOptions field, which gives the
capability of specifying whether a movie is made up of frames or fields (2
fields per frame):

typedef struct _PlxMovieOptions
{
        unsigned        frameOrField : 1;       /* Indicates whether the movie is storing a series of...        */
                        			/* ...frames or fields; if 0 (default), the movie is...         */
                        			/* ...a series of full frames; if 1, the movie is a...  */
                        			/* ...series of fields, in which case two fields should...      */
                        			/* ...be stored for each frame.  In other words, for...         */
                        			/* ...field-wise movies, each frame will have two...    */
                        			/* ..."LOAD_JPEG" opcodes, one for each field in the frame.     */
        unsigned        polarity : 1;   	/* Useful only for field-wise compression: if 0, then...        */
                        			/* ...the 1st LOAD_JPEG opcode seen for a frame is meant...     */
                        			/* ...to start at line 0 during display; if 1, then the...      */
                        			/* ...1st LOAD_JPEG opcode seen for a frame is meant to...      */
                        			/* ...start at line 1 during display, and the 2nd...    */
                        			/* ... LOAD_JPEG opcode for the frame is meant to start...      */
                       				/* ...at line 0 during display.         */ 
} PlxMovieOptions;


Attributes

A description of each movie-file attribute defined in the movie file header
data structures follows. Some apply only to the later versions of the
MovieTool JPEG movie file structure (JPEG_VERSION_3 or later) which are
implemented in Parallax MovieTool in Sun Solaris 2.5 or HP version 9.3 or
later.



  
 Movie File Attribute 
  
 Description 


  
 Audio_hdr audio 
  
 Audio header needed to initialize audio device 


  
 audioslice 
  
 The size of the audio portion of a movie frame (in number
       of bytes).  This value is calculated as:
       ((audio_sample_rate * audio_samples_per_unit *
       audio_bytes_per_unit * audio_channels)/fps).
  


  
 bandwidth 
  
 The amount of bandwidth required to play back this movie file
       (in Kbytes per second).  Bandwidth can refer to a
       disk or network "bandwidth"
 


  
 filler 
  
 Filler is added, as needed, to pad the jpheader to fill 128 bytes


  
 firstValidFrame
       lastValidFrame 
  
 (JPEG_VERSION_3 or later movies) The first and last frames of the
       movie to be played. Useful for trimming a few frames off the ends
       of the movie without having to save the whole movie again (see
       Multimedia User's Guide manual, Using MovieTool chapter, Editing
       a Movie section.


  
 fps
  
 The movie file playback rate (in frames per second). This value is
       usually based on the frame speed delivered by the original video
       source (30 for NTSC, 25 for PAL/SECAM).
  

  
 frames 
  
 The number of movie frames (video-only, or AV) in this file


  
 height 
  
 The image height of any frame in this movie (in pixels) 


  
 indexbuf 
  
 Index address (in number of bytes);  acts as pointer to the
       file's integer array to frame offsets (this array contains
       the UNIX file equivalent of Computer Video Control (CVC)
       frame addresses). 
  


  
 magic 
  
 The magic work (the first 8 bytes of the movie file, which
       distinguishes the file type) is defined as "j_movie"
  


  
 mapsize 
  
 The number of colors in video images stored in this file; the
       Parallax Video 24-bit true color mapsize is 2^24
  


  
 options
  
 (JPEG_VERSION_4 or later movies) Specifies frame (default)
versus field mode, and for field mode, whether to start on even (0, usual
setting) or odd (1) fields. IMPORTANT: Only frame mode is supported at this
time. True field mode capture does not work at this time, so you must only
use frame mode.
  


  
 qfactor 
  
 The Quantization (Q) factor used in compression (from Q tables
       defined in Annex K of the ISO CD 10918).
  


  
 tracks 
  
 The number of audio tracks interleaved within each frame
  


  
 unused
  
 (JPEG_VERSION_3 or earlier movies) This 4-byte wide field
       is unspecified.
  


  
 version 
  
 The version number of this j_movie file format


  
 volbase 
  
 (JPEG_VERSION_4 or later movies) The baseline for volume control
       (default baseline is 0). (Not implemented in current version of
       MovieTool.)
  


  
 width 
  
 The image width in any frame of this movie (in pixels).





Movie Frames

Following the fixed record data is a sequence of movie frames,
which appear in the movie file in the order they are to be
performed on playback.

The linear sequence can consist of one or more video-only movie
frames consisting of video only, or many audio/video (A/V) movie
frames consisting of video with synchronized audio.

Each frame consists of a linear sequence of instructions to be
performed during a slice of time, and their operands:

Sample Instructions

1.  LOAD_JPEG instructs the application to load image (video) data.
    This instruction is followed by 4 bytes that represent the
    number of bytes in the JPEG image, and then the JPEG image data.

    NOTE: If you are writing your own application supporting HP
             with shared memory (Parallax software version 9.3 or higher 
             for HP), and if there is a possibility that you may use
             software decompression of JPEG data, then you should search
             for and remove a string of garbage data (FFFFFFD0) in each
             JPEG frame before you write the frame.  The four bytes of
             garbage data would be located right after LOAD_JPEG.  In
             Parallax software verison 9.3 or higher for HP, MovieTool
             and VideoTool remove this garbage data; scomp does not.

2.  LOAD_AUDIO instructs the application to load the audio track.
    The audio data immediately follows the LOAD_AUDIO instruction.
    The (sizeof audio) is taken from the audioslice attribute defined
    in the jpheader.

3.  EOCF indicates the end of the current frame (for every frame).


These instructions are repeated for each movie frame in the file unitl
the last frame is reached.

Movie File Operands (movie.h)

The operands are encoded within a single byte and are defined in a private
include file, movie.h.  These operands are instructions-specific and are
variable in length.

Operands for JPEG_VERSION_2 and JPEG_VERSION_3

The following operands apply to the MovieTool JPEG movie file structure for
movies that are in JPEG_VERSION_2 and JPEG_VERSION_3 formats. MovieTool
contains examples:



  
 Hex Addresses 
  
 Operand 
  
 Description 


  
 (0xed)
  
 END_FRAME
  
 Specifies the end of the current frame.  Use for every frame;
       it is the minimal frame that can be specified.


  
 (0xee)
  
 CLEAR_FRAME
  
 For software-decompressed files only;  Initializes off-screen
       image data.  Use before changing a color map (omit otherwise).
  


  
 (0xe5)
  
 LOAD_AUDIO_0
  
 Loads audio stream from track 0.  Length of audio data is given
       by value of audioslice in header.

       Note that JPEG audio data is not compressed.  Only one audio
       track is currently playable, so only the user-specified track
       is processed;  all others are discarded.
  


  
 (0xe4)
  
 LOAD_AUDIO_1
  
 Loads audio stream from track 1.  
  


  
 (0xe3)
  
 LOAD_AUDIO_2
  
 Loads audio stream from track 2.  
  


  
 (0xe2)
  
 LOAD_AUDIO_3
  
 Loads audio stream from track 3.  
  


  
 (0xf9)
  
 LOAD_CMAP
  
 For software-decompressed files only;  Loads a new colormap
       into the frame-buffer registers.  Use on frame-by-frame basis
       or set once to change from default colormap.  The mapsize field
       in the jpheader specifies the number of color values to be used
       in the colormap (can be 0 to 16.78 million).  The colormap is
       defined as:  mapsize * three bytes of RGB (8 bits each of R, G, and B).
  


  
 (0xf8)
  
 LOAD_MMAP
  
 For software-decompressed files only;  Mutates the current
       colormap into a new one using the difference table stored with
       this operand.  The difference table is defined as follows:
       First byte is the number of new colors;  following two bytes
       contain a color slot number (index to colormap value to be
       changed/mutated), and an RGB triplet value
  


  
 (0xdb)
  
 NEW_FPS
  
 Specifies an additional byte which contains a new frames per
       second value (1 to 30).  Audio rate is unchanges, and may not
       be synchronized;  Use at your own discretion for special effects
  


  
 (0xec)
  
 LOAD_JPEG
  
 Indicates the beginning of JPEG compressed data.  First 4 bytes
       contain the length of the JPEG relevant information.
	
       Note that DQT and DHT markers are not defined in the JPEG
       Movie file data.  The DQT data is generated with the qfactor
       value specified, and the default Huffman tables are always used.
  



Additional Operands for JPEG_VERSION_4

The following operands have been added in JPEG_VERSION_4 (all the operands
on the previous page still apply). Please note that these operands are not
yet implemented in the current version of MovieTool (Solaris 2.5/HP version
9.3/10.10), so there is no example code:



  
 Hex Addresses 
  
 Operand 
  
 Description 


  
 (0xe6)
  
 NEW_QFACTOR 
  
 Indicates that a new Q factor (i.e. different from
the previous Q factor, such as the one in the movie header) should be used
for all frames following this instruction. First 2 bytes contain the new Q
factor. You can change the Q factor once, several times, or every frame.
NOTE: If you vary the Q factor, this can slow down performance a little
while the Q table is calculated and placed in the GC. To minimize this
problem, you can limit the available Q factors (instead of 20, 21, 22, ...
use 20, 25, 30, ...), pre-detect the Q factors used in a movie, and
pre-compile the Q tables.
  


  
 (0xf0)
  
 APP_DATA_0      
  
  Allows an application to store application-specific
information in the movie. First 4 bytes contain the length of the
application data that follows.
  


  
 (0xf1)
  
 APP_DATA_1      
  
 For storing additional application-specific data.
  


  
 (0xf2)
  
 APP_DATA_2      
  
 For storing additional application-specific data.
  


  
 (0xf3)
  
 APP_DATA_3      
  
 For storing additional application-specific data.
  


  
 (0xf4)
  
 LOAD_COMPRESSED_AUDIO_0         
  
  Used to load compressed audio from
audio track 0, First 4 bytes contain the length of the audio data. (Note
MovieTool does not support compressed audio, but you could build it into
your own application.)
  


  
 (0xf5)
  
 LOAD_COMPRESSED_AUDIO_1         
  
 Load compressed audio from track 1.
  


  
 (0xf6)
  
 LOAD_COMPRESSED_AUDIO_2         
  
 Load compressed audio from track 2.
  


  
 (0xf7)
  
 LOAD_COMPRESSED_AUDIO_3         
  
 Load compressed audio from track 3.
  



Movie File Index (Frame Offset Array)

At the end of the movie frames is an index to the movie frames
(an integer array of frame offsets).

The jp_header record field indexbuf is the offset in bytes
from the beginning of the file to the index (frame offset array
of integers).

The address of the first frame of the movie is offset(0), the
address of the second frame is offset(1), and so forth until the
last frame (offset(n)).

Interpreting the Movie File Structure

An application interprets the movie file structure as follows:

1.  Reads the fixed length movie header record and sets up a video
    window for JPEG decompression/playback based on movie
    attributes defined in the jp_header.

2.  Moves to the Index (from start of file, offsets the number of
    bytes stored as indexbuf).

3.  Reads offsets (integers) that are stored in the frame
    offset array and uses these offsets to locate movie frames
    (stored in movie file in sequential order) for playback.

4.  Plays back each movie frame per the playback instructions stored
    in each frame.

The instruction sets used can vary, depending upon how the file is to
be decompressed for playback.

Sample instructions for hardware decompressed files are as follows:

  LOAD_JPEG--Loads video still.
  LOAD_AUDIOn--Loads specific audio track (if requested)
  END_FRAME--Ends current frame; transfers image from the 
      frame buffer to the display.
  Repeat until specified number of frames has been processed.

Sample instructions for software decompressed files are as follows:

  LOAD_JPEG--Loads video still.
  LOAD_AUDIOn--Loads specific audio track (if requested)
  END_FRAME--Ends current frame; transfers image from the 
      frame buffer to the display.
  CLEAR_FRAME--Clears offscreen memory.  Use this if you plan
      to change the colormap (using LOAD_CMAP or LOAD_MMAP) in the
      next frame (otherwise, omit).
  END_FRAME--Ends current frame; transfers image from the 
      frame buffer to the display.
  LOAD_CMAP or LOAD_MMAP--Loads colormap (if desired).  Image
      is dithered to the number of bits supported by the frame
      buffer using the newly loaded colormap.
  LOAD_JPEG--Loads video still.
  LOAD_AUDIOn--Loads specific audio track (if requested)
  END_FRAME--Ends current frame; transfers image from the 
      frame buffer to the display.
  Repeat until specified number of frames has been processed.


 




[ Home ]
[ New! ]
[ Products ]
[ Solutions ]
[ Support ]
[ Company ]
[ Contacts ]



Copyright 1997 Parallax Graphics, Inc.  All rights reserved.