Transcoder Class Reference

Provides functionality for audio and video encoding, decoding and transforming. More...

Inherits Reference.

List of all members.

Public Member Functions
virtual MediaSocketList *	inputs () const =0
	Returns a modifiable collection of MediaSocket objects which describe the input data of the Transcoder.
virtual MediaSocketList *	outputs () const =0
	Returns a modifiable collection of MediaSocket objects which describe the output data of the Transcoder.
virtual void	setAutoConnect (bool_t autoConnect)=0
	Sets the autoConnect property of the transcoder.
virtual bool_t	autoConnect () const =0
	Returns the autoConnect property of the transcoder.
virtual bool_t	open ()=0
	Initializes the transcoder based on the specified input and desired output.
virtual bool_t	run ()=0
	Runs an automatic transcoding.
virtual bool_t	push (int32_t inputIndex, primo::codecs::MediaSample *inputSample)=0
	Pushes input data to the Transcoder.
virtual bool_t	pull (int32_t &outputIndex, primo::codecs::MediaSample *outputData)=0
	Pulls output data from the transcoder.
virtual void	close ()=0
	Closes the transcoder.
virtual bool_t	flush ()=0
	Flushes the data buffered in the transcoder to the output.
virtual bool_t	stop (int32_t inputIndex)=0
	Tells the transcoder that there's no more data for the specified input socket.
virtual void	setCallback (primo::avblocks::TranscoderCallback *callback)=0
	Sets a TranscoderCallback instance which is used to receive notifications from the transcoder.
virtual primo::avblocks::TranscoderCallback *	callback ()=0
	Returns the TranscoderCallback object that is used by the Transcoder to send notifications and events while running.
virtual const ErrorInfo *	error () const =0
	Returns the error information for the last operation.
virtual void	setAllowDemoMode (bool_t allowDemoMode)=0
	Sets whether demo mode (unlicensed transcoding) should be allowed by the Transcoder.
virtual bool_t	allowDemoMode () const =0
	Returns whether the Transcoder allows demo mode (unlicensed transcoding).
Protected Member Functions
	~Transcoder ()
	This object can be destroyed only by the AVBlocks library.

---

Detailed Description

Provides functionality for audio and video encoding, decoding and transforming.

---

Constructor & Destructor Documentation

~Transcoder

(

)

[protected]

This object can be destroyed only by the AVBlocks library.

The caller must use Reference::release.

See also:

Object Management

---

Member Function Documentation

virtual bool_t allowDemoMode

(

)

const [pure virtual]

Returns whether the Transcoder allows demo mode (unlicensed transcoding).

Returns:

If TRUE a demo overlay (watermark) is applied when a required codec is not licensed. If FALSE the Transcoder returns an error (AVBlocksError::UnlicensedFeature) instead of applying the demo overlay when a required codec is not licensed.

Remarks:

The default value is TRUE in the Demo release and FALSE in the OEM release.

virtual bool_t autoConnect

(

)

const [pure virtual]

Returns the autoConnect property of the transcoder.

Returns:

TRUE the transcoder automatically maps input to output pins when opened.

virtual primo::avblocks::TranscoderCallback* callback

(

)

[pure virtual]

Returns the TranscoderCallback object that is used by the Transcoder to send notifications and events while running.

Returns:

A pointer to TranscoderCallback object or NULL if the callback is not set.

virtual void close

(

)

[pure virtual]

Closes the transcoder.

When closed it cannot accept data. Inputs and outputs are not modified.

virtual bool_t flush

(

)

[pure virtual]

Flushes the data buffered in the transcoder to the output.

This method can be used only in push mode.

Returns:

TRUE if the buffered data is successfully flushed, otherwise FALSE.

Remarks:

This method also marks the end-of-stream for all inputs. No data should be pushed to the transcoder after it is flushed.

virtual MediaSocketList* inputs

(

)

const [pure virtual]

Returns a modifiable collection of MediaSocket objects which describe the input data of the Transcoder.

Each socket in the collection represents an input point - it can be a container with one or more streams or just an elementary stream.

Returns:

A pointer to a collection of input sockets. Cannot be NULL.

The returned collection exists only in the context of the Transcoder. The caller cannot influence the lifetime of the returned object.

virtual bool_t open

(

)

[pure virtual]

Initializes the transcoder based on the specified input and desired output.

If this method succeeds the transcoder is ready to process input data. The data flow may be driven by the following methods:

• push() - The caller pushes input data to the transcoder. The transcoder writes the output data to a file or user stream.
• pull() - The caller pulls output data from the transcoder. The transcoder reads the input data from a file or user stream.
• push() and pull() - The caller pushes input data to the transcoder. It also pulls the output data from the transcoder.
• run() - The caller waits for the transcoding to finish. The transcoder automatically reads the input data from a file or user stream and writes the output to a file or user stream. The process runs until the input data is depleted or there's a processing error.

However not all stream types can be used in push or pull mode. See Transcoder Input/Output Model for more info.

Returns:

TRUE	The transcoder is successfully initialized and is ready to process data.
FALSE	The transcoder cannot process the specified input and output data.

virtual MediaSocketList* outputs

(

)

const [pure virtual]

Returns a modifiable collection of MediaSocket objects which describe the output data of the Transcoder.

Each socket in the collection describes an output point - it can be a container with one or more streams or just an elementary stream.

