matroska.dll

Downlaods

1. By meaning

Opening a file
Closing a file
Retrieving information on a segment
Retrieving information about a Track
Retrieving information about a Chapter
Retrieving an Attachment
Retrieving DLL version information
older stuff

2. By function name

mtrClose
mtrGetAttachment
mtrGetChapterInfo
mtrGetDLLInfo
mtrGetSegmentInfo
mtrGetTrackInfo
mtrOpen

General

Backward compatibility of future versions of this DLL

The interface should be stable now, and it should not be required to make changes that require older applications to be recompiled to work with future versions of the DLL. That means, if anyone wants to make include files for other languages, please go on.

Calling convention

All functions use _stdcall and return MTR_OK to signal that a call succeeded. If an invalid parameter is passed, the return value is MTR_INVALIDPARAM.

Units

All sizes of structures and buffers are indicated in bytes. This also applies to buffers receiving unicode strings.

cbSize

All structures have a member in common: cbSize. This member must be set to the size of the structure, if it does not match, the call fails.

Buffers

All structures that contain a pointer to a buffer (pBuffer) receiving data have a member max_buffer_size which must be set to the size of that buffer. These structures also have a member required_buffer_size which will be set to the size the buffer must have to receive all data the function could return.

Character sets

Structures having a charset member allow the user to specify if the input and/or output strings use ANSI, UTF-8 or UTF-16 encoding (values MTR_ANSI, MTR_UTF8, MTR_UTF16).

Titles

All structures designed to receive titles include the following member values:

number_of_titles	number of titles that could be returned if the buffer was large enough
number_of_titles_returned	number of titles for which at least one character has been returned. If this number is smaller than number_of_titles, the buffer was (far) too small
title_txt	Array of pointers to titles. All pointers will point somewhere into pBuffer
title_lng	Array of pointers to language codes identifying the language the title is written in. If a language is not indicated in the source file, this pointer will either be NULL or point to an empty string.

Opening a file

typedef struct
{
	int	cbSize;
	int	charset;
	int	access;
	char*	filename;	
} OPEN_MATROSKA_FILE_STRUCT;

access	MTROF_READ - open file for reading
filename	name of the file to open, using the character set indicated in charset

Call:

mtrOpen(
  OPEN_MATROSKA_FILE_STRUCT* 	open_file_struct, 
  void** 			matroska
);

open_file_struct	Pointer to a valid OPEN_MATROSKA_FILE_STRUCT struct
matroska	Pointer to a pointer that will receive a pointer to an internal structure of matroska.dll that you'll need each time you want to access the file.

Closing a file

Call:

mtrClose(
  void**	matroska
);

matroska

Pointer to a pointer that was obtained using mtrOpen .

Retrieving DLL version information

Call:

int mtrGetDLLInfo(
  int		info;
  char*         build_date;
);

info	Value indicating what information is to be retrieved: MTRDLL_VERNBR return version number as result of the function call MTRDLL_BUILDDATE return build date of this DLL as string
build_date	buffer to receive the build date. This buffer is never required to be larger than 128 bytes

Retrieving information about a Segment

typedef struct
{
	// input
	int		cbsize;
	int		index;
	int		max_buffer_len;
	int		charset;

	// output
	char*		pBuffer;
	int		required_buffer_len;

	int		flags;
	char*		segment_uid;
	char*		segment_filename;

	char*		next_uid;
	char*		next_filename;

	char*		prev_uid;
	char*		prev_filename;
	char*		segment_family;

	char*		muxing_app;
	char*		writing_app;
	
	int		number_of_titles;
	int		number_of_titles_returned;
	char**		title_txt;
	char**		title_lng;

	int		number_of_chapters;
	int		number_of_tracks;
	int		number_of_attachments;

	__int64		timecode_scale;
	__int64		duration;
	__int64		date;
} GET_SEGMENT_INFO_STRUCT;

index	retrieve information on the index-th segment
flags	This member indicates which values were present in the source file. If the buffer was too small, some may not have been returned. The following flags are defined: GSISF_SEGMENTUIDGSISF_NEXTUID GSISF_PREVUID GSISF_SEGMENTFAMILY GSISF_MUXINGAPP GSISF_WRITINGAPP GSISF_DATE A flag not being set means the corresponding member is undefined
_uid, _filename	Pointer to the corresponding UID and filenames as stored in the segment.
*_app	Pointer to muxing and writing app as stored in the matroska files. Those strings are usually present.
number_*	Contains the number of chapters (or better: editions), attachments and tracks the segment contains.
timecode_scale	Contains the value all scaled timecodes must be multiplied with to get nanoseconds.
duration	Contains the scaled duration of the segment.
date	Production date, timecode in nanoseconds relative to 2001-01-01, 12am earth standard time.

