Audio - Ren'Py

documentation index ◦ reference manual ◦ function index

# Audio

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

- WAV (uncompressed PCM only)
- MP3
- OGG Vorbis
- OGG Speex, particularly useful for speech
- Various MOD formats, as supported by Modplug Tracker

Ren'Py supports eight channels of audio. By default, the first three channels (0-2) are dedicated to sound effects, while the rest are intended for music. When the voice extra is used to provide a voice support interface, channel 2 is reserved for playing the voice audio files, instead of general sound effects. The 'Music Volume', 'Sound Volume', and potentially the 'Voice Volume' settings of the in-game preferences menu are used to set individual volumes for each group of channels.

Sounds can also be set to play when buttons, menu choices, or imagemaps enter their hovered or activated states. See Sound Properties.

### Statements

The usual way to play music and sound in Ren'Py is using the three music/sound statements:

- The Play Statement.
- The Queue Statement.
- The Stop Statement.

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.

### Music Functions

The music subsystem, unlike the general sound effect functions, keeps track of what should be playing at any particular spot in the script. This means that the correct music will play after loading a saved game, or after using rollback or returning from the game menu. This is also useful for sound effects such as wind or background noise loops that are intended to play over multiple script lines.

The music functions, like the sound effect functions, implements a queue system, allowing multiple music files to be playing, or to be in line to be played, at any given time.

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.

Function: | renpy.music.play | (filenames, channel=7, loop=True, fadeout=None, synchro_start=False, fadein=0, tight=False, 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 may be a single file, or a list of files.

loop - If True, the tracks will loop while they are the last thing in the queue.

fadeout - If None, the fadeout time is taken from config.fade_music, otherwise it is a time in seconds to fade out for.

synchro_start - If True, all the channels that have had play called on them with synchro_start set to True will be started at the same time, in a sample accurate manner. This can be used to, for instance, have a piece of music separated into separate percussion, melody, and background chord audio files, and play them simultaneously.

fadein - The number of seconds to fade the music in for, on the first loop only.

tight - If True, then fadeouts will span into the next-queued sound.

if_changed - If 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.)

Function: | renpy.music.queue | (filenames, channel=7, loop=True, clear_queue=True, fadein=0, tight=False):

This queues the given filenames on the specified channel.

filenames - May either be a single filename, or a list of filenames.

loop - If True, then this music will repeat as long as it is the last element of the queue. The filenames given becomes the last queued file if loop is True. If loop is False, then the last queued file is set to None.

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 - The number of seconds to fade the music in for, on the first loop only.

tight - If True, then fadeouts will span into the next-queued sound.

Function: | renpy.music.stop | (channel=7, fadeout=None):

This stops the music that is currently playing on the given (or default) channel, dequeues all queued music, and sets the last queued file to None.

fadeout - If None, the music is faded out for the time given in config.fade_music, otherwise it is faded for the given number of seconds.

Function: | renpy.music.set_volume | (volume, channel=7):

This sets the volume of the given channel. The volume is a number between 0.0 and #0, and is interpreted as a fraction of the mixer volume for the channel.

This value takes effect immediately, and is persistent through rollback, menu transitions, and game saves / loads.

Function: | renpy.music.set_music | (channel, flag):

This should be called to indicate if the given channel should be treated as a music channel. If the flag is True, the channel will be treated as a music channel, if False, the channel will be treated as a sound effects channel. Please note that this will not change the mixer controlling the channel. Use renpy.sound.set_mixer to do that.

By default, channels 3-7 are considered music channels.

Function: | renpy.music.get_playing | (channel=7):

Returns the filename of the music playing on the given channel, or None if no music is playing on that channel. Note that None may be returned when the user sets the music volume to zero, even if the game script requested that music be played on that channel.

### Sound Effect Functions

The sound effect functions, unlike the music functions, are intended for short audio files providing emphasis for a particular script interaction. This is because they do not persist through game loads, rollback, or menu changes, and thus will only be played at the point in the script where the actual play command is called.

Function: | renpy.sound.play | (filename, channel=0, fadeout=0, fadein=0, tight=False):

Plays the named file once on the given channel. This will cause any playing sound effect to be stopped (after the given fadeout number of seconds, if necessary), and the new sound to be played in its place. The sound is faded in for the given number of seconds.

The filename may be that of a file in an archive.

If tight is True, then a fadeout of this sound will continue into the next-queued sound.

Function: | renpy.play | (filename, channel=0, fadeout=0, fadein=0, tight=False):

This is an alias for renpy.sound.play

Plays the named file once on the given channel. This will cause any playing sound effect to be stopped (after the given fadeout number of seconds, if necessary), and the new sound to be played in its place. The sound is faded in for the given number of seconds.

The filename may be that of a file in an archive.

If tight is True, then a fadeout of this sound will continue into the next-queued sound.

Function: | renpy.sound.queue | (filename, channel=0, clear_queue=True, fadein=0, tight=False):

This causes the named file to be queued to be played on the given channel. If clear_queue is True, the queue will be cleared before playback, so this sound is played immediately after the currently playing sound. If False, the channel's queue will not be cleared, and the sound will only be played after every other playing sound. If no sound is currently playing, then the sound will be played immediately.

Function: | renpy.sound.stop | (channel=0, fadeout=0):

This dequeues everything from the given channel, and stops the currently playing sound. If fadeout is 0, the sound is stopped immediately. Otherwise, it is interpreted as a number of seconds to fadeout for.

Function: | renpy.sound.is_playing | (channel=0):

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

This works with both sound and music channels, although it's intended for the former.

Function: | renpy.sound.set_volume | (volume, channel=0):

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

This volume is not persisted or rolled-back, as are volumes set with renpy.music.set_volume for music channels.

Function: | renpy.sound.set_mixer | (channel, mixer):

This sets the name of the mixer associated with a given channel. By default, there are two mixers, 'sfx' and 'music'. 'sfx' is on channels 0 to 2, and 'music' on 3 to 7. The voice module calls this function to set channel 2 to voice. You can create your own mixer, but will need to add a preference if you wish to allow the user to set it.

This function should only be called in an init block.

Function: | renpy.sound.set_queue_empty_callback | (callback, channel=0):

This sets a callback function 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.sound.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.

documentation index ◦ reference manual ◦ function index