Returns:

A pointer to a collection of output sockets. Cannot be NULL.

The returned collection exists only in the context of Transcoder. The caller cannot influence the lifetime of the returned object.

virtual bool_t pull	(	int32_t &	outputIndex,
		primo::codecs::MediaSample *	outputData
	)		[pure virtual]

Pulls output data from the transcoder.

Parameters:

outputIndex	[out] contains the index of the output socket to which the data belongs.
outputData	[out] A pointer to a MediaSample object that receives the output data. When the method returns successfully the outputData contains the output sample. The MediaBuffer is provided by the AVBlocks library. It is valid until the next call to Transcoder::pull The MediaBuffer is lost when the Transcoder object is closed or released.

Returns:

TRUE The transcoder has successfully generated output, otherwise FALSE.

Remarks:

In order to use the pull mode the output sockets must not have an associated file or user stream. If the transcoder operates in the hybrid push/pull mode it will return TranscoderError::InputNeeded when there's no available output. In this case Transcoder::push() must be called to supply input data to the transcoder.

Warning:

This method is not thread-safe (as all other functions in AVBlocks). It cannot be called simultaneously from multiple threads. You must implement your own synchronization if the method will be called from multiple threads.

virtual bool_t push	(	int32_t	inputIndex,
		primo::codecs::MediaSample *	inputSample
	)		[pure virtual]

Pushes input data to the Transcoder.

Parameters:

inputIndex

[in] Specifies the index of the input socket whose data is pushed to the Transcoder.

inputSample

[in] A pointer to a MediaSample object that contains the input data. The MediaSample provided is used only within this method and the object is not retained by the Transcoder. It is not guaranteed that the whole input will be consumed (read) by the Transcoder after this method has returned. It's possible that the Transcoder may consume only part of the provided input data. In this case the Transcoder will increment the MediaBuffer::dataOffset with the number of bytes read and the free space in the buffer will become fragmented. This must be taken into consideration if more data should be appended for subsequent pushing.

Returns:

TRUE The transcoder has successfully processed the input data, otherwise FALSE.

Remarks:

In order to use this method the input socket must not have an associated file or user stream. If the transcoder operates in the hybrid push/pull mode it will return TranscoderError::BufferFull when it cannot accept the input. In this case Transcoder::pull() must be called to retrieve the available output.

Note:

The input sample can contain an image like bmp, png or jpeg. This makes it possible to create a video from one or more images with any duration. The start time of each input sample must be set explicitly and must increase for each successive sample.

Warning:

This method is not thread-safe (as all other functions in AVBlocks). It cannot be called simultaneously from multiple threads. You must implement your own synchronization if the method will be called from multiple threads.

virtual bool_t run

(

)

[pure virtual]

Runs an automatic transcoding.

Returns:

TRUE The transcoding has succeeded. FALSE There's a transcoding error or the run() method cannot be used with the specified inputs and outputs.

In order to use the run mode all input and output sockets must be associated with files or user streams. The method returns when the transcoding is finished because there's no more input data to process or when there's an error.

Note:

The input socket can specify an image file in which case the output video contains a single frame. A single frame video (MPEG-2) can be used as a background in DVD-Video authoring. For generating a custom video from many images see Transcoder::push.

virtual void setAllowDemoMode

(

bool_t

allowDemoMode

)

[pure virtual]

Sets whether demo mode (unlicensed transcoding) should be allowed by the Transcoder.

Parameters:

autoDemoMode

[in] specifies whether unlicensed transcoding is allowed.

Remarks:

The demo mode is enabled by default in the Demo release but not in the OEM release of AVBlocks. Therefore in order to test transcoding with the OEM release without a valid license the transcoder demo mode must be enabled explicitly.

virtual void setAutoConnect

(

bool_t

autoConnect

)

[pure virtual]

Sets the autoConnect property of the transcoder.

If autoConnect is TRUE the transcoder automatically maps input to output pins when opened.

Parameters:

autoConnect

[in] specifies to auto connect input and output pins.

virtual void setCallback

(

primo::avblocks::TranscoderCallback *

callback

)

[pure virtual]

Sets a TranscoderCallback instance which is used to receive notifications from the transcoder.

The TranscoderCallback is used only when the transcoding is performed via Transcoder::run.

Parameters:

callback

[in] A pointer to TranscoderCallback object that will be invoked by the transcoder while running. It is allowed to set a NULL object.

Internally the TranscoderCallback specified by setCallback is retained (if not NULL). The previous TranscoderCallback is released (if not NULL). The TranscoderCallback instance is released when the Transcoder itself is being destroyed.

Note:

If the user code inherits from TranscoderCallback but does not override primo::Reference::release() and primo::Reference::retain() it must ensure that the callback instance is valid until it is used by the transcoder. This is so because the default implementation of primo::Reference in TranscoderCallback keeps a constant reference count of 1.

See also:

TranscoderCallback

virtual bool_t stop

(

int32_t

inputIndex

)

[pure virtual]

Tells the transcoder that there's no more data for the specified input socket.

If the last input socket is stopped the transcoder flushes its internal buffers to the output. This method can be used only in push mode.

Parameters:

inputIndex

[in] specifies the index of the input socket for which there's no more data.

Returns:

TRUE if the operation is successful, otherwise FALSE.