FFmpegSource2 API Documentation

FFmpegSource2 (FFMS2) is a wrapper library around ffmpeg, plus some additional components to deal with file formats libavformat has (or used to have) problems with. It gives you a convenient way to say "open and decompress this media file for me, I don't care how you do it", without having to bother with the sometimes less than straightforward and less than perfectly documented ffmpeg internals. May be frame and/or sample accurate on good days. The library is written in C++, but the public API is C-friendly and it is possible to simply include and link directly with a pure C application.

The source is MIT licensed and can be obtained from the Google Code project SVN; see http://code.google.com/p/ffmpegsource/source/checkout.

Limitations

FFMS2 does not mux or encode anything. FFMS2 does not give you fine control over codec internals. FFMS2 does not let you demux raw compressed data, you get it decompressed or not at all. FFMS2 does not provide you with a good solution for realtime playback, since it needs to index the input file before you can retreive frames or audio samples. FFMS2 does not currently handle things like subtitles, file attachments or chapters. FFMS2's video frame and audio sample retrieval functions are not threadsafe; you may only have one request going at a time.

Compilation

FFMS2 has the following dependencies:

Compiling the library itself is fairly straightforward. For the basics, just add the include folder to your include paths and compile everything in src/core; everything else can be skipped. src/avisynth contains code for some Avisynth filters (optional and Windows-only); src/config is some (mostly autogenerated) configuration headers; src/index is a stand-alone indexing application (built separately and linked against the main FFMS2 library); and src/test is an (incomplete) automatic regression test tool (also built separately). Take a look in doc/compiling.txt in the source tree for further details.

Windows-specific compilation notes

If you're compiling the library on Windows, it is suggested that you use the Microsoft Visual Studio 2008 solution file from SVN. Any version of MSVC2008 should work for compiling it, including the free Express Edition (but if you use that you must undefine HAALISOURCE or find a copy of the ATL libraries). The project file in question assumes that you have compiled ffmpeg with MinGW (guides on how to do that are easy to find) and want to link FFMS2 with it statically (linking it dynamically is possible but not recommended since it usually leads to DLL hell). Add your mingw/include and mingw/lib folders to MSVC's respective global directory settings (Tools menu -> Options -> Projects and Solutions -> VC++ Directories) and you should be good to go.

If you're using anything else, you're on your own. It's possible to build the library (but not the Avisynth plugin) using MinGW; this is also the only way to build a 64-bit version of it at the moment. If you're rolling your own MSVC solution file, remember that you need to #define FFMS_EXPORTS somewhere when compiling the library. You may also #define HAALISOURCE if you want to make the library able to open MPEG TS/PS and OGM files using Haali's DirectShow splitter (if you do not define it, those files will be opened with libavformat instead, and that usually doesn't work out all that well). Note that if you do so, opening those files will fail unless the user has the Haali Media Splitter DirectShow filter installed. Both those defines are enabled by default in the solution file in SVN.

Quickstart guide for impatient people

If you don't want to know anything about anything and just want to open some video with FFMS2 in the absolutely simplest possible manner, without selective indexing, progress reporting, saved index files, keyframe or timecode reading or anything like that, here's how to do it with the absolutely bare minimum of code.

#include <ffms.h>
#ifdef _WIN32
#include <objbase.h>
#endif

int main (...) {
	/* If you are on Windows you should first initialize COM, or all MPEG-TS/PS and OGM
	files may return an error when you try to open them (if the library was built
	with HAALISOURCE defined). All other formats will work normally. */
#ifdef _WIN32
	bool com_inited = false;
	HRESULT res = CoInitializeEx(NULL, COINIT_MULTITHREADED);
	if (SUCCEEDED(res)) 
		com_inited = true;
	else if (res != RPC_E_CHANGED_MODE) {
		/* com initialization failed, handle error */
	}
#endif

	/* Initialize the library itself.
	You'll probably want to do the CPU caps detection automatically,
	or pass 0 if you don't care. */
	FFMS_Init(FFMS_CPU_CAPS_MMX | FFMS_CPU_CAPS_MMX2);

	/* Index the source file. Note that this example does not index any audio tracks. */
	char errmsg[1024];
	FFMS_ErrorInfo errinfo;
	errinfo.Buffer      = errmsg;
	errinfo.BufferSize  = sizeof(errmsg);
	errinfo.ErrorType   = FFMS_ERROR_SUCCESS;
	errinfo.SubType     = FFMS_ERROR_SUCCESS;
	const char *sourcefile = "somefilename";
	FFMS_Index *index = FFMS_MakeIndex(sourcefile, 0, 0, NULL, NULL, FFMS_IEH_ABORT, NULL, NULL, &errinfo);
	if (index == NULL) {
		/* handle error (print errinfo.Buffer somewhere) */
	}

	/* Retrieve the track number of the first video track */
	int trackno = FFMS_GetFirstTrackOfType(index, FFMS_TYPE_VIDEO, &errinfo);
	if (trackno < 0) {
		/* no video tracks found in the file, this is bad and you should handle it */
		/* (print the errmsg somewhere) */
	}

	/* We now have enough information to create the video source object */
	FFMS_VideoSource *videosource = FFMS_CreateVideoSource(sourcefile, trackno, index, 1, FFMS_SEEK_NORMAL, &errinfo);
	if (videosource == NULL) {
		/* handle error (you should know what to do by now) */
	}

	/* Since the index is copied into the video source object upon its creation,
	we can and should now destroy the index object. */
	FFMS_DestroyIndex(index);

	/* Retrieve video properties so we know what we're getting.
	As the lack of the errmsg parameter indicates, this function cannot fail. */
	const FFMS_VideoProperties *videoprops = FFMS_GetVideoProperties(videosource);

	/* Now you may want to do something with the info, like check how many frames the video has */
	int num_frames = videoprops->NumFrames;
	
	/* Get the first fram for examination so we know what we're getting. */
	const FFMS_Frame *propframe = FFMS_GetFrame(videosource, 0, errinfo);

	/* Now you may want to do something with the info; particularly interesting values are:
	propframe->EncodedWidth; (frame width in pixels)
	propframe->EncodedHeight; (frame height in pixels)
	propframe->EncodedPixelFormat; (actual frame colorspace)
	*/

	/* If you want to change the output colorspace or resize the output frame size,
	now is the time to do it. */
	/* See libavutil/pixfmt.h for the list of pixel formats/colorspaces.
	To get the name of a given pixel format, strip the leading PIX_FMT_
	and convert to lowercase. For example, PIX_FMT_YUV420P becomes "yuv420p". */
	int64_t pixfmt = (int64_t)1 << FFMS_GetPixFmt("bgra");
	if (FFMS_SetOutputFormatV(videosource, pixfmt, propframe->EncodedWidth, propframe->EncodedHeight, FFMS_RESIZER_BICUBIC, &errinfo)) {
		/* handle error */
	}

	/* now we're ready to actually retrieve the video frames */
	int framenumber = 0; /* valid until next call to FFMS_GetFrame* on the same video object */
	const FFMS_Frame *curframe = FFMS_GetFrame(videosource, framenumber, &errinfo);
	if (curframe = NULL) {
		/* handle error */
	}
	/* do something with curframe */
	/* continue doing this until you're bored, or something */

	/* now it's time to clean up */
	FFMS_DestroyVideoSource(videosource);
#ifdef _WIN32
	if (com_inited)
		CoUninitialize();
#endif
	
	exit 0;
}

