AVBlocks for C++  2.1
Audio and Video Software Development Kit
Transcoder Class Referenceabstract

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

Inheritance diagram for Transcoder:
Block Reference

Public Member Functions

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

Protected Member Functions

 ~Transcoder ()
 This object can be destroyed only by the AVBlocks library. More...
 

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 can neither accept, nor deliver data. Inputs and outputs are not modified.

Implements Block.

virtual bool_t endOfStream ( 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.

Implements Block.

virtual const primo::error::ErrorInfo* error ( ) const
pure virtual

Returns the error information for the last operation.

Returns
A pointer to an ErrorInfo object.

Implements Block.

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.

Implements Block.

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.

Implements Block.

virtual bool_t open ( )
pure virtual

Initializes the transcoder based on the specified inputs and outputs.

If this method succeeds the transcoder is ready to process 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_io for more info.

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

Implements Block.

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.

Implements Block.

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.

Each time output data is generated a new MediaBuffer instance is created and attached to outputData. The new MediaBuffer instance belongs to the caller and must be released when it is not needed anymore.

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.
Supported Stream Types
StreamType::LPCM
StreamType::ALAW_PCM
StreamType::MULAW_PCM
StreamType::G726_ADPCM
StreamType::UncompressedVideo
StreamType::MPEG1_Video
StreamType::MPEG2_Video
StreamType::MPEG4_Video
StreamType::H264
StreamType::MPEG_TS
StreamType::MPEG_PSI_PACKETS
StreamType::MPEG_TS_PACKETS
StreamType::WAVE

Implements Block.

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.
Supported Stream Types MediaSample format
StreamType::LPCM
StreamType::ALAW_PCM
StreamType::MULAW_PCM
StreamType::G726_ADPCM
StreamType::UncompressedVideo
StreamType::MPEG1_Video
StreamType::MPEG2_Video
StreamType::MPEG4_Video
StreamType::H264
StreamType::MJPEG
StreamType::MPEG_TS
StreamType::BMP
StreamType::PNG
StreamType::JPEG See Pushing JPEG
StreamType::TIFF
StreamType::GIF

Implements Block.

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
allowDemoMode[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