Streaming - ALURE

# Streaming

Summary

Streaming |
Functions |
alureStreamSizeIsMicroSec | Specifies if the chunk size value given to the alureCreateStream functions is in bytes (default) or microseconds.
alureCreateStreamFromFile | Opens a file and sets it up for streaming.
alureCreateStreamFromMemory | Opens a file image from memory and sets it up for streaming, similar to alureCreateStreamFromFile.
alureCreateStreamFromStaticMemory | Identical to alureCreateStreamFromMemory, except the given memory is used directly and not duplicated.
alureCreateStreamFromCallback | Creates a stream using the specified callback to retrieve data.
alureGetStreamFrequency | Retrieves the frequency used by the given stream.
alureBufferDataFromStream | Buffers the given buffer objects with the next chunks of data from the stream.
alureRewindStream | Rewinds the stream so that the next alureBufferDataFromStream call will restart from the beginning of the audio file.
alureSetStreamOrder | Skips the module decoder to the specified order, so following buffering calls will decode from the specified order.
alureSetStreamPatchset | Specifies the patchset to use for MIDI streams.
alureGetStreamLength | Retrieves an approximate number of samples for the stream.
alureDestroyStream | Closes an opened stream.

### Functions

### alureStreamSizeIsMicroSec

> ALURE_API ALboolean ALURE_APIENTRY alureStreamSizeIsMicroSec( | ALboolean | useUS | )

Specifies if the chunk size value given to the alureCreateStream functions is in bytes (default) or microseconds. Specifying the size in microseconds can help manage the time needed in between needed updates (since the format and sample rate of the stream may not be known), while specifying the size in bytes can help control memory usage.

#### Returns

Previously set value.

Version Added: 1.1

#### See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback

### alureCreateStreamFromFile

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromFile(
> | const | ALchar | * | fname,
> |  | ALsizei |  | chunkLength,
> |  | ALsizei |  | numBufs,
> |  | ALuint | * | bufs
> )

Opens a file and sets it up for streaming. The given chunkLength is the number of bytes, or microseconds worth of bytes if alureStreamSizeIsMicroSec was last called with AL_TRUE, each buffer will fill with. ALURE will optionally generate the specified number of buffer objects, fill them with the beginning of the data, then place the new IDs into the provided storage, before returning. Requires an active context.

#### Returns

An opaque handle used to control the opened stream, or NULL on error.

#### See Also

alureStreamSizeIsMicroSec, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback

### alureCreateStreamFromMemory

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromMemory(
> | const | ALubyte | * | fdata,
> |  | ALuint |  | length,
> |  | ALsizei |  | chunkLength,
> |  | ALsizei |  | numBufs,
> |  | ALuint | * | bufs
> )

Opens a file image from memory and sets it up for streaming, similar to alureCreateStreamFromFile. The given data buffer can be safely deleted after calling this function. Requires an active context.

#### Returns

An opaque handle used to control the opened stream, or NULL on error.

#### See Also

alureStreamSizeIsMicroSec, alureCreateStreamFromFile, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback

### alureCreateStreamFromStaticMemory

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromStaticMemory(
> | const | ALubyte | * | fdata,
> |  | ALuint |  | length,
> |  | ALsizei |  | chunkLength,
> |  | ALsizei |  | numBufs,
> |  | ALuint | * | bufs
> )

Identical to alureCreateStreamFromMemory, except the given memory is used directly and not duplicated. As a consequence, the data buffer must remain valid while the stream is alive. Requires an active context.

#### Returns

An opaque handle used to control the opened stream, or NULL on error.

#### See Also

alureStreamSizeIsMicroSec, alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromCallback

### alureCreateStreamFromCallback

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromCallback(
> | ALuint |  | (*callback)(void *userdata, ALubyte *data, ALuint bytes),
> | void | * | userdata,
> | ALenum |  | format,
> | ALuint |  | samplerate,
> | ALsizei |  | chunkLength,
> | ALsizei |  | numBufs,
> | ALuint | * | bufs
> )

Creates a stream using the specified callback to retrieve data. Requires an active context.

#### Parameters

callback | This is called when more data is needed from the stream. Up to the specified number of bytes should be written to the data pointer, and the number of bytes actually written should be returned. The number of bytes written must be block aligned for the format (eg. a multiple of 4 for AL_FORMAT_STEREO16), or an OpenAL error may occur during buffering.
userdata | A handle passed through to the callback.
format | The format of the data the callback will be giving. The format must be valid for the context.
samplerate | The sample rate (frequency) of the stream

#### Returns

An opaque handle used to control the opened stream, or NULL on error.

#### See Also

alureStreamSizeIsMicroSec, alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory

### alureGetStreamFrequency

> ALURE_API ALsizei ALURE_APIENTRY alureGetStreamFrequency( | alureStream | * | stream | )

Retrieves the frequency used by the given stream.

#### Returns

0 on error.

Version Added: 1.1

### alureBufferDataFromStream

> ALURE_API ALsizei ALURE_APIENTRY alureBufferDataFromStream( | alureStream | * | stream,
> | ALsizei |  | numBufs,
> | ALuint | * | bufs | )

