audio.setVolume()

Type Function
Library audio.*
Return value Boolean
Revision Current Public Release (2017.3135)
Keywords audio, volume, set volume
See also audio.getVolume()
audio.play()

Overview

Sets the volume either for a specific channel, or sets the master volume.

This function returns true on success, or false on failure.

Gotchas

Note that the master volume is not necessarily the device's ringer volume. However, all volumes are scaled proportionally to the ringer volume.

When you set the volume, that new volume level is persistent until you set it again. Particularly with channels, you should always keep this in mind. If you change the volume, say on channel 1, channel 1 will continue to stay set at that level even if the sound finishes playing on that channel and you start playing a new sound on that channel.

If you are playing audio with auto-assigned channels, please understand that if you had previously changed the volume on the channel you are auto-assigned, the volume will play at that level for your new sound. For defensive programming, you may consider using manual channel assignment for channels you intend to change the volume for and use the audio.reserveChannels() API to prevent those channels from being auto-assigned.

Syntax

audio.setVolume( volume [, options ] )
volume (required)

Number. The new volume level you want to apply. Valid numbers range from 0.0 to 1.0, where 1.0 is the maximum value.

options (required)

Table. Table that supports a single key, channel, which is the channel number you want to set the volume on. Valid channels are 1 to the maximum number of channels (currently 32). Specify 0 to apply the volume to all channels. Omitting this parameter entirely sets the master volume which is different than the channel volume. All channel volumes are scaled by the master volume.

Example

audio.setVolume( 0.5 )  -- set the master volume
audio.setVolume( 0.75, { channel=1 } ) -- set the volume on channel 1