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

File Name

Description

format_interface.h

Declares format-related APIs.

format_type.h

Declares format-related structures and enumerations, including custom data types for file information, programs, information about audio and video subtitle tracks, source data types, output data types, split types, and data frames.

parameter_item.h

Defines format-related structures and enumerations used to configure and obtain dynamic parameters.

Data Structures

Data Structure Name

Description

FormatBufferSetting

Defines the buffer configuration.

FormatFrame

Defines the data frame, which is used for data transferring.

AudioTrackInfo

Defines audio track information.

VideoTrackInfo

Defines video track information.

SubImageInfo

Defines image information.

ImageTrackInfo

Defines image stream information.

SubtitleTrackInfo

Defines subtitle stream information.

TrackInfo

Defines track information.

ProgramInfo

Defines program information.

FileInfo

Defines movie file information.

BufferStream

Defines the function for reading stream data.

FormatSource

Defines the demuxer data source.

FormatOutputConfig

Defines the muxer output configuration.

VideoTrackSourceInfo

Defines information about the muxer video source.

AudioTrackSourceInfo

Defines information about the muxer audio source.

DataTrackSourceInfo

Defines information about the muxer data source.

TrackSource

Defines information about the muxer source.

FormatCallback

Defines listener callbacks for the format.

ParameterItem

Defines a structure for configuring and obtaining dynamic parameters.

Macros

Macro Name and Value

Description

FORMAT_MAX_LANGUAGE_NUM   4

 

FORMAT_LANGUAGE_LEN   4

 

FORMAT_TITLE_LEN   64

 

FORMAT_INVALID_TRACK_ID   -1

 

FORMAT_INVALID_PROGRAM_ID   -1

 

URL_LEN   4096

 

Typedefs

Typedef Name

Description

CALLBACK_HANDLE

typedef void * 

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

Enumerations

Enumeration Name

Description

FrameType {   FRAME_TYPE_NONE, FRAME_TYPE_AUDIO, FRAME_TYPE_VIDEO, FRAME_TYPE_IMAGE,   FRAME_TYPE_SUB, FRAME_TYPE_DATA, FRAME_TYPE_BUT }

Enumerates data frame types.

FormatSeekMode { FORMAT_SEEK_MODE_FORWARD_KEY, FORMAT_SEEK_MODE_BACKWARD_KEY, FORMAT_SEEK_MODE_CLOSEST_KEY, SEEK_MODE_BUT }

Enumerates seek modes.

CodecFormat {   CODEC_H264 = 0, CODEC_H265, CODEC_JPEG, CODEC_AAC,   CODEC_G711A, CODEC_G711U, CODEC_PCM, CODEC_MP3,   CODEC_BUT }

Enumerates audio, video, and image encoding formats.

AudioSampleFmt {   AUDIO_SAMPLE_FMT_S8 = 0, AUDIO_SAMPLE_FMT_S16, AUDIO_SAMPLE_FMT_S24, AUDIO_SAMPLE_FMT_S32,   AUDIO_SAMPLE_FMT_FLOAT }

Enumerates audio sampling formats.

SubtitleFrameType { HI_SVR_SUBTITLE_BITMAP = 0x0, HI_SVR_SUBTITLE_TEXT }

Enumerates subtitle frame types.

SubtitleFormat {   FORMAT_SUB_ASS = 0x0, FORMAT_SUB_LRC, FORMAT_SUB_SRT, FORMAT_SUB_SMI,   FORMAT_SUB_SUB, FORMAT_SUB_TXT, FORMAT_SUB_HDMV_PGS, FORMAT_SUB_DVB_SUB,   FORMAT_SUB_DVD_SUB, FORMAT_SUB_TTML, FORMAT_SUB_WEBVTT, FORMAT_SUB_BUTT }

Enumerates subtitle file formats.

TrackType {   TRACK_TYPE_VIDEO, TRACK_TYPE_AUDIO, TRACK_TYPE_IMAGE, TRACK_TYPE_SUB,   TRACK_TYPE_DATA, TRACK_TYPE_BUT }

Enumerates track types.