Buffers the given buffer objects with the next chunks of data from the stream. The given buffer objects do not need to be ones given by the alureCreateStream functions. Requires an active context.

#### Returns

The number of buffers filled with new data, or -1 on error. If the value returned is less than the number requested, the end of the stream has been reached.

### alureRewindStream

> ALURE_API ALboolean ALURE_APIENTRY alureRewindStream( | alureStream | * | stream | )

Rewinds the stream so that the next alureBufferDataFromStream call will restart from the beginning of the audio file.

#### Returns

AL_FALSE on error.

#### See Also

alureSetStreamOrder

### alureSetStreamOrder

> ALURE_API ALboolean ALURE_APIENTRY alureSetStreamOrder( | alureStream | * | stream,
> | ALuint |  | order | )

Skips the module decoder to the specified order, so following buffering calls will decode from the specified order. For non-module formats, setting order 0 is identical to rewinding the stream (other orders will fail).

#### Returns

AL_FALSE on error.

Version Added: 1.1

#### See Also

alureRewindStream

### alureSetStreamPatchset

> ALURE_API ALboolean ALURE_APIENTRY alureSetStreamPatchset(
> |  | alureStream | * | stream,
> | const | ALchar | * | patchset
> )

Specifies the patchset to use for MIDI streams. By default, the FluidSynth decoder will look for one in the FLUID_SOUNDFONT environment variable, but this can be used to change it to something different. On non-MIDI streams, this has no effect.

#### Returns

AL_FALSE on error.

Version Added: 1.1

### alureGetStreamLength

> ALURE_API alureInt64 ALURE_APIENTRY alureGetStreamLength( | alureStream | * | stream | )

Retrieves an approximate number of samples for the stream. Not all streams or decoders can return such info, and may return 0 if the stream length is unknown.

#### Returns

-1 on error.

Version Added: 1.2

### alureDestroyStream

> ALURE_API ALboolean ALURE_APIENTRY alureDestroyStream( | alureStream | * | stream,
> | ALsizei |  | numBufs,
> | ALuint | * | bufs | )

Closes an opened stream. For convenience, it will also delete the given buffer objects. The given buffer objects do not need to be ones given by the alureCreateStream functions. Requires an active context.

#### Returns

AL_FALSE on error.

> ALURE_API ALboolean ALURE_APIENTRY alureStreamSizeIsMicroSec( | ALboolean | useUS | )

Specifies if the chunk size value given to the alureCreateStream functions is in bytes (default) or microseconds.

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromFile(
> | const | ALchar | * | fname,
> |  | ALsizei |  | chunkLength,
> |  | ALsizei |  | numBufs,
> |  | ALuint | * | bufs
> )

Opens a file and sets it up for streaming.

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromMemory(
> | const | ALubyte | * | fdata,
> |  | ALuint |  | length,
> |  | ALsizei |  | chunkLength,
> |  | ALsizei |  | numBufs,
> |  | ALuint | * | bufs
> )

Opens a file image from memory and sets it up for streaming, similar to alureCreateStreamFromFile.

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromStaticMemory(
> | const | ALubyte | * | fdata,
> |  | ALuint |  | length,
> |  | ALsizei |  | chunkLength,
> |  | ALsizei |  | numBufs,
> |  | ALuint | * | bufs
> )

Identical to alureCreateStreamFromMemory, except the given memory is used directly and not duplicated.

> ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromCallback(
> | ALuint |  | (*callback)(void *userdata, ALubyte *data, ALuint bytes),
> | void | * | userdata,
> | ALenum |  | format,
> | ALuint |  | samplerate,
> | ALsizei |  | chunkLength,
> | ALsizei |  | numBufs,
> | ALuint | * | bufs
> )

Creates a stream using the specified callback to retrieve data.

> ALURE_API ALsizei ALURE_APIENTRY alureGetStreamFrequency( | alureStream | * | stream | )

Retrieves the frequency used by the given stream.

> ALURE_API ALsizei ALURE_APIENTRY alureBufferDataFromStream( | alureStream | * | stream,
> | ALsizei |  | numBufs,
> | ALuint | * | bufs | )

Buffers the given buffer objects with the next chunks of data from the stream.

> ALURE_API ALboolean ALURE_APIENTRY alureRewindStream( | alureStream | * | stream | )

Rewinds the stream so that the next alureBufferDataFromStream call will restart from the beginning of the audio file.

> ALURE_API ALboolean ALURE_APIENTRY alureSetStreamOrder( | alureStream | * | stream,
> | ALuint |  | order | )

Skips the module decoder to the specified order, so following buffering calls will decode from the specified order.

> ALURE_API ALboolean ALURE_APIENTRY alureSetStreamPatchset(
> |  | alureStream | * | stream,
> | const | ALchar | * | patchset
> )

Specifies the patchset to use for MIDI streams.

> ALURE_API alureInt64 ALURE_APIENTRY alureGetStreamLength( | alureStream | * | stream | )

Retrieves an approximate number of samples for the stream.

> ALURE_API ALboolean ALURE_APIENTRY alureDestroyStream( | alureStream | * | stream,
> | ALsizei |  | numBufs,
> | ALuint | * | bufs | )

Closes an opened stream.
Close