Chapter 4. How to write a decoder

The decoder does the mathematical part of the process of playing a stream. It is separated from the demultiplexers (in the input module), which manage packets to rebuild a continuous elementary stream, and from the output thread, which takes samples reconstituted by the decoder and plays them. Basically, a decoder has no interaction with devices, it is purely algorithmic.

In the next section we will describe how the decoder retrieves the stream from the input. The output API (how to say "this sample is decoded and can be played at xx") will be talked about in the next chapters.

The input thread spawns the appropriate decoder modules from src/input/input_dec.c. The Dec_CreateThread function selects the more accurate decoder module. Each decoder module looks at decoder_config.i_type and returns a score [ see the modules section ]. It then launches module.pf_run(), with a decoder_config_t, described in include/input_ext-dec.h.

The generic decoder_config_t structure, gives the decoder the ES ID and type, and pointers to a stream_control_t structure (gives information on the play status), a decoder_fifo_t and pf_init_bit_stream, which will be described in the next two sections.

The input module provides an advanced API for delivering stream data to the decoders. First let's have a look at the packet structures. They are defined in include/input_ext-dec.h.

data_packet_t contains a pointer to the physical location of data. Decoders should only start to read them at p_payload_start until p_payload_end. Thereafter, it will switch to the next packet, p_next if it is not NULL. If the b_discard_payload flag is up, the content of the packet is messed up and it should be discarded.

data_packet_t are contained into pes_packet_t. pes_packet_t features a chained list (p_first) of data_packet_t representing (in the MPEG paradigm) a complete PES packet. For PS streams, a pes_packet_t usually only contains one data_packet_t. In TS streams though, one PES can be split among dozens of TS packets. A PES packet has PTS dates (see your MPEG specification for more information) and the current pace of reading that should be applied for interpolating dates (i_rate). b_data_alignment (if available in the system layer) indicates if the packet is a random access point, and b_discontinuity tells whether previous packets have been dropped.