And that's pretty much it. Easy, ain't it?

Indexing and You

Before opening a media file with FFMS2, you must index it. This is to ensure that keyframe positions, timecode data and other interesting things are known so that frame-accurate seeking is easily possible.

There are two ways to index a media file. The first one is really a backwards compatibility thing and uses FFMS_MakeIndex. You call the function with the source filename, a binary mask representing what audio tracks you want to index (all video tracks are always automatically indexed; you have no choice in the matter), another binary mask representing what audio tracks you want to dump to Wave64 files on disk, an optional progress reporting callback and a likewise optional audio dump filename generation callback; and it will create an index object. With this method there is no way of telling ahead of time how many tracks the file has and hence the only two masks that are useful in practice are 0 (index nothing) and -1 (index everything). If you want to index only certain tracks you will have to redo the indexing after examining the index. This indexing method may be used if you only want to index video tracks, or if you want all the audio tracks regardless of how many they are, or if you already know the track layout of the file you're going to open.

The other method is a bit more sophisticated. First, you create an indexer object using FFMS_CreateIndexer and the source filename. You can then examine the indexer using FFMS_GetNumTracksI, FFMS_GetTrackTypeI and FFMS_GetCodecNameI to determine how many tracks there are and what their respective types are. When you have done so, you call FFMS_DoIndexing, which is exactly like FFMS_MakeIndex except you pass it the indexer object instead of the source filename. Since you now know the track layout, you are free to pass a more restrictive track mask to index only the tracks relevant to your interests. As with FFMS_MakeIndex, all video tracks are always indexed; the trackmask only applies to audio tracks. If you change your mind and decide there are no tracks interesting to you in the file, call FFMS_CancelIndexing. Both FFMS_DoIndexing and FFMS_CancelIndexing destroys the indexer object and frees its memory.

When you have indexed the file you can write the index object to a disk file using FFMS_WriteIndex, which is useful if you expect to open the same file more than once, since it saves you from reindexing it every time. It can be particularly time-saving with very large files or files with a lot of audio tracks, since both of those can take quite some time to index.

To create an index object from a saved disk file, use FFMS_ReadIndex. Note that the index file written has an internal version number; if you have a version of FFMS2 that isn't the same as the one that created the index, it will most likely not accept the index at all (the read function will fail). If you want to verify that a given index file actually is an index of the source file you think it is, use FFMS_IndexBelongsToFile.

Function Reference