DataFlags {   DATA_FLAG_NONE = 0, DATA_FLAG_SYNCFRAME = 1, DATA_FLAG_CODECCONFIG = 2, DATA_FLAG_EOS = 4,   DATA_FLAG_PARTIAL_FRAME = 8, DATA_FLAG_ENDOFFRAME = 16, DATA_FLAG_MUXER_DATA = 32 }

Enumerates flags of raw stream data.

SourceType { SOURCE_TYPE_FD = 0, SOURCE_TYPE_URI, SOURCE_TYPE_STREAM, SOURCE_TYPE_BUT }

Enumerates types of the demuxer data source.

OutputFormat {   OUTPUT_FORMAT_MPEG_4 = 0, OUTPUT_FORMAT_TS = 1, OUTPUT_FORMAT_THREE_GPP = 2, OUTPUT_FORMAT_HEIF = 3,   OUTPUT_FORMAT_OGG = 4, OUTPUT_FORMAT_INVALID }

Enumerates output file formats.

FormatInfoType {   MUXER_INFO_MAX_DURATION_APPROACHING = 0, MUXER_INFO_MAX_FILESIZE_APPROACHING, MUXER_INFO_MAX_DURATION_REACHED, MUXER_INFO_MAX_FILESIZE_REACHED,   MUXER_INFO_NEXT_OUTPUT_FILE_STARTED, MUXER_INFO_FILE_SPLIT_FINISHED, MUXER_INFO_FILE_START_TIME_MS, DEMUXER_INFO_PREPARED = 10000,   DEMUXER_INFO_SEEK_COMPLETE, DEMUXER_INFO_NETWORK_DISCONNECTED, DEMUXER_INFO_NETWORK_RECONNECTED }

Enumerates types of callback information.

FormatErrorType

Enumerates callback error types.

OutputType { OUTPUT_TYPE_FD = 0, OUTPUT_TYPE_URI, OUTPUT_TYPE_INVALID }

Enumerates muxer output types.

ManualSplitType { MANUAL_SPLIT_POST = 0, MANUAL_SPLIT_PRE, MANUAL_SPLIT_NORMAL }

Enumerates manual split types for the muxer.

TrackSourceType { TRACK_SOURCE_TYPE_VIDEO = 0, TRACK_SOURCE_TYPE_AUDIO, TRACK_SOURCE_TYPE_DATA, TRACK_SOURCE_TYPE_INVALID }

Enumerates types of the muxer source track.

KeyType { KEY_TYPE_MIME = 0x6d696d65, KEY_TYPE_HTTP_HEADERS = 0x68706864, KEY_TYPE_LANGUAGE = 0x6c616e67, KEY_TYPE_PRE_CACHE = 0x70726361 }

Enumerates key types used for setting and obtaining parameters.

Functions

Function Name

Description

FormatInit (void)

void 

Initializes the format.

FormatDeInit (void)

void 

Deinitializes the format.

FormatDemuxerCreate (const FormatSourcesource, void **handle)

int32_t 

Creates a demuxer component and returns its context handle.

FormatDemuxerSetParameter (const void handle, int32_t trackId, const ParameterItemmetaData, int32_t metaDataCnt)

int32_t 

Sets demuxer attributes.

FormatDemuxerGetParameter (const void handle, int32_t trackId, ParameterItemmetaData)

int32_t 

Obtains demuxer attributes.

FormatDemuxerSetCallBack (void handle, const FormatCallbackcallBack)

int32_t 

Sets a callback for the demuxer.

FormatDemuxerSetBufferConfig (void handle, const FormatBufferSettingsetting)

int32_t 

Sets buffer information for the demuxer.

FormatDemuxerGetBufferConfig (const void handle, FormatBufferSettingsetting)

int32_t 

Obtains the buffer information of the demuxer.

FormatDemuxerPrepare (void handle)

int32_t 

Makes preparations for the demuxer.

FormatDemuxerGetFileInfo (void handle, FileInfoinfo)

int32_t 

Obtains the attributes of a media file.

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

int32_t 

Selects a specified media track.

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

int32_t 

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

FormatDemuxerStart (void handle)

int32_t 

Starts the demuxer.

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

int32_t 

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

