Format

Overview

Defines format-related APIs.

For example, you use this module to define custom data types and to initialize, create, destroy the muxer and demuxer, and set their parameters. Also, you can read demuxer data frames, select demuxer tracks, add muxer tracks, and write data frames into a container.

Since:

1.0

Version:

1.0

Summary

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Details

Macro Definition Documentation

FORMAT_INVALID_PROGRAM_ID

#define FORMAT_INVALID_PROGRAM_ID   -1

Description:

Indicates an invalid program ID.

FORMAT_INVALID_TRACK_ID

#define FORMAT_INVALID_TRACK_ID   -1

Description:

Indicates an invalid track ID.

FORMAT_LANGUAGE_LEN

#define FORMAT_LANGUAGE_LEN   4

Description:

Indicates the number of characters contained in the language description.

FORMAT_MAX_LANGUAGE_NUM

#define FORMAT_MAX_LANGUAGE_NUM   4

Description:

Indicates the number of languages in the subtitle file.

FORMAT_TITLE_LEN

#define FORMAT_TITLE_LEN   64

Description:

Indicates the number of title characters.

URL_LEN

#define URL_LEN   4096

Description:

Indicates the URL length.

Typedef Documentation

CALLBACK_HANDLE

typedef void* [CALLBACK_HANDLE]($api-api-SmartVision-Devices-Format.md#gab928f39c359734527bda3fd160f89331)

Description:

Indicates the pointer to the callback handle for listening the muxer.

Enumeration Type Documentation

AudioSampleFmt

enum [AudioSampleFmt]($api-api-SmartVision-Devices-Format.md#gadf0700999998f587f0017c4d02977b22)

Description:

Enumerates audio sampling formats.

CodecFormat

enum [CodecFormat]($api-api-SmartVision-Devices-Format.md#gaf7ed135f15d4b218d41705bac0122ba7)

Description:

Enumerates audio, video, and image encoding formats.

DataFlags

enum [DataFlags]($api-api-SmartVision-Devices-Format.md#gacff079fdf8427c743f9197ea5be33a7f)

Description:

Enumerates flags of raw stream data.

FormatErrorType

enum [FormatErrorType]($api-api-SmartVision-Devices-Format.md#ga31e7fcf42722fa15e4e5489c2fef9092)

Description:

Enumerates callback error types.

FormatInfoType

enum [FormatInfoType]($api-api-SmartVision-Devices-Format.md#ga6f00342925d3d5e586c76f8695985cad)

Description:

Enumerates types of callback information.

FormatSeekMode

enum [FormatSeekMode]($api-api-SmartVision-Devices-Format.md#ga14aa9d18a71eff4a0b70f748f0377c94)

Description:

Enumerates seek modes.

FrameType

enum [FrameType]($api-api-SmartVision-Devices-Format.md#gad495a9f61af7fff07d7e97979d1ab854)

Description:

Enumerates data frame types.

KeyType

enum [KeyType]($api-api-SmartVision-Devices-Format.md#gaab0feaba617470cb4aa830dc5935238c)

Description:

Enumerates key types used for setting and obtaining parameters.

ManualSplitType

enum [ManualSplitType]($api-api-SmartVision-Devices-Format.md#ga10d9833450f29129d249c41d9acb4bc4)

Description:

Enumerates manual split types for the muxer.

OutputFormat

enum [OutputFormat]($api-api-SmartVision-Devices-Format.md#gaeb712c6c6c0a8af0dfd79f451ecb9277)

Description:

Enumerates output file formats.

OutputType

enum [OutputType]($api-api-SmartVision-Devices-Format.md#ga4e0517338e6c4a31a2addafc06d4f3a3)

Description:

Enumerates muxer output types.

SourceType

enum [SourceType]($api-api-SmartVision-Devices-Format.md#ga3ae727773c367ac1041d72ac770a0ab1)

Description:

Enumerates types of the demuxer data source.

SubtitleFormat

enum [SubtitleFormat]($api-api-SmartVision-Devices-Format.md#gadac45ce4731516c262292c15433439b3)

Description:

Enumerates subtitle file formats.

SubtitleFrameType

enum [SubtitleFrameType]($api-api-SmartVision-Devices-Format.md#ga43b7f046e365a89697272d850b0517b7)

Description:

Enumerates subtitle frame types.

TrackSourceType

enum [TrackSourceType]($api-api-SmartVision-Devices-Format.md#ga953bc46f95d7b2d8866838d792f8f6aa)

Description:

Enumerates types of the muxer source track.

TrackType

enum [TrackType]($api-api-SmartVision-Devices-Format.md#gad80740dd555f7d3688d2c4d9f44d3b04)

Description:

Enumerates track types.

Function Documentation

FormatDeInit()

void FormatDeInit (void )

Description:

Deinitializes the format.

You can call this function to deinitialize the demuxer and muxer. This function works in pair with FormatInit.

FormatDemuxerCreate()

int32_t FormatDemuxerCreate (const [FormatSource]($api-api-SmartVision-Devices-FormatSource.md) * source, void ** handle )

Description:

Creates a demuxer component and returns its context handle.

This function returns the demuxer context handle without probing the container format or obtaining stream information.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerDestory()

int32_t FormatDemuxerDestory (void * handle)

Description:

Destroys demuxer resources.

This function works in pair with FormatDemuxerCreate. If you do not call this function, resource leakage may occur.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerFreeFrame()

int32_t FormatDemuxerFreeFrame (void * handle, [FormatFrame]($api-api-SmartVision-Devices-FormatFrame.md) * frame )

Description:

Frees data frames.

You can call this function to free the data frames obtained by calling FormatDemuxerReadFrame.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerGetBufferConfig()

int32_t FormatDemuxerGetBufferConfig (const void * handle, [FormatBufferSetting]($api-api-SmartVision-Devices-FormatBufferSetting.md) * setting )

Description:

Obtains the buffer information of the demuxer.

If there is a buffer mechanism in the demuxer, you can call this function to obtain the maximum buffer size and time.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerGetFileInfo()

int32_t FormatDemuxerGetFileInfo (void * handle, [FileInfo]($api-api-SmartVision-Devices-FileInfo.md) * info )

Description:

Obtains the attributes of a media file.

The attributes contain file, program, and stream attributes. This function should be called after FormatDemuxerPrepare is called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerGetParameter()

int32_t FormatDemuxerGetParameter (const void * handle, int32_t trackId, [ParameterItem]($api-api-SmartVision-Devices-ParameterItem.md) * metaData )

Description:

Obtains demuxer attributes.

You can call this function to obtain the HTTP header, HTTP referer, and other extension items for the demuxer after FormatDemuxerCreate is called. The demuxer will store the value in the metaData based on the key.If the demuxer has allocated memory for the metaData to store the value, the caller should manually free the memory.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerGetSelectedTrack()

int32_t FormatDemuxerGetSelectedTrack (const void * handle, int32_t * programId, int32_t trackId[], int32_t * nums )

Description:

Obtains the ID of the media track selected by the demuxer for output.

The demuxer automatically selects the default program and its media tracks. However, if the program and media tracks have changed after FormatDemuxerSelectTrack and FormatDemuxerUnselectTrack are called, you can obtain the currently selected program and media tracks by calling this function (FormatDemuxerGetSelectedTrack.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerPrepare()

int32_t FormatDemuxerPrepare (void * handle)

Description:

Makes preparations for the demuxer.

This function triggers the demuxer to probe the media file container format and parse stream information. You can obtain media file attributes only after this function is called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerReadFrame()

int32_t FormatDemuxerReadFrame (const void * handle, [FormatFrame]($api-api-SmartVision-Devices-FormatFrame.md) * frame, int32_t timeOutMs )

Description:

Reads data frames.

After the data frames are read, you need to call FormatDemuxerFreeFame to free them.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerSeek()

int32_t FormatDemuxerSeek (const void * handle, int32_t streamIndex, int64_t timeStampUs, [FormatSeekMode]($api-api-SmartVision-Devices-Format.md#ga14aa9d18a71eff4a0b70f748f0377c94) mode )

Description:

Seeks for a specified position for the demuxer.

After being started, the demuxer seeks for a specified position to read data frames. You can specify the position close to the time specified by streamIndex.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerSelectTrack()

int32_t FormatDemuxerSelectTrack (const void * handle, int32_t programId, int32_t trackId )

Description:

Selects a specified media track.

The media tracks to select must belong to the same program. If you do not call this function, the default media tracks of the default program are selected. If programId is valid but trackId is invalid, the default media track of the specified program is used.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerSetBufferConfig()

int32_t FormatDemuxerSetBufferConfig (void * handle, const [FormatBufferSetting]($api-api-SmartVision-Devices-FormatBufferSetting.md) * setting )

Description:

Sets buffer information for the demuxer.

If there is a buffer mechanism in the demuxer, you can call this function to set the maximum buffer size and time. Alternatively, you can disable the buffer mechanism by setting the buffer size and time to 0 in the setting parameter. If there is no buffer mechanism or the default setting is retained, you can skip this function.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerSetCallBack()

int32_t FormatDemuxerSetCallBack (void * handle, const [FormatCallback]($api-api-SmartVision-Devices-FormatCallback.md) * callBack )

Description:

Sets a callback for the demuxer.

The callback will be invoked to notify the upper layer of internal events of the demuxer.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerSetParameter()

int32_t FormatDemuxerSetParameter (const void * handle, int32_t trackId, const [ParameterItem]($api-api-SmartVision-Devices-ParameterItem.md) * metaData, int32_t metaDataCnt )

Description:

Sets demuxer attributes.

You can call this function to set the HTTP header, HTTP referer, and other extension items for the demuxer after FormatDemuxerCreate is called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerStart()

int32_t FormatDemuxerStart (void * handle)

Description:

Starts the demuxer.

After being started, the caller can read data frames from the demuxer. This function should be called after FormatDemuxerPrepare is called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerStop()

int32_t FormatDemuxerStop (void * handle)

Description:

Stops the demuxer from working.

After this function is called, the demuxer cannot resume decapsulation.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatDemuxerUnselectTrack()

int32_t FormatDemuxerUnselectTrack (const void * handle, int32_t programId, int32_t trackId )

Description:

Unselects a specified media track from which the demuxer reads data frames.

The demuxer can read all media tracks of the default program. You can call this function to unselect all or certain tracks of a specified program that the demuxer is expected not to read. If trackId is invalid, the demuxer will read none of the tracks of the specified program.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatInit()

void FormatInit (void )

Description:

Initializes the format.

You can call this function to initialize the demuxer and muxer. This function should always be called before other format-specific functions, and it can be called only once within a process.

FormatMuxerAddTrack()

int32_t FormatMuxerAddTrack (void * handle, const [TrackSource]($api-api-SmartVision-Devices-TrackSource.md) * trackSource )

Description:

Adds a media track source for the muxer. For details about track sources, see TrackSource.

This function must be called after FormatMuxerCreate is successfully called and before FormatMuxerStart is called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerCreate()

int32_t FormatMuxerCreate (void ** handle, [FormatOutputConfig]($api-api-SmartVision-Devices-FormatOutputConfig.md) * outputConfig )

Description:

Creates a muxer and returns its context handle.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerDestory()

int32_t FormatMuxerDestory (const void * handle)

Description:

Destroys a muxer and release its resources created by calling FormatMuxerCreate.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerGetParameter()

int32_t FormatMuxerGetParameter (void * handle, int32_t trackId, [ParameterItem]($api-api-SmartVision-Devices-ParameterItem.md) * item, int32_t itemNum )

Description:

Obtains muxer attributes.

This is an extended function that can be used to obtain muxer or track attributes. The demuxer then obtains the muxer attributes based on the key contained in item.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value if any requested attribute fails to be obtained or is not found.

FormatMuxerSetCallBack()

int32_t FormatMuxerSetCallBack (void * handle, const [FormatCallback]($api-api-SmartVision-Devices-FormatCallback.md) * callBack )

Description:

Sets a callback for the muxer. For details about the callback, see FormatCallback.

This function should be called after FormatMuxerCreate is successfully called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerSetFileSplitDuration()

int32_t FormatMuxerSetFileSplitDuration (const void * handle, [ManualSplitType]($api-api-SmartVision-Devices-Format.md#ga10d9833450f29129d249c41d9acb4bc4) type, int64_t timestampUs, uint32_t durationUs )

Description:

Manually splits a file.

This function can be called after FormatMuxerStart is called. Once this function is called, the file is split based on the manual split type. After manual split is complete, file split will proceed to use the initially set split type. You can call this function again only after the MUXER_INFO_FILE_SPLIT_FINISHED event is reported.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerSetLocation()

int32_t FormatMuxerSetLocation (const void * handle, int latitude, int longitude )

Description:

Sets the geographical information for the output file of the muxer.

This function should be called after FormatMuxerCreate is successfully called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerSetMaxFileDuration()

int32_t FormatMuxerSetMaxFileDuration (void * handle, int64_t durationUs )

Description:

Sets the maximum duration (in seconds) for the output file.

You need to call this function before calling FormatMuxerStart. If the maximum duration you set is valid and capturing is approaching 90% of that duration or the remaining duration is 1s, the message MUXER_INFO_MAX_DURATION_APPROACHING is reported via OnInfo of FormatCallback. If the output file has been set by calling FormatMuxerCreate, you need to call FormatMuxerSetNextOutputFile to set the next output file. Otherwise, the current output file will be overwritten when the capturing reaches the maximum duration you set.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerSetMaxFileSize()

int32_t FormatMuxerSetMaxFileSize (void * handle, int64_t bytes )

Description:

Sets the maximum size (in bytes) for the output file of the muxer.

This function should be called after FormatMuxerCreate is successfully called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerSetNextOutputFile()

int32_t FormatMuxerSetNextOutputFile (const void * handle, int32_t fd )

Description:

Sets the descriptor for the next output file.

If FormatMuxerCreate is successfully called and the file descriptor involved is valid, you can call this function (FormatMuxerSetNextOutputFile) upon receiving the message MUXER_INFO_MAX_FILESIZE_APPROACHING or MUXER_INFO_MAX_DURATION_APPROACHING.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerSetOrientation()

int32_t FormatMuxerSetOrientation (void * handle, int degrees )

Description:

Sets the orientation of the video track for the muxer.

This function should be called after FormatMuxerAddTrack is successfully called. The following degrees are supported: 0, 90, 180, and 270.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerSetParameter()

int32_t FormatMuxerSetParameter (void * handle, int32_t trackId, const [ParameterItem]($api-api-SmartVision-Devices-ParameterItem.md) * item, int32_t itemNum )

Description:

Sets muxer attributes.

This is an extended function that can be used to add MP4-dedicated boxes and tags (such as exif).

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerStart()

int32_t FormatMuxerStart (void * handle)

Description:

Starts the muxer.

You can call this function to encapsulate media data after the muxer is created, media tracks are added, and related parameters are set.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerStop()

int32_t FormatMuxerStop (const void * handle, bool block )

Description:

Stops the muxer that was started by calling FormatMuxerStart.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

FormatMuxerWriteFrame()

int32_t FormatMuxerWriteFrame (const void * handle, const [FormatFrame]($api-api-SmartVision-Devices-FormatFrame.md) * frameData )

Description:

Writes data frames into the muxer.

This function should be called after FormatMuxerCreate is successfully called.

Parameters:

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.