AVBlocks for .NET  2.3
Audio and Video Software Development Kit
Transcoder Class Reference

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

Inheritance diagram for Transcoder:
Block

Public Member Functions

 Transcoder ()
 Creates a Transcoder object in its default state. More...
 
override void Close ()
 Closes the Transcoder. More...
 
override void Dispose ()
 Disposes the Transcoder and reclaims the resources used by the object. More...
 
override bool EndOfStream (int inputIndex)
 Tells the Transcoder that there's no more data for the specified input socket. More...
 
override bool Flush ()
 Flushes the data buffered in the Transcoder to the output. More...
 
override bool Open ()
 Initializes the Transcoder based on the specified input and desired output. More...
 
override bool Pull (out int outputIndex, MediaSample outputSample)
 Pulls output data from the Transcoder. More...
 
override bool PullUnmanaged (out int outputIndex, MediaSample outputSample)
 Pulls output data from the Transcoder. More...
 
override bool Push (int inputIndex, MediaSample inputSample)
 Pushes input data to the Transcoder. More...
 
override bool PushUnmanaged (int inputIndex, MediaSample inputSample)
 Pushes input data to the Transcoder. More...
 
bool Run ()
 Runs an automatic transcoding. More...
 

Properties

bool AllowDemoMode [get, set]
 Specifies whether the Transcoder allows demo mode (unlicensed transcoding). More...
 
bool AutoConnect [get, set]
 Specifies whether the Transcoder automatically connects input to output pins when opened. More...
 
override ErrorInfo Error [get]
 The error information for the last transcoder operation. More...
 
override MediaSocketList Inputs [get]
 A modifiable collection of MediaSocket objects which describe the input data of the Transcoder. More...
 
override MediaSocketList Outputs [get]
 A modifiable collection of MediaSocket objects which describe the output data of the Transcoder. More...
 
- Properties inherited from Block
abstract ErrorInfo Error [get]
 The error information for the last block operation. More...
 
abstract MediaSocketList Inputs [get]
 A modifiable collection of MediaSocket objects which describe the input data of the Block. More...
 
abstract MediaSocketList Outputs [get]
 A modifiable collection of MediaSocket objects which describe the output data of the Blocks. More...
 

Events

EventHandler< TranscoderContinueEventArgsOnContinue
 This event is raised by the Transcoder to give the user code a chance to stop the transcoding process started by Transcoder.Run. More...
 
EventHandler< TranscoderInputChangeEventArgsOnInputChange
 This event is raised by the Transcoder when an input format has been detected or has changed. More...
 
EventHandler< TranscoderProgressEventArgsOnProgress
 This event is raised periodically by the Transcoder to report transcoding progress. More...
 
EventHandler< TranscoderStatusEventArgsOnStatus
 This event is raised by the Transcoder to report the status of current operation. More...
 

Detailed Description

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

Constructor & Destructor Documentation

Creates a Transcoder object in its default state.

When the Transcoder object is not needed anymore it should be disposed in order to deterministically reclaim the allocated resources.

References Transcoder.Inputs.

Member Function Documentation

override void Close ( )
virtual

Closes the Transcoder.

When closed it can neither accept, nor deliver data.

Transcoder.Inputs and Transcoder.Outputs are not modified.

Implements Block.

override void Dispose ( )
virtual

Disposes the Transcoder and reclaims the resources used by the object.

Implements Block.

override bool EndOfStream ( int  inputIndex)
virtual

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

Parameters
inputIndexSpecifies the index of the input socket for which there's no more data.
Returns
true if the operation is sucessfull; otherwise false.

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

Implements Block.

References TranscoderContinueEventArgs.Continue, Transcoder.OnContinue, Transcoder.OnInputChange, Transcoder.OnProgress, and Transcoder.OnStatus.

override bool Flush ( )
virtual

Flushes the data buffered in the Transcoder to the output.

Returns
true if the buffered data is sucessfully flushed; otherwise false.

This method can be used only in write mode.

Implements Block.

override bool Open ( )
virtual

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

Returns
true if the Transcoder is sucessfully initialized and is ready to process data; otherwise false.

If this method succeeds the Transcoder is ready to process input data.

The data flow may be driven by one of 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 both pushes and pulls data to/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 related page "Transcoder Input/Output Model" for more info.

Implements Block.

References Transcoder.Inputs, and Transcoder.Outputs.

override bool Pull ( out int  outputIndex,
MediaSample  outputSample 
)
virtual

Pulls output data from the Transcoder.

Parameters
outputIndexReturns the index of the output socket to which the data belongs.
outputSampleThe MediaSample object receives the output data in the MediaBuffer property.
Returns
true if the Transcoder has successfully generated output, otherwise false.

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 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.ALawPCM
StreamType.MuLawPCM
StreamType.G726ADPCM
StreamType.UncompressedVideo
StreamType.Mpeg1Video
StreamType.Mpeg2Video
StreamType.Mpeg4Video
StreamType.H264
StreamType.MpegTS
StreamType.MpegPsiPackets
StreamType.MpegTsPackets
StreamType.Wave

Implements Block.

References MediaSample.Buffer, Transcoder.PullUnmanaged(), UnmanagedMediaBuffer.Release(), and MediaSample.UnmanagedBuffer.

override bool PullUnmanaged ( out int  outputIndex,
MediaSample  outputSample 
)
virtual

Pulls output data from the Transcoder.

Parameters
outputIndexReturns the index of the output socket to which the data belongs.
outputSampleThe MediaSample object receives the output data in the UnmanagedMediaBuffer property.
Returns
true if the Transcoder has successfully generated output, otherwise false.

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 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.

