cannam@86: cannam@86: cannam@86: cannam@86: libvorbis - API Overview cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

libvorbis documentation

libvorbis version 1.3.2 - 20101101

cannam@86: cannam@86:

Libvorbis API Overview

cannam@86: cannam@86:

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

cannam@86: cannam@86:

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

cannam@86: cannam@86:

Encoding workflow

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

Decoding workflow

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

Metadata workflow

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

cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

copyright © 2010 Xiph.Org

Ogg Vorbis

libvorbis documentation

libvorbis version 1.3.2 - 20101101

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: