Vorbis dev - Jul 2004 - Tutorial/Docs for using libvorbis directly

Hi,


We needed a vorbis decoder that operated differently from the approach taken
libvorbisfile. So I sat down, looked through the docs, and the sample decoder
that come with libvorbis and wrote our own.

Since I couldn't find any docs for the API for libvorbis itself, I've
written
some. It details all the steps you need to go through to write a _basic_
reusable decoder library using libvorbis. It's designed both as a basic
tutorial as to how to build a basic reusable decoder, and also as
documentation.

The reusable core is designed for use as follows:

While decoding and no errors:
Ask for audio - to which we get a response
If we're asked for data,
respond with bytes for decode (received, for example, from a network
socket)
If we get audio we can do something with it. (e.g. go "beep")

Some of it is clearly conjecture as a result of working back from source.
I'd
like to pass the doc and code back to xiph if you're interested. (It does
not
document the internals, just the external API needed for simple decoders -
I'm not an audio person)

As far as I'm aware it's the most detailed document on how to create a
basic
decoder using libvorbis directly.

Regards,


Michael.
--
Michael Sparks, Senior R&D Engineer, Digital Media Group
Michael.Sparks@rd.bbc.co.uk,
British Broadcasting Corporation, Research and Development
Kingswood Warren, Surrey KT20 6NP

On Friday 02 July 2004 02:27, Michael Sparks wrote:
> Hi,
>
>
> We needed a vorbis decoder that operated differently from the approach
> taken libvorbisfile. So I sat down, looked through the docs, and the sample
> decoder that come with libvorbis and wrote our own.
>
> Since I couldn't find any docs for the API for libvorbis itself,
I've
> written some. It details all the steps you need to go through to write a
> _basic_ reusable decoder library using libvorbis. It's designed both as
a
> basic tutorial as to how to build a basic reusable decoder, and also as
> documentation.
Libvorbis documentation hasn't been a priority for us (which is why it
doesn't
already exist), mostly because the vast majority of developers are happy
using libvorbisfile. However, for those that DO need libvorbis directly, this
will be very, very helpful. Thanks a lot for doing this, we really appreciate
any help with documentation.

We'd love to get your code/docs - sending them to this list would be the
best
approach. We'll review things, and commit it to svn.

Thanks in advance,

Mike

<200407020951.29645.msmith@xiph.org>
Message-ID: <004801c45fc9$40fc5380$96e11704@stever>

I haven't yet begun, but I will be, delving into the integration of
vorbis/speex into my program, and I'm trying to decipher what's being
said
here.  Does this amount to creating a library that plays a given ogg file,
using the ogg api?
----- Original Message -----
From: "Michael Smith" <msmith@xiph.org>
To: <Michael.Sparks@rd.bbc.co.uk>; "Michael Sparks"
<michaels@rd.bbc.co.uk>;
<vorbis-dev@xiph.org>
Sent: Thursday, July 01, 2004 7:51 PM
Subject: Re: [Vorbis-dev] Tutorial/Docs for using libvorbis directly

> On Friday 02 July 2004 02:27, Michael Sparks wrote:
> > Hi,
> >
> >
> > We needed a vorbis decoder that operated differently from the approach
> > taken libvorbisfile. So I sat down, looked through the docs, and the
sample
> > decoder that come with libvorbis and wrote our own.
> >
> > Since I couldn't find any docs for the API for libvorbis itself,
I've
> > written some. It details all the steps you need to go through to write
a
> > _basic_ reusable decoder library using libvorbis. It's designed
both as
a
> > basic tutorial as to how to build a basic reusable decoder, and also
as
> > documentation.
>
> Libvorbis documentation hasn't been a priority for us (which is why it
doesn't
> already exist), mostly because the vast majority of developers are happy
> using libvorbisfile. However, for those that DO need libvorbis directly,
this
> will be very, very helpful. Thanks a lot for doing this, we really
appreciate
> any help with documentation.
>
> We'd love to get your code/docs - sending them to this list would be
the
best
> approach. We'll review things, and commit it to svn.
>
> Thanks in advance,
>
> Mike
>
> _______________________________________________
> Vorbis-dev mailing list
> Vorbis-dev@xiph.org
> http://lists.xiph.org/mailman/listinfo/vorbis-dev

