Re: [AD] docs: play_audio_stream clarification

[Ben Davis <bnd25@xxxxxxxxxx>]

On Thursday 12 February 2004 9:19 pm, Eric Botcazou wrote:
> > This function creates a new audio stream and starts playing it. The
> > length is the size of each transfer buffer in sample frames, where a
> > sample frame is a single sample point (i.e. value) for mono data or a
> > pair of sample points for stereo data.
>
> This is better (although I think "sample value" instead of "sample point"
> would be even better) but IMHO not yet crystal clear because...

Go for "a single sample value for mono data" then. I agree, it's more 
intuitive.

> > The length should normally be (but doesn't have to
> > be) a power of two somewhere around 1k in size. Larger buffers are more
> > efficient and require fewer updates, but result in more latency between
> > you providing the data and it actually being played. The bits parameter
> > must be 8 or 16. freq is the sample rate of the data in Hertz. The vol
> > and pan values use the same 0-255 ranges as the regular sample playing
> > functions. The stereo parameter should be set to 1 for stereo streams, or
> > 0 otherwise. If you want to adjust the pitch, volume, or panning of a
> > stream once it is playing, you can use the regular voice_*() functions
> > with stream-&gtvoice as a parameter. The sample data are always in
> > unsigned format. For stereo waveforms, the samples are interleaved, left
> > first.
>
> ...this is confusing.  Above you were talking about "sample frame" and
> "sample point", now you are talking about "sample".

"the sample values are interleaved" then.

I'm surprised this actually confuses you though. Granted it's inconsistent, 
but it's not confusing.

Ben