audio.rewind()

Overview

Rewinds audio to the beginning position on either an active channel or directly on the audio handle (rewinds all channels if no arguments are specified).

This function returns true on success or false if otherwise.

Gotchas

There are subtle behavior differences depending on whether you used audio.loadSound() or audio.loadStream() on what you are trying to rewind.

Audio loaded with audio.loadSound() may only rewind using the channel parameter. You may not rewind using the audio handle. This is because audio.loadSound() is optimized to share the audio data so you can play back multiple instances of the sound simultaneously (at different positions). Seeking (rewinding) the underlying data complicates this optimization.

In contrast, audio loaded with audio.loadStream() cannot be shared (you would load multiple instances of the same file if you needed multiple, simultaneous playback). So rewinding the data does not cause a conflict. So generally you are expected to rewind using the audioHandle parameter for audio loaded with audio.loadStream(). But if you rewind streamed data using the channel, it will automatically rewind as if you used the audioHandle parameter. So you are allowed to specify either parameter safely.

Also note that for files loaded with audio.loadStream() and are currently playing, you may not hear the audio immediate update until after the current buffer finishes playing. If you want seemingly instantaneous rewinding, you should pause the playback first using audio.pause(), rewind, then resume playing.

Syntax

audio.rewind( [audioHandle | options] )

Example

audio.rewind()  -- rewind all channels
audio.rewind( backgroundMusic ) -- rewind the audio handle
audio.rewind( { channel=1 } )  -- rewind channel 1