Dependencies/libvorbis/doc/vorbisfile/example.html

   1 <html>
   2
   3 <head>
   4 <title>Vorbisfile - Example Code</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>Vorbisfile documentation</p></td>
  12 <td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>Decoding Example Code</h1>
  17
  18 <p>
  19 The following is a run-through of the decoding example program supplied
  20 with libvorbisfile, <a href="vorbisfile_example_c.html">vorbisfile_example.c</a>.
  21 This program takes a vorbis bitstream from stdin and writes raw pcm to stdout.
  22
  23 <p>
  24 First, relevant headers, including vorbis-specific "vorbis/codec.h" and "vorbisfile.h" have to be included.
  25
  26 <br><br>
  27 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
  28 <tr bgcolor=#cccccc>
  29         <td>
  30 <pre><b>
  31 #include &lt;stdio.h&gt;
  32 #include &lt;stdlib.h&gt;
  33 #include &lt;math.h&gt;
  34 #include "vorbis/codec.h"
  35 #include "vorbisfile.h"
  36 </b></pre>
  37         </td>
  38 </tr>
  39 </table>
  40 <p>
  41 We also have to make a concession to Windows users here.  If we are using windows for decoding, we must declare these libraries so that we can set stdin/stdout to binary.
  42 <br><br>
  43 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
  44 <tr bgcolor=#cccccc>
  45         <td>
  46 <pre><b>
  47 #ifdef _WIN32
  48 #include &lt;io.h&gt;
  49 #include &lt;fcntl.h&gt;
  50 #endif
  51 </b></pre>
  52         </td>
  53 </tr>
  54 </table>
  55 <p>
  56 Next, a buffer for the pcm audio output is declared.
  57
  58 <br><br>
  59 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
  60 <tr bgcolor=#cccccc>
  61         <td>
  62 <pre><b>
  63 char pcmout[4096];
  64 </b></pre>
  65         </td>
  66 </tr>
  67 </table>
  68
  69 <p>Inside main(), we declare our primary OggVorbis_File structure.  We also declare a few other helpful variables to track out progress within the file.
  70 Also, we make our final concession to Windows users by setting the stdin and stdout to binary mode.
  71 <br><br>
  72 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
  73 <tr bgcolor=#cccccc>
  74         <td>
  75 <pre><b>
  76 int main(int argc, char **argv){
  77   OggVorbis_File vf;
  78   int eof=0;
  79   int current_section;
  80
  81 #ifdef _WIN32
  82   _setmode( _fileno( stdin ), _O_BINARY );
  83   _setmode( _fileno( stdout ), _O_BINARY );
  84 #endif
  85 </b></pre>
  86         </td>
  87 </tr>
  88 </table>
  89
  90 <p>We call <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to
  91 initialize the <b>OggVorbis_File</b> structure with default values.
  92 <a href="ov_open_callbacks.html">ov_open_callbacks()</a> also checks
  93 to ensure that we're reading Vorbis format and not something else. The
  94 OV_CALLBACKS_NOCLOSE callbacks instruct libvorbisfile not to close
  95 stdin later during cleanup.
  96
  97 <br><br>
  98 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
  99 <tr bgcolor=#cccccc>
 100         <td>
 101 <pre><b>
 102   if(ov_open_callbacks(stdin, &vf, NULL, 0, OV_CALLBACKS_NOCLOSE) < 0) {
 103       fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n");
 104       exit(1);
 105   }
 106
 107 </b></pre>
 108         </td>
 109 </tr>
 110 </table>
 111
 112 <p>
 113 We're going to pull the channel and bitrate info from the file using <a href="ov_info.html">ov_info()</a> and show them to the user.
 114 We also want to pull out and show the user a comment attached to the file using <a href="ov_comment.html">ov_comment()</a>.
 115
 116 <br><br>
 117 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 118 <tr bgcolor=#cccccc>
 119         <td>
 120 <pre><b>
 121   {
 122     char **ptr=ov_comment(&vf,-1)->user_comments;
 123     vorbis_info *vi=ov_info(&vf,-1);
 124     while(*ptr){
 125       fprintf(stderr,"%s\n",*ptr);
 126       ++ptr;
 127     }
 128     fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate);
 129     fprintf(stderr,"\nDecoded length: %ld samples\n",
 130             (long)ov_pcm_total(&vf,-1));
 131     fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor);
 132   }
 133
 134 </b></pre>
 135         </td>
 136 </tr>
 137 </table>
 138
 139 <p>
 140 Here's the read loop:
 141
 142 <br><br>
 143 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 144 <tr bgcolor=#cccccc>
 145         <td>
 146 <pre><b>
 147
 148   while(!eof){
 149     long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,&current_section);
 150     if (ret == 0) {
 151       /* EOF */
 152       eof=1;
 153     } else if (ret < 0) {
 154       /* error in the stream.  Not a problem, just reporting it in
 155          case we (the app) cares.  In this case, we don't. */
 156     } else {
 157       /* we don't bother dealing with sample rate changes, etc, but
 158          you'll have to*/
 159       fwrite(pcmout,1,ret,stdout);
 160     }
 161   }
 162
 163
 164 </b></pre>
 165         </td>
 166 </tr>
 167 </table>
 168
 169 <p>
 170 The code is reading blocks of data using <a href="ov_read.html">ov_read()</a>.
 171 Based on the value returned, we know if we're at the end of the file or have invalid data.  If we have valid data, we write it to the pcm output.
 172
 173 <p>
 174 Now that we've finished playing, we can pack up and go home.  It's important to call <a href="ov_clear.html">ov_clear()</a> when we're finished.
 175
 176 <br><br>
 177 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 178 <tr bgcolor=#cccccc>
 179         <td>
 180 <pre><b>
 181
 182   ov_clear(&vf);
 183
 184   fprintf(stderr,"Done.\n");
 185   return(0);
 186 }
 187 </b></pre>
 188         </td>
 189 </tr>
 190 </table>
 191
 192 <p>
 193
 194 <br><br>
 195 <hr noshade>
 196 <table border=0 width=100%>
 197 <tr valign=top>
 198 <td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
 199 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
 200 </tr><tr>
 201 <td><p class=tiny>Vorbisfile documentation</p></td>
 202 <td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
 203 </tr>
 204 </table>
 205
 206 </body>
 207
 208 </html>