FormatDemuxerReadFrame (const void handle, FormatFrameframe, int32_t timeOutMs)

int32_t 

Reads data frames.

FormatDemuxerFreeFrame (void handle, FormatFrameframe)

int32_t 

Frees data frames.

FormatDemuxerSeek (const void handle, int32_t streamIndex, int64_t timeStampUs, FormatSeekMode mode)

int32_t 

Seeks for a specified position for the demuxer.

FormatDemuxerStop (void handle)

int32_t 

Stops the demuxer from working.

FormatDemuxerDestory (void handle)

int32_t 

Destroys demuxer resources.

FormatMuxerCreate (void **handle, FormatOutputConfig outputConfig)

int32_t 

Creates a muxer and returns its context handle.

FormatMuxerDestory (const void handle)

int32_t 

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

FormatMuxerAddTrack (void handle, const TrackSourcetrackSource)

int32_t 

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

FormatMuxerSetCallBack (void handle, const FormatCallbackcallBack)

int32_t 

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

FormatMuxerSetOrientation (void handle, int degrees)

int32_t 

Sets the orientation of the video track for the muxer.

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

int32_t 

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

FormatMuxerSetMaxFileSize (void handle, int64_t bytes)

int32_t 

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

FormatMuxerSetMaxFileDuration (void handle, int64_t durationUs)

int32_t 

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

FormatMuxerSetFileSplitDuration (const void handle, ManualSplitType type, int64_t timestampUs, uint32_t durationUs)

int32_t 

Manually splits a file.

FormatMuxerStart (void handle)

int32_t 

Starts the muxer.

FormatMuxerWriteFrame (const void handle, const FormatFrameframeData)

int32_t 

Writes data frames into the muxer.

FormatMuxerSetNextOutputFile (const void handle, int32_t fd)

int32_t 

Sets the descriptor for the next output file.

FormatMuxerStop (const void handle, bool block)

int32_t 

Stops the muxer that was started by calling FormatMuxerStart.

FormatMuxerSetParameter (void handle, int32_t trackId, const ParameterItemitem, int32_t itemNum)

int32_t 

Sets muxer attributes.

FormatMuxerGetParameter (void handle, int32_t trackId, ParameterItem *item, int32_t itemNum)

int32_t 

Obtains muxer attributes.

Details

Macro Definition Documentation

FORMAT_INVALID_PROGRAM_ID

  1. #define FORMAT_INVALID_PROGRAM_ID -1

Description:

Indicates an invalid program ID.

FORMAT_INVALID_TRACK_ID

  1. #define FORMAT_INVALID_TRACK_ID -1

Description:

Indicates an invalid track ID.

FORMAT_LANGUAGE_LEN

  1. #define FORMAT_LANGUAGE_LEN 4

Description:

Indicates the number of characters contained in the language description.

FORMAT_MAX_LANGUAGE_NUM

  1. #define FORMAT_MAX_LANGUAGE_NUM 4

Description:

Indicates the number of languages in the subtitle file.

FORMAT_TITLE_LEN

  1. #define FORMAT_TITLE_LEN 64

Description:

Indicates the number of title characters.

URL_LEN

  1. #define URL_LEN 4096

Description:

Indicates the URL length.

Typedef Documentation