Call:

mtrGetSegmentInfo(
  void* 			matroska
  GET_SEGMENT_INFO_STRUCT* 	segment_info_struct, 
);

segment_info_struct	Pointer to a valid GET_SEGMENT_INFO_STRUCT struct
matroska	Pointer retrieved by mtrOpen

Retrieving information about a Track

typedef struct
{
	// input
	int		cbsize;
	int		index;
	int		max_buffer_len;
	int		charset;

	// output
	char*		pBuffer;

	int		flags;
	int		required_buffer_size;
	double		bitrate;

	int		track_number;
	__int64		track_uid;
	int		track_type;
	int		flag_enabled;
	int		flag_default;
	int		flag_forced;
	int		flag_lacing;

	int		min_cache;
	int		max_cache;
	__int64		default_duration;
	double		timecode_scale;

	int		number_of_titles;
	int		number_of_titles_returned;
	char**		title_txt;
	char**		title_lng;

	char*		codec_id;
	void*		codec_private;
	int		codec_private_size;
	char*		codec_name;

	__int64		attachment_link;
	__int64		track_overlay;

	int		pixel_width;
	int		pixel_height;
	int		pixel_crop_left;
	int		pixel_crop_top;
	int		pixel_crop_right;
	int		pixel_crop_bottom;

	int		display_width;
	int		display_height;
	int		display_unit;

	int		aspect_ratio_type;
	__int32		color_space;

	double		sampling_frequency;
	double		output_sampling_frequency;
	int		channels;

	int		compression;
	int		compression_settings_length;
	char*		compression_settings;

} GET_TRACK_INFO_STRUCT;

index	retrieve information on the index-th track of the segment (1st track -> index = 0)
flags	This member indicates which values were present in the source file. If the buffer was too small, some may not have been returned. The following flags are defined: GTISF_BITRATE A flag not being set means the corresponding member is undefined
bitrate	contains the bitrate of the track if the segment contains a tag stating this bitrate. The DLL will NOT start reading into the segment in order to get an estimation of the track's bitrate. If such a tag is not present, the GTISF_BITRATE flag is not set and this value is undefined.
track_uid	UID of the track, usually 32 or 64 bits
track_number	Number of the track, usually one-based increasing (note: the index is zero-based)
track_type	Can be MTR_TRACKTYPE_VIDEO MTR_TRACKTYPE_AUDIO MTR_TRACKTYPE_SUBTITLES
flag_*	Conains the flags as specified in the track header. Those flags are returned as they are, they are not auto-corrected or otherwise changed if they are nonsense (p.e. if 2 video tracks are marked as default)
default_duration	Duration of one frame of this track in nanoseconds. For VFR tracks, this value will be 0
timecode_scale	Factor by which timecodes of this track are to be multiplied. This value will usually be one, as the code the DLL is based on already performs this multiplication before delivering any data. This member is only there in order to avoid a change of this structure in the case that this behaviour is changed.
codec_id	Points to a string describing the codec used for this track.
codec_private codec_private_size	Pointer to the CodecPrivate data of this track and size of CodecPrivate.
codec_name	A human readable name of the codec. At the moment, this is rarely used.
pixel_width pixel_height	the resolution the video track is encoded in.
pixel_crop_*	number of pixels to be cropped during replay. This is applied after decoding, but before changing aspect ratio
display_width display_height display_unit	the size the picture is to be stretched to during replay
sampling_frequency output_sampling_frequency	The sampling rate the stream is encoded at, and the sampling rate it is to be replayed at. Those values are identical for most audio codecs, the only acception currently being HE-AAC. Note: In a matroska file, the second value is usually not stored if it does not differ from the first one. This is of no importance for this DLL, both values will always be returned.
compression	Inidicates what compression algorithm has been used for this track. Note: Theoretically, Matroska allows to use several compression algorithms one after another on the same track. This is not supported by this DLL, neither by the underlying code.
compression_settings compression_settings_length	Like codec_private and codec_private_size, but for the lossless compressor used for this track.

Call:

mtrGetTrackInfo(
  void* 			matroska
  GET_TRACK_INFO_STRUCT* 	track_info_struct 
);

track_info_struct	Pointer to a valid GET_TRACK_INFO_STRUCT struct
matroska	Pointer retrieved by mtrOpen

Retrieving information about a Chapter

typedef struct
{
	// input
	int		cbSize;

	int*		pIndex;
	int		max_buffer_len;
	int		charset;

	// output
	char*		pBuffer;

	int		error;
	int		is_edition;
	int		is_enabled;
	int		is_hidden;
	int		is_ordered;
	int		is_default;
	int		has_segmentuid;

	__int64		start_time;
	__int64		end_time;

	int		number_of_titles;
	int		number_of_titles_returned;
	char**		title_txt;
	char**		title_lng;

	int		number_of_subchapters;
	int		required_buffer_size;
	unsigned char*  pSegmentUID;
} GET_CHAPTER_STRUCT;