Implements Block.

Referenced by Transcoder.Pull().

override bool Push ( int  inputIndex,
MediaSample  inputSample 
)
virtual

Pushes input data to the Transcoder.

Parameters
inputIndexSpecifies the index of the input socket whose data is pushed to the Transcoder.
inputSampleA MediaSample object that contains the input data in the MediaBuffer property. 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. When this method returns successfully the MediaBuffer.DataSize and the MediaBuffer.DataOffset are updated to reflect how much data is left and where it starts in the buffer. This must be taken into consideration if more data should be appended for subsequent pushing.
Returns
true when the Transcoder has successfully processed some or all of the input data, otherwise false.

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.InputFull when it cannot accept the input. In this case 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.ALawPCM
StreamType.MuLawPCM
StreamType.G726ADPCM
StreamType.UncompressedVideo
StreamType.Mpeg1Video
StreamType.Mpeg2Video
StreamType.Mpeg4Video
StreamType.H264
StreamType.Mjpeg
StreamType.MpegTS
StreamType.Bmp
StreamType.Png
StreamType.Jpeg See Pushing JPEG
StreamType.Tiff
StreamType.Gif

Implements Block.

References MediaSample.Buffer, MediaBuffer.DataOffset, MediaBuffer.DataSize, UnmanagedMediaBuffer.DataSize, Transcoder.PushUnmanaged(), MediaBuffer.SetData(), MediaBuffer.Start, and MediaSample.UnmanagedBuffer.

override bool PushUnmanaged ( int  inputIndex,
MediaSample  inputSample 
)
virtual

Pushes input data to the Transcoder.

Parameters
inputIndexSpecifies the index of the input socket whose data is pushed to the Transcoder.
inputSampleA MediaSample object that contains the input data in the UnmanagedMediaBuffer property. 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. When this method returns successfully the UnmanagedMediaBuffer.DataSize and the UnmanagedMediaBuffer.DataOffset are updated to reflect how much data is left and where it starts in the buffer. This must be taken into consideration if more data should be appended for subsequent pushing.
Returns
true when the Transcoder has successfully processed some or all of the input data, otherwise false.

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.InputFull when it cannot accept the input. In this case 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.

Implements Block.

Referenced by Transcoder.Push().

bool Run ( )

Runs an automatic transcoding.

Returns
true when the transcoding has succeeded.

false when 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. This 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 Push().

Property Documentation

bool AllowDemoMode
getset

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

If true a demo watermark is applied when a required feature (codec/format) is not licensed. If false the Transcoder returns an AVBlocksError.UnlicensedFeature error instead of applying the demo watermark when a required feature is not licensed.

bool AutoConnect
getset

Specifies whether the Transcoder automatically connects input to output pins when opened.

Only pins that have their ID property equal to PinConnection.Auto participate in the automatic connection. Those pins that are sucessfully connected have their ID property set to a unique value that is greater than PinConnection.Auto.

See also
MediaPin.Connection
override ErrorInfo Error
get

The error information for the last transcoder operation.

See also
ErrorInfo
override MediaSocketList Inputs
get

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.

The default value of this property is an empty collection which can be modified but it cannot be replaced.

Referenced by Transcoder.Open(), and Transcoder.Transcoder().

override MediaSocketList Outputs
get

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.

The default value of this property is an empty collection which can be modified but it cannot be replaced.

Referenced by Transcoder.Open().

Event Documentation

EventHandler<TranscoderContinueEventArgs> OnContinue

This event is raised by the Transcoder to give the user code a chance to stop the transcoding process started by Transcoder.Run.

When instructed the Transcoder stops the transcoding process gracefully so that the media data processed so far is valid (playable).

This event is called as often as possible so that the user code may stop the transcoding process as soon as it is required. For this reason there should be minimal processing in this event, otherwise the overall transcoding may be slowed down.

See also
TranscoderContinueEventArgs

Referenced by Transcoder.EndOfStream().

EventHandler<TranscoderInputChangeEventArgs> OnInputChange

This event is raised by the Transcoder when an input format has been detected or has changed.

The user code has a chance to inspect detected inputs, re-configure outputs, connect or disable pins.

Currently this event is raised by the Transcoder when an input socket is configured without pins and the input stream is pushed via Transcoder.Push(). The event is called when the input format is detected and after the appropriate pins are added to the input socket. The user code may inspect the input pins and can decide which pins to connect (via MediaPin.Connection. It may also add or remove output sockets and pins. The Transcoder is fully initialized only after all inputs have been detected and the user code returns from the event.

See also
TranscoderInputChangeEventArgs

Referenced by Transcoder.EndOfStream().

EventHandler<TranscoderProgressEventArgs> OnProgress

This event is raised periodically by the Transcoder to report transcoding progress.

See Transcoder.Run.

For performance reasons this event is not raised for every processed media sample. Currently it is called once for every 0.5 seconds of processed media data. This notification is intended for user interface updates.

The transcoding progress in percents is given by the properties of TranscoderProgressEventArgs:
(CurrentTime / TotalTime * 100).
The Transcoder does not guarantee that CurrentTime will ever reach TotalTime even when the transcoding completes sucessfully.

See also
TranscoderProgressEventArgs

Referenced by Transcoder.EndOfStream().

EventHandler<TranscoderStatusEventArgs> OnStatus

This event is raised by the Transcoder to report the status of current operation.

See also
TranscoderStatusEventArgs, TranscoderStatus

Referenced by Transcoder.EndOfStream().