Tremor/doc/example.html

   1 <html>
   2
   3 <head>
   4 <title>Tremor - 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>Tremor documentation</p></td>
  12 <td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>Example Code</h1>
  17
  18 <p>
  19 The following is a run-through of the decoding example program supplied
  20 with libvorbisidec, ivorbisfile_example.c.
  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 "ivorbiscodec.h" and "ivorbisfile.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 "ivorbiscodec.h"
  35 #include "ivorbisfile.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><a href="ov_open.html">ov_open()</a> must be
  91 called to initialize the <b>OggVorbis_File</b> structure with default values.
  92 <a href="ov_open.html">ov_open()</a> also checks to ensure that we're reading Vorbis format and not something else.
  93
  94 <br><br>
  95 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
  96 <tr bgcolor=#cccccc>
  97         <td>
  98 <pre><b>
  99   if(ov_open(stdin, &vf, NULL, 0) < 0) {
 100       fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n");
 101       exit(1);
 102   }
 103
 104 </b></pre>
 105         </td>
 106 </tr>
 107 </table>
 108
 109 <p>
 110 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.
 111 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>.
 112
 113 <br><br>
 114 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 115 <tr bgcolor=#cccccc>
 116         <td>
 117 <pre><b>
 118   {
 119     char **ptr=ov_comment(&vf,-1)->user_comments;
 120     vorbis_info *vi=ov_info(&vf,-1);
 121     while(*ptr){
 122       fprintf(stderr,"%s\n",*ptr);
 123       ++ptr;
 124     }
 125     fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate);
 126     fprintf(stderr,"\nDecoded length: %ld samples\n",
 127             (long)ov_pcm_total(&vf,-1));
 128     fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor);
 129   }
 130
 131 </b></pre>
 132         </td>
 133 </tr>
 134 </table>
 135
 136 <p>
 137 Here's the read loop:
 138
 139 <br><br>
 140 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 141 <tr bgcolor=#cccccc>
 142         <td>
 143 <pre><b>
 144
 145   while(!eof){
 146     long ret=ov_read(&vf,pcmout,sizeof(pcmout),&current_section);
 147     if (ret == 0) {
 148       /* EOF */
 149       eof=1;
 150     } else if (ret < 0) {
 151       /* error in the stream.  Not a problem, just reporting it in
 152          case we (the app) cares.  In this case, we don't. */
 153     } else {
 154       /* we don't bother dealing with sample rate changes, etc, but
 155          you'll have to*/
 156       fwrite(pcmout,1,ret,stdout);
 157     }
 158   }
 159
 160
 161 </b></pre>
 162         </td>
 163 </tr>
 164 </table>
 165
 166 <p>
 167 The code is reading blocks of data using <a href="ov_read.html">ov_read()</a>.
 168 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.
 169
 170 <p>
 171 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.
 172
 173 <br><br>
 174 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 175 <tr bgcolor=#cccccc>
 176         <td>
 177 <pre><b>
 178
 179   ov_clear(&vf);
 180
 181   fprintf(stderr,"Done.\n");
 182   return(0);
 183 }
 184 </b></pre>
 185         </td>
 186 </tr>
 187 </table>
 188
 189 <p>
 190
 191 <br><br>
 192 <hr noshade>
 193 <table border=0 width=100%>
 194 <tr valign=top>
 195 <td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
 196 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
 197 </tr><tr>
 198 <td><p class=tiny>Tremor documentation</p></td>
 199 <td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
 200 </tr>
 201 </table>
 202
 203 </body>
 204
 205 </html>