| 1 | <html>
|
|---|
| 2 |
|
|---|
| 3 | <head>
|
|---|
| 4 | <title>libvorbis - API Overview</title>
|
|---|
| 5 | <link rel=stylesheet href="style.css" type="text/css">
|
|---|
| 6 | </head>
|
|---|
| 7 |
|
|---|
| 8 | <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
|
|---|
| 9 | <table border=0 width=100%>
|
|---|
| 10 | <tr>
|
|---|
| 11 | <td><p class=tiny>libvorbis documentation</p></td>
|
|---|
| 12 | <td align=right><p class=tiny>libvorbis version 1.3.2 - 20101101</p></td>
|
|---|
| 13 | </tr>
|
|---|
| 14 | </table>
|
|---|
| 15 |
|
|---|
| 16 | <h1>Libvorbis API Overview</h1>
|
|---|
| 17 |
|
|---|
| 18 | <p>Libvorbis is the reference implementation of the Vorbis codec. It is
|
|---|
| 19 | the lowest-level interface to the Vorbis encoder and decoder, working
|
|---|
| 20 | with packets directly.</p>
|
|---|
| 21 |
|
|---|
| 22 | <p>All libvorbis routines and structures are declared in "vorbis/codec.h".</p>
|
|---|
| 23 |
|
|---|
| 24 | <h2>Encoding workflow</h2>
|
|---|
| 25 |
|
|---|
| 26 | <ol>
|
|---|
| 27 | <li>Initialize a <a href="vorbis_info.html">vorbis_info</a> structure
|
|---|
| 28 | by calling <a href="vorbis_info_init.html">vorbis_info_init</a> and
|
|---|
| 29 | then functions from <a href="../vorbisenc/index.html">libvorbisenc</a>
|
|---|
| 30 | on it.</li>
|
|---|
| 31 | <li>Initialize a <a href="vorbis_dsp_state.html">vorbis_dsp_state</a>
|
|---|
| 32 | for encoding based on the parameters in the vorbis_info by using <a
|
|---|
| 33 | href="vorbis_analysis_init.html">vorbis_analysis_init</a>.</li>
|
|---|
| 34 | <li>Initialize a <a href="vorbis_comment.html">vorbis_comment</a>
|
|---|
| 35 | structure using <a href="vorbis_comment_init.html">vorbis_comment_init</a>,
|
|---|
| 36 | populate it with any comments you wish to store in the stream, and call
|
|---|
| 37 | <a href="vorbis_analysis_headerout.html">vorbis_analysis_headerout</a> to
|
|---|
| 38 | get the three Vorbis stream header packets. Output the packets.</li>
|
|---|
| 39 | <li>Initialize a <a href="vorbis_block.html">vorbis_block</a> structure
|
|---|
| 40 | using <a href="vorbis_block_init.html">vorbis_block_init</a>.</li>
|
|---|
| 41 | <li>While there is more audio to encode:<ol>
|
|---|
| 42 | <li>Submit a chunk of audio data using <a
|
|---|
| 43 | href="vorbis_analysis_buffer.html">vorbis_analysis_buffer</a> and <a
|
|---|
| 44 | href="vorbis_analysis_wrote.html">vorbis_analysis_wrote</a>.</li>
|
|---|
| 45 | <li>Obtain all available blocks using <a
|
|---|
| 46 | href="vorbis_analysis_blockout.html">vorbis_analysis_blockout</a>
|
|---|
| 47 | in a loop. For each block obtained:<ol>
|
|---|
| 48 | <li>Encode the block into a packet (or prepare it for bitrate management)
|
|---|
| 49 | using <a href="vorbis_analysis.html">vorbis_analysis</a>. (It's a good
|
|---|
| 50 | idea to always pass the blocks through the bitrate
|
|---|
| 51 | management mechanism; more information is on the <a
|
|---|
| 52 | href="vorbis_analysis.html">vorbis_analysis</a> page. It does not affect
|
|---|
| 53 | the resulting packets unless you are actually using a bitrate-managed
|
|---|
| 54 | mode.)</li>
|
|---|
| 55 | <li>If you are using bitrate management, submit the block using <a
|
|---|
| 56 | href="vorbis_bitrate_addblock.html">vorbis_bitrate_addblock</a> and obtain
|
|---|
| 57 | packets using <a
|
|---|
| 58 | href="vorbis_bitrate_flushpacket.html">vorbis_bitrate_flushpacket</a>.</li>
|
|---|
| 59 | <li>Output any obtained packets.</li>
|
|---|
| 60 | </ol></li>
|
|---|
| 61 | </ol></li>
|
|---|
| 62 | <li>Submit an empty buffer to indicate the end of input; this will result
|
|---|
| 63 | in an end-of-stream packet after all encoding steps are done to it.</li>
|
|---|
| 64 | <li>Destroy the structures using the appropriate vorbis_*_clear routines.</li>
|
|---|
| 65 | </ol>
|
|---|
| 66 |
|
|---|
| 67 | <h2>Decoding workflow</h2>
|
|---|
| 68 |
|
|---|
| 69 | <em>Note: if you do not need to do anything more involved than just
|
|---|
| 70 | decoding the audio from an Ogg Vorbis file, you can use the far simpler
|
|---|
| 71 | <a href="../vorbisfile/index.html">libvorbisfile</a> interface, which
|
|---|
| 72 | will take care of all of the demuxing and low-level decoding operations
|
|---|
| 73 | (and even the I/O, if you want) for you.</em>
|
|---|
| 74 |
|
|---|
| 75 | <ol>
|
|---|
| 76 | <li>When reading the header packets of an Ogg stream, you can use <a
|
|---|
| 77 | href="vorbis_synthesis_idheader.html">vorbis_synthesis_idheader</a> to
|
|---|
| 78 | check whether a stream might be Vorbis.</li>
|
|---|
| 79 | <li>Initialize a <a href="vorbis_info.html">vorbis_info</a> and a <a
|
|---|
| 80 | href="vorbis_comment.html">vorbis_comment</a> structure using the
|
|---|
| 81 | appropriate vorbis_*_init routines, then pass the first three packets
|
|---|
| 82 | from the stream (the Vorbis stream header packets) to <a
|
|---|
| 83 | href="vorbis_synthesis_headerin.html">vorbis_synthesis_headerin</a> in
|
|---|
| 84 | order. At this point, you can see the comments and basic parameters of
|
|---|
| 85 | the Vorbis stream.</li>
|
|---|
| 86 | <li>Initialize a <a href="vorbis_dsp_state.html">vorbis_dsp_state</a>
|
|---|
| 87 | for decoding based on the parameters in the vorbis_info by using <a
|
|---|
| 88 | href="vorbis_synthesis_init.html">vorbis_synthesis_init</a>.</li>
|
|---|
| 89 | <li>Initialize a <a href="vorbis_block.html">vorbis_block</a> structure
|
|---|
| 90 | using <a href="vorbis_block_init.html">vorbis_block_init</a>.</li>
|
|---|
| 91 | <li>While there are more packets to decode:<ol>
|
|---|
| 92 | <li>Decode the next packet into a block using <a
|
|---|
| 93 | href="vorbis_synthesis.html">vorbis_synthesis</a>.</li>
|
|---|
| 94 | <li>Submit the block to the reassembly layer using <a
|
|---|
| 95 | href="vorbis_synthesis_blockin.html">vorbis_synthesis_blockin</a>.</li>
|
|---|
| 96 | <li>Obtain some decoded audio using <a
|
|---|
| 97 | href="vorbis_synthesis_pcmout.html">vorbis_synthesis_pcmout</a> and <a
|
|---|
| 98 | href="vorbis_synthesis_read.html">vorbis_synthesis_read</a>. Any audio data
|
|---|
| 99 | returned but not marked as consumed using vorbis_synthesis_read carries
|
|---|
| 100 | over to the next call to vorbis_synthesis_pcmout.</li>
|
|---|
| 101 | </ol></li>
|
|---|
| 102 | <li>Destroy the structures using the appropriate vorbis_*_clear routines.</li>
|
|---|
| 103 | </ol>
|
|---|
| 104 |
|
|---|
| 105 | <h2>Metadata workflow</h2>
|
|---|
| 106 |
|
|---|
| 107 | <em>Note: if you do not need to do anything more involved than just
|
|---|
| 108 | reading the metadata from an Ogg Vorbis file, <a
|
|---|
| 109 | href="../vorbisfile/index.html">libvorbisfile</a> can do this for you.</em>
|
|---|
| 110 |
|
|---|
| 111 | <ol>
|
|---|
| 112 | <li>Follow the decoding workflow above until you have access to the comments
|
|---|
| 113 | and basic parameters of the Vorbis stream.</li>
|
|---|
| 114 | <li>If you want to alter the comments, copy the first packet to the output
|
|---|
| 115 | file, then create a packet for the modified comments using <a
|
|---|
| 116 | href="vorbis_commentheader_out.html">vorbis_commentheader_out</a> and output
|
|---|
| 117 | it, then copy the third packet and all subsequent packets into the output
|
|---|
| 118 | file.</li>
|
|---|
| 119 | </ol>
|
|---|
| 120 |
|
|---|
| 121 | <br><br>
|
|---|
| 122 | <hr noshade>
|
|---|
| 123 | <table border=0 width=100%>
|
|---|
| 124 | <tr valign=top>
|
|---|
| 125 | <td><p class=tiny>copyright © 2010 Xiph.Org</p></td>
|
|---|
| 126 | <td align=right><p class=tiny><a href="https://xiph.org/vorbis/">Ogg Vorbis</a></p></td>
|
|---|
| 127 | </tr><tr>
|
|---|
| 128 | <td><p class=tiny>libvorbis documentation</p></td>
|
|---|
| 129 | <td align=right><p class=tiny>libvorbis version 1.3.2 - 20101101</p></td>
|
|---|
| 130 | </tr>
|
|---|
| 131 | </table>
|
|---|
| 132 |
|
|---|
| 133 | </body>
|
|---|
| 134 |
|
|---|
| 135 | </html>
|
|---|
| 136 |
|
|---|
