ILMMpg2MxT Interface

This is the interface for the LEAD MPEG2 Transport Multiplexer.

Interface Properties:

Type

Name

Description

long

OutputType

Controls the format of the output stream. Set to a bitwise OR of a flag from each of the output type categories (only one flag from each category). See Note 1 at the end of this topic for the possible values.

VARIANT_BOOL

AutoClosePrivateData

Set to VARIANT_TRUE to allow the multiplexer to close the application-provided private data stream when the normal audio/video stream has reached its end. Otherwise, the multiplexer will wait until the user has called ClosePrivateData. This is typically set to VARIANT_TRUE in a live capture situation.

VARIANT_BOOL

EnablePrivateData

Set to VARIANT_TRUE to enable the use of application-provided private data.

VARAINT_BOOL

IsEndOfStream

A read-only property that indicates whether the multiplexer is at the end of the audio/video streams.

ILMKlvBuilder *

KlvBuilder

A read-only property. Contains a pointer to the multiplexer's default KLVBuilder object. This object can be used to construct KLV-specific private data.

long

PrivateDataFormatID

The 32-bit Format ID used in the application-provided private data’s registration descriptor. An example of such an ID is mmioFOURCC('K', 'L', 'V', 'A').

long

PrivateDataPID

The PID of the application-provided private data.

double

ResyncInterval

Specifies the time interval (in seconds) between header packets. This will effectively set the maximum time required for a demultiplexer to start decoding the stream at any given point.

Mpg2MxT_PrecisionTimeStampAction PrecisionTimeStampAction

Specifies which action to take regarding precision time stamps. The default value is Mpg2MxT_PrecisionTimeStampAction_Ignore. See the Precision Time Stamps topic for more information on precision time stamps. This property indicates whether the time stamps will be:

  • Ignored (no action = write them if they are present, do not do anything if they are absent)
  • Removed, even if they are present in the compressed stream
  • Added only if they are not present in the compressed stream
  • Always added, overwriting time stamps that might be present in the compressed stream
double PrecisionTimeStampStartValue

The starting value for the precision time stamp. This value is in microseconds since January 1, 1970 and is relative to Coordinates Universal Time (UTC). Use the ConvertDateToPrecisionTimeStamp method to convert a date string to this value.

This value is used only if the PrecisionTimeStampAction property is set to  Mpg2MxT_PrecisionTimeStampAction_AddIfMissing or Mpg2MxT_PrecisionTimeStampAction_AddAlways.

long Throttle

Enumeration value that indicates which type of throttling to use.

The values indicate whether output throttling should be disabled, forced, or automatically applied to recognized output sinks. The default value is Mpg2MxT_Throttle_Automatic, which automatically applies throttling to recognized output sinks.

The MPEG2 Multiplexer has its own clock to deliver samples to the UDP Sink filter for throttling the output stream to control data delivery. If another clock is being used as well, the two clocks can become out-of-sync, resulting in either the KLV writer or the video sample delivery taking increasing amounts of time to complete. This enumeration makes it possible to force or disable throttling if needed.

Interface Methods:

HRESULT ClosePrivateData();

Description

Informs the multiplexer that the application will not be providing any more private data. This will allow the multiplexer to properly close the output stream. This method is not required if the AutoClosePrivateData property is set to VARIANT_TRUE.

Returns

S_OK if successful, < 0 if an error occurred.

HRESULT GetPrivateDataFormatInfo(VARIANT* pInfo);

Parameters

pInfo

Pointer to a location to be filled with a byte array containing the user-specified private format information.

Description

Retrieves the information set with SetPrivateFormatInfo.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_POINTER                  [0x80004003] pInfo is NULL

HRESULT SetPrivateDataFormatInfo(VARIANT Info, long InfoLength);

Parameters

pInfo

Variant containing a byte array with user-specified private format information

InfoLength

The size of the data to be written.

Description

Sets the user-specified private format information. It is used as the additional identification information in the registration descriptor. By default, no additional information is written.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_INVALIDARG              [0x80070057] pInfo is not a byte array variant

HRESULT WritePrivateData(long Flags, double PTS, VARIANT Data, long DataLength);

Parameters

Flags

Long value containing combinations of the Mpg2MxT_WriteFlag constants.

PTS

A double value containing the presentation time stamp of the user-provided data.

Data

A variant containing a byte array of user-provided data.

DataLength

The length of the data to write.

Description

