Chris@1: Chris@1: Chris@1: Chris@1: libvorbis - API Overview Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1:

libvorbis documentation

libvorbis version 1.3.2 - 20101101

Chris@1: Chris@1:

Libvorbis API Overview

Chris@1: Chris@1:

Libvorbis is the reference implementation of the Vorbis codec. It is Chris@1: the lowest-level interface to the Vorbis encoder and decoder, working Chris@1: with packets directly.

Chris@1: Chris@1:

All libvorbis routines and structures are declared in "vorbis/codec.h".

Chris@1: Chris@1:

Encoding workflow

Chris@1: Chris@1:
    Chris@1:
  1. Initialize a vorbis_info structure Chris@1: by calling vorbis_info_init and Chris@1: then functions from libvorbisenc Chris@1: on it.
    2. Chris@1:
  2. Initialize a vorbis_dsp_state Chris@1: for encoding based on the parameters in the vorbis_info by using vorbis_analysis_init.
    3. Chris@1:
  3. Initialize a vorbis_comment Chris@1: structure using vorbis_comment_init, Chris@1: populate it with any comments you wish to store in the stream, and call Chris@1: vorbis_analysis_headerout to Chris@1: get the three Vorbis stream header packets. Output the packets.
    4. Chris@1:
  4. Initialize a vorbis_block structure Chris@1: using vorbis_block_init.
    5. Chris@1:
  5. While there is more audio to encode:
      Chris@1:
    1. Submit a chunk of audio data using vorbis_analysis_buffer and vorbis_analysis_wrote.
      2. Chris@1:
    2. Obtain all available blocks using vorbis_analysis_blockout Chris@1: in a loop. For each block obtained:
        Chris@1:
      1. Encode the block into a packet (or prepare it for bitrate management) Chris@1: using vorbis_analysis. (It's a good Chris@1: idea to always pass the blocks through the bitrate Chris@1: management mechanism; more information is on the vorbis_analysis page. It does not affect Chris@1: the resulting packets unless you are actually using a bitrate-managed Chris@1: mode.)
        2. Chris@1:
      2. If you are using bitrate management, submit the block using vorbis_bitrate_addblock and obtain Chris@1: packets using vorbis_bitrate_flushpacket.
        3. Chris@1:
      3. Output any obtained packets.
        4. Chris@1:
      3. Chris@1:
    6. Chris@1:
  6. Submit an empty buffer to indicate the end of input; this will result Chris@1: in an end-of-stream packet after all encoding steps are done to it.
    7. Chris@1:
  7. Destroy the structures using the appropriate vorbis_*_clear routines.
    8. Chris@1:
Chris@1: Chris@1:

Decoding workflow

Chris@1: Chris@1: Note: if you do not need to do anything more involved than just Chris@1: decoding the audio from an Ogg Vorbis file, you can use the far simpler Chris@1: libvorbisfile interface, which Chris@1: will take care of all of the demuxing and low-level decoding operations Chris@1: (and even the I/O, if you want) for you. Chris@1: Chris@1:
    Chris@1:
  1. When reading the header packets of an Ogg stream, you can use vorbis_synthesis_idheader to Chris@1: check whether a stream might be Vorbis.
    2. Chris@1:
  2. Initialize a vorbis_info and a vorbis_comment structure using the Chris@1: appropriate vorbis_*_init routines, then pass the first three packets Chris@1: from the stream (the Vorbis stream header packets) to vorbis_synthesis_headerin in Chris@1: order. At this point, you can see the comments and basic parameters of Chris@1: the Vorbis stream.
    3. Chris@1:
  3. Initialize a vorbis_dsp_state Chris@1: for decoding based on the parameters in the vorbis_info by using vorbis_synthesis_init.
    4. Chris@1:
  4. Initialize a vorbis_block structure Chris@1: using vorbis_block_init.
    5. Chris@1:
  5. While there are more packets to decode:
      Chris@1:
    1. Decode the next packet into a block using vorbis_synthesis.
      2. Chris@1:
    2. Submit the block to the reassembly layer using vorbis_synthesis_blockin.
      3. Chris@1:
    3. Obtain some decoded audio using vorbis_synthesis_pcmout and vorbis_synthesis_read. Any audio data Chris@1: returned but not marked as consumed using vorbis_synthesis_read carries Chris@1: over to the next call to vorbis_synthesis_pcmout.
      4. Chris@1:
    6. Chris@1:
  6. Destroy the structures using the appropriate vorbis_*_clear routines.
    7. Chris@1:
Chris@1: Chris@1:

Metadata workflow

Chris@1: Chris@1: Note: if you do not need to do anything more involved than just Chris@1: reading the metadata from an Ogg Vorbis file, libvorbisfile can do this for you. Chris@1: Chris@1:
    Chris@1:
  1. Follow the decoding workflow above until you have access to the comments Chris@1: and basic parameters of the Vorbis stream.
    2. Chris@1:
  2. If you want to alter the comments, copy the first packet to the output Chris@1: file, then create a packet for the modified comments using vorbis_commentheader_out and output Chris@1: it, then copy the third packet and all subsequent packets into the output Chris@1: file.
    3. Chris@1:
Chris@1: Chris@1:

Chris@1:
Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1:

copyright © 2010 Xiph.Org

Ogg Vorbis

libvorbis documentation

libvorbis version 1.3.2 - 20101101

Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: