The following functions are provided by the Prosody Audio Video Format (AVF) API:
| API call | W | Description |
|---|---|---|
| sm_avfplay_create() | D | Create AVF player |
| sm_avfplay_destroy() | D | Destroy a previously allocated AVF player |
| sm_avfplay_get_datafeed() | D | Obtain a datafeed from a AVF player |
| sm_avfplay_get_event() | D | Obtain an event for a AVF player |
| sm_avfplay_put_data() | D | Write data to a AVF player |
| sm_avfplay_start() | D | Starts a previously allocated AVF player |
| sm_avfplay_status() | D | Determine AVF player status |
| sm_avfplay_stop() | D | Stops a previously started AVF player. |
| sm_avfplay_sync() | D | Synchronise with another AVF player |
| sm_avfrec_create() | D | Create AVF recorder |
| sm_avfrec_datafeed_connect() | D | Connect a datafeed to an AVF recorder |
| sm_avfrec_destroy() | D | Destroy a previously allocated AVF recorder |
| sm_avfrec_get_data() | D | Read data from a AVF recorder |
| sm_avfrec_get_event() | D | Obtain an event for a AVF recorder |
| sm_avfrec_start() | D | Starts a previously allocated AVF recorder |
| sm_avfrec_status() | D | Determine AVF recorder status |
| sm_avfrec_stop() | D | Aborts a previously allocated AVF recorder if it is active. |
| sm_avfrec_sync() | D | Synchronise with another AVF recorder |
Key to W column:
| D | Deprecated |
|---|
This document is also available as separate pages for each function.
This function is deprecated.
int sm_avfplay_create(struct sm_avfplay_create_parms *avfcp)
typedef struct sm_avfplay_create_parms {
tSMAVFplayId avfplay; /* out */
tSMModuleId module; /* in */
} SM_AVFPLAY_CREATE_PARMS;
Creates a player which can replay an AVF stream. An AVF player is a task which accepts as input an AVF stream from the host, and generates as output one of a number of data formats including the raw unchanged AVF stream and linear audio.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_destroy(tSMAVFplayId avfplay)
Destroys avfplay invalidating the tSMAVFplayId.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_get_datafeed(struct sm_avfplay_datafeed_parms *datafeedp)
typedef struct sm_avfplay_datafeed_parms {
tSMAVFplayId avfplay; /* in */
tSMDatafeedId datafeed; /* out */
} SM_AVFPLAY_DATAFEED_PARMS;
Request a datafeed identifier from a AVF player. This identifer can
subsequently be used in a call to any of the *_datafeed_connect()
functions to connect the output from the AVF player to a destination.
It is valid until the AVF player is destroyed. Note that the type of
data to be output - e.g. AVF AMR-NB audio stream, linear audio stream,
AVF H.263 video stream, etc. - is set by
sm_avfplay_start()
and that it is the application writer's responsibility to ensure that
any task (e.g. VMP[tx]) connected to the AVF player's datafeed is
able to process this data.
Datafeed connections can only be made between objects allocated on the
same tSMModuleId.
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_get_event(struct sm_avfplay_event_parms *eventp)
typedef struct sm_avfplay_event_parms {
tSMAVFplayId avfplay; /* in */
tSMEventId event; /* out */
} SM_AVFPLAY_EVENT_PARMS;
If the call completes successfully event will hold the tSMEventId belonging to avfplay. The tSMEventId is valid until the AVF player is destroyed using sm_avfplay_destroy(). This event will be signalled when a status change occurs on the AVF player. When the event is signalled the user must call sm_avfplay_status() to discover the nature of the status change.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_put_data(struct sm_avfplay_put_data_parms *datap)
typedef struct sm_avfplay_put_data_parms {
tSMAVFplayId avfplay; /* in */
char *data; /* in */
tSM_INT max_length; /* in */
tSM_INT done_length; /* out */
} SM_AVFPLAY_PUT_DATA_PARMS;
Attempt to write data to a AVF player. Less than the maximum will be written when either:
To permit maximum system throughput, this function refuses to write to an AVF player whose status has changed since it was last checked. This allows an application to avoid checking the status during bulk data transfer. The application only needs to check the status (using sm_avfplay_status()) when a call to sm_avfplay_put_data() returns with done_length equal to zero. If a status change occurs while writing data, done_length may indicate that some, but not all, of the data was written. In this case, often the most convenient way for an application to react is to note how much data has been sent, and to try to send more. Since the new attempt will indicate that no data was written, it means that the application does not need to have different cases to handle a status change at the beginning of the data buffer and a status change after a partial write.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_start(struct sm_avfplay_start_parms *avfsp)
typedef struct sm_avfplay_start_parms {
tSMAVFplayId avfplay; /* in */
enum kSMAVFOutputType {
kSMAVFOutputAVFVideo,
kSMAVFOutputAVFAudio,
kSMAVFOutputLinearAudio,
} dest_type; /* in */
union {
struct {
tSM_INT sampling_rate; /* in */
enum kSMAudioDataFormat {
kSMAudioDataFormatALawPCM,
kSMAudioDataFormatULawPCM,
kSMAudioDataFormatAMRNB,
kSMAudioDataFormat16bit,
kSMAudioDataFormat8bit,
} src_type; /* in */
} audio; /* in */
} u_dest_type; /* in */
tSM_INT hbuf_size; /* in */
tSM_INT test_mode; /* in */
} SM_AVFPLAY_START_PARMS;
Starts the necessary tasks on the module for playback of AVF-encapsulated video or audio.
Note that, unlike most tasks, an AVF player can output different types of data - e.g. AVF AMR-NB audio stream, AVF H.263 video stream, etc. - dependant on how it is started. It is the application writer's responsibility to ensure that any task (e.g. VMP[tx]) connected to the AVF player's datafeed is able to process this data.
Note: The union in in the above struct is used to allow future expansion.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_status(struct sm_avfplay_status_parms *statusp)
typedef struct sm_avfplay_status_parms {
tSMAVFplayId avfplay; /* in */
enum kSMAVFplayStatus {
kSMAVFplayStatusRunning,
kSMAVFplayStatusUnderrun,
kSMAVFplayStatusCompleteData,
kSMAVFplayStatusComplete,
} status; /* out */
} SM_AVFPLAY_STATUS_PARMS;
Returns the current status of the AVF player or an error to indicate that a problem occurred during start-up.
When the event, obtained from sm_avfplay_get_event(), is signalled the user must call this function to determine the nature of the status change. The change in status may indicate that an error occurred whilst processing a user request or it may be notifiying the user of a change to the previous state of the AVF player.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_stop(struct sm_avfplay_stop_parms *avfsp)
typedef struct sm_avfplay_stop_parms {
tSMAVFplayId avfplay; /* in */
tSM_INT immediate; /* in */
} SM_AVFPLAY_STOP_PARMS;
Stops the AVF player tasks.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfplay_sync(struct sm_avfplay_sync_parms *avfsp)
typedef struct sm_avfplay_sync_parms {
tSMAVFplayId avfplay; /* in */
tSMAVFplayId sync_avfplay; /* in */
} SM_AVFPLAY_SYNC_PARMS;
Ensures that all future playbacks on avfplay are synchronised with those on sync_avfplay. To achieve synchronised playbacks following a call to sm_avfplay_sync() , sm_avfplay_start() must be called on both avfplay and sync_avfplay . The playbacks can be started in any order. Once started, the playbacks will not process data until at least one full AVF frame has been put to both. If data is supplied to one playback before the other has started, that data will be buffered until the other playback has received at least one full AVF frame. Once the playbacks begin processing data, they progress as usual.
When two playbacks are synchronised and processing data, if one playback is stopped then restarted it will not re-synchronise with the running playback and an error will be returned. If both playbacks are stopped then restarted, the two playbacks will synchronise as described above.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_create(struct sm_avfrec_create_parms *vcp)
typedef struct sm_avfrec_create_parms {
tSMAVFrecId avfrec; /* out */
tSMModuleId module; /* in */
} SM_AVFREC_CREATE_PARMS;
Creates a recorder which can record an AVF stream. An AVF recorder is a task which accepts as input one of a number of data formats - including a raw AVF stream and linear audio - and generates as output an AVF stream to the host.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_datafeed_connect(struct sm_avfrec_datafeed_connect_parms *datafeedp)
typedef struct sm_avfrec_datafeed_connect_parms {
tSMAVFrecId avfrec; /* in */
tSMDatafeedId data_source; /* in */
} SM_AVFREC_DATAFEED_CONNECT_PARMS;
Connects a datafeed to a AVF recorder. The
data_source
must be a datafeed obtained from
sm_vmprx_get_datafeed()
Datafeed connections can only be made between objects allocated
on the same tSMModuleId.
The AVF recorder
avfrec
will receive any data that is generated by the output task from which
data_source
was derived. Note that the type of data accepted as input - e.g. AVF
AMR-NB audio stream, linear audio stream, AVF H.263 video stream, etc.
- is set by
sm_avfrec_start()
and that it is the application writer's responsibility to ensure that
the output task provides data of the correct type.
To disconnect a AVF recorder from a datafeed, specify
kSMNullDatafeedId as the tSMDatafeedId in
data_source
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error.
This function is deprecated.
int sm_avfrec_destroy(tSMAVFrecId avfrec)
Destroys avfrec invalidating the tSMAVFrecId.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_get_data(struct sm_avfrec_get_data_parms *datap)
typedef struct sm_avfrec_get_data_parms {
tSMAVFrecId avfrec; /* in */
char *data; /* in */
tSM_INT max_length; /* in */
tSM_INT done_length; /* out */
} SM_AVFREC_GET_DATA_PARMS;
Attempt to read data from a AVF recorder. Less than the maximum will be read when either:
To permit maximum system throughput, this function refuses to read from a AVF recorder whose status has changed since it was last checked. This allows an application to avoid checking the status during bulk data transfer. The application only needs to check the status when a call to sm_avfrec_get_data() returns with done_length equal to zero. This also ensures that status changes are reported at the point in the data at which they occurred, which may be important for some applications.
If an error is reported, the done_length field indicates the amount of data which was read before the error occurred.
Any amount of data (up to max_length) may be returned.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_get_event(struct sm_avfrec_event_parms *eventp)
typedef struct sm_avfrec_event_parms {
tSMAVFrecId avfrec; /* in */
tSMEventId event; /* out */
} SM_AVFREC_EVENT_PARMS;
If the call completes successfully event will hold the tSMEventId belonging to avfrec. The tSMEventId is valid until the AVF recorder is destroyed using sm_avfrec_destroy(). This event will be signalled when a status change occurs on the AVF recorder. When the event is signalled the user must call sm_avfrec_status() to discover the nature of the status change.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_start(struct sm_avfrec_start_parms *avfsp)
typedef struct sm_avfrec_start_parms {
tSMAVFrecId avfrec; /* in */
enum kSMAVFInputType {
kSMAVFInputAVFVideo,
kSMAVFInputAVFAudio,
kSMAVFInputLinearAudio,
} src_type; /* in */
union {
struct {
tSM_INT payload_type; /* in */
enum kSMAudioDataFormat dest_type; /* in */
union {
struct {
tSM_INT bitrate; /* in */
tSM_INT vad_enable; /* in */
} amrnb; /* in */
} u_dest_type; /* in */
} audio; /* in */
} u_src_type; /* in */
tSM_INT hbuf_size; /* in */
tSM_INT test_mode; /* in */
} SM_AVFREC_START_PARMS;
Starts the necessary tasks on the module for record of AVF-encapsulated video or audio.
If src_type is set to kSMAVFInputAVFVideo once the AVF recorder has been started, it will not emit any AVF frames to the host until it has received an AVF frame containing a video I-Frame. This helps to ensure that when the resulting video is rendered - e.g. by a 3GP file player - the video starts cleanly. When recording both audio and video, sm_avfrec_sync() can be used to help achieve lipsync even when the video AVF stream to the host starts some time after the audio AVF stream.
Note that, unlike most tasks, an AVF recorder can input different types of data - e.g. AVF AMR-NB audio stream, AVF H.263 video stream, etc. - dependant on how it is started. It is the application writer's responsibility to ensure that the task (e.g. VMP[rx]) to which the AVF rec's datafeed is connected is able to generate this data.
Note: The unions in in the above struct are used to allow future expansion.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_status(struct sm_avfrec_status_parms *statusp)
typedef struct sm_avfrec_status_parms {
tSMAVFrecId avfrec; /* in */
enum kSMAVFrecordStatus {
kSMAVFrecordStatusRunning,
kSMAVFrecordStatusOverrun,
kSMAVFrecordStatusCompleting,
kSMAVFrecordStatusComplete,
} status; /* out */
} SM_AVFREC_STATUS_PARMS;
Returns the current status of the AVF recorder or an error to indicate that a problem occurred during start-up.
When the event, obtained from sm_avfrec_get_event(), is signalled the user must call this function to determine the nature of the status change. The change in status may indicate that an error occurred whilst processing a user request or it may be notifiying the user of a change to the previous state of the AVF recorder.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_stop(struct sm_avfrec_stop_parms *avfsp)
typedef struct sm_avfrec_stop_parms {
tSMAVFrecId avfrec; /* in */
tSM_INT immediate; /* in */
} SM_AVFREC_STOP_PARMS;
Stop the AVF recorder task.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_avfrec_sync(struct sm_avfrec_sync_parms *avfsp)
typedef struct sm_avfrec_sync_parms {
tSMAVFrecId avfrec; /* in */
tSMAVFrecId sync_avfrec; /* in */
} SM_AVFREC_SYNC_PARMS;
Ensures that all future records on avfrec are synchronised with those on sync_avfrec. To achieve synchronised records following a call to sm_avfrec_sync() , sm_avfrec_start() must be called on both, avfrec and sync_avfrec . The records can be started in any order. Once started, the records will not process any data until the first full AVF frame arrives at either. This allows their internal time references to start in step and, therefore, for synchronised playback of a recorded AVF stream pair to be achieved. Once the records begin processing data, they progress as usual.
When two records are synchronised and processing data, if one record is stopped then restarted it will not re-synchronise with the running record and an error will be returned. If both records are stopped then restarted, the two records will synchronise as described above.
0 if call completed successfully, otherwise a standard error such as:
These functions constitute the Prosody Audio Video Format (AVF) API.