pIndex	Pointer to an array describing the index of the chapter. The first element contains the number of valid values. Example: [3, 2, 5, 1] refers to chapter 2.5.1. If an invalid chapter is indicated, the return value will be MTR_OK , but the error member will be MTRCHI_INVALIDINDEX
is_*	Those values are one if the chapter has the property in question, i.e. is hidden, is an edition etc.
has_segmentuid pSegmentUID	When this value is not zero, pSegmentUID is valid and points to an array of 16 bytes containing the UID of the segment this chapter is refering to.
start_time end_time	Unscaled time when the chapter starts and ends. If the end time is not indicated in the source file, the end_time member is set to -1.
number_of_subchapters	contains the number of subchapters this chapter has.

Call:

mtrGetChapter(
  void* 		matroska
  GET_CHAPTER_STRUCT* 	chapter_struct, 
);

chapter_struct	Pointer to a valid GET_CHAPTER_STRUCT struct
matroska	Pointer retrieved by mtrOpen

Retrieving an Attachment

typedef struct
{
	// input
	int		cbsize;
	int		index;  
	int		max_buffer_len;
	int		charset;

	// input/output
	__int64		uid;

	// output
	char*		pBuffer;

	char*		filename;
	char*		description;
	char*		mime_type;
	char*		binary_data;
	int		binary_data_size;

	int		required_buffer_size;
} GET_ATTACHMENT_STRUCT;

index	Retrieve the index-th attachment. If this value is -1, retrieve the attachment having the uid uid
uid	If index is not -1, this member will be set to the uid the index-th attachment has.
filename	pointer to filename of this attachment
description	Pointer to human readable description of this attachment
mime_type	Pointer to a string describing the type of this attachment
binary_data binary_data_size	Pointer to binary data of the attachment and size of the attachment.

Call:

mtrGetChapter(
  void* 			matroska
  GET_ATTACHMENT_STRUCT*	attachment_struct, 
);

attachment_struct	Pointer to a valid GET_CHAPTER_STRUCT struct
matroska	Pointer retrieved by mtrOpen

Older functions

Function

Decription

int mtrOpenRead

char*	pFilename
MATROSKA_DESCR**	pDescr

Opens a matroska file for reading and returns a descriptor which you need each time you want to access this file.
The internal structure of this is not of any importance for you. Declare it as a Pointer, void* or whatever it is called in the language you want to use this library with.

The function returns MTR_OK if it succeeds, and will set *pDescr to NULL and return MTR_OPEN_INVALIDFILE if the indicated source file could not be opened.

int mtrRead(

MATROSKA_DESCR*	pDescr
int	iTrack
READ_STRUCT*	pRead

Reads one block from the specified track iTrack, or as few as possible, if the next block of that stream is laced and if delacing is not supported for this track, and returns this block(s) along with some information on it in *pRead.

Return values:

MTR_RD_OK	no error has occured
MTR_RD_ENDOFSEGMENT	end of active segment has been reached when trying to fill input queues
MTR_RD_SPARSEQUEUEEMPTY	you are trying to read from a sparse stream, but the input queue for that stream is empty.

READ_STRUCT {

void*	pBuffer
int	iSize
REFERENCES	references
FRAMES	frames
__int64	iTimecode
__int64	iDuration

}

REFERENCES {

int	iCount
int	iRefs[4]

}

FRAMES {

int	iCount
int	iSize[256]

}

mtrSetReadConfig(

MATROSKA_DESCR*	pDescr
int	iState
int	iIndex
int	iVal

Set parameters for reading from a matroska file.

iState

usage

MTRRCFG_QUEUETRACK

iVal = 1	enable queuing for track iIndex
iVal = 0	disable queuing for track iIndex
iIndex = -1	refer to all tracks
Note: You cannot read data from any track which is not queued, and you will waste a lot of RAM if you queue tracks you don't read from

MTRRCFG_ACTIVESEGMENT

activate the iIndex - th segment of a matroska file

MTRRCFG_SPARSE

iVal = 1	set sparse read mode for track iIndex
iVal = 0	set normal read mode for track iIndex

matroska.dll

Downlaods

Table of contents

1. By meaning

2. By function name

General

Backward compatibility of future versions of this DLL

Calling convention

Units

cbSize

Buffers

Character sets

Titles

Opening a file

Call:

Closing a file

Call:

Retrieving DLL version information

Call:

Retrieving information about a Segment

Call:

Retrieving information about a Track

Call:

Retrieving information about a Chapter

Call:

Retrieving an Attachment

Call:

Older functions