Libvorbis API Overview

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

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

Encoding workflow

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

Decoding workflow

1. When reading the header packets of an Ogg stream, you can use vorbis_synthesis_idheader to check whether a stream might be Vorbis.
2. Initialize a vorbis_info and a vorbis_comment structure using the appropriate vorbis_*_init routines, then pass the first three packets from the stream (the Vorbis stream header packets) to vorbis_synthesis_headerin in order. At this point, you can see the comments and basic parameters of the Vorbis stream.
3. Initialize a vorbis_dsp_state for decoding based on the parameters in the vorbis_info by using vorbis_synthesis_init.
4. Initialize a vorbis_block structure using vorbis_block_init.
5. While there are more packets to decode:
   1. Decode the next packet into a block using vorbis_synthesis.
   2. Submit the block to the reassembly layer using vorbis_synthesis_blockin.
   3. Obtain some decoded audio using vorbis_synthesis_pcmout and vorbis_synthesis_read. Any audio data returned but not marked as consumed using vorbis_synthesis_read carries over to the next call to vorbis_synthesis_pcmout.
6. Destroy the structures using the appropriate vorbis_*_clear routines.

Metadata workflow

1. Follow the decoding workflow above until you have access to the comments and basic parameters of the Vorbis stream.
2. If you want to alter the comments, copy the first packet to the output file, then create a packet for the modified comments using vorbis_commentheader_out and output it, then copy the third packet and all subsequent packets into the output file.