Ren'Py supports playing music and sound effects in the background, using the following audio file formats
Ren'Py supports an arbitrary number of audio channels. There are three normal channels defined by default:
Normal channels support playing and queueing audio, but only play back
one audio file at a time. New normal channels can be registered with
The 'Music Volume', 'Sound Volume', and 'Voice Volume' settings of the in-game preferences menu are used to set individual volumes for these channels.
In addition to the normal channel, there is one special channel,
The audio channel supports playing back multiple audio files at one time,
but does not support queueing sound or stopping playback.
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
for the given music files to be played as the main and game menu music,
In-game, the usual way to play music and sound in Ren'Py is using the three music/sound statements.
The play statement is used to play sound and music. If a file is currently playing on a normal channel, it is interrupted and replaced with the new file.
The name of a channel is expected following keyword
(Usually, this is either "sound", "music", "voice", or "audio"). 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.
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
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
On the audio channel, multiple play statements play multiple sounds at the same time:
play audio "sfx1.opus" play audio "sfx2.opus"
The stop statement begin with keyword
stop, followed by the the name of a
channel to stop sound on. It may optionally have a
stop sound stop music fadeout 1.0
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
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.
Ren'Py supports partial of audio files. This is done by putting a playback specification, enclosed in angle brackets, at the start of the file. The partial playback specification should consist of alternating property name and value pairs, with every thing separated by spaces.
The values are always interpreted as seconds from the start of the file. The three properties are:
fromif specified, or to the start of the file.)
play music "<from 5 to 15.5>waves.opus"
Will play 10.5 seconds of waves.opus, starting at the 5 second mark. The code:
play music "<loop 6.333>song.opus"
Will play song.opus all the way through once, then loop back to the 6.333 second mark before playing it again all the way through to the end.
A specified duration of silence can played using a filename like "<silence 3.0>", where 3.0 is the number of seconds of silence that is desired. This can be used to delay the start of a sound file. For example:
play audio [ "<silence .5>", "boom.opus" ]
Will play silence for half a second, and then an explosion sound.
queue statements evaluate their arguments in the
audio namespace. This means it is possible to use the define statement
to provide an alias for an audio file.
For example, one can write:
define audio.sunflower = "music/sun-flower-slow-jam.ogg"
and then use:
play music sunflower
play(filename, channel=None, **kwargs) link
Returns True if the given filename has been played at least once on the current user's system.
Returns the duration of the audio or video file on channel. Returns 0.0 if no file is playing on channel.
Returns the pause flag for channel.
If the given channel is playing, returns the playing file name. Otherwise, returns None.
Returns the current position of the audio or video file on channel, in seconds. Returns None if no audio is playing on channel.
As this may return None before a channel starts playing, or if the audio channel involved has been muted, code that calls this function should always handle a None value.
Returns True if the channel is currently playing a sound, False if it is not, or if the sound system isn't working.
play(filenames, channel='music', loop=None, fadeout=None, synchro_start=False, fadein=0, tight=None, if_changed=False) link
This stops the music currently playing on the numbered channel, dequeues any queued music, and begins playing the specified file or files.
This clears the pause flag for channel.
queue(filenames, channel='music', loop=None, clear_queue=True, fadein=0, tight=None) link
This queues the given filenames on the specified channel.
This clears the pause flag for channel.
register_channel(name, mixer=None, loop=None, stop_on_mute=True, tight=False, file_prefix='', file_suffix='', buffer_queue=True, movie=False) link
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.
set_pan(pan, delay, channel='music') link
Sets the pan of this channel.
set_pause(value, channel='music') link
Sets the pause flag for channel to value. If True, the channel will pause, otherwise it will play normally.
set_queue_empty_callback(callback, channel='music') link
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.
set_volume(volume, delay=0, channel='music') link
Sets the volume of this channel, as a fraction of the volume of the mixer controlling the channel.
stop(channel='music', fadeout=None) link
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.
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.