<200407020951.29645.msmith@xiph.org>
<004801c45fc9$40fc5380$96e11704@stever>
Message-ID: <200407021145.25651.msmith@xiph.org>

On Friday 02 July 2004 10:12, Steve Russell wrote:
> I haven't yet begun, but I will be, delving into the integration of
> vorbis/speex into my program, and I'm trying to decipher what's
being said
> here.  Does this amount to creating a library that plays a given ogg file,
> using the ogg api?
It's about creating a decoder application (for an ogg vorbis file, not an
arbitrary ogg file - so this isn't relevant for ogg speex) using libvorbis.

However, the vast majority of developers don't want to use libvorbis
directly
- they want to use libvorbisfile. libvorbisfile is a high-level decode
interface, and it's much more convenient to use.

Direct use of libvorbis (which the original poster said he needed) is usually
only needed if libvorbisfile is, for some reason, not usable for a particular
purpose - like if you're trying to get your data from an asychronous data
source.

Mike

<200407020951.29645.msmith@xiph.org>
<004801c45fc9$40fc5380$96e11704@stever>
<200407021145.25651.msmith@xiph.org>
Message-ID: <006d01c45fdb$67a946c0$96e11704@stever>

Thank you for that explanation, which I will not actually be able to
completely comprehend until I start looking into the vorbis code.  What are
"the vast majority of developers" doing with libvorbisfile?  Creating
interactive players for music?  That's not what I'm after, so one audio
expert advised me that I could either play files with DirectShow using only
the few lines of code, installing the Ogg DirectShow filters as part of my
install; or I could create a library that plays a given ogg file using the
ogg API.  Any comment or suggestion of examples in this regard?
----- Original Message -----
From: "Michael Smith" <msmith@xiph.org>
To: "Steve Russell" <srussell@innernet.net>;
<vorbis-dev@xiph.org>
Sent: Thursday, July 01, 2004 9:45 PM
Subject: Re: [Vorbis-dev] Tutorial/Docs for using libvorbis directly

> On Friday 02 July 2004 10:12, Steve Russell wrote:
> > I haven't yet begun, but I will be, delving into the integration
of
> > vorbis/speex into my program, and I'm trying to decipher
what's being
said
> > here.  Does this amount to creating a library that plays a given ogg
file,
> > using the ogg api?
>
> It's about creating a decoder application (for an ogg vorbis file, not
an
> arbitrary ogg file - so this isn't relevant for ogg speex) using
libvorbis.
>
> However, the vast majority of developers don't want to use libvorbis
directly
> - they want to use libvorbisfile. libvorbisfile is a high-level decode
> interface, and it's much more convenient to use.
>
> Direct use of libvorbis (which the original poster said he needed) is
usually
> only needed if libvorbisfile is, for some reason, not usable for a
particular
> purpose - like if you're trying to get your data from an asychronous
data
> source.
>
> Mike
>

<200407020951.29645.msmith@xiph.org>
<004801c45fc9$40fc5380$96e11704@stever>
<200407021145.25651.msmith@xiph.org>
<006d01c45fdb$67a946c0$96e11704@stever>
Message-ID: <20040702023949.GB17939@vergenet.net>

On Thu, Jul 01, 2004 at 10:22:20PM -0400, Steve Russell
wrote:
> Thank you for that explanation, which I will not actually be able to
> completely comprehend until I start looking into the vorbis code.  What are
> "the vast majority of developers" doing with libvorbisfile? 
Creating
> interactive players for music?  That's not what I'm after, so one
audio
> expert advised me that I could either play files with DirectShow using only
> the few lines of code, installing the Ogg DirectShow filters as part of my
> install; or I could create a library that plays a given ogg file using the
> ogg API.  Any comment or suggestion of examples in this regard?
what are you trying to do?