Writes the application-provided data to multiplexer output.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_INVALIDARG              [0x80070057] Data is not a byte array variant

HRESULT ConvertDateToPrecisionTimeStamp(BSTR pszDateString, BSTR pszFormatString, double *pPrecisionTimeStampValue);

Parameters

pszDateString

The string containing the date and time

pszFormatString

Optional string describing the format in pszDateString. Can be NULL or an empty string (""), in which case the date string should be in one of the standard formats. See Custom Formats for more details on the custom format string.

pPrecisionTimeStampValue

Pointer to a value that will receive the time in microseconds since Jan 1, 1970.

Description

Use this method to convert a string containing the date and time to a number representing microseconds since Jan 1, 1970. This value can be then used to set the PrecisionTimeStampStartValue property.

See the Precision Time Stamps topic for more information on precision time stamps and the format of the strings that can be converted.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes:

E_INVALIDARG                  [0x80070057] pszDateString or pszFormatString is invalid

HRESULT ResetToDefaultsEx(Mpg2MxT_APILEVEL ApiLevel);

Parameters

ApiLevel

The desired API level for reset. Pass Mpg2MxT_APILEVEL_1.

Description

Call this method to ensure future versions of the multiplexer will use the same defaults as the current version. Call this method before calling any other method in this interface.

If you do not call this method, the multiplexer will use the defaults that were last set by the user in the property page.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

N/A

HRESULT GetStreamCount(Mpg2MxT_StreamType streamType, long *pVal);

Parameters

streamType

Indicates which type of stream to count.

pVal

Pointer to a value that will be updated with the number of streams of the specified type.

Description

Use this method to count of the number of streams of a certain type (Audio, Video, Metadata, Other). Valid values for streamType are any member of Mpg2MxT_StreamType enumeration except Mpg2MxT_StreamType_ProgramMap.

Note: Build the graph before calling this method because the method counts connected input pins.

This method does not count any private data stream added with EnablePrivateData. It only counts the streams from the input file being written to the output file.

Use the number of streams returned by this function to know which values to pass to the GetStreamPID/SetStreamPID methods.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_POINTER                  [0x80004003] pVal is NULL

HRESULT GetStreamType(long streamIndex, Mpg2MxT_StreamType *pVal);

Parameters

streamIndex

Indicates the 0-based index of the input stream whose type you wish to retrieve.

pVal

Pointer to a value that will be updated with the stream type.

Description

Use this method to find out the type of a particular stream. The streamIndex must be between 0 and the total number of streams being written to the file minus 1.

Note: Build the graph before calling this method because the method counts connected input pins.

This method does not count any private data stream added with EnablePrivateData. It only counts the streams from the input file being written to the output file.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_POINTER [0x80004003] pVal is NULL
DISP_E_BADINDEX [0x8002000B] There is no stream with this index

HRESULT SetPreferredStreamPID(long streamIndex, long newVal);

Parameters

streamIndex

Indicates the index of the input stream whose type you wish to retrieve.

newVal

The new PID value. This must be either -1 or between 16 (0x10) and 8190 (0x1FFE).

Description

Use this method to set the preferred stream PID for the stream indicated by streamIndex. Setting the stream PID to -1 allows the mux to pick the appropriate PID for each stream.

streamIndex can identify a generic stream, a video stream, audio stream, etc. The following values are possible:

Mpg2MxT_StreamType_ProgramMap (same as -1). The program map stream. Every MPEG2 Transport Stream will contain a program map stream. Use this define to select the PID for the program map stream.
N Stream with index N (0 <=N <= Mpg2MxT_StreamType_Video - 1). So 0 = first stream, 1 = second stream, etc. Here stream 0 is the stream connected to the first input pin. The stream can be any kind supported by the MPEG2 mux: video, audio, metadata, etc.
Mpg2MxT_StreamType_Video + N The video stream with index N, where (0 <= N <= 31). So Mpg2MxT_StreamType_Video = first video stream, Mpg2MxT_StreamType_Video + 1 = second video stream, etc.
Mpg2MxT_StreamType_Audio + N The audio stream with index N (0 <= N <= 31). So Mpg2MxT_StreamType_Audio = first video stream, etc.
Mpg2MxT_StreamType_Metadata_KLV + N The KLV metadata stream N (0 <= N <= 31).
Mpg2MxT_StreamType_Metadata_Other + N Other metadata stream N (0 <= N <= 31).
Mpg2MxT_StreamType_Other + N Other (non-metadata) stream N (0 <= N <= 31).