CALLBACK_HANDLE

  1. typedefvoid*[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

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

Description:

Enumerates audio sampling formats.

Enumerator

Description

AUDIO_SAMPLE_FMT_S8 

8-bit integer for a single sample

AUDIO_SAMPLE_FMT_S16 

16-bit integer for a single sample

AUDIO_SAMPLE_FMT_S24 

24-bit integer for a single sample

AUDIO_SAMPLE_FMT_S32 

32-bit integer for a single sample

AUDIO_SAMPLE_FMT_FLOAT 

Single-precision floating point number for a single sample

CodecFormat

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

Description:

Enumerates audio, video, and image encoding formats.

Enumerator

Description

CODEC_H264 

H264 or AVC

CODEC_H265 

H265 or HEVC

CODEC_JPEG 

JPEG

CODEC_AAC 

AAC

CODEC_G711A 

G711A

CODEC_G711U 

G711u

CODEC_PCM 

PCM

CODEC_MP3 

MP3

CODEC_BUT 

Undefined format

DataFlags

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

Description:

Enumerates flags of raw stream data.

Enumerator

Description

DATA_FLAG_NONE 

None

DATA_FLAG_SYNCFRAME 

Synchronization frame

DATA_FLAG_CODECCONFIG 

Codec configuration information

DATA_FLAG_EOS 

End of a single stream

DATA_FLAG_PARTIAL_FRAME 

Partial synchronization frame. This flag is used for multiple segments (except for the last one) into which a single frame is divided.

DATA_FLAG_ENDOFFRAME 

End of a frame. This flag is used in pair with DATA_FLAG_PARTIAL_FRAME for the last segment of the frame.

DATA_FLAG_MUXER_DATA 

Encapsulated data with its container

FormatErrorType

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

Description:

Enumerates callback error types.

FormatInfoType

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

Description:

Enumerates types of callback information.

Enumerator

Description

MUXER_INFO_MAX_DURATION_APPROACHING 

The capturing duration is reaching the threshold specified by FormatMuxerSetMaxFileDuration. This information is reported when only one second or 10% is left to reach the allowed duration.

MUXER_INFO_MAX_FILESIZE_APPROACHING 

The captured file size is reaching the threshold specified by FormatMuxerSetMaxFileSize. This information is reported when only 100 KB or 10% is left to reach the allowed size.

MUXER_INFO_MAX_DURATION_REACHED 

The capturing duration reached the threshold specified by FormatMuxerSetMaxFileDuration, and the capturing is ended. If the file is set by a file descriptor, the caller needs to close the file.

MUXER_INFO_MAX_FILESIZE_REACHED 

The captured file size reached the threshold specified by FormatMuxerSetMaxFileSize, and the capturing is ended. If the file is set by a file descriptor, the caller needs to close the file.

MUXER_INFO_NEXT_OUTPUT_FILE_STARTED 

The capturing started for the next output file.

MUXER_INFO_FILE_SPLIT_FINISHED 

Manual file split is completed.

MUXER_INFO_FILE_START_TIME_MS 

Start time of the captured file

DEMUXER_INFO_PREPARED 

The prepare function is asynchronously executed. This information is reported after the execution is complete.

DEMUXER_INFO_SEEK_COMPLETE 

The seek function is asynchronously executed. This information is reported after the execution is complete.

DEMUXER_INFO_NETWORK_DISCONNECTED 

The network is disconnected during network playback.

DEMUXER_INFO_NETWORK_RECONNECTED 

The network is automatically reconnected during network playback.

FormatSeekMode

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

Description:

Enumerates seek modes.

Enumerator

Description

FORMAT_SEEK_MODE_FORWARD_KEY 

Seeks forwards for the keyframe closest to specified position.

FORMAT_SEEK_MODE_BACKWARD_KEY 

Seeks backwards for the keyframe closest to specified position.

FORMAT_SEEK_MODE_CLOSEST_KEY 

Seeks for the keyframe closest to specified position.

SEEK_MODE_BUT 

Undefined mode

FrameType

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

Description:

Enumerates data frame types.

Enumerator

Description

FRAME_TYPE_NONE 

Unknown type, which can be used for transport stream (TS) packets

FRAME_TYPE_AUDIO 

Audio frame

FRAME_TYPE_VIDEO 

Video frame

FRAME_TYPE_IMAGE 

Image frame

FRAME_TYPE_SUB 

Subtitle frame

FRAME_TYPE_DATA 

Data

FRAME_TYPE_BUT 

Undefined type

KeyType

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

Description:

Enumerates key types used for setting and obtaining parameters.

Enumerator

Description

KEY_TYPE_MIME 

MIME type. The value type is cstring.

KEY_TYPE_HTTP_HEADERS 

HTTP header. The value type is cstring.

KEY_TYPE_LANGUAGE 

Track language, which is usually the language of audio and subtitles. The value type is cstring.

KEY_TYPE_PRE_CACHE 

Precapture cache size. The value type is int

ManualSplitType

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

Description:

Enumerates manual split types for the muxer.

Enumerator

Description

MANUAL_SPLIT_POST 

Search forwards from the current I-frame and split the file at the closest I-frame.

MANUAL_SPLIT_PRE 

Search backwards from the current I-frame and split the file at the closest I-frame.

MANUAL_SPLIT_NORMAL 

Normal split

OutputFormat

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

Description:

Enumerates output file formats.

Enumerator

Description

OUTPUT_FORMAT_MPEG_4 

MP4

OUTPUT_FORMAT_TS 

TS

OUTPUT_FORMAT_THREE_GPP 

3GPP

OUTPUT_FORMAT_HEIF 

HEIF

OUTPUT_FORMAT_OGG 

Ogg

OUTPUT_FORMAT_INVALID 

Invalid format

OutputType

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

Description:

Enumerates muxer output types.

Enumerator

Description

OUTPUT_TYPE_FD 

File descriptor

OUTPUT_TYPE_URI 

Local file URI

OUTPUT_TYPE_INVALID 

Undefined type

SourceType

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

Description:

Enumerates types of the demuxer data source.

Enumerator

Description

SOURCE_TYPE_FD 

File descriptor

SOURCE_TYPE_URI 

URI, which can be a network address or a local file path

SOURCE_TYPE_STREAM 

Streams

SOURCE_TYPE_BUT 

Undefined source

SubtitleFormat

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

Description:

Enumerates subtitle file formats.

Enumerator

Description

FORMAT_SUB_ASS 

ASS

FORMAT_SUB_LRC 

LRC

FORMAT_SUB_SRT 

SRT

FORMAT_SUB_SMI 

SMI

FORMAT_SUB_SUB 

SUB

FORMAT_SUB_TXT 

RAW UTF-8

FORMAT_SUB_HDMV_PGS 

HDMV PGS

FORMAT_SUB_DVB_SUB 

DVB

FORMAT_SUB_DVD_SUB 

DVD

FORMAT_SUB_TTML 

TTML

FORMAT_SUB_WEBVTT 

WebVTT

FORMAT_SUB_BUTT 

Undefined format

SubtitleFrameType

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

Description:

Enumerates subtitle frame types.

Enumerator

Description

HI_SVR_SUBTITLE_BITMAP 

Bitmap (BMP)

HI_SVR_SUBTITLE_TEXT 

Text

TrackSourceType

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

Description:

Enumerates types of the muxer source track.

Enumerator

Description

TRACK_SOURCE_TYPE_VIDEO 

Video track

TRACK_SOURCE_TYPE_AUDIO 

Audio track

TRACK_SOURCE_TYPE_DATA 

Data track

TRACK_SOURCE_TYPE_INVALID 

Invalid type

TrackType

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

Description:

Enumerates track types.

Enumerator

Description

TRACK_TYPE_VIDEO 

Video track

TRACK_TYPE_AUDIO 

Audio track

TRACK_TYPE_IMAGE 

Image track

TRACK_TYPE_SUB 

Subtitle track

TRACK_TYPE_DATA 

Data track

TRACK_TYPE_BUT 

Undefined track

Function Documentation

FormatDeInit()

  1. voidFormatDeInit(void)

Description:

Deinitializes the format.

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

FormatDemuxerCreate()

  1. int32_tFormatDemuxerCreate(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:

Name

Description

sourceIndicates the pointer to the format source of the demuxer. For details, see FormatSource.
handleIndicates the double pointer to the demuxer context handle.

Returns:

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

FormatDemuxerDestory()

  1. int32_tFormatDemuxerDestory(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:

Name

Description

handleIndicates the pointer to the demuxer context handle.

Returns:

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

FormatDemuxerFreeFrame()

  1. int32_tFormatDemuxerFreeFrame(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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
frameIndicates the pointer to the data structure FormatFrame.

Returns:

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

FormatDemuxerGetBufferConfig()

  1. int32_tFormatDemuxerGetBufferConfig(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
settingIndicates the pointer to the maximum demuxer buffer size and time, as defined in FormatBufferSetting.

Returns:

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

FormatDemuxerGetFileInfo()

  1. int32_tFormatDemuxerGetFileInfo(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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
infoIndicates the pointer to the source attributes, as defined in FileInfo.

Returns:

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

FormatDemuxerGetParameter()

  1. int32_tFormatDemuxerGetParameter(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
trackIdIdentifies the track. If the value is an invalid value (-1), this parameter identifies the file or program.
metaDataIndicates the pointer to the buffer for storing the parameters values that the demuxer has searched for based on the input key. For details, see ParameterItem.

Returns:

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

FormatDemuxerGetSelectedTrack()

  1. int32_tFormatDemuxerGetSelectedTrack(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
programIdIdentifies the pointer to the program.
trackIdIdentifies the array of selected media tracks. This parameter works in pair with nums.
numsIndicates the pointer to the total number of selected media tracks. This parameter works in pair with trackId.

Returns:

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

FormatDemuxerPrepare()

  1. int32_tFormatDemuxerPrepare(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:

Name

Description

handleIndicates the pointer to the demuxer context handle.

Returns:

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

FormatDemuxerReadFrame()

  1. int32_tFormatDemuxerReadFrame(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
frameIndicates the pointer to the data structure FormatFrame.
timeOutMsIndicates the time required for waiting data frame read. The value 0 indicates that data frames are immediately read without any wait.

Returns:

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

FormatDemuxerSeek()

  1. int32_tFormatDemuxerSeek(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
streamIndexIdentifies the stream in the media file.
timeStampUsIndicates the target position, in microseconds.
modeIndicates the seek mode, as defined in FormatSeekMode.

Returns:

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

FormatDemuxerSelectTrack()

  1. int32_tFormatDemuxerSelectTrack(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
programIdIdentifies the program.
trackIdIdentifies the media track. If a valid value is passed, the media track must belong to the specified program. If an invalid value is passed, the default media track of the specified program is used. If multiple audio tracks are specified, the player determines which audio track to use.

Returns:

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

FormatDemuxerSetBufferConfig()

  1. int32_tFormatDemuxerSetBufferConfig(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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
settingIndicates the pointer to the maximum demuxer buffer size and time, as defined in FormatBufferSetting.

Returns:

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

FormatDemuxerSetCallBack()

  1. int32_tFormatDemuxerSetCallBack(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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
callBackIndicates the pointer to the callback, as defined in FormatCallback.

Returns:

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

FormatDemuxerSetParameter()

  1. int32_tFormatDemuxerSetParameter(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
trackIdIdentifies the track. If the value is an invalid value (-1), this parameter identifies the file or program.
metaDataIndicates the pointer to an array of key-value pairs representing parameter names and values. For details, see ParameterItem.
metaDataCntIndicates the number of key-value pairs in the array. This parameter works in pair with metaData.

Returns:

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

FormatDemuxerStart()

  1. int32_tFormatDemuxerStart(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:

Name

Description

handleIndicates the pointer to the demuxer context handle.

Returns:

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

FormatDemuxerStop()

  1. int32_tFormatDemuxerStop(void* handle)

Description:

Stops the demuxer from working.

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

Parameters:

Name

Description

handleIndicates the pointer to the demuxer context handle.

Returns:

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

FormatDemuxerUnselectTrack()

  1. int32_tFormatDemuxerUnselectTrack(constvoid* 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:

Name

Description

handleIndicates the pointer to the demuxer context handle.
programIdIdentifies the program.
trackIdIdentifies the media track that the demuxer will unselect. This parameter works in pair with programId. If a valid value is passed, the media track must belong to the program specified by programId. If an invalid value is passed, and all media tracks of the specified program are unselected.

Returns:

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

FormatInit()

  1. voidFormatInit(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()

  1. int32_tFormatMuxerAddTrack(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:

Name

Description

handleIndicates the pointer to the muxer context handle.
trackSourceIndicates the pointer to the track source.

Returns:

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

FormatMuxerCreate()

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

Description:

Creates a muxer and returns its context handle.

Parameters:

Name

Description

handleIndicates the double pointer to the muxer context handle.
outputConfigIndicates the pointer to the muxer output configuration, as defined in FormatOutputConfig.

Returns:

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

FormatMuxerDestory()

  1. int32_tFormatMuxerDestory(constvoid* handle)

Description:

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

Parameters:

Name

Description

handleIndicates the pointer to the muxer context handle.

Returns:

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

FormatMuxerGetParameter()

  1. int32_tFormatMuxerGetParameter(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:

Name

Description

handleIndicates the pointer to the muxer context handle.
trackIdIdentifies the media track. If the value is FORMAT_INVALID_TRACK_ID, this function obtains the muxer attributes.
itemIndicates the pointer to the items carrying muxer attributes. You can specify multiple items at a time in this parameter, which works in pair with itemNum.
itemNumIndicates the number of attributes set at a time.

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()

  1. int32_tFormatMuxerSetCallBack(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:

Name

Description

handleIndicates the pointer to the muxer context handle.
FormatCallbackIndicates the pointer to the muxer callback to set.

Returns:

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

FormatMuxerSetFileSplitDuration()

  1. int32_tFormatMuxerSetFileSplitDuration(constvoid* 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:

Name

Description

handleIndicates the pointer to the muxer context handle.
typeIndicates the file split type, as defined in FileSplitType.
timestampIndicates the file split timestamp. This parameter is not supported currently. The value �C1 indicates that the file is split at the time this function is called.
durationIndicates the period from the file split time to the time the next output file starts.

Returns:

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

FormatMuxerSetLocation()

  1. int32_tFormatMuxerSetLocation(constvoid* 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:

Name

Description

handleIndicates the pointer to the muxer context handle.
latitudeIndicates the latitude, within the range [-90,90].
longitudeIndicates the longitude, within the range [-180,180].

Returns:

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

FormatMuxerSetMaxFileDuration()

  1. int32_tFormatMuxerSetMaxFileDuration(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:

Name

Description

handleIndicates the pointer to the muxer context handle.
durationIndicates the maximum duration to set, in seconds. If the value is 0 or negative, the operation fails. In this case, the default duration (60 seconds) will be used.

Returns:

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

FormatMuxerSetMaxFileSize()

  1. int32_tFormatMuxerSetMaxFileSize(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:

Name

Description

handleIndicates the pointer to the muxer context handle.
bytesIndicates the maximum size of a file, in bytes. If the value is 0 or negative, the operation fails and the maximum size does not take effect. In this case, the maximum size of a single file supported by the current file system is used as the value of this parameter.

Returns:

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

FormatMuxerSetNextOutputFile()

  1. int32_tFormatMuxerSetNextOutputFile(constvoid* 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:

Name

Description

handleIndicates the pointer to the muxer context handle.
fdIndicates the file descriptor to set.

Returns:

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

FormatMuxerSetOrientation()

  1. int32_tFormatMuxerSetOrientation(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:

Name

Description

handleIndicates the pointer to the muxer context handle.
degreesIndicates the clockwise angle of the video track.

Returns:

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

FormatMuxerSetParameter()

  1. int32_tFormatMuxerSetParameter(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:

Name

Description

handleIndicates the pointer to the muxer context handle.
trackIdIdentifies the media track. If the value is FORMAT_INVALID_TRACK_ID, this function sets the muxer attributes.
itemIndicates the pointer to the items carrying muxer attributes. You can specify multiple items at a time in this parameter, which works in pair with itemNum.
itemNumIndicates the number of attributes set at a time.

Returns:

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

FormatMuxerStart()

  1. int32_tFormatMuxerStart(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:

Name

Description

handleIndicates the pointer to the muxer context handle.

Returns:

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

FormatMuxerStop()

  1. int32_tFormatMuxerStop(constvoid* handle,bool block )

Description:

Stops the muxer that was started by calling FormatMuxerStart.

Parameters:

Name

Description

handleIndicates the pointer to the muxer context handle.
blockIndicates how to stop the muxer. The value true indicates that the muxer is stopped after all buffered data is processed, and false indicates that the buffered data is discarded and the muxer is immediately stopped.

Returns:

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

FormatMuxerWriteFrame()

  1. int32_tFormatMuxerWriteFrame(constvoid* 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:

Name

Description

handleIndicates the pointer to the muxer context handle.
frameDataIndicates the pointer to the data structure FormatFrame.

Returns:

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