Detailed decoder pseudocode (was: Re: [vorbis-dev] ETA?)

[Monty]

> > Which part?
> 
> Well, my biggest problem is dealing with files.  As you have mentioned
> that fill_buffer() is obsolete, what has replaced it?  ogg_sync_buffer()
> didn't seem to be what I was looking for, as far as I can tell...  am I
> headed in completely the wrong direction?

Ah, OK, I understand where you're headed now.

The libvorbis API is different than the preceeding generations of Ogg.
Unfortunately, the command line player that's there is stuck halfway between.
I'll be cleaning that up this week now that I've got the whole libvorbis API
there.

I've written an example decoder in C (appears below).  It neglects most trivial
error checking (it checks the 'big things') and isn't exactly valid C, but it
will do as an instructional tool for the moment.  Actual code that compiles
(and runs) will be around in a few days, but the example will still be useful
as something simpler and easier to understand before looking at a more
complicated working module.

This looks different than the command line player, but the basic divisions will
be set up the same (eg, there's no 'fill_buffer' in the command line player
right now because that was just a convenience function in the player that made
a bunch of libogg calls.  There will be a similar thing performing the same
function making libvorbis calls in the near future that looks alot like part 
of the below).

OK, now I go get on an airplane.  See you all tomorrow :-)

--- >8 cut here ----

/* ignoring proper error handling, signals, main(), etc :-) */

ogg_sync_state   oy; /* sync and verify incoming physical bitstream */
ogg_stream_state os; /* take physical pages, weld into a logical
                        stream of packets */
ogg_page         og; /* one Ogg bitstream page.  Vorbis packets are inside */
ogg_packet       op; /* one raw packet of data for decode */

vorbis_info      vi; /* struct that stores all the static vorbis bitstream
                        settings */
vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */
vorbis_block     vb; /* local working space for packet->PCM decode */

char *buffer;
int  bytes;
int i;
int eos=0;

/********** Decode setup ************/

ogg_sync_init(&oy); /* Now we can parse pages out of the bitstream */

/* grab some data at the head of the stream.  We want the first page
   (which is guaranteed to be small and only contain the Vorbis stream
   initial header) We need the first page to get the stream serialno. */

/* submit a 4k block (safe size) to libvorbis */
buffer=ogg_sync_buffer(&oy,4096);
bytes=read(STDIN_FILENO,buffer,4096);
ogg_sync_wrote(&oy,bytes);

/* Get the first page. */
if(ogg_sync_pageout(&oy,&og)!=1){ /* error case.  Must not be Vorbis data */}

/* Get the serial number and use it to set up a logical stream */
ogg_stream_init(&os,ogg_page_serialno(&og));

/* extract the initial header from the first page and verify that the
   Ogg bitstream is in fact Vorbis data */

/* I handle the initial header first instead of just having the code
   read all three Vorbis headers at once because reading the initial
   header is an easy way to identify a Vorbis bitstream and it's
   useful to see that functionality seperated out. */

vorbis_info_init(&vi);
if(ogg_stream_pagein(&os,&og)<0){ /* error; stream version mismatch perhaps */}
if(ogg_stream_packetout(&os,&op)!=1){ /* no page? must not be vorbis */}
if(vorbis_info_headerin(&vi,&op)<0){ /* error case; not a vorbis header */}

/* At this point, we're sure we're Vorbis.  We've set up the logical
   (Ogg) bitstream decoder.  Get the comment and codebook headers and
   set up the Vorbis-specific decoder */

/* The next two packets in order are the comment and codebook headers.
   They're likely large and may span multiple pages.  Thus we reead
   and submit data until we get our two packets, watching that no
   pages are missing.  If a page is missing, error out; losing a
   header page is the only place where missing/corrupt data is fatal. */

i=0;
while(i<2){
  while(i<2 && ogg_sync_pageout(&oy,&og)==1){
    ogg_stream_pagein(&os,&og);
    while(i<2){
      int result=ogg_stream_packetout(&os,&op);
      if(result==0)break;
      if(result==-1){
        /* Uh oh; data at some point was corrupted or missing!
           We can't tolerate that in a header.  Die. */
        exit(1);
      }
      vorbis_info_headerin(&vi,&op);
      i++;
    }
  }
  /* no harm in not checking before adding more */
  buffer=ogg_sync_buffer(&oy,4096);
  bytes=read(STDIN_FILENO,buffer,4096);
  ogg_sync_wrote(&oy,bytes);
}

/* OK, got and parsed all three headers. Initialize the Vorbis
   packet->PCM decoder. */
vorbis_synthesis_init(&vd,&vi); /* central decode state */
vorbis_block_init(&vd,&vb);     /* local state for most of the decode
                                   so multiple block decodes can
                                   proceed in parallel.  We could init
                                   multiple vorbis_block structures
                                   for vd here */

/* The rest is just a straight decode loop until end of stream */
while(!eos){
  while(!eos){
    int result=ogg_sync_pageout(&oy,&og);
    if(result==0)break; /* need more data */
    if(result==-1){ /* missing or corrupt data at this page position */
      /* complain */
    }
    ogg_stream_pagein(&os,&og); 
    while(1){
      int result=ogg_stream_packetout(&os,&op);
      if(result==0)break; /* need more data */
      if(result==-1){ /* missing or corrupt data at this page position */
        /* no reason to complain; already complained above */
      }else{
        /* we have a packet.  Decode it */
        char **pcm;
        int samples;

        vorbis_synthesis(&vb,&op);
        vorbis_synthesis_blockin(&vd,&vb);
        samples=vorbis_synthesis_pcmout(&vd,&pcm);
        if(samples>0){
          /* **pcm is a multichannel float vector.  In stereo, for
             example, pcm[0][...] is left, and pcm[1][...] is right.  
             samples is the size of each channel.  Convert the float 
             values (-1.<=range<=1.) to whatever PCM format and write 
             it out */

          /* [ intentionally blank ] */

          vorbis_synthesis_read(&vd,samples); /* tell libvorbis how
                                                 many samples we
                                                 actually consumed */
        }
      }
    }
    if(ogg_page_eos(&og))eos=1;
  }
  if(!eos){
    buffer=ogg_sync_buffer(&oy,4096);
    bytes=read(STDIN_FILENO,buffer,4096);
    if(bytes==0)eos=1;
  }else
    ogg_sync_wrote(&oy,bytes);
}

  /* clean up and exit (this example doesn't deal with the possibility
     of chaining logical streams) */

ogg_sync_clear(&oy);
ogg_stream_clear(&os);

/* ogg_page and ogg_packet structs always point to storage in
   libvorbis.  They're never freed or manipulated directly */

vorbis_info_clear(&vi);
vorbis_synthesis_clear(&vd);
vorbis_block_clear(&vb);

exit(0);

--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/