|
Packit |
06404a |
<html>
|
|
Packit |
06404a |
|
|
Packit |
06404a |
<head>
|
|
Packit |
06404a |
<title>libvorbis - API Overview</title>
|
|
Packit |
06404a |
<link rel=stylesheet href="style.css" type="text/css">
|
|
Packit |
06404a |
</head>
|
|
Packit |
06404a |
|
|
Packit |
06404a |
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
libvorbis documentation
|
|
Packit |
06404a |
libvorbis version 1.3.2 - 20101101
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Libvorbis API Overview
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Libvorbis is the reference implementation of the Vorbis codec. It is
|
|
Packit |
06404a |
the lowest-level interface to the Vorbis encoder and decoder, working
|
|
Packit |
06404a |
with packets directly.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
All libvorbis routines and structures are declared in "vorbis/codec.h".
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Encoding workflow
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Initialize a vorbis_info structure
|
|
Packit |
06404a |
by calling vorbis_info_init and
|
|
Packit |
06404a |
then functions from libvorbisenc
|
|
Packit |
06404a |
on it.
|
|
Packit |
06404a |
Initialize a vorbis_dsp_state
|
|
Packit |
06404a |
for encoding based on the parameters in the vorbis_info by using
|
|
Packit |
06404a |
href="vorbis_analysis_init.html">vorbis_analysis_init.
|
|
Packit |
06404a |
Initialize a vorbis_comment
|
|
Packit |
06404a |
structure using vorbis_comment_init,
|
|
Packit |
06404a |
populate it with any comments you wish to store in the stream, and call
|
|
Packit |
06404a |
vorbis_analysis_headerout to
|
|
Packit |
06404a |
get the three Vorbis stream header packets. Output the packets.
|
|
Packit |
06404a |
Initialize a vorbis_block structure
|
|
Packit |
06404a |
using vorbis_block_init.
|
|
Packit |
06404a |
While there is more audio to encode:
|
|
Packit |
06404a |
Submit a chunk of audio data using
|
|
Packit |
06404a |
href="vorbis_analysis_buffer.html">vorbis_analysis_buffer and
|
|
Packit |
06404a |
href="vorbis_analysis_wrote.html">vorbis_analysis_wrote.
|
|
Packit |
06404a |
Obtain all available blocks using
|
|
Packit |
06404a |
href="vorbis_analysis_blockout.html">vorbis_analysis_blockout
|
|
Packit |
06404a |
in a loop. For each block obtained:
|
|
Packit |
06404a |
Encode the block into a packet (or prepare it for bitrate management)
|
|
Packit |
06404a |
using vorbis_analysis. (It's a good
|
|
Packit |
06404a |
idea to always pass the blocks through the bitrate
|
|
Packit |
06404a |
management mechanism; more information is on the
|
|
Packit |
06404a |
href="vorbis_analysis.html">vorbis_analysis page. It does not affect
|
|
Packit |
06404a |
the resulting packets unless you are actually using a bitrate-managed
|
|
Packit |
06404a |
mode.)
|
|
Packit |
06404a |
If you are using bitrate management, submit the block using
|
|
Packit |
06404a |
href="vorbis_bitrate_addblock.html">vorbis_bitrate_addblock and obtain
|
|
Packit |
06404a |
packets using
|
|
Packit |
06404a |
href="vorbis_bitrate_flushpacket.html">vorbis_bitrate_flushpacket.
|
|
Packit |
06404a |
Output any obtained packets.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Submit an empty buffer to indicate the end of input; this will result
|
|
Packit |
06404a |
in an end-of-stream packet after all encoding steps are done to it.
|
|
Packit |
06404a |
Destroy the structures using the appropriate vorbis_*_clear routines.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Decoding workflow
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Note: if you do not need to do anything more involved than just
|
|
Packit |
06404a |
decoding the audio from an Ogg Vorbis file, you can use the far simpler
|
|
Packit |
06404a |
libvorbisfile interface, which
|
|
Packit |
06404a |
will take care of all of the demuxing and low-level decoding operations
|
|
Packit |
06404a |
(and even the I/O, if you want) for you.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
When reading the header packets of an Ogg stream, you can use
|
|
Packit |
06404a |
href="vorbis_synthesis_idheader.html">vorbis_synthesis_idheader to
|
|
Packit |
06404a |
check whether a stream might be Vorbis.
|
|
Packit |
06404a |
Initialize a vorbis_info and a
|
|
Packit |
06404a |
href="vorbis_comment.html">vorbis_comment structure using the
|
|
Packit |
06404a |
appropriate vorbis_*_init routines, then pass the first three packets
|
|
Packit |
06404a |
from the stream (the Vorbis stream header packets) to
|
|
Packit |
06404a |
href="vorbis_synthesis_headerin.html">vorbis_synthesis_headerin in
|
|
Packit |
06404a |
order. At this point, you can see the comments and basic parameters of
|
|
Packit |
06404a |
the Vorbis stream.
|
|
Packit |
06404a |
Initialize a vorbis_dsp_state
|
|
Packit |
06404a |
for decoding based on the parameters in the vorbis_info by using
|
|
Packit |
06404a |
href="vorbis_synthesis_init.html">vorbis_synthesis_init.
|
|
Packit |
06404a |
Initialize a vorbis_block structure
|
|
Packit |
06404a |
using vorbis_block_init.
|
|
Packit |
06404a |
While there are more packets to decode:
|
|
Packit |
06404a |
Decode the next packet into a block using
|
|
Packit |
06404a |
href="vorbis_synthesis.html">vorbis_synthesis.
|
|
Packit |
06404a |
Submit the block to the reassembly layer using
|
|
Packit |
06404a |
href="vorbis_synthesis_blockin.html">vorbis_synthesis_blockin.
|
|
Packit |
06404a |
Obtain some decoded audio using
|
|
Packit |
06404a |
href="vorbis_synthesis_pcmout.html">vorbis_synthesis_pcmout and
|
|
Packit |
06404a |
href="vorbis_synthesis_read.html">vorbis_synthesis_read. Any audio data
|
|
Packit |
06404a |
returned but not marked as consumed using vorbis_synthesis_read carries
|
|
Packit |
06404a |
over to the next call to vorbis_synthesis_pcmout.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Destroy the structures using the appropriate vorbis_*_clear routines.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Metadata workflow
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Note: if you do not need to do anything more involved than just
|
|
Packit |
06404a |
reading the metadata from an Ogg Vorbis file,
|
|
Packit |
06404a |
href="../vorbisfile/index.html">libvorbisfile can do this for you.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
Follow the decoding workflow above until you have access to the comments
|
|
Packit |
06404a |
and basic parameters of the Vorbis stream.
|
|
Packit |
06404a |
If you want to alter the comments, copy the first packet to the output
|
|
Packit |
06404a |
file, then create a packet for the modified comments using
|
|
Packit |
06404a |
href="vorbis_commentheader_out.html">vorbis_commentheader_out and output
|
|
Packit |
06404a |
it, then copy the third packet and all subsequent packets into the output
|
|
Packit |
06404a |
file.
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
copyright © 2010 Xiph.Org
|
|
Packit |
06404a |
Ogg Vorbis
|
|
Packit |
06404a |
|
|
Packit |
06404a |
libvorbis documentation
|
|
Packit |
06404a |
libvorbis version 1.3.2 - 20101101
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
|
|
Packit |
06404a |
</body>
|
|
Packit |
06404a |
|
|
Packit |
06404a |
</html>
|
|
Packit |
06404a |
|