About

About the reference software

The reference software is provided in source form, along with instructions for building the software on a number of platforms. On all platforms the main parts to be concerned with are:

• The libisomediafile library: This is the library that you will link with your own code that uses this API.

• ISOMovies.h: This file contains all the exported routines used by the libisomediafile library. You will need to #include this file in your code.

• MP4OSMacros.h: There are copies of this file for each platform. This file is used to customize the software for any platform specific needs. This file is #included by ISOMovies.h, so the proper platform-specific directory must be in your preprocessor’s search path.

Building the software

The build directories are platform-specific subdirectories of mp4lib. For example, on Linux, go to mp4lib/linux/libisomediafile. The targets and their build environment are:

• Linux: Makefile for GNU make / gcc

• Win32: Visual Studio 2008, 2012 and 2015 project files

• MacOS X: XCode project file (FreeBSD, Solaris, Classic Mac, and Mac OS X Server makes are no longer supported.)

The code should build without warnings or errors. If you have any problems please report them. Other unix-like platforms could probably be built from the Linux directory. If you find that you have to modify any files to get a good build on some other platform, consider making a separate platform-specific subdirectory of mp4lib and donating your changes to ISO.

Note that on OS X, the projects assume that XCode is set with the preference for Legacy Build Locations (XCode preferences, locations, advanced).

The build target on all platforms is a library called libisomediafile. This is the library that you link your code with.

Namespace / runtime issues

All exported routines begin with the prefixes MP4 (MPEG-4 specific), MJ2 (Motion JPEG specific) or ISO (general). The released library will not create any global variables.

For this current release, threading considerations are:

• There is no provided mechanism for synchronization of the routines that modify the movie’s metadata. Only one thread should call the movie, media, or track modification functions at any time.
• On playback there are no known threading problems. You can dedicate a separate thread for each track, or even read the same track at different points in the movie using multiple threads.

Error handling / debugging

The current release contains a DEBUG_RETURN macro that you can define to break to the debugger when a function returns with error. This was the default behaviour of prior releases and has been turned off so error codes are now correctly returned to the function's caller. A good place to define this macro is in the MP4OSMacros.h file.

Important known limitations of the library

The routines herein should only be used for the following situations:

• Creating a new media file, adding media samples, and then saving it.
• Opening and reading an existing media file.

The process of editing media files (for example, opening a file and adding a track) is explicitly not supported by the current release of this library. This could be remedied in a future release.

The current release has been tested for memory leaks. The default movie routines operate on an in-memory copy of the movie file. It may be possible to make movies that are too large for this release to handle if you do not have a large enough amount of virtual memory.