Mercurial > hg > sv-dependency-builds

annotate src/libvorbis-1.3.3/doc/libvorbis/overview.html @ 86:98c1576536ae

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