In most cases, there will be one audio and one video stream. So the following pseudo-code will set the PIDs for program map, audio, video and KLV metadata streams:

pMpgDmx->SetPreferredStreamPID(Mpg2MxT_StreamType_ProgramMap, 0x20);
pMpgDmx->SetPreferredStreamPID(Mpg2MxT_StreamType_Video, 0x30);
pMpgDmx->SetPreferredStreamPID(Mpg2MxT_StreamType_Audio, 0x40);
pMpgDmx->SetPreferredStreamPID(Mpg2MxT_StreamType_Metadata_KLV, 0x50);

When using this method to set a PID for each stream, be sure each PID is unique. Otherwise, the multiplexer could pick a different PID for this stream if it conflicts with another stream.

The PID is the number between 0 and 0x1FFF used to identify an elementary in the MPEG2 Transport stream. See the ISO ISO/IEC 13818-1 MPEG-2 Transport specification for more details on this value. The values between 0 and 15 and 0x1FFF are reserved, so you cannot use them.

This method does not affect any private data stream added with EnablePrivateData. It only affects the streams from the input file being written to the output file. To set the PID of the private data stream, use the PrivateDataPID property.

Note: Build the graph before calling this method because the method affects only connected input pins.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_POINTER [0x80004003] newVal is NULL
DISP_E_BADINDEX [0x8002000B] There is no stream with this index

HRESULT GetPreferredStreamPID(long streamIndex, long *pVal);

Parameters

streamIndex

Indicates the index of the input stream whose type is being retrieved.

pVal

Pointer to a value that will be updated with the preferred stream PID. This will be set to -1 if you never called SetStreamPID for this stream.

Description

Use this method to get the preferred stream PID for the stream indicated by streamIndex. See the SetPreferredStreamPID method for a description of the possible values for streamIndex.

By default, the preferred stream PID value is -1, which lets the mux pick the stream PID.

Note: Build the graph before calling this method because the method counts connected input pins.

The PID is the number between 0 and 0x1FFF used to identify an elementary in the MPEG2 Transport stream. See the ISO ISO/IEC 13818-1 MPEG-2 Transport specification for more details on this value.

This method does not count any private data stream added with EnablePrivateData. It only counts the streams from the input file being written to the output file. To get the PID of the private data stream, use the PrivateDataPID property.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_POINTER [0x80004003] pVal is NULL
DISP_E_BADINDEX [0x8002000B] There is no stream with this index

Data types:

Flags being passed to the WritePrivateData method:

typedef enum Mpg2MxT_WriteFlag 
{ 
   Mpg2MxT_WriteFlag_PTSValid = 0x00000001,              /* The PTS value is valid */ 
   Mpg2MxT_WriteFlag_PTSInSeconds = 0x00000002,          /* The PTS value is specified in seconds */ 
   Mpg2MxT_WriteFlag_UseStreamPTS = 0x00000004,          /* The current stream time should be used instead of the provided PTS */ 
   Mpg2MxT_WriteFlag_SyncPoint = 0x00000008,             /* The data is a synchronization point, and is seekable */ 
   Mpg2MxT_WriteFlag_Discontinuity = 0x00000010,         /* reserved */ 
} Mpg2MxT_WriteFlags; 

Flags being passed to the OutputType property:

typedef enum Mpg2MxT_OutputType 
{ 
   Mpg2MxT_OutputType_Default = 0x00000000,              /* Default output mode (non-broadcast) */ 
   Mpg2MxT_OutputType_Broadcast = 0x00000001,            /* Broadcast mode */ 
   Mpg2MxT_OutputType_HLS = 0x00000002,                   /* HTTP Live Streaming */ 
   Mpg2MxT_OutputType_Mode = 0x0000000F,               /* Internal use - the mode covers the lower 4 bits, all are mutually exclusive */ 
   Mpg2MxT_OutputType_UsePadding = 0x00000010,           /* Use padding to achieve constant bitrate */ 
   Mpg2MxT_OutputType_AsynchronousMetadata = 0x00000000, /* Write metadata using Asynchronous streams */ 
   Mpg2MxT_OutputType_SynchronousMetadata = 0x00000020,  /* Write metadata using Synchronous streams */ 
   Mpg2MxT_OutputType_LowLatency = 0x00000040,  /* Low latency mode (each sample is sent to the sink without buffering) */ 
   Mpg2MxT_OutputType_FullyMultiplexMetadata = 0x00000080, /* Force the multiplexer to wait for metadata, supplied through the input pin, so that the output can be fully multiplexed with the other streams */ 
   Mpg2MxT_OutputType_ModeMax = 0x00000002,           /* Internal use - Set this to the maximum mode value */ 
   Mpg2MxT_OutputType_ValidFlags = 0x000000FF,           /* Internal use - Change this whenever new OutputType flags are added */ 
} Mpg2MxT_OutputType; 