Most functions that can fail in one way or another (as well as some that should be able to but currently don't) support error reporting using the ErrorMsg and MsgSize parameters. Example:

char errmsg[1024];
FFMS_ErrorInfo errinfo;
errinfo.Buffer      = errmsg;
errinfo.BufferSize  = sizeof(errmsg);
errinfo.ErrorType   = FFMS_ERROR_SUCCESS;
errinfo.SubType     = FFMS_ERROR_SUCCESS;

const FFMS_Frame *frame = FFMS_GetFrame(vb, frameno, &errinfo);
/* failure? */
if (frame == NULL) {
	printf("failed to get frame number %d, error message: %s", frameno, errinfo.Buffer);
	/* etc... */
}

How many characters you want to allocate to the error message is up to you; if you allocate too few the messages may get truncated. 1024 should be enough for anyone.

FFMS_Init - initializes the library

void FFMS_Init(int CPUFeatures)

Initializes the FFMS2 library. This function must be called once at the start of your program, before doing any other FFMS2 function calls. Its only argument is an integer representing what CPU instruction sets may be used by the parts of FFmpeg that have handwritten assembler but no runtime CPU detection, i.e. libswscale and libpostproc (see FFMS_CPUFeatures in the Constants and Preprocessor Definitions section; binary OR the constants together if you want more than one). Pass 0 if you don't care; the performance hit won't be that big unless you do a lot of postprocessing or rescaling.

If you are on Windows, you should also initialize COM before calling this function, since the library might have been built with HAALISOURCE. If it was indeed built with HAALISOURCE but you do not intialize COM, all MPEG-TS/PS and OGM files will cause an error when you try to open them. All other file types will work normally. Typically, you'd initialize COM something like the following:

#include <objbase.h>
/* later on, in the actual code... */
bool com_inited = false;
HRESULT res = CoInitializeEx(NULL, COINIT_MULTITHREADED);
if (SUCCEEDED(res)) 
	com_inited = true;
else if (res != RPC_E_CHANGED_MODE) {
	/* com initialization failed, handle error */
}
/* your code goes here */
/* and after you're done: */
if (com_inited)
	CoUninitialize();

FFMS_GetLogLevel - gets ffmpeg message level

int FFMS_GetLogLevel()

Retrieves ffmpeg's current logging/message level (i.e. how much diagnostic noise it prints to STDERR). If you want to make any sense of the returned value you'd better #include <libavutil/log.h> from the ffmpeg source tree to get the relevant constant definitions. Alternatively, just copy the relevant constant definitions into your own code and hope the ffmpeg devs doesn't change them randomly for no particular reason like they do with everything else.

FFMS_SetLogLevel - sets ffmpeg message level

void FFMS_SetLogLevel(int Level)

Sets ffmpeg's logging/message level; see FFMS_GetLogLevel() for details.

FFMS_CreateVideoSource - creates a video source object

FFMS_VideoSource *FFMS_CreateVideoSource(const char *SourceFile, int Track, FFMS_Index *Index,
	int Threads, int SeekMode, FFMS_ErrorInfo *ErrorInfo)

Creates a FFMS_VideoSource object with the given properties. The FFMS_VideoSource object represents a video stream, and can be passed to other functions to retreive frames and metadata from said stream. The video stream in question must be indexed first (see the indexing functions). Note that the index object is copied into the FFMS_VideoSource object upon its creation, so once you've created the video source you can generally destroy the index object immediately, since all info you can retrieve from it is also retrievable from the FFMS_VideoSource object.

Arguments

const char *SourceFile
The source file to open. Can be an absolute or relative path.

int Track
The track number of the video track to open, as seen by the relevant demuxer. See FFMS_GetNumTracks, FFMS_GetTrackType, FFMS_GetFirstTrackOfType and their variants for further information on how to determine this.

FFMS_Index *Index
A pointer to a FFMS_Index object containing indexing information for the track you want to open.

int Threads
The number of decoding threads to use. Passing funny values like 0 or -1 may lead to undefined behavior so you better sanity check the input if you let the user set this. Values >1 have no effect if ffmpeg was not compiled with threading support.

int SeekMode
Controls how seeking (random access) is handled and hence affects frame accuracy. You will almost always want to use FFMS_SEEK_NORMAL. Has no effect on Matroska files, where the equivalent of FFMS_SEEK_NORMAL is always used. For a list of valid values, see the Constants and Preprocessor Definitions section.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns a pointer to the created FFMS_VideoSource object on success. Returns NULL and sets ErrorMsg on failure.

FFMS_CreateAudioSource - creates an audio source object

FFMS_AudioSource *FFMS_CreateAudioSource(const char *SourceFile, int Track, FFMS_Index *Index,
	FFMS_ErrorInfo *ErrorInfo)

Does exactly the same thing as FFMS_CreateVideoSource, but for audio tracks. Arguments and return values are identical. Do note that audio support is somewhat experimental and not guaranteed to be sample-accurate.

FFMS_DestroyVideoSource, FFMS_DestroyAudioSource - deallocates a video or audio source object

void FFMS_DestroyVideoSource(FFMS_VideoSource *V)
void FFMS_DestroyAudioSource(FFMS_AudioSource *A)

Deallocates the given FFMS_VideoSource or FFMS_AudioSource object and frees the memory allocated by FFMS_CreateVideoSource or FFMS_CreateAudioSource, respectively.

FFMS_GetVideoProperties - retrieves video properties

const FFMS_VideoProperties *FFMS_GetVideoProperties(FFMS_VideoSource *V)

Retreives the video properties from the given FFMS_VideoSource object and stores them in a FFMS_VideoProperties struct (see the Data Structures section below). Returns a pointer to said struct.

FFMS_GetAudioProperties - retrieves audio properties

const FFMS_AudioProperties *FFMS_GetAudioProperties(FFMS_AudioSource *A)

Does the exact same thing as FFMS_GetVideoProperties, but for an FFMS_AudioSource object.

FFMS_GetFrame - retrieves a given video frame

const FFMS_Frame *FFMS_GetFrame(FFMS_VideoSource *V, int n, FFMS_ErrorInfo *ErrorInfo)

Gets and decodes a video frame from the video stream represented by the given FFMS_VideoSource object and stores it in a FFMS_Frame struct. The colorspace and resolution of the frame can be changed by calling FFMS_SetOutputFormatV with the appropriate parameters before calling this function. Note that this function is not threadsafe (you can only request one frame at a time from a given FFMS_VideoSource object) and that the returned pointer to the FFMS_Frame is a const pointer.

Arguments

FFMS_VideoSource *V
A pointer to the FFMS_VideoSource object that represents the video stream you want to retrieve a frame from.

int n
The frame number to get. Frame numbering starts from zero, and hence the first frame is number 0 (not 1) and the last frame is number FFMS_VideoProperties->NumFrames minus 1. Requesting a frame number beyond the stream end or before the stream start (i.e. negative) may cause undefined behavior.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns a pointer to the FFMS_Frame on success. Returns NULL and sets ErrorMsg on failure.

FFMS_GetFrameByTime - retrieves a video frame at a given timestamp

const FFMS_Frame *FFMS_GetFrameByTime(FFMS_VideoSource *V, double Time, FFMS_ErrorInfo *ErrorInfo)

Does the exact same thing as FFMS_GetFrame except instead of giving it a frame number you give it a timestamp in milliseconds, and it will retrieve the frame that starts closest to that timestamp. This function exists for the people who are too lazy to build and traverse a mapping between frame numbers and timestamps themselves. Note that it is measurably slower than FFMS_GetFrame.

FFMS_GetAudio - decodes a number of audio samples

int FFMS_GetAudio(FFMS_AudioSource *A, void *Buf, int64_t Start, int64_t Count, FFMS_ErrorInfo *ErrorInfo)

Decodes the requested audio samples from the audio stream represented by the given FFMS_AudioSource object and stores them in the given buffer. Note that this function is not threadsafe; you can only request one decoding operation at a time from a given FFMS_AudioSource object.

Arguments

FFMS_AudioSource *A
A pointer to the FFMS_AudioSource object that represents the audio stream you want to get samples from.

void *Buf
A pointer to the buffer where the decoded samples will end up. You are responsible for allocating and freeing this buffer yourself, so you better check the FFMS_AudioProperties for the sample format, number of channels, channel layout etc first, so you know how much memory you need to allocate. The formula to calculate the required size of the buffer is (obviously) num_bytes = bytes_per_sample * num_channels * num_samples.

int64_t Start, int64_t Count
The range of samples you want decoded. The output is Count samples long, starting from Start (inclusive). Like video frame numbers, sample numbers start from zero and hence the last sample in the stream is number FFMS_AudioProperties->NumSamples minus 1. Requesting samples beyond the stream end or before the stream start may result in undefined behavior.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns 0 on success. Returns non-0 and sets ErrorMsg on failure.

FFMS_SetOutputFormatV - sets the output format for video frames

int FFMS_SetOutputFormatV(FFMS_VideoSource *V, int64_t TargetFormats, int Width, int Height, int Resizer,
	FFMS_ErrorInfo *ErrorInfo)

Sets the colorspace and frame dimensions to be used for output of frames from the given FFMS_VideoSource by all further calls to FFMS_GetFrame and FFMS_GetFrameByTime, until next time you call FFMS_SetOutputFormatV or FFMS_ResetOutputFormatV. You can change the output format at any time without having to reinitialize the FFMS_VideoSource object or anything else. Can be used to convert the video to grayscale or monochrome if you are so inclined. If you provided a list of more than one colorspace/pixelformat, you should probably check the FFMS_Frame properties afterwards to see which one got selected.

Arguments

FFMS_VideoSource *V
A pointer to the FFMS_VideoSource object that represents the video stream you want to change the output format for.

int64_t TargetFormats
The desired output colorspace(s). You may binary OR several colorspaces you are willing to accept together; the function will then choose the colorspace that gives the least lossy conversion from the source colorspace. To get the integer constant representing a given colorspace, see FFMS_GetPixFmt. Once you have the integer constant(s), shift 1 left by each constant to get the value suitable for passing as this argument. Example:
int64_t targetformats = (1 << pixfmt1) | (1 << pixfmt2) | (1 << pixfmt3);

int Width, int Height
The desired image dimensions, in pixels. If you do not want to resize just pass the input dimensions. Passing invalid dimensions (like 0 or negative) has undefined behavior.

int Resizer
The desired image resizing algorithm, represented by an integer as enumerated in FFMS_Resizers (see the Constants and Preprocessor Definitions section). You must choose one even if you're not actually rescaling the image, because the video may change resolution mid-stream and then you will be using a resizer whether you want it or not (you will only know that the resolution changed after you actually decoded a frame with a new resolution), and it may also get used for rescaling subsampled chroma planes.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns 0 on success. Returns non-0 and sets ErrorMsg on failure.

FFMS_ResetOutputFormatV - resets the video output format

void FFMS_ResetOutputFormatV(FFMS_VideoSource *V)

Resets the output format for the given FFMS_VideoSource object so that no conversion takes place. Note that the results of this function may vary wildly, particularly if the video changes resolution mid-stream. If you call it, you'd better call FFMS_GetFrame afterwards and examine the properties to see what you actually ended up with.

FFMS_SetPP - sets postprocessing options

int FFMS_SetPP(FFMS_VideoSource *V, const char *PP, FFMS_ErrorInfo *ErrorInfo)

Sets the postprocessing filter chain that will be applied to frames retrieved from the given FFMS_VideoSource object by all further calls to FFMS_GetFrame and FFMS_GetFrameByTime until the next call to FFMS_SetPP or FFMS_ResetPP. The filter chain is described by a text string; see the PP string format section below for details.

Arguments

FFMS_VideoSource *V
A pointer to the FFMS_VideoSource object that represents the video stream you want to change the postprocessing settings for.

const char *PP
A string describing the desired postprocessing. See the PP string format section below for details. Pass NULL or an empty string to disable postprocessing.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns 0 on success. Returns non-0 and sets ErrorMsg on failure.

FFMS_ResetPP - resets postprocessing options

void FFMS_ResetPP(FFMS_VideoSource *V)

Resets the postprocessing filter chain that will be applied to frames retrieved from the given FFMS_VideoSource object by all further calls to FFMS_GetFrame and FFMS_GetFrameByTime until the next call to FFMS_SetPP or FFMS_ResetPP so that no postprocessing will be applied. Is equivalent to FFMS_SetPP(VideoSource, NULL, ErrorInfo) but is more efficient.

FFMS_DestroyIndex - deallocates an index object

void FFMS_DestroyFFMS_Index(FFMS_Index *Index)

Deallocates the given FFMS_Index object and frees the memory that was allocated when it was created.

FFMS_GetSourceType - gets which source module was used to open the given index

int FFMS_GetSourceType(FFMS_Index *Index)

Checks which source module (libavformat, Haali's Matroska parsing library, or Haali's DirectShow splitter) was used when opening the file represented by the given FFMS_Index and returns an integer (as enumerated in FFMS_Sources; see the Constants and Preprocessor Definitions section below) that represents it.

FFMS_GetFirstTrackOfType - gets the track number of the first track of a given type

int FFMS_GetFirstTrackOfType(FFMS_Index *Index, int TrackType, FFMS_ErrorInfo *ErrorInfo)

Finds the first track of the given FFMS_TrackType in the given FFMS_Index and returns its track number, suitable for use as an argument to FFMS_CreateVideoSource or FFMS_CreateAudioSource, as well as to some other functions.

Arguments

FFMS_Index *Index
A pointer to the FFMS_Index object that represents the media file you want to look for tracks in.

int TrackType
The track type to look for. See FFMS_TrackType in the Constants and Preprocessor Definitions" section for valid values.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns the track number (an integer greater than or equal to 0) on success. Returns a negative integer and sets ErrorMsg on failure (i.e. if no track of the given type was found).

FFMS_GetFirstIndexedTrackOfType - gets the track number of the first track of a given type

int FFMS_GetFirstIndexedTrackOfType(FFMS_Index *Index, int TrackType, FFMS_ErrorInfo *ErrorInfo)

Does the exact same thing as FFMS_GetFirstTrackOfType but ignores tracks that have not been indexed.

FFMS_GetNumTracks - gets the number of tracks in a given index

int FFMS_GetNumTracks(FFMS_Index *Index)

Returns the total number of tracks in the media file represented by the given FFMS_Index.

FFMS_GetNumTracksI - gets the number of tracks in a given indexer

int FFMS_GetNumTracksI(FFMS_Indexer *Indexer)

Returns the total number of tracks in the media file represented by the given FFMS_Indexer. In other words, does the same thing as FFMS_GetNumTracks but does not require indexing the entire file first.

FFMS_GetTrackType - gets the track type of a given track

int FFMS_GetTrackType(FFTrack *T)

Returns an integer representing the FFMS_TrackType (see the Constants and Preprocessor Definitions section) of the track represented by the given FFTrack object.

FFMS_GetTrackTypeI - gets the track type of a given track

int FFMS_GetTrackTypeI(FFMS_Indexer *Indexer, int Track)

Returns an integer representing the FFMS_TrackType (see the Constants and Preprocessor Definitions section) of the track number Track in the media file represented by the given FFMS_Indexer. In other words, does the same thing as FFMS_GetTrackType, but does not require having indexed the file first. If you have indexed the file, use FFMS_GetTrackType instead since the FFMS_Indexer object is destructed when the index is created. Note that specifying an invalid track number may lead to undefined behavior.

FFMS_GetCodecNameI - gets the name of the codec used for a given track

const char *FFMS_GetCodecNameI(FFMS_Indexer *Indexer, int Track)

Returns the human-readable name ("long name" in ffmpeg terms) of the codec used in the given track number in the media file represented by the given FFMS_Indexer object. Useful if you want to, say, pop up a menu asking the user which tracks he or she wishes to index. Note that specifying an invalid track number may lead to undefined behavior.

FFMS_GetNumFrames - gets the number of frames in a given track

int FFMS_GetNumFrames(FFTrack *T)

Returns the number of frames in the track represented by the given FFTrack. For a video track this is the number of video frames, which can be useful; for an audio track it's the number of packets, which is almost never useful, since nothing in the API exposes those. A return value of 0 indicates the track has not been indexed.

FFMS_GetFrameInfo - gets information about a given frame

const FFMS_FrameInfo *FFMS_GetFrameInfo(FFTrack *T, int Frame)

Gets information about the given frame (identified by its frame number) from the indexing information in the given FFTrack and stores it in a FFMS_FrameInfo struct. See the Data Structures section below for more information. Using this function on a FFTrack representing a non-video track has undefined behavior.

Arguments

FFTrack *T
A pointer to the FFTrack object that represents the video track containing the frame you want to get information about.

int Frame
The frame number to get information about. See FFMS_GetFrame for information about frame numbers. Requesting information about a frame before the start or after the end of the video track may result in undefined behavior, so don't do that.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns a pointer to the FFMS_FrameInfo struct on success. Returns NULL and sets ErrorMsg on failure.

FFMS_GetTrackFromIndex - retrieves track info from an index

FFTrack *FFMS_GetTrackFromIndex(FFMS_Index *Index, int Track)

Gets track data for the given track number from the given FFMS_Index object, stores it in a FFTrack object and returns a pointer to it. Use this function if you don't want to (or cannot) open the track with FFMS_CreateVideoSource or FFMS_CreateAudioSource first. If you already have a FFMS_VideoSource or FFMS_AudioSource object it's safer to use FFMS_GetTrackFromVideo or FFMS_GetTrackFromAudio (see below) instead. Note that specifying a nonexistent or invalid track number leads to undefined behavior (usually an access violation). Also note that the returned FFTrack object is only valid until its parent FFMS_Index object is destroyed.

Arguments

FFMS_Index *Index
A pointer to the FFMS_Index object that represents the media file containing the track whose index information you want to get.

int Track
The track number, as seen by the relevant demuxer (see FFMS_GetNumTracks, FFMS_GetTrackType, FFMS_GetFirstTrackOfType and their variants).

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns the FFTrack on success. Note that requesting indexing information for a track that has not been indexed will not cause an error, it will just return an empty FFTrack (check for >0 frames using FFMS_GetNumFrames to see if the returned object actually contains indexing information).

FFMS_GetTrackFromVideo, FFMS_GetTrackFromAudio - retrieves track info from audio or video source

FFTrack *FFMS_GetTrackFromVideo(FFMS_VideoSource *V)
FFTrack *FFMS_GetTrackFromAudio(FFMS_AudioSource *A)

Gets information about the track represented by the given FFMS_VideoSource or FFMS_AudioSource object and returns a pointer to a FFTrack object containing said information. It's generally safer to use these functions instead of FFMS_GetTrackFromIndex, since unlike that function they cannot cause access violations if you specified an nonexistent tracknumber, return a FFTrack that doesn't actually contain any indexing information, or return an object that ceases to be valid when the index is destroyed. Note that the returned FFTrack object is only valid until its parent FFMS_VideoSource or FFMS_AudioSource object is destroyed.

FFMS_GetTimeBase - retrieves the time base for the given track

const FFMS_TrackTimeBase *FFMS_GetTimeBase(FFTrack *T)

Finds the basic time unit for the track represented by the given FFTrack, stores it in a FFMS_TrackTimeBase struct and returns a pointer to said struct. See the Data Structures section for information about the time base; note that it is only meaningful for video tracks.

FFMS_WriteTimecodes - writes timecodes for the given track to disk

int FFMS_WriteTimecodes(FFTrack *T, const char *TimecodeFile, FFMS_ErrorInfo *ErrorInfo)

Writes Matroska v2 timecodes for the track represented by the given FFTrack to the given file. Only meaningful for video tracks.

Arguments

FFTrack *T
A pointer to the FFTrack object that represents the video track you want to write timecodes for.

const char *TimecodeFile
The filename to write to. Can be a relative or absolute path. The file will be truncated and overwritten if it already exists.

FFMS_ErrorInfo *ErrorInfo
See above.

Return values

Returns 0 on success. Returns non-0 and sets ErrorMsg on failure.

FFMS_MakeIndex - indexes a given source file

FFMS_Index *FFMS_MakeIndex(const char *SourceFile, int IndexMask, int DumpMask,
	TAudioNameCallback ANC, void *ANCPrivate, bool IgnoreDecodeErrors, TIndexCallback IC, void *ICPrivate,
	FFMS_ErrorInfo *ErrorInfo)

Indexes all video tracks and the given audio tracks in the given media file and returns a FFMS_Index object representing the file in question. Can also decode and write audio tracks to Wave64 files on disk while indexing.

Arguments

const char *SourceFile
The filename of the media file to index. Can be a relative or absolute path.

int IndexMask, int DumpMask
Binary masks of the track numbers of the audio tracks to index and decode to disk, respectively. Pass 0 to index/decode no audio tracks, or -1 to index/decode all. Decoding a track means it will automatically be indexed regardless of what the IndexMask says, but indexing a track does not automatically mean that it will be decoded.

TAudioNameCallback ANC
A function pointer to a callback function that will generate the filename(s) for the dumped audio tracks. To get the default filename(s), pass &FFMS_DefaultAudioFilename. See Callbacks below for details if you want to write your own function. If the DumpMask is 0, you may pass NULL here.

void *ANCPrivate
A pointer of your choice that will be passed as an argument to the audio filename generation callback function. See Callbacks below for details. If DumpMask is 0, you may pass NULL here. If you are using FFMS_DefaultAudioFilename, you must pass a format string here. See the Audio Filename Format Strings section for details.

bool IgnoreDecodeErrors
If true, audio decoding errors will not cause indexing to fail. Tracks that cannot be decoded will not be indexed, however. Has no effect if the DumpMask is non-zero, in which case audio decoding errors will always cause the indexing to fail.

TIndexCallback IC
A function pointer to a callback function that can be used to update progress. See Callbacks below for details.

void *ICPrivate
A pointer of your choice that will be passed as an argument to the progress reporting callback function. See Callbacks below for details.

FFMS_ErrorInfo *ErrorInfo
See above.

Callbacks

This function has two potential callbacks. One can, if you so desire, call your code back intermittently so you can see how the indexing is progressing. This is accomplished using a function pointer to a function with the following signature: 

int FFMS_CC FunctionName(int64_t Current, int64_t Total, void *ICPrivate)

The callback function's arguments are as follows:

Return 0 from the callback function to continue indexing, non-0 to cancel indexing (returning non-0 will make FFMS_MakeIndex fail with the reason "indexing cancelled by user").

The other callback is used to generate the filename(s) of the audio file(s) written if DumpMask is non-zero. It has the following signature: 

int FFMS_CC FunctionName(const char *SourceFile, int Track, const FFMS_AudioProperties *AP,
	char *FileName, int FNSize, void *Private)

The callback function is called twice for each audio file generated. The first time FileName is NULL, and you should return the number of characters your generated filename will use plus one, and do nothing else. The second time FileName is a pointer to a pre-allocated array of char; you should write your generated filename to that and return the number of characters actually written plus one. Generally the easiest way to do this in both cases is to use snprintf. See the implementation of GenAudioFilename in ffmsindex.cpp for an example on how to do it.
The callback function's arguments are as follows:

Most of the parameters may seem pointless since you don't need to use them, but they are passed so that you can easily generate a filename based on the audio track's properties if you want to.

Return values

Returns a pointer to the created FFMS_Index on success. Returns NULL and sets ErrorMsg on failure.

FFMS_DefaultAudioFilename - default callback for audio filename generation

This function generates a default audio filename for use when dumping audio tracks to disk as Wave64 files during indexing. Its only use in the public API is as a default callback for FFMS_MakeIndex and FFMS_DoIndexing; you should never call it directly. See FFMS_MakeIndex for a description of its arguments.

FFMS_CreateIndexer - creates an indexer object for the given file

FFMS_Indexer *FFMS_CreateIndexer(const char *SourceFile, FFMS_ErrorInfo *ErrorInfo)

Creates a FFMS_Indexer object for the given SourceFile and returns a pointer to it. See Indexing and You for details on how to use the indexer.

Return values

Returns a pointer to the FFMS_Indexer on success. Returns NULL and sets ErrorMsg on failure.

FFMS_DoIndexing - indexes the file represented by an indexer object

FFMS_Index *FFMS_DoIndexing(FFMS_Indexer *Indexer, int IndexMask, int DumpMask,
	TAudioNameCallback ANC, void *ANCPrivate, bool IgnoreDecodeErrors, TIndexCallback IC, void *ICPrivate,
	FFMS_ErrorInfo *ErrorInfo)

Does the exact same thing as FFMS_MakeIndex, but takes an indexer object instead of a source filename. Return values and arguments are identical to FFMS_MakeIndex; see that function for details. See the Indexing and You section for more details about indexing. Note that calling this function destroys the FFMS_Indexer object and frees the memory allocated by FFMS_CreateIndexer.

FFMS_CancelIndexing - destroys the given indexer object

void FFMS_CancelIndexing(FFMS_Indexer *Indexer)

Destroys the given FFMS_Indexer object and frees the memory allocated by FFMS_CreateIndexer.

FFMS_ReadIndex - reads an index file from disk

FFMS_Index *FFMS_ReadIndex(const char *IndexFile, FFMS_ErrorInfo *ErrorInfo)

Attempts to read indexing information from the given IndexFile, which can be an absolute or relative path. Returns the FFMS_Index on success; returns NULL and sets ErrorMsg on failure.

FFMS_IndexBelongsToFile - check if a given index belongs to a given file

int FFMS_IndexBelongsToFile(FFMS_Index *Index, const char *SourceFile, FFMS_ErrorInfo *ErrorInfo)

Makes a heuristic (but very reliable) guess about whether the given FFMS_Index is an index of the given SourceFile or not. Useful to determine if the index object you just read with FFMS_ReadIndex is actually relevant to your interests, since the only two ways to pair up index files with source files are a) trust the user blindly, or b) comparing the filenames; neither is very reliable.

