[speex-dev] API suggestions

[Christian Buchner]

Hi there. I made a couple of noted regarding the speex API.
These are not meant be seen as critisism - rather constructive
suggestions.

I like speex a lot, but I would like it even more if some
of the following features were available. ;)

Christian

<p>Comments about the Speex API - from a developer's perspective
-------------------------------------------------------------

*** Unnecessary additional work for the developer on Stereo
    sources:

It is unusual to require a different sequence of API calls
depending on whether the signal is Mono or Stereo.
This is especially evident in the decoder where you would
register a callback for the SPEEX_INBAND_STEREO message.
The need for explicitly calling the speex_en/decode_stereo()
function in addition to speex_en/decode() is cumbersome.
All these tasks could be done by the API automatically,
once it knows that it is dealing with a Stereo source.

A unified API not requiring separate code paths would be
helpful.

<p>*** Filling the "bit bucket".

An additional function similar to speex_bits_read_from()
would come in handy. This should append the bytes passed
into it to the bytes already in the buffer instead of
replacing the buffer contents.

The intended use would be for streaming sources that bring
in data in small portions (smaller than an encoded frame).
This way the speex_bits could be used as a buffer.

Suggested name: speex_bits_append_from(). Or alternatively
a flag passed into speex_bits_read_from() signalling whether
to append or to replace.

<p>*** Querying the codec if there's enough data for a full frame
    decode and verifying the bitstream

It appears there is no way to tell in advance if the decoder
has enough information in the speex_bits buffer to decode a full
frame of audio. Sure, after a decode attempt one could see if
speex_bits_remaining() returns a negative value, but this POST
DECODE check would not allow to retry decoding gracefully.

A function like speex_verify_decode(st, &speex_bits) could
perform two functions:
- verify the syntax of the bitstream
- verify that the input data has sufficient length for decoding
  a frame
- but NOT actually perform any decoding

In case either of these conditions are not met, the decoder
could (for example) try to remedy the problem by 
- buffering more data
- notify the sender about corruption and/or request a resend

This function would be required for progressively decoding a
VBR bitstream that contains no side information (page sizes).
Without it, I could not (easily) implement VBR decoding in my
ACM codec. And storing frame sizes between frames is a waste
of bits in a .WAV container ;)

--- >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 'speex-dev-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.