--- /dev/null
+<TITLE>LibMPEG3</TITLE>
+
+<CENTER>
+
+<FONT FACE=HELVETICA SIZE=+4><B>Using LibMPEG3 for advanced MPEG
+decoding</B></FONT><P>
+
+<TABLE>
+<TR>
+<TD>
+<CODE>
+Author: Heroine Virtual Ltd. (Motion picture solutions for Linux without a warranty)<BR>
+Harassment: broadcast@earthling.net<BR>
+Homepage: heroinewarrior.com<P>
+
+libmpeg3 is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.<P>
+
+libmpeg3 is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.<P>
+
+
+</CODE> </TD> </TR> </TABLE> </CENTER>
+
+
+<H1>Table of contents</H1><P>
+<A HREF="#INTRO">Intro</A><BR>
+<A HREF="#BUILDING">Building the library</A><BR>
+<A HREF="#USAGE">Usage</A><BR>
+<A HREF="#TOC">Using tables of contents for editing</A><BR>
+<A HREF="#SUBTITLES">Decoding subtitles</A><BR>
+<A HREF="#UTILITIES">Using the utilities</A><BR>
+
+
+
+
+
+
+
+
+<P>
+
+<A NAME=INTRO>
+
+LibMPEG3 decodes several MPEG standards into uncompressed data suitable
+for editing and playback.<P>
+
+libmpeg3 currently decodes:<P>
+
+<BLOCKQUOTE>MPEG-2 video<BR>
+MPEG-1 video<BR>
+mp3 audio<BR>
+mp2 audio<BR>
+ac3 audio<BR>
+MPEG-2 transport streams<BR>
+MPEG-2 program streams<BR>
+MPEG-1 program streams<BR>
+IFO files<BR>
+</BLOCKQUOTE><P>
+
+The video output can be in many different color models and frame
+sizes. The audio output can be in twos compliment or floating point.
+Frame accurate seeking, normally impossible in transport streams, is
+possible in libmpeg3 through the use of a <B>table of contents</B>.
+MPEG-2 video in YUV-422 colorspace is decodable. Digital TV broadcasts
+and DVD's can be edited using libmpeg3. Libmpeg3 takes what is
+normally a last mile distribution format and makes it editable.<P>
+
+Because of these and other features libmpeg3 is not intended for
+consumer applications but serves users who are interested in high
+quality editing and footage acquisition.<P>
+
+
+
+
+
+
+
+<A NAME=BUILDING>
+<FONT FACE=HELVETICA SIZE=+4><B>Building the library</B></FONT><P>
+
+libmpeg3 depends on the CFLAGS environment variable to get optimization
+flags. You should set it to <P>
+
+<TT>-O3 -march=i686 -fmessage-length=0 -funroll-all-loops
+-fomit-frame-pointer -malign-loops=2 -malign-jumps=2
+-malign-functions=2</TT><P>
+
+You must run <B>make</B> to build the library and should be using
+Kernel 2.4.9 or later. The makefile automatically determines
+appropriate parameters and puts the library in i686/libmpeg3.a.
+Several utilities are also built. Install the utilities by running
+<B>make install</B>.<P>
+
+Unfortunately libmpeg3 excercizes the
+system more aggressively than a consumer library and this brings out
+different bugs in each kernel version.<P>
+
+
+2.4.9: ext3 filesystem failure<BR>
+
+2.4.10: memory management failure when running mpeg3toc<BR>
+
+2.4.17: memory management failure after 5 hours of decoding video<P>
+
+
+As libmpeg3 is not one of the standard MPEG decoding
+libraries, these utilities are unlike any you've ever seen before.
+Remember a utility is only as illegal or legal as the guy who runs
+it.<P>
+
+
+
+
+<A NAME=USAGE>
+<H1>Usage</H1><P>
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 1: Verifying file compatibility</B></FONT><P>
+
+Programs using libmpeg3 must <CODE>#include "libmpeg3.h"</CODE>.<P>
+
+Call <CODE>mpeg3_check_sig</CODE> to verify if the file can be read by
+libmpeg3. This returns a 1 if it is compatible and 0 if it isn't.<P>
+
+
+
+
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 2: Open the file</B></FONT><P>
+
+You need an <CODE>mpeg3_t*</CODE> file descriptor:<P>
+<CODE>
+mpeg3_t* file;
+</CODE>
+<P>
+
+Then you need to open the file:<P>
+
+<CODE>file = mpeg3_open(char *path);</CODE><P>
+
+<CODE>mpeg3_open</CODE> returns a NULL if the file couldn't be opened
+for some reason. Be sure to check this. Everything you do with
+libmpeg3 requires passing the <CODE>file</CODE> pointer.<P>
+
+Another way of opening a file is <P>
+
+<CODE>mpeg3_open_copy(char *path, mpeg3_t *old_file)</CODE><P>
+
+You need to open multiple copies of a file in realtime situations
+because only one thread can access a mpeg3_t structure at a time. The
+audio and video can't read simultaneously. The solution is not to
+repeatedly call mpeg3_open but to call mpeg3_open_copy for every file
+handle after the first one. This copies tables from the first file to
+speed up opening.<P>
+
+
+
+
+
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 3: Set optimization strategies</B></FONT><P>
+
+Call <CODE>mpeg3_set_cpus(mpeg3_t *file, int cpus)</CODE> to set how
+many CPUs should be devoted to video decompression. LibMPEG3 can use
+any number.<P>
+
+Call <CODE>mpeg3_set_mmx(mpeg3_t *file, int use_mmx)</CODE> to set if
+MMX is used for video. Disabling MMX is mandatory for low bitrate
+streams since it is very lossy. By the way, lately the compiled MMX
+output has been producing corrupted video. This is a change in the way
+modern compilers and CPU's handle MMX from the way it was done 4 years
+ago but since modern CPU's are so fast, you're better off not using MMX
+at all.<P>
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 4: Query the file.</B></FONT><P>
+
+There are a number of queries for the audio components of the stream:<P>
+
+<CODE><PRE>
+int mpeg3_has_audio(mpeg3_t *file);
+int mpeg3_total_astreams(mpeg3_t *file); // Number of multiplexed audio streams
+int mpeg3_audio_channels(mpeg3_t *file, int stream);
+int mpeg3_sample_rate(mpeg3_t *file, int stream);
+long mpeg3_audio_samples(mpeg3_t *file, int stream); // Total length
+</PRE></CODE>
+
+The audio is presented as a number of <B>streams</B> starting at 0 and
+including <CODE>mpeg3_total_astreams</CODE> - 1. Each stream contains a
+certain number of <B>channels</B> starting at 0 and including
+<CODE>mpeg3_audio_channels</CODE> - 1.
+
+The methodology is first determine if the file has audio, then get
+the number of streams in the file, then for each stream get the number
+of channels, sample rate, and length.<P>
+
+There are also queries for the video components:<P>
+
+<CODE><PRE>
+int mpeg3_has_video(mpeg3_t *file);
+int mpeg3_total_vstreams(mpeg3_t *file); // Number of multiplexed video streams
+int mpeg3_video_width(mpeg3_t *file, int stream);
+int mpeg3_video_height(mpeg3_t *file, int stream);
+float mpeg3_frame_rate(mpeg3_t *file, int stream); // Frames/sec
+long mpeg3_video_frames(mpeg3_t *file, int stream); // Total length
+int mpeg3_colormodel(mpeg3_t *file, int stream);
+</PRE></CODE>
+
+The video behavior is the same as with audio, except that video has no
+subdivision under <B>streams</B>. Frame rate is a floating point
+number of frames per second.<P>
+
+<TT>mpeg3_colormodel</TT> returns either MPEG3_YUV420P or
+MPEG3_YUV422P. MPEG3_YUV422P is only encountered in high quality video
+not available in any consumer distribution medium.<P>
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 5: Seeking to a point in the file</B></FONT><P>
+
+Each audio stream and each video stream has a position in the file
+independant of each other stream. A variety of methods are available
+for specifying the position of a stream: <B>byte offset, frame,
+sample</B>. Which method you use depends on whether you're seeking
+audio or video and whether you have a table of contents for the
+stream.<P>
+
+The preferred seeking method if you're writing a player is:<P>
+
+<CODE><PRE>
+int mpeg3_seek_byte(mpeg3_t *file, int64_t byte);
+int64_t mpeg3_tell_byte(mpeg3_t *file);
+</PRE></CODE>
+
+This seeks all tracks to an absolute byte offset in the file. The
+byte offset is from 0 to the result of:<P>
+
+<CORE><PRE>
+mpeg3_get_bytes(mpeg3_t *file)
+</PRE></CODE>
+
+
+The alternative to byte seeking is <B>frame or sample seeking</B>.
+Frame seeking is only possible if a <B>table of contents</B> exists.
+The <B>mpeg3toc</B> that comes with libmpeg3 creates tables of contents
+from MPEG 1 & 2 streams. Sample seeking is only possible if the stream
+is fixed bitrate audio. The audio seeking is handled by:<P>
+
+<CODE><PRE>
+int mpeg3_set_sample(mpeg3_t *file, long sample, int stream); // Seek
+long mpeg3_get_sample(mpeg3_t *file, int stream); // Tell current position
+</PRE></CODE>
+
+and the video seeking is handled by:<P>
+
+<CODE><PRE>
+int mpeg3_set_frame(mpeg3_t *file, long frame, int stream); // Seek
+long mpeg3_get_frame(mpeg3_t *file, int stream); // Tell current position
+</PRE></CODE>
+
+
+You can either perform percentage seeking or absolute byte seeking but
+not both on the same file handle. Once you perform either method, the
+file becomes configured for that method.<P>
+
+If you're in byte seeking mode and you want the current time stamp in
+the file you can't use mpeg3_get_frame or mpeg3_get_sample because you
+don't know the total length in the desired units. The
+<CODE>mpeg3_audio_samples</CODE> and <CODE>mpeg3_video_frames</CODE>
+commands don't work in percentage seeking either. Instead use
+
+<CODE><PRE>
+double mpeg3_get_time(mpeg3_t *file);
+</PRE></CODE>
+
+which gives you the last timecode read in seconds. The MPEG standard
+specifies timecodes being placed in the streams. Now you know the
+absolute byte position in the file and the current time stamp, enough
+to update a progress bar or a text box.<P>
+
+Finally, there is a way to seek to the previous frame of video:
+
+
+<CODE><PRE>
+int mpeg3_previous_frame(mpeg3_t *file, int stream);
+</PRE></CODE>
+
+Because MPEG 1 & 2 are really hairy, the set commands won't do much
+good for playing backwards. mpeg3_previous_frame does some tricks to
+seek to the previous frame. Next you have to call a read_frame
+command to read it.
+<P>
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 6: Read the data</B></FONT><P>
+
+<I>To read <B>audio</B> data use:</I><P>
+
+<CODE><PRE>
+int mpeg3_read_audio(mpeg3_t *file,
+ float *output_f, // Pointer to pre-allocated buffer of floats
+ short *output_i, // Pointer to pre-allocated buffer if int16's
+ int channel, // Channel to decode
+ long samples, // Number of samples to decode
+ int stream); // Stream containing the channel
+</PRE></CODE>
+
+This decodes a buffer of sequential floats or int16's for a single
+channel, depending on which *output... parameter has a nonzero
+argument. To get a floating point buffer pass a pre-allocated buffer
+to <CODE>output_f</CODE> and NULL to <CODE>output_i</CODE>. To get an
+int16 buffer pass NULL to <CODE>output_f</CODE> and a pre-allocated
+buffer to <CODE>output_i</CODE>. Alternatively you can pass NULL to
+both buffer arguments and the decoder won't render anything.<P>
+
+After reading an audio buffer, the current position in the one stream
+is advanced. Remember that if you're using percentage seeking you
+can't call <TT>mpeg3_set_sample</TT> to rewind and read every channel.
+How then, do you read more than one channel of audio data? Use
+
+<CODE><PRE>
+mpeg3_reread_audio(mpeg3_t *file,
+ float *output_f, /* Pointer to pre-allocated buffer of floats */
+ short *output_i, /* Pointer to pre-allocated buffer of int16's */
+ int channel, /* Channel to decode */
+ long samples, /* Number of samples to decode */
+ int stream);
+</PRE></CODE>
+
+to read each remaining channel after the first channel.<P>
+
+
+
+
+
+
+
+<I>To read <B>video</B> data there are two methods. RGB frames or YUV
+frames. To get an RGB frame use:</I> <BR>
+
+<CODE><PRE>
+int mpeg3_read_frame(mpeg3_t *file,
+ unsigned char **output_rows, // Array of pointers to the start of each output row
+ int in_x, // Location in input frame to take picture
+ int in_y,
+ int in_w,
+ int in_h,
+ int out_w, // Dimensions of output_rows
+ int out_h,
+ int color_model, // One of the color model #defines given above.
+ int stream);
+</PRE></CODE>
+
+The video decoding works like a camcorder taking copies of a movie
+screen. The decoder "sees" a region of the movie screen defined by
+<CODE>in_x, in_y, in_w, in_h</CODE> and transfers it to the frame
+buffer defined by <CODE>**output_rows</CODE>. The input values must be
+within the boundaries given by <CODE>mpeg3_video_width</CODE> and
+<CODE>mpeg3_video_height</CODE>. The size of the frame buffer is
+defined by <CODE>out_w, out_h</CODE>. Although the input dimensions
+are constrained, the frame buffer can be any size.<P>
+
+<CODE>color_model</CODE> defines which RGB color model the picture
+should be decoded to and the possible values are given in
+<B>libmpeg3.h</B>. The frame buffer pointed to by
+<CODE>output_rows</CODE> must have enough memory allocated to store the
+color model you select.<P>
+
+<B>You must allocate 4 extra bytes in the last output_row.</B> This is
+scratch area for the MMX routines.<P>
+
+<CODE>mpeg3_read_frame</CODE> advances the position in the one stream by 1 frame.<P>
+
+<I>To read YUV frames use one of two methods:</I><BR>
+
+<CODE><PRE>
+int mpeg3_read_yuvframe(mpeg3_t *file,
+ char *y_output,
+ char *u_output,
+ char *v_output,
+ int in_x,
+ int in_y,
+ int in_w,
+ int in_h,
+ int stream);
+</PRE></CODE>
+
+The behavior of in_x, in_y, in_w, in_h is identical to mpeg3_read_frame
+except here you have no control over the output frame size. <B>You
+must allocate in_w * in_h for the y_output, and in_w * in_h / 4 for the
+u_output and v_output.</B>
+
+While <B>mpeg3_read_yuvframe</B> allows cropping of letterbox it still
+requires one memcpy. A faster alternative is:<P>
+
+<CODE><PRE>
+int mpeg3_read_yuvframe_ptr(mpeg3_t *file,
+ char **y_output,
+ char **u_output,
+ char **v_output,
+ int stream);
+</PRE></CODE>
+
+This redirects a *y_output, *u_output, and *v_output pointer to the
+scratch buffer that decoding took place in. Since MPEG is temporal
+compression, there is always a buffer containing the last decoder
+output.<P>
+
+
+
+
+For professional use the library can decode YUV 4:2:2 video in addition
+to YUV 4:2:0. This variable is determined at encoding time, won't
+affect the usage of <B>mpeg3_read_frame</B> but you do need an extra
+function call in order to use <B>mpeg3_read_yuvframe</B>. To determine
+the encoding of the video stream use
+
+<CODE><PRE>
+mpeg3_colormodel(mpeg3_t *file, int stream)
+</PRE></CODE>
+
+This returns either <B>MPEG3_YUV420P</B> or <B>MPEG3_YUV422P</B>. The
+output buffers and the YUV to RGB conversion for
+<B>mpeg3_read_yuvframe</B> must be adjusted for the higher sampling of
+MPEG3_YUV422P. When using <B>mpeg3_read_yuvframe_ptr</B> you don't
+need to adjust any output buffers.<P>
+
+<FONT FACE=HELVETICA SIZE=+4><B>Synchronizing video with audio</B></FONT><P>
+
+To synchronize video with audio in realtime you need to sometimes delay
+the video and sometimes drop frames. It's easy to calculate the number
+of frames to drop but if you're using percentage seeking you can't
+calculate the exact percentage to seek forward by. Instead call <P>
+
+<CODE>mpeg3_drop_frames(mpeg3_t *file, long frames, int stream);</CODE><P>
+
+This skips <CODE>frames</CODE> frames from the current position whether
+in percentage seeking or absolute seeking.<P>
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 7: Close the file</B></FONT><P>
+
+Be sure to close the file with <CODE>mpeg3_close(mpeg3_t *file)</CODE>
+when you're done with it.
+
+
+
+
+
+
+
+
+
+<P>
+<A NAME=TOC>
+<FONT FACE=HELVETICA SIZE=+4><B>Using tables of contents for editing</B></FONT><P>
+
+In 1985 everyone watched Smurfs but one guy watched Robotech. In 1990
+everyone watched Teenage Mutant Ninja Turtles but one guy watched
+Transformers. In 1995 everyone watched Pokemon but one guy watched
+Behind the Scenes. Now everyone wants handheld organizers but one guy
+wants MPEG editors. For the wierdos who always looked at the camera
+rig instead of the celebrity, libmpeg3 supports a way of seeking to an
+exact frame or sample in any kind of MPEG encapsulation format for
+editing.<P>
+
+A table of contents must be built for any footage to be edited with
+libmpeg3. Run <TT>mpeg3toc <mpeg stream> <output table of contents></TT><P>
+
+
+For editing DVD footage, the mpeg stream argument should be the ifo
+file belonging to the title set to be edited. This utility reads
+through every file comprising the mpeg stream and records the offset of
+every 65536th sample and every keyframe so it can be pretty slow.<P>
+
+The resulting table of contents file should be passed to mpeg3_open
+and mpeg3_open_copy just like a normal file. The only difference is
+frame seeking of video is available.<P>
+
+
+
+
+
+
+
+
+
+
+<A NAME=SUBTITLES
+<FONT FACE=HELVETICA SIZE=+4><B>Decoding subtitles</B></FONT><P>
+
+Subtitles are encoded in DVD Program streams as 4 color bitmaps. They
+require invoking mpeg3_open with the IFO file corresponding to the VOB
+files in order to play the VOB files. The IFO file contains the color
+palette.
+
+
+
+
+<A NAME=UTILITIES
+<FONT FACE=HELVETICA SIZE=+4><B>USING THE UTILITIES</B></FONT><P>
+
+
+
+
+
projects / goodguy / history.git / blobdiff