documentation index ◦ reference manual ◦ function index
Contents |
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. Three are defined by default:
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 Sound Properties.
The usual way to play music and sound in Ren'Py is using the three music/sound statements:
play channelname audiofile(s) [fadein] [fadeout]
is used to play sound and music. If a file is currently playing, it is interrupted and replaced with the new file.
channelname is expected to be the name of a channel. (Usually, this is either "sound", "music", or "voice".)
audiofile(s) can be one file or list of files.
fadein and fadeout clauses are all 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.
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 sound
stop music fadeout 1.0
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.
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.
It's possible to define your own channel by calling renpy.music.register_channel in init code.
| Function: | renpy.music.register_channel | (channel, mixer, loop, tight=False): |
This registers a new audio channel named channel.
mixer - The name of the mixer the channel uses. The three mixers Ren'Py knows about by default are "music", "sfx", and "voice".
loop - Determines if sounds on this channel loop by default.
tight - Determines if sounds loop even during fadeout.
The music functions provide a programmatic interface to music playback.
| Function: | renpy.music.play | (filenames, channel="music", loop=None, fadeout=None, synchro_start=False, fadein=0, tight=False, if_changed=False): |
This stops the music currently playing on the named 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 once they finish playing. If False, they will not. If None, takes the default for the channel.
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 False, it will not, and if None, takes the channel default.
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="music", loop=None, clear_queue=True, fadein=0, tight=None): |
This queues the given filenames on the named channel.
filenames - May either be a single filename, or a list of filenames.
loop - If True, this music will loop. If False, it will not. If None, takes the channel default.
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. If False, it will not, and if None, takes the channel default.
| Function: | renpy.music.stop | (channel="music", fadeout=None): |
This stops the music that is currently playing on the named 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, delay=0, channel="music"): |
This sets the volume of the named channel. The volume is a number between 0.0 and 1.0, and is interpreted as a fraction of the mixer volume for the channel.
It takes delay seconds to change the volume. This value is persisted into saves, and participates in rollback.
| Function: | renpy.music.set_pan | (pan, delay, channel="music"): |
This function allows sound and music to be panned between the two stereo channels.
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.
| Function: | renpy.music.get_playing | (channel="music"): |
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.
| Function: | renpy.music.set_volume | (volume, delay=0, channel="music"): |
This sets the volume of the named channel. The volume is a number between 0.0 and 1.0, and is interpreted as a fraction of the mixer volume for the channel.
It takes delay seconds to change the volume. This value is persisted into saves, and participates in rollback.
| Function: | renpy.music.set_queue_empty_callback | (callback, channel="music"): |
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.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.
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.