Arguments

FFMS_Index *Index
The index object to check.

const char *SourceFile
The source file to verify the index against.

Return values

Returns 0 if the given index is determined to belong to the given file. Returns non-0 and sets ErrorMsg otherwise.

FFMS_WriteIndex - writes an index object to disk

int FFMS_WriteIndex(const char *IndexFile, FFMS_Index *TrackIndices, FFMS_ErrorInfo *ErrorInfo)

Writes the indexing information from the given FFMS_Index to the given IndexFile (which can be an absolute or relative path; it will be truncated and overwritten if it already exists). Returns 0 on success; returns non-0 and sets ErrorMsg on failure.

FFMS_GetPixFmt - gets a colorspace identifier from a colorspace name

int FFMS_GetPixFmt(const char *Name)

Translates a given colorspace/pixel format Name to an integer constant representing it, suitable for passing to FFMS_SetOutputFormatV (after some manipulation, see that function for details). This function exists so that you don't have to include a ffmpeg header file in every single program you ever write. For a list of colorspaces and their names, see libavutil/pixfmt.h. To get the name of a colorspace, strip the leading PIX_FMT_ and convert the remainder to lowercase. For example, the name of PIX_FMT_YUV420P is yuv420p. It is strongly recommended to use this function instead of including pixfmt.h directly, since this function guarantees that you will always get the constant definitions from the version of ffmpeg that FFMS2 was linked against.

