Mercurial > hg > sv-dependency-builds

comparison src/libvorbis-1.3.3/doc/libvorbis/overview.html @ 1:05aa0afa9217

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bring in flac, ogg, vorbis
author Chris Cannam
date Tue, 19 Mar 2013 17:37:49 +0000
parents
children
comparison
equal deleted inserted replaced
0:c7265573341e 1:05aa0afa9217
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 &copy; 2010 Xiph.Org</p></td>
126 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">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