The MPEG Library Version 1.3.1 8 August, 1999 MPEG decoding engine (c) 1992 The Regents of the University of California Front end (c) 1994-99 Gregory P. Ward (gward@python.net) The MPEG Library is a collection of C routines to decode MPEG-1 video streams to a variety of colour schemes. Most of the code in the library comes directly from an old version of the Berkeley MPEG player, "mpeg_play", an X11-specific implementation that worked fine but suffered from minimal documentation and a lack of modularity. A front end to the Berkeley decoding engine was developed by Greg Ward at the Montreal Neurological Institute in May/June 1994 to facilitate the development of an MPEG player specifically for Silicon Graphics workstations; the decoding engine together with the MNI front end constitute the MPEG Library. AVAILABILITY ============ Both the above-mentioned SGI-specific MPEG player (glmpeg_play) and the MPEG Library itself are available from ftp://ftp.bic.mni.mcgill.ca/pub/mpeg/ as well as from the MPEG Library home page at http://starship.python.net/~gward/mpeglib/ The original Berkeley decoder is available at ftp://mm-ftp.cs.berkeley.edu/pub/multimedia/mpeg/play/ A great many other MPEG goodies (another encoder, sample MPEG files, etc.) can also be found on this FTP site -- good hunting ground for the budding MPEG hacker. BUILDING THE LIBRARY (Unix) =========================== The MPEG Library comes with a GNU-style configure script, meaning that building it should be a simple matter: ./configure make Note that you must have an ANSI-compliant compiler to build the library. In general, you should use the same compiler on all code that is to be linked together; this means that (for example), compiling (say) the GIMP with compiler X (ANSI compliant or not), and then linking with an MPEG library built with compiler Y, is just asking for trouble. The configure script does make a good effort to find an ANSI-compliant compiler. The default is to use gcc, or cc if that's not found. If gcc is not found and cc is not ANSI-compliant, configure then takes a chance and looks for acc -- the alternative ANSI compiler provided by Sun (at a price). (Of course, this is probably only meaningful on Sun platforms.) If none of these are found, configure crashes -- you'll have to run it again, telling it the name of the compiler to use (see below for how to do this). Customizing the configuration ----------------------------- You can set a number of environment variables before running `configure' to customize its operation. All of them customize the pre-processing, compilation, and linking stages: CC C compiler to use OPTIMIZE compiler optimization/debugging flags EXTRA_CFLAGS any other compiler flags to use INCLUDE_DIRS -I flags for the pre-processor DEFINES -D or -U flags for the pre-processor EXTRA_LDFLAGS extra linker flags to use when building the standalone executables (mpegtest and easympeg) For instance, on an SGI system, you might wish to use cc instead of gcc (SGI's compiler generally compiles a lot faster than gcc, and generates slightly faster code.) You could then run `configure' as follows: CC=cc ./configure (That's assuming a Bourne-style shell, such as sh, zsh, ksh, or bash. For C-shell and descendents, use "env CC=cc ./configure".) Or you might need to specify extra flags to put your compiler into ANSI mode; this is necessary on some versions of HP-UX as follows: CC=cc EXTRA_CFLAGS=-Aa ./configure Or if your compiler is broken and generates bad code with -O2 (the default), you could tone down or turn off optimization: OPTIMIZE=-O0 ./configure Customizing the build --------------------- All of the variables above can also be overridden at build time, e.g. make CC=gcc EXTRA_CFLAGS=-Wall to use gcc and make it emit lots of warnings. It's generally better to do the overriding at configure time, so that `configure' uses the same flags for compiling test cases as you'll be using to compile the library. Build targets ------------- The default behaviour when you run "make" (or "make all") is to build the library plus whatever standalone executables are supported on your system. Source for the standlone executables lives in the `extras/' subdirectory. The simple test program `mpegtest' is always built; it just decodes an MPEG stream, optionally computing a checksum of each decoded frame. On IRIX systems (SGI workstations), you will also get `easympeg', a simple MPEG player that works under GL. This is provided solely as an example of how little code is needed to make a working MPEG player with the MPEG Library; if you're interested in a full-blown MPEG player for SGI workstations, take a look at my glmpeg_play (available from ftp://ftp.bic.mni.mcgill.ca/pub/mpeg/). If you want to skip building these standalone executables, just run "make lib". Nit-picking optimizations ------------------------- If you are building the library *exclusively* for use with a larger program that takes care of all colour conversion tasks (such as the GIMP), then you can save a bit of code size by omitting most of the colour conversion code supplied with the library. In this case, just run ./configure --disable-dither and you will build a reduced version of the library. This is not necessary to compile or link successfully -- it'll just save a little space. Note that this will result in a version of the library with reduced functionality; only do it if your sole purpose in building the library is to link it statically into a larger program (such as the GIMP) that takes care of colour conversion itself. BUILDING THE LIBRARY (Windows) ============================== Starting with version 1.3.1, the MPEG Library should build under Windows as well as Unix, using either Borland C++ 5.4 or Microsoft Visual C++ 6.0. Thanks to George Yohng for providing the Windows port. Separate batch files are supplied for each compiler; if you're using Borland C++, just run build_bc which will create a single library file (mpegbc.lib) in the "lib" subdirectory. For Visual C++, run build_msvc which will create three library files in the "lib" subdirectory. The three versions of the library are: mpegc.lib - for single-threaded applications mpegcmt.lib - for multi-threaded applications mpegcrt.lib - for applications which use the dynamically loadable run-time library (msvcrt.dll) HOW TO USE THE LIBRARY ====================== There is a short but (hopefully) complete document in the "doc/" subdirectory of the MPEG Library distribution. This is supplied in both PostScript form and as LaTeX 2e source. Comments and suggestions on the documentation are welcome. PROBLEMS? ========= Anyone who has problems under Unix with configuring or compiling the MPEG Library, or linking it with other software, should contact me (gward@python.net). If you have problems with compiling or linking with the library under Windows, please contact George Yohng , since he provided the Windows port and batch files. Problems with using the library (coredumps, memory leaks, and other bugs; or misunderstood documentation) should first be dealt with by re-reading the documentation, and then by reading the source code. If, after carefully reading the documentation, conducting rigorous experiments to isolate the source of the problem, and inspecting the relevant source code, you *still* can't figure out what's going on, contact me at gward@python.net. I will ask if you have read the documentation, conducted experiments, and checked the source code, remind you that the library is unsupported free software, and gratefully accept a patch to fix any problems you may have found. EXAMPLES AND TESTING ==================== For a very simple MPEG player that uses the SGI Graphics Library to display frames, take a look at easympeg.c, included in the "extras/" subdirectory of this distribution. (If you configured and built the library on an SGI platform, easympeg should have been automatically built for you.) Even if you don't have an SGI, the source code can be instructive -- the calls to GL functions are not too intrusive, and not too hard to figure out either. Also, it ought to be possible to convert this program to OpenGL for improved portability. There is also a simple, portable (across Unix versions) program to test the Library: extras/mpegtest.c. It is similar in structure to easympeg, but with all display-related code removed, and with the addition of code to time the playback and to compute simple image checksums. The timing code may be of interest (eg. to answer questions such as "Can I achieve a playback rate of X on platform Y?" or "How much faster will playback be if I decode to shades of gray instead of full 24-bit colour?"), and the checksum code provides a way to ensure that the library returns identical results across platforms (which is currently *not* the case, for reasons unknown to me). Run "mpegtest " to just get timing information on the MPEG in ; add the "-checksum" option to get checksum information; add "-dither " to try out various dithering modes. The possible values of are: "hybrid", "hybrid2", "fs4", "fs2", "fs2fast", "2x2", "gray", "fullcolor", "none", "ordered", "mono", "mono_threshold", "ordered2", and "mbordered". A tiny MPEG stream, test.mpg, is included with the distribution. You can try mpegtest and easympeg on it, but don't expect perfection; for one thing, the library does *not* give identical results across platforms, so the results of running "easympeg -checksum" will not be consistent. I have also written glmpeg_play, a full-fledged MPEG player for SGI platfoms (with frame-buffering, interactive controls, dynamic zooming, etc.). It is available via anonymous ftp as explained above. FUTURE DIRECTIONS ================= None planned, many required. The MPEG Library is based on an out-of-date version of the Berkeley X11 MPEG player ("mpeg_play"), and should be updated to the latest version of mpeg_play. The current version is heavily dependent on global variables -- thus it's not even remotely thread-safe, and you can't interleave the decoding of two streams. This is definitely not desirable, and could be fixed by catching up with mpeg_play. The MPEG Library should be restructured so that it is easier to keep in sync with the Berkeley code in future. All external identifiers should be renamed to avoid conflict with other code, and the interface revamped to be clearer, more consistent, and modular for multi-threaded code and interleaved decoding of multiple streams. The library should probably be renamed to make it clear that it only handles decoding of MPEG-1 video streams (there's a lot more to the MPEG world now than there was in 1994). However, none of this will happen unless others step in to fill the breach. I have little to no interest in multimedia or desktop video, and do not intend to devote any significant time or energy to maintaining the MPEG Library. (This is entirely consistent -- it has, after all, taken me nearly three years to get this minor bugfix release out!) So: if you *are* interested in seeing an open-source, documented library for decoding MPEG video streams become a better, more widely-available and used thing, then please get in touch with me. I'd love to hand this code over to someone willing and able to look after it. Late-breaking news: I just discovered the MPEG Software Simulation Group's (MSSG) free MPEG-2 codec (that's "coder/decoder", if you're not up on your MPEG jargon). This looks like what the MPEG Library should grow up to be if there was anyone to grow it. I'll continue to release bug fixes to the MPEG Library, but I strongly suggest that anyone writing new MPEG code should at least look at the MSSG's work: http://www.mpeg.org/MPEG/MSSG/ ACKNOWLEDGEMENTS ================ Thanks to: * John Cristy for making the MPEG Library an optional add-on to ImageMagick, providing me with more free publicity (and lots of traffic on our ftp site!) than I could have imagined, and for suggesting some important fixes early on * Magnus Heldestat for providing patches to speed up full-colour dithering * Andrew Kuchling for extensive testing of beta versions of 1.2 on a variety of Unix platforms * Adam Moss for writing the mpeg plug-in for the GIMP, causing yet more demand for the library * George Yohng for porting the library to Windows COMPLETE LACK OF WARRANTY ========================= This software is supplied without even the faintest shred of assurance that it works in its entirety. Copyright (c) 1994-99 by Gregory P. Ward. All rights reserved. This file is part of the MNI front end of the Berkeley MPEG decoder. Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without written agreement is hereby granted, provided that the above copyright notice and the following two paragraphs appear in all copies of this software. IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE AUTHOR HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. Please drop me a line if you use the MPEG Library, either successfully or not. And if you use it unsuccessfully and find a nice, easy fix, do please let me know about it! My email address is gward@python.net. $Id: README,v 1.9 1999/08/09 00:33:38 greg Rel $