Arguments

const char *Name
The name of the desired colorspace/pixel format, as a nul-terminated ASCII string.

Return values

Returns the integer constant representing the given colorspace/pixel format on success. Returns the integer constant representing PIX_FMT_NONE (that is, -1) on failure (i.e. if no matching colorspace was found), but note that you can call FFMS_GetPixFmt("none") and get the same return value without it being a failed call, strictly speaking.

FFMS_GetPresentSources - checks what source modules the library was compiled with

int FFMS_GetPresentSources()

Checks which source modules the library was compiled with and returns an integer by binary OR'ing the relevant constants from FFMS_Sources together.

FFMS_GetEnabledSources - checks what source modules are actually available for use

int FFMS_GetEnabledSources()

Does the same thing as FFMS_GetPresentSources but checks what source modules are actually available for use instead of which ones are compiled in.

Data Structures

The following public data structures may be of interest.

FFMS_Frame

typedef struct {
	uint8_t *Data[4];
	int Linesize[4];
	int EncodedWidth;
	int EncodedHeight;
	int EncodedPixelFormat;
	int ScaledWidth;
	int ScaledHeight;
	int ConvertedPixelFormat;
	int KeyFrame;
	int RepeatPict;
	int InterlacedFrame;
	int TopFieldFirst;
	char PictType;
} FFMS_Frame;

