Prosody Audio Video Format (AVF): API: sm_avfrec_start

Prototype Definition

int sm_avfrec_start(struct sm_avfrec_start_parms *avfsp)

Parameters

*avfsp
a structure of the following type: 
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;

Description

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.

Fields

avfrec
A tSMAVFrecId that has been prevously created by a call to sm_avfrec_create().
src_type
The type of data expected as input from the datafeed. One of these values:
kSMAVFInputAVFVideo
Expect AVF-encapsulated video frames.
kSMAVFInputAVFAudio
Expect AVF-encapsulated audio frames.
kSMAVFInputLinearAudio
Expect linear audio, converting the supplied AVF-encapsulated audio frames' payload using the audio encoder specified in the dest_type field.
u_src_type
audio
This struct is valid only if src_type is kSMAVFInputAVFAudio or kSMAVFInputLinearAudio
payload_type
The payload type which should be used in the output AVF. Note that on AVF replay the payload type in the AVF is ignored so, in general, the value supplied here is irrelevant. However if, for instance, the resulting file was to be output using a streaming server, the payload type may well be used. This value is ignored unless src_type is kSMAVFInputLinearAudio as it is only in this case that the AVF frames are constructed in the tasks started by this function.
dest_type
This specifies the type of audio to be output - i.e. the encoder to be run on the input linear audio. It is ignored unless src_type is set to kSMAVFInputLinearAudio One of these values:
kSMAudioDataFormatALawPCM
G.711 A-law. This uses 8 bits per sample.
kSMAudioDataFormatULawPCM
G.711 mu-law. This uses 8 bits per sample.
kSMAudioDataFormatAMRNB
AMR-NB. The sampling rate must be 8000Hz.
kSMAudioDataFormat16bit
16-bit linear coding, where each sample is a signed value (-32768 to 32767). The first octet of each sample is the less significant one.
kSMAudioDataFormat8bit
8-bit unsigned linear coding, where each sample is an unsigned value (0 to 255). This is Microsoft's 8-bit format.
u_dest_type
amrnb
This struct is valid only if dest_type is kSMAudioDataFormatAMRNB and is ignored unless src_type is set to kSMAVFInputLinearAudio
bitrate
The speed to use in bits per second. It must be one of the speeds which the AMR codec can encode, which are: 4750, 5150, 5900, 6700, 7400, 7950, 10200, and 12200.
vad_enable
Whether to enable the Voice Activity Detector.
hbuf_size
This must be set to the desired size of the record's buffer on the module in bytes. For audio records 8188 is generally a suitable value. For video records the value depends on the video content but MUST be comfortably larger than the largest AVF frame to be recorded. If set to 0, for src_type kSMAVFInputAVFAudio the assumed size is 8188, and for src_type kSMAVFInputAVFVideo the assumed size is 32764. This value is ignored if src_type is kSMAVFInputLinearAudio and, in this case, a default buffer size is used as for regular audio record. Note that in order to achieve optimum memory allocation on the Prosody X platform, this value should generally be a power of two, minus 4.
test_mode
For Aculab use only: sets the test mode. Must be set to 0 for normal operation.

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody Audio Video Format (AVF) API.