audio.seek()

Type Function
Library audio.*
Return value Boolean
Revision Current Public Release (2017.3068)
Keywords audio, seek, position
See also audio.rewind()

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 ] )
time (required)

Number. The time in milliseconds within the audio handle you want to seek to.

audioHandle (optional)

Object. The audio handle of the data you want to seek. This should only be used for audio loaded with audio.loadStream(). Do not use the options.channel parameter in the same call.

options (optional)

Table. Table that supports a single key, channel, which is the channel you want the seek operation to apply to. This is best for audio loaded with audio.loadSound(). Do not use the audioHandle parameter in the same call.

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