Audio — Ren'Py Documentation

### Navigation

- index
- next |
- previous |
- Ren'Py Home |
- Ren'Py Documentation

# Audio

Ren'Py supports playing music and sound effects in the background, using the following audio file formats

- OGG Vorbis
- MP3
- WAV (uncompressed PCM only)

Ren'Py supports an arbitrary number of audio channels. Three are defined by default:

- music - A channel for music playback.
- sound - A channel for sound effects.
- voice - A channel for voice.

New channels can be registered with `renpy.music.register_channel()`.

The 'Music Volume', 'Sound Volume', and 'Voice Volume' settings of the in-game preferences menu are used to set individual volumes for these channels.

Sounds can also be set to play when buttons, menu choices, or imagemaps enter their hovered or activated states. See Button Style Properties. Two configuration variables, `config.main_menu_music` and `config.game_menu_music` allow for the given music files to be played as the main and game menu music, respectively.

In-game, the usual way to play music and sound in Ren'Py is using the three music/sound statements.

## Play Statement

The play statement is used to play sound and music. If a file is currently playing, it is interrupted and replaced with the new file.

The name of a channel is expected following keyword `play`, (Usually, this is either "sound", "music", or "voice"). This is followed by audiofile(s), where audiofile(s) can be one file or list of files. When the list is given, the item of it is played in order.

The `fadein` and `fadeout` clauses are optional. Fadeout gives the fadeout time for currently playing music, in seconds, while fadein gives the time it takes to fade in the new music. If fadeout is not given, config.fade_music is used.

The `loop` and `noloop` clauses are also optional. The loop clause causes the music to loop, while noloop causes it to play only once. If both of them isn't given, the default of the channel is used.

    play music "mozart.ogg"
    play sound "woof.mp3"
    play myChannel "punch.wav" # 'myChannel' needs to be defined with renpy.music.register_channel().

    "We can also play a list of sounds, or music."
    play music [ "a.ogg", "b.ogg" ] fadeout 1.0 fadein 1.0

## Stop Statement

The stop statement begin with keyword `stop`, followed by the the name of a channel to stop sound on. It may optionally have a `fadeout` clause.

    stop sound
    stop music fadeout 1.0

## Queue Statement

The queue statement is used to queue up audio files. They will be played when the channel finishes playing the currently playing file.

The queue statement begin with keyword `queue`, followed by the the name of a channel to play sound on. It optionally takes the `loop` and `noloop` clauses.

    queue sound "woof.ogg"
    queue music [ "a.ogg", "b.ogg" ]

The advantage of using these statements is that your program will be checked for missing sound and music files when lint is run. The functions below exist to allow access to allow music and sound to be controlled from python, and to expose advanced (rarely-used) features.

## Functions

`renpy.` `seen_audio`(filename)

  Returns True if the given filename has been played at least once on the current user's system.

`renpy.music.` `get_playing`(channel='music')

  If the given channel is playing, returns the playing file name. Otherwise, returns None.

`renpy.music.` `is_playing`(channel='music')

  Returns True if the channel is currently playing a sound, False if it is not, or if the sound system isn't working.

`renpy.music.` `play`(filenames, channel='music', loop=None, fadeout=None, synchro_start=False, fadein=0, tight=None, if_changed=False)

  This stops the music currently playing on the numbered channel, dequeues any queued music, and begins playing the specified file or files.

  filenames
    This may be a single file, or a list of files to be played.
  channel
    The channel to play the sound on.
  loop
    If this is True, the tracks will loop while they are the last thing in the queue.
  fadeout
    If not None, this is a time in seconds to fade for. Otherwise the fadeout time is taken from config.fade_music.
  synchro_start
    Ren'Py will ensure that all channels of with synchro_start set to true will start playing at exactly the same time. Synchro_start should be true when playing two audio files that are meant to be synchronized with each other.
  fadein
    This is the number of seconds to fade the music in for, on the first loop only.
  tight
    If this is True, then fadeouts will span into the next-queued sound.
  if_changed
    If this is True, and the music file is currently playing, then it will not be stopped/faded out and faded back in again, but instead will be kept playing. (This will always queue up an additional loop of the music.)