A struct representing a video frame. The fields are:

FFMS_TrackTimeBase

typedef struct {
	int64_t Num;
	int64_t Den;
} FFMS_TrackTimeBase;

A struct representing the basic time unit of a track, as a rational number where Num is the numerator and Den is the denominator. Note that while this rational number may occasionally turn out to be equal to 1/framerate for some CFR video tracks, it really has no relation whatsoever with the video framerate and you should definitely not assume anything framerate-related based on it.

FFMS_FrameInfo

typedef struct {
	int64_t PTS;
	int RepeatPict;
	int KeyFrame;
} FFMS_FrameInfo;

A struct representing basic metadata about a given video frame. The fields are:

FFMS_VideoProperties

typedef struct {
	int FPSDenominator;
	int FPSNumerator;
	int RFFDenominator;
	int RFFNumerator;
	int NumFrames;
	int SARNum;
	int SARDen;
	int CropTop;
	int CropBottom;
	int CropLeft;
	int CropRight;
	int TopFieldFirst;
	int ColorSpace;
	int ColorRange;
	double FirstTime;
	double LastTime;
} FFMS_VideoProperties;

A struct containing metadata about a video track. The fields are:

FFMS_AudioProperties

typedef struct {
	int SampleFormat;
	int SampleRate;
	int BitsPerSample;
	int Channels;
	int64_t ChannelLayout;
	int64_t NumSamples;
	double FirstTime;
	double LastTime;
} FFMS_AudioProperties;

