From XiphWiki
Revision as of 20:27, 22 November 2004 by Arc (talk | contribs) (Application API)
Jump to: navigation, search


  • Abstract:
    • application (app) can be nothing more than a gui frontend to liboggstream
      • allows very simple media players, editors, and stream systems to be developed
      • minimizes duplicated effort (and thus faster deployment)
      • ensures consistant Ogg support for all media players (ie, chaining, seeking, etc)
    • can also be used to just decode codecs, choosing to handle file/stream receiving

  • Technical:
    • apps need to know information about a stream;
      • what codecs it contains
      • what it's total length is (or non-seekable)
    • apps need to be able to exchange uncompressed data with the library for encoding/decoding
    • for non-transcoding operations (ie, streaming), apps also need to be able to exchange raw codec packets
    • when meta/effects codecs are available, apps need to be able to access "processed" and "unprocessed" data
    • support multiple "protocol" plugins (ie, file, http, etc)
      • must provide buffered/cached info for app. (ie, for seek bar to show buffer status)
        • makes it easy to show holes in stream
      • allow app to provide data through "pipe" or "memory" protocol plugin
    • "Auto Update" system for automatic plugin search/installation from central site
      • list licenses and restrictions
        • it should prefer Xiph, then Free, then Proprietary, and finally Commercial
        • this can either be based on their country or simply run with US IP law
      • Linux-based systems can use distro-specific installation method (Gentoo can use Portage, Redhat use RPM, etc)

Application API

An oggs_state object is returned from oggs_create (or a previous one is reset), then input(s) are added with oggs_init_input (one call per input). The oggs_state will expose information about the inputs to the application allowing it to build appropriate outputs. Ie, if an Ogg input is received, the application will know if it needs to define just an pcm audio output, a yuv video output, or some other form of output. Then it'll initialize the outputs, each one connected to one or more inputs. It is the library's job to find a way to convert the input format to the requested output format, or return failure if it cannot.

typedef struct {
  /* Not finished yet */
extern oggs_state *oggs_create(void);
extern int oggs_reset(*oggs_state);
extern int oggs_destroy(*oggs_state);
extern int oggs_init_input(oggs_state *oss,
                           char *method,
                           void *address,);
extern int oggs_init_output(oggs_state *oss,
                            int  num_inputs,
                            int  *input_ids,
                            oggs_format *format);

Plugin API

There are three kinds of plugins: input plugins, codec plugins, and output plugins. These plugins are chained together by liboggstream to connect a "circuit" from the input(s) to the output(s) which fufill the requirements of the client. If a "circuit" cannot be established liboggstream should return an appropriate error, whereas the application can utilize the plugin browser functions to find and install the missing plugins through an appropriate method.

Input Plugins have a method and output a specific format. This format is provided after the plugin is initialized. Multiple input plugins may be opened to pull data from multiple sources (ie, an audio source and video source).

Codec Plugins change the data from one format to another. In almost every case they are needed to satisfy the requirements of the application to process the input format to the output format. They can be used in series to satisfy requirements.

Output Plugins send the formatted data (encoded, transcoded, or decoded) to it's final destination. It needs an output method and is opened with a specific input format. Some output plugins may only support one format (Ogg, pcm, yuv, etc).