Possible values passed to ResetToDefaultsEx:

typedef enum Mpg2MxT_APILEVEL 
{ 
   Mpg2MxT_APILEVEL_1 = 0, 
} Mpg2MxT_APILEVEL; 

Possible values for the PrecisionTimeStampAction property:

typedef enum 
{ 
   Mpg2MxT_PrecisionTimeStampAction_Ignore = 0, /* Do nothing - the timestamps will be written in the output file if they are present in the compressed stream */ 
   Mpg2MxT_PrecisionTimeStampAction_RemoveExisting = 1, /* Do not write any precision time stamps. Remove them if they are present in the compressed stream */ 
   Mpg2MxT_PrecisionTimeStampAction_AddIfMissing = 2, /* Add the precision time stamps only if they are not present in the compressed stream. If the compressed stream contains precision time stamps already, leave them in the stream */ 
   Mpg2MxT_PrecisionTimeStampAction_AddAlways = 3 /* Always write the precision time stamps. If the compressed stream contains time stamps, overwrite them. If the compressed stream does not contain them, add them */ 
} Mpg2MxT_PrecisionTimeStampAction; 

Enumeration used by GetStreamCount, GetStreamType, SetPreferredStreamPID and GetPreferredStreamPID methods to specify stream types:

typedef enum 
{ 
   Mpg2MxT_StreamType_ProgramMap = -1, 
   Mpg2MxT_StreamType_Any = 0, /* all the streams */ 
   Mpg2MxT_StreamType_Video = 0x80, 
   Mpg2MxT_StreamType_Audio = 0xA0, 
   Mpg2MxT_StreamType_Metadata_KLV = 0xC0, 
   Mpg2MxT_StreamType_Metadata_Other = 0xE0, 
   Mpg2MxT_StreamType_Other = 0x100 
} Mpg2MxT_StreamType; 

Possible values for the Throttle property:

typedef enum 
{ 
   Mpg2MxT_Throttle_Disabled = 0, /* Disable all output throttling */ 
   Mpg2MxT_Throttle_Automatic = 1, /* Automatically apply throttling to recognized output sinks. This is the default value. */ 
   Mpg2MxT_Throttle_Enabled = 2 /* Force output throttling */ 
} Mpg2MxT_Throttle; 

Note 1: Possible values for the OutputType property

The OutputType property can be set to a bitwise OR of at most one flag from each of the following categories. You cannot OR two flags from the same category:

Output type category: Description
Mpg2MxT_OutputType_Default [0x00000000] Default output mode (non-broadcast)
Mpg2MxT_OutputType_Broadcast [0x00000001] Generates streams compatible with broadcast industry standards.
Mpg2MxT_OutputType_HLS [0x00000002] Generates output compatible with video-on-demand systems.
Padding category:
Mpg2MxT_OutputType_UsePadding [0x00000010] Adds padding packets to achieve constant bitrate.
Metadata (private data) category:
Mpg2MxT_OutputType_AsynchronousMetadata [0x00000000] Writes metadata using Asynchronous streams.
Mpg2MxT_OutputType_SynchronousMetadata [0x00000020]  Writes metadata using Synchronous streams.
Mpg2MxT_OutputType_FullyMultiplexMetadata [0x00000080]  Forces the multiplexer to wait for metadata, supplied through the input pin, so that the output maybe fully multiplexed with the other streams. 
Latency category:
Mpg2MxT_OutputType_LowLatency [0x00000040] Low latency mode (each sample is sent to the sink without buffering).

 

Example 1. To generate non-broadcast streams with Synchronous metadata and no padding, set OutputType to the following value:

Mpg2MxT_OutputType_Default | Mpg2MxT_OutputType_SynchronousMetadata

Example 2. To generate broadcast streams with padding, set OutputType to the following value:

Mpg2MxT_OutputType_Broadcast | Mpg2MxT_OutputType_Padding

Help Version 19.0.2017.10.19
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS Filters C API Help