A struct containing metadata about an audio track. The fields are:

Constants and Preprocessor Definitions

The following constants and preprocessor definititions defined in ffms.h are suitable for public usage.

FFMS_Errors

enum FFMS_Errors {
	// No error
	FFMS_ERROR_SUCCESS = 0,

	// Main types - where the error occurred
	FFMS_ERROR_INDEX = 1,
	FFMS_ERROR_INDEXING,
	FFMS_ERROR_POSTPROCESSING,
	FFMS_ERROR_SCALING,
	FFMS_ERROR_DECODING,
	FFMS_ERROR_SEEKING,
	FFMS_ERROR_PARSER,
	FFMS_ERROR_TRACK,
	FFMS_ERROR_WAVE_WRITER,
	FFMS_ERROR_CANCELLED,

	// Subtypes - what caused the error
	FFMS_ERROR_UNKNOWN = 20,
	FFMS_ERROR_UNSUPPORTED,
	FFMS_ERROR_FILE_READ,
	FFMS_ERROR_FILE_WRITE,
	FFMS_ERROR_NO_FILE,
	FFMS_ERROR_VERSION,
	FFMS_ERROR_ALLOCATION_FAILED,
	FFMS_ERROR_INVALID_ARGUMENT,
	FFMS_ERROR_CODEC,
	FFMS_ERROR_NOT_AVAILABLE,
	FFMS_ERROR_FILE_MISMATCH,
	FFMS_ERROR_USER
};

Used to identify errors. Should be self-explanatory.

FFMS_Sources

enum FFMS_Sources {
	FFMS_SOURCE_LAVF		= 0x01,
	FFMS_SOURCE_MATROSKA	= 0x02,
	FFMS_SOURCE_HAALIMPEG	= 0x04,
	FFMS_SOURCE_HAALIOGG	= 0x08
};

Identifies source modules.

FFMS_CPUFeatures

enum FFMS_CPUFeatures {
	FFMS_CPU_CAPS_MMX       = 0x01,
	FFMS_CPU_CAPS_MMX2      = 0x02,
	FFMS_CPU_CAPS_3DNOW     = 0x04,
	FFMS_CPU_CAPS_ALTIVEC   = 0x08,
	FFMS_CPU_CAPS_BFIN      = 0x10
};

Used in FFMS_Init to indicate CPU instruction set capabilities. Should be self explanatory. For a lot of applications you can probably get away with simply hardcoding in FFMS_CPU_CAPS_MMX | FFMS_CPU_CAPS_MMX2 in the call to FFMS_Init.

FFMS_SeekMode

enum FFMS_SeekMode {
	FFMS_SEEK_LINEAR_NO_RW  = -1,
	FFMS_SEEK_LINEAR        = 0,
	FFMS_SEEK_NORMAL        = 1,
	FFMS_SEEK_UNSAFE        = 2,
	FFMS_SEEK_AGGRESSIVE    = 3
};

Used in FFMS_CreateVideoSource to control the way seeking is handled. Explanation of the values:

FFMS_IndexErrorHandling

enum FFMS_IndexErrorHandling {
	FFMS_IEH_ABORT = 0,
	FFMS_IEH_CLEAR_TRACK = 1,
	FFMS_IEH_STOP_TRACK = 2,
	FFMS_IEH_IGNORE = 3
};

