OggStream

Goals

• 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 required for all OggStream functionality.  */
/* The application must receive a new oggs_state with oggs_create and */
/* return it with oggs_destroy to prevent memory leakage.   To reuse  */
/* an oggs_state for new media the oggs_reset function may be called. */
extern oggs_state *oggs_create(void);
extern int oggs_reset(*oggs_state);
extern int oggs_destroy(*oggs_state);

/* Plugins are specified by requirements rather than name.  Input and */
/* output plugins are chosen based on the desired i/o method, while a */
/* codec plugin is chosen based on its ability to read the oggs_media */
/* provided.  Multiple codec plugins may be setup in series to output */
/* a desired media format, or an application can simply call a single */
/* init_codec with the desired format and allow the library to find a */
/* combination of codec plugins which can fufill the request. Null is */
/* returned if no plugins are available to complete a given request.  */
extern oggs_media *oggs_init_input(oggs_state  *oss,
                                   oggs_method *method);
extern oggs_media *oggs_init_codec(oggs_state  *oss,
                                   oggs_media  *media,
                                   oggs_format *format);
extern int oggs_init_output(oggs_state  *oss,
                            oggs_media  *media,
                            oggs_method *method);

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