[vorbis] ao changes

[volsung at asu.edu]

On Tue, 21 Aug 2001, Rik Hemsley wrote:

> Why has ao been changed so that there are now two open() functions ?
> 
> IMHO the original ao_open() was fine - if you wanted to set the
> filename for output, you could add an option via ao_append_option
> and if you wanted to avoid overwriting an existing file, you could
> stat() it yourself.
> 
> Having ao_open_live() and ao_open_file() just makes more work for
> the user of the library for no gain, AFAICT.

Sorry for not responding to this earlier.  I've been a bit busy, and wanted to
give a proper answer to this.  I've also CC'ed this to vorbis-dev, since
it is more dev than user related.  I apologize for the length.  Skip to the
end if you are in a hurry. :)

According to the very spartan design principle that a library (or program)
should do only one thing and do it well, file output really doesn't belong in
libao at all.  As Segher pointed out to me at one point (and correctly so),
libaudiofile handle the audio file output problem better and much more
completely than libao ever will.  One could rightly say that I should just
chuck ao_open_file() entirely and tell everyone to use libaudiofile, which is
available everywhere libao currently runs.

I bring this up because it highlights the quandary of file output in
libao.  File output exists in libao because it is convenient, not because it
"belongs" in the library.  Any API encompassing both will feel a little
kludgy, so I don't pretend that the current API is ideal.

The old API was designed around the principle that any output driver *could*
potentially be used with no options (in the ao_option sense) provided.  
Options are for "tweaking knobs" inside the driver and should all have a
sensible default value.  In the case of file output drivers--which in the old
API were opened with the same function as live output drivers--this meant that
the output filename had to be passed as an ao_option, and therefore had to
have a default value (like "output.wav").

At first, I didn't think much of the default filename feature, but now I
consider it downright silly.  If you think about normal usage, I'm sure that
more than 99% of actual usage instances override the default.  Whenever you
want to output audio to a file, you *know* what filename you want to
use.  With the old API, you would have to append a new option specifying the
filename, which is less straightforward than just passing the filename as an
option to the ao_open_file function.  The overwrite flag was just a
convenience option since you were going to let ao_open_file open the file
for you anyway.  It saves you a little code at minimal cost to the library.

Basically, the change was motivated by this notion: If you're going to open a
file for audio output, you should know that you are doing this, and you should
know what the filename is.  Normal open functions in C all make you give the
filename, and libao would be less clear if it did not do the same.

I hope that answers your question.  If not, I'll try to clear it up.  I
haven't totally brain-dumped all my thoughts on the libao API into this
email.  :)


---
Stan Seibert

--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'vorbis-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.