`renpy.music.` `queue`(filenames, channel='music', loop=None, clear_queue=True, fadein=0, tight=None)

  This queues the given filenames on the specified channel.

  filenames
    This may be a single file, or a list of files to be played.
  channel
    The channel to play the sound on.
  loop
    If this is True, the tracks will loop while they are the last thing in the queue.
  clear_queue
    If True, then the queue is cleared, making these files the files that are played when the currently playing file finishes. If it is False, then these files are placed at the back of the queue. In either case, if no music is playing these files begin playing immediately.
  fadein
    This is the number of seconds to fade the music in for, on the first loop only.
  tight
    If this is True, then fadeouts will span into the next-queued sound.

`renpy.music.` `register_channel`(name, mixer=None, loop=None, stop_on_mute=True, tight=False, file_prefix='', file_suffix='', buffer_queue=True)

  This registers a new audio channel named name. Audio can then be played on the channel by supplying the channel name to the play or queue statements.

  mixer
    The name of the mixer the channel uses. By default, Ren'Py knows about the "music", "sfx", and "voice" mixers. Using other names is possible, but may require changing the preferences screens.
  loop
    If true, sounds on this channel loop by default.
  stop_on_mute
    If true, music on the channel is stopped when the channel is muted.
  tight
    If true, sounds will loop even when fadeout is occurring. This should be set to True for a sound effects or seamless music channel, and False if the music fades out on its own.
  file_prefix
    A prefix that is prepended to the filenames of the sound files being played on this channel.
  file_suffix
    A suffix that is appended to the filenames of the sound files being played on this channel.
  buffer_queue
    Should we buffer the first second or so of a queued file? This should be True for audio, and False for movie playback.

`renpy.music.` `set_pan`(pan, delay, channel='music')

  Sets the pan of this channel.

  pan
    A number between -1 and 1 that control the placement of the audio. If this is -1, then all audio is sent to the left channel. If it's 0, then the two channels are equally balanced. If it's 1, then all audio is sent to the right ear.
  delay
    The amount of time it takes for the panning to occur.
  channel
    The channel the panning takes place on. This can be a sound or a music channel. Often, this is channel 7, the default music channel.

`renpy.music.` `set_queue_empty_callback`(callback, channel='music')

  This sets a callback that is called when the queue is empty. This callback is called when the queue first becomes empty, and at least once per interaction while the queue is empty.

  The callback is called with no parameters. It can queue sounds by calling renpy.music.queue with the appropriate arguments. Please note that the callback may be called while a sound is playing, as long as a queue slot is empty.

`renpy.music.` `set_volume`(volume, delay=0, channel='music')

  Sets the volume of this channel, as a fraction of the volume of the mixer controlling the channel.

  volume
    This is a number between 0.0 and 1.0, and is interpreted as a fraction of the mixer volume for the channel.
  delay
    It takes delay seconds to change/fade the volume from the old to the new value. This value is persisted into saves, and participates in rollback.
  channel
    The channel to be set

`renpy.music.` `stop`(channel='music', fadeout=None)

  This stops the music that is currently playing, and dequeues all queued music. If fadeout is None, the music is faded out for the time given in config.fade_music, otherwise it is faded for fadeout seconds.

  This sets the last queued file to None.

  channel
    The channel to stop the sound on.
  fadeout
    If not None, this is a time in seconds to fade for. Otherwise the fadeout time is taken from config.fade_music.

## Sound Functions

Most renpy.music functions have aliases in renpy.sound. These functions are similar, except they default to the sound channel rather than the music channel, and default to not looping.

### Navigation

- index
- next |
- previous |
- Ren'Py Home |
- Ren'Py Documentation