Used by the indexing functions to control behavior when a decoding error is encountered.

FFMS_TrackType

enum FFMS_TrackType {
	FFMS_TYPE_UNKNOWN = -1,
	FFMS_TYPE_VIDEO,
	FFMS_TYPE_AUDIO,
	FFMS_TYPE_DATA,
	FFMS_TYPE_SUBTITLE,
	FFMS_TYPE_ATTACHMENT
};

Used for determining the type of a given track. Note that there are currently no functions to handle any type of track other than FFMS_TYPE_VIDEO and FFMS_TYPE_AUDIO. See FFMS_GetTrackType, FFMS_GetFirstTrackOfType and their variants.

FFMS_SampleFormat

enum FFMS_SampleFormat {
    FFMS_FMT_U8 = 0,
    FFMS_FMT_S16,
    FFMS_FMT_S32,
    FFMS_FMT_FLT,
    FFMS_FMT_DBL
};

Identifies various audio sample formats.

FFMS_AudioChannel

enum FFMS_AudioChannel {
	FFMS_CH_FRONT_LEFT              = 0x00000001,
	FFMS_CH_FRONT_RIGHT             = 0x00000002,
	FFMS_CH_FRONT_CENTER            = 0x00000004,
	FFMS_CH_LOW_FREQUENCY           = 0x00000008,
	FFMS_CH_BACK_LEFT               = 0x00000010,
	FFMS_CH_BACK_RIGHT              = 0x00000020,
	FFMS_CH_FRONT_LEFT_OF_CENTER    = 0x00000040,
	FFMS_CH_FRONT_RIGHT_OF_CENTER   = 0x00000080,
	FFMS_CH_BACK_CENTER             = 0x00000100,
	FFMS_CH_SIDE_LEFT               = 0x00000200,
	FFMS_CH_SIDE_RIGHT              = 0x00000400,
	FFMS_CH_TOP_CENTER              = 0x00000800,
	FFMS_CH_TOP_FRONT_LEFT          = 0x00001000,
	FFMS_CH_TOP_FRONT_CENTER        = 0x00002000,
	FFMS_CH_TOP_FRONT_RIGHT         = 0x00004000,
	FFMS_CH_TOP_BACK_LEFT           = 0x00008000,
	FFMS_CH_TOP_BACK_CENTER         = 0x00010000,
	FFMS_CH_TOP_BACK_RIGHT          = 0x00020000,
	FFMS_CH_STEREO_LEFT             = 0x20000000,
	FFMS_CH_STEREO_RIGHT            = 0x40000000
};

Describes various audio channel configurations. The names should be self-explanatory. The actual order if FFmpeg dictated and may vary.

FFMS_Resizers

enum FFMS_Resizers {
    FFMS_RESIZER_FAST_BILINEAR  = 0x01,
    FFMS_RESIZER_BILINEAR       = 0x02,
    FFMS_RESIZER_BICUBIC        = 0x04,
    FFMS_RESIZER_X              = 0x08,
    FFMS_RESIZER_POINT          = 0x10,
    FFMS_RESIZER_AREA           = 0x20,
    FFMS_RESIZER_BICUBLIN       = 0x40,
    FFMS_RESIZER_GAUSS          = 0x80,
    FFMS_RESIZER_SINC           = 0x100,
    FFMS_RESIZER_LANCZOS        = 0x200,
    FFMS_RESIZER_SPLINE         = 0x400
};

Describes various image resizing algorithms, as used in the arguments to FFMS_SetOutputFormatV. The names should be self-explanatory.

FFMS_CC

#ifdef _WIN32
#	define FFMS_CC __stdcall
#else
#	define FFMS_CC
#endif

The calling convention used by FFMS2 API functions and callbacks. Defined to __stdcall if _WIN32 is defined. Otherwise defined, but not used.

Picture types

As stored in FFMS_Frame->PictType:

I: Intra
P: Predicted
B: Bi-dir predicted
S: S(GMC)-VOP MPEG4
i: Switching Intra
p: Switching Predicted
b: FF_BI_TYPE (no good explanation available)
?: Unknown

Audio Filename Format Strings

The following variables can be used:

Example string: %sourcefile%_track%trackzn%.w64

PP string format

Available postprocessing filters:
Filters                        Options
short  long name       short   long option     Description
*      *               a       autoq           CPU power dependent enabler
                       c       chrom           chrominance filtering enabled
                       y       nochrom         chrominance filtering disabled
                       n       noluma          luma filtering disabled
hb     hdeblock        (2 threshold)           horizontal deblocking filter
       1. difference factor: default=32, higher -> more deblocking
       2. flatness threshold: default=39, lower -> more deblocking
                       the h & v deblocking filters share these
                       so you can't set different thresholds for h / v
vb     vdeblock        (2 threshold)           vertical deblocking filter
ha     hadeblock       (2 threshold)           horizontal deblocking filter
va     vadeblock       (2 threshold)           vertical deblocking filter
h1     x1hdeblock                              experimental h deblock filter 1
v1     x1vdeblock                              experimental v deblock filter 1
dr     dering                                  deringing filter
al     autolevels                              automatic brightness / contrast
f      fullyrange                              stretch luminance to (0..255)
lb     linblenddeint                           linear blend deinterlacer
li     linipoldeint                            linear interpolating deinterlace
ci     cubicipoldeint                          cubic interpolating deinterlacer
md     mediandeint                             median deinterlacer
fd     ffmpegdeint                             ffmpeg deinterlacer
l5     lowpass5                                FIR lowpass deinterlacer
de     default                                 hb:a,vb:a,dr:a
fa     fast                                    h1:a,v1:a,dr:a
ac                                             ha:a:128:7,va:a,dr:a
tn     tmpnoise        (3 threshold)           temporal noise reducer
                     1. <= 2. <= 3.            larger -> stronger filtering
fq     forceQuant      <quantizer>             force quantizer
Usage:
<filterName>[:<option>[:<option>...]][[,|/][-]<filterName>[:<option>...]]...
long form example:
vdeblock:autoq/hdeblock:autoq/linblenddeint    default,-vdeblock
short form example:
vb:a/hb:a/lb                                   de,-vb
more examples:
tn:64:128:256