Codec

A codec usually works in one of the following modes:

• Frame based mode. In this mode, the codec accepts one frame of data from its input and converts it to one frame of output data. The codec must consume its input Buffer and generate an output Buffer.

  This mode is useful when the codec can handle any size of input. A simple gain codec fits this model: it multiplies each sample with the gain factor and puts the product in an output Buffer. Another scenario where this mode is useful is when the codec can only process data that's in a fixed, pre-determined frame size and the input Buffer is already packetized accordingly. One example of such a codec is a GSM audio decoder, which accepts a compressed GSM audio packet from an RTP depacketizer, decodes the packet, and then puts the result in an output Buffer.
   

• Stream based mode. In this mode, the codec accepts chunks of data from its input and might generate an output Buffer. The codec might consume only part of the input Buffer each time its process method is called and might not generate an output Buffer during each round of processing. This mode is useful in stream packetizers, which accept a stream of bytes and divide the stream into packets (frames) that are used in the next processing phase. Another scenario where this mode is useful is when two audio processing units that have incompatible frame sizes need to be chained.

Some restrictions apply to the processing a Codec can perform on its input and output Buffer objects:

• The Codec might receive an output Buffer that is not big enough to hold its output data. In this case, the Codec should allocate a new Buffer for its output data.
   
• The Codec cannot cache references to Buffer object fields. It must read all of the parameters from the input and output Buffer objects each time its process method is called.
   
• If the Codec needs to keep references to a Buffer object's data (for performance reasons), the Codec must assign other data to the input Buffer object by calling setData before returning from the process method. The data assigned can be null, but it is better to assign some unneeded data to the Buffer, such as input data received earlier. Such manipulations can be used for in-place processing (where the output of the processing is put in the same location as input data in order to enhance memory utilization) or for codecs that need access to more than one frame of data without copying the data (for example, temporal video effects).