RTE Client Interface Overview

This is an overview of the interface between applications and the RTE library. See section Modules for details.

RTE client applications #include <librte.h>.

A rte_context must be allocated to create an output stream, this can be an elementary stream such as mp3 audio, or a complex multiplexed stream with several video and audio tracks.

A rte_codec must be allocated and assigned to a rte_context track to compress raw input to an elementary video or audio stream for this track.

Options

Both contexts and codecs can have options which are assigned by name like variables. These are often canonical (like "sampling_freq", an integer expressing the audio sampling frequency in Hertz), but the same name does not necessarily imply the same semantics in different contexts.

Input Stream Parameters

Codecs need information about the raw data input, for example the image size or audio sample format. These parameters are negotiated with the codec, the client can propose a set of parameters and the codec will return modified parameters shaped by any limitations it has. For example image alignment requirements or supported sample format conversions.

The client can also begin negotiation with a blank set of parameters, the returned defaults will be suitable for the requested kind of stream and the given options. Note some input stream parameters and options seemingly specify the same property. In case of sampling_freq for example that means the codec resamples from the input sampling frequency (device specific parameter) to the encoded sampling frequency (user option).

Input/Output Interface

An input method must be selected for each rte_codec. Data is always passed in blocks of one video image or a fixed number of audio samples. Either the client or the codec can maintain the buffer memory. RTE does not include driver interfaces, the client is responsible for device or file read access.

An output method must be selected for each rte_context. RTE can pass encoded data in blocks or directly write to a file.

Starting and Stopping

This version of RTE will always launch one, sometimes more, subthreads for encoding. This happens when the rte_start() function is called, which returns immediately. The rte_stop() function stops encoding and returns after joining the subthread.

Options, parameters and i/o methods cannot be changed when encoding is in progress.

Status Report

During encoding the context and its codecs can be polled for status information, such as the number of bytes processed or coding time elapsed.

Typical Recording Session

  1. Enumeration of available contexts (i. e. file formats)
  2. Allocation of a context with rte_context_new()
  3. Enumeration of context options
  4. Assignment of context options
  5. Enumeration of available codecs.
    For each elementary stream to be encoded:
    1. Selection of the codec to encode a track with rte_set_codec(), options are reset to their default value
    2. Enumeration of codec options
    3. Assignment of codec options
    4. Input stream parameters negotiation, locks the codec options
    5. Selection of the input method, locks parameters
  6. Selection of the output method, locks the context options and codecs table
  7. Start of recording with rte_start(), no properties can be changed until stopping
  8. Status polling
  9. Stop recording with rte_stop()
  10. rte_context_delete()

The operations in bold face are mandatory, the rest optional.

When a property is locked, changing it resets this and all following properties in the sequence above. Said properties must be renegotiated to proceed. Stopping resets all parameters, input and output methods. Enumeration and get functions are always available.


Generated on Fri Mar 17 20:30:03 2006 for RTE Library by  doxygen 1.4.6