audio.seek()

Overview

Seeks to a time position on either an active channel or directly on the audio handle.

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 seek.

Audio loaded with audio.loadSound() may only seek using the channel parameter. You may not seek using the audioHandle. 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 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 seeking the data does not cause a conflict. So generally you are expected to seek using the audioHandle parameter for audio loaded with audio.loadStream(). But if you seek streamed data using the channel parameter, it will automatically seek 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 seeking, you should stop the playback first using audio.stop(), seek, then start playing.

Syntax

audio.seek( time [, audioHandle ] [, options ] )

Example

audio.seek( 3000 )  -- seek all active channels to 3 seconds
audio.seek( 4000, backgroundMusic )  -- seek the audio handle to 4 seconds
audio.seek( 5000, { channel=1 } )  -- seek channel 1 to 5 seconds