my offer is that you can use libfishsound, which handles both vorbis and
speex:

http://www.annodex.net/software/libfishsound/

docs and examples included there, eg. a full decoder:

http://www.annodex.net/software/libfishsound/html/group__decode.html

Conrad.

<200407020951.29645.msmith@xiph.org>
<004801c45fc9$40fc5380$96e11704@stever>
<200407021145.25651.msmith@xiph.org>
<006d01c45fdb$67a946c0$96e11704@stever>
<20040702023949.GB17939@vergenet.net>
Message-ID: <009c01c45fe0$8263fb40$96e11704@stever>

To answer the question, I'm developing a commercial language program that
will use background music sometimes, but mostly speech.  I buffer up a
sentence or two on each cycle and play it as something like a prompt.  There
will also be stories.  And often a sound effect and/or sentence will fire
immediately when the user makes a mistake (in drag and drop operations, for
instance).  To this point, I am using multimedia and waveOut API.  It's
great, except that with standard wav format we are headed toward several
gigs of audio.

Thank you very much for the links below, which I will surely check out.

----- Original Message -----
From: "Conrad Parker" <conrad@metadecks.org>
---------------------
> what are you trying to do?
>
> my offer is that you can use libfishsound, which handles both vorbis and
> speex:
>
>   http://www.annodex.net/software/libfishsound/
>
> docs and examples included there, eg. a full decoder:
>
>   http://www.annodex.net/software/libfishsound/html/group__decode.html
>
> Conrad.

<200407020951.29645.msmith@xiph.org>
Message-ID: <200407021721.04435.michaels@rd.bbc.co.uk>

On Friday 02 Jul 2004 00:51, Michael Smith wrote:
> We'd love to get your code/docs - sending them to this list would be
the
> best approach. We'll review things, and commit it to svn.
Great - there's a couple of minor things I have to do to the docs/code
before
I send them out, but I'll make sure I send them out on Monday. The review
would be helpful - since some parts are very much conjecture. IMO no docs but
source is better than no docs and no source, and infinitely better than
incorrect documentation.

Regarding the other minor points:
* libvorbis not a priority due to libvorbisfile being generally more
useful - that makes sense and is pretty much what I assumed to
be the case.

* Steve Russell - no, it's not a playback library. It's designed to
allow
you to decode audio that you recieve in a manner that makes using
libvorbisfile awkward.

As Michael Smith wrote scenarios where this happen include where you
recieve data from an asynchronous data source - which is precisely the
scenario I'm in.

Regards,


Michael.
--
Michael Sparks, Senior R&D Engineer, Digital Media Group
Michael.Sparks@rd.bbc.co.uk,
British Broadcasting Corporation, Research and Development
Kingswood Warren, Surrey KT20 6NP

On Friday 02 Jul 2004 00:51, Michael Smith wrote:
> sending them to this list would be the best approach. We'll review
things,
> and commit it to svn.
I tried sending this yesterday, but the size of the tar ball/attachment caused
it to bounce. I've copied the tar ball onto my home DSL box, and you can get
at it here:
* http://www.thwackety.com/bytestobeeps.tar.gz

Since we're hoping it's useful enough to go into your svn tree, and the
code
is heavily derived from the sample decoder that you guys wrote, this code is
covered by whatever license you deem it necessary for inclusion. (this was
suggested by my research leader)

Clearly we would retain copyright (the BBC does this for everything), but
when participating in standards groups we generally adhere to the common
ground rules the group is working to. In this case that means the same
license as vorbis is distributed under. I hope it's useful :)

The actual docs for libvorbis are separated out in the last page, in a format
probably suitable for munging into a separate reference document.

Any comments/corrections welcome :)

Best Regards,


Michael.
--
Michael Sparks, Senior R&D Engineer, Digital Media Group
Michael.Sparks@rd.bbc.co.uk,
British Broadcasting Corporation, Research and Development
Kingswood Warren, Surrey KT20 6NP