1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
<html><head><title>renpy/doc/reference/Audio - Ren'Py</title><link href="../shared.css" rel="stylesheet"><link href="../monobook.css" rel="stylesheet"><link href="../common.css" rel="stylesheet"><link href="../monobook2.css" rel="stylesheet"><link href="../docs.css" rel="stylesheet" /></link></link></link></link></head><body><div id="bodyContent">
<p class="docnav"><a href="../index.html">documentation index</a> ◦ <a href="Reference_Manual.html">reference manual</a> ◦ <a href="Function_Index.html">function index</a></p><table class="toc" id="toc" summary="Contents">
<tr>
<td>
<div id="toctitle">
<h2>Contents</h2>
</div>
<ul>
<li class="toclevel-1"><a href="#Audio"><span class="tocnumber">1</span> <span class="toctext">Audio</span></a>
<ul>
<li class="toclevel-2"><a href="#Statements"><span class="tocnumber">1.1</span> <span class="toctext">Statements</span></a></li>
<li class="toclevel-2"><a href="#Music_Functions"><span class="tocnumber">1.2</span> <span class="toctext">Music Functions</span></a></li>
<li class="toclevel-2"><a href="#Sound_Effect_Functions"><span class="tocnumber">1.3</span> <span class="toctext">Sound Effect Functions</span></a></li>
</ul>
</li>
</ul>
</td>
</tr>
</table>
<script type="text/javascript">
//
if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); }
//
</script>
<p><a id="Audio" name="Audio"></a></p>
<h1><span class="mw-headline">Audio</span></h1>
<p>Ren'Py supports playing music and sound effects in the background, using any of the following audio file formats:</p>
<ul>
<li>WAV (uncompressed PCM only)</li>
<li>MP3</li>
<li><a class="external text" href="http://www.vorbis.com/" rel="nofollow" title="http://www.vorbis.com/">OGG Vorbis</a></li>
<li><a class="external text" href="http://www.speex.org/" rel="nofollow" title="http://www.speex.org/">OGG Speex</a>, particularly useful for speech</li>
<li>Various MOD formats, as supported by <a class="external text" href="http://openmpt.xwiki.com/xwiki/bin/view/Main/WebHome" rel="nofollow" title="http://openmpt.xwiki.com/xwiki/bin/view/Main/WebHome">Modplug Tracker</a></li>
</ul>
<p>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 <i>group</i> of channels.</p>
<p>Sounds can also be set to play when buttons, menu choices, or imagemaps enter their hovered or activated states. See <a href="../reference/List_of_Properties#sound" title="renpy/doc/reference/List of Properties">Sound Properties</a>.</p>
<p><a id="Statements" name="Statements"></a></p>
<h3><span class="mw-headline">Statements</span></h3>
<p>The usual way to play music and sound in Ren'Py is using the three music/sound statements:</p>
<ul>
<li><a href="../reference/The_Ren%27Py_Language#Play_Statement" title="renpy/doc/reference/The Ren'Py Language">The Play Statement</a>.</li>
<li><a href="../reference/The_Ren%27Py_Language#Queue_Statement" title="renpy/doc/reference/The Ren'Py Language">The Queue Statement</a>.</li>
<li><a href="../reference/The_Ren%27Py_Language#Stop_Statement" title="renpy/doc/reference/The Ren'Py Language">The Stop Statement</a>.</li>
</ul>
<p>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.</p>
<p><a id="Music_Functions" name="Music_Functions"></a></p>
<h3><span class="mw-headline">Music Functions</span></h3>
<p>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.</p>
<p>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.</p>
<p>Two configuration variables, <a href="../reference/Configuration_Variables#config.main_menu_music" title="renpy/doc/reference/Configuration Variables">config.main_menu_music</a> and <a href="../reference/Configuration_Variables#config.game_menu_music" title="renpy/doc/reference/Configuration Variables">config.game_menu_music</a> allow for the given music files to be played as the main and game menu music, respectively.</p>
<p><br />
<span id="renpy.music.play" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.music.play.html" title="renpy/doc/reference/functions/renpy.music.play">renpy.music.play</a></b></td>
<td valign="top">(filenames, channel=7, loop=True, fadeout=None, synchro_start=False, fadein=0, tight=False, if_changed=False):</td>
</tr>
</table>
<div class="renpy-doc">
<p>This stops the music currently playing on the numbered <i>channel</i>, dequeues any queued music, and begins playing the specified file or files.</p>
<p><i>filenames</i> may be a single file, or a list of files.</p>
<p><i>loop</i> - If True, the tracks will loop while they are the last thing in the queue.</p>
<p><i>fadeout</i> - If None, the fadeout time is taken from <a href="../reference/Configuration_Variables#config.fade_music" title="renpy/doc/reference/Configuration Variables">config.fade_music</a>, otherwise it is a time in seconds to fade out for.</p>
<p><i>synchro_start</i> - 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.</p>
<p><i>fadein</i> - The number of seconds to fade the music in for, on the first loop only.</p>
<p><i>tight</i> - If True, then fadeouts will span into the next-queued sound.</p>
<p><i>if_changed</i> - 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.)</p>
</div>
<p><br /></p>
<p><span id="renpy.music.queue" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.music.queue.html" title="renpy/doc/reference/functions/renpy.music.queue">renpy.music.queue</a></b></td>
<td valign="top">(filenames, channel=7, loop=True, clear_queue=True, fadein=0, tight=False):</td>
</tr>
</table>
<div class="renpy-doc">
<p>This queues the given filenames on the specified <i>channel</i>.</p>
<p><i>filenames</i> - May either be a single filename, or a list of filenames.</p>
<p><i>loop</i> - 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.</p>
<p><i>clear_queue</i> - 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.</p>
<p><i>fadein</i> - The number of seconds to fade the music in for, on the first loop only.</p>
<p><i>tight</i> - If True, then fadeouts will span into the next-queued sound.</p>
</div>
<p><br /></p>
<p><span id="renpy.music.stop" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.music.stop.html" title="renpy/doc/reference/functions/renpy.music.stop">renpy.music.stop</a></b></td>
<td valign="top">(channel=7, fadeout=None):</td>
</tr>
</table>
<div class="renpy-doc">
<p>This stops the music that is currently playing on the given (or default) <i>channel</i>, dequeues all queued music, and sets the last queued file to None.</p>
<p><i>fadeout</i> - If None, the music is faded out for the time given in <a href="../reference/Configuration_Variables#config.fade_music" title="renpy/doc/reference/Configuration Variables">config.fade_music</a>, otherwise it is faded for the given number of seconds.</p>
</div>
<p><br /></p>
<p><span id="renpy.music.set_volume" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.music.set_volume.html" title="renpy/doc/reference/functions/renpy.music.set volume">renpy.music.set_volume</a></b></td>
<td valign="top">(volume, channel=7):</td>
</tr>
</table>
<div class="renpy-doc">
<p>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.</p>
<p>This value takes effect immediately, and is persistent through rollback, menu transitions, and game saves / loads.</p>
</div>
<p><br /></p>
<p><span id="renpy.music.set_music" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.music.set_music.html" title="renpy/doc/reference/functions/renpy.music.set music">renpy.music.set_music</a></b></td>
<td valign="top">(channel, flag):</td>
</tr>
</table>
<div class="renpy-doc">
<p>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.</p>
<p>By default, channels 3-7 are considered music channels.</p>
</div>
<p><br /></p>
<p><span id="renpy.music.get_playing" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.music.get_playing.html" title="renpy/doc/reference/functions/renpy.music.get playing">renpy.music.get_playing</a></b></td>
<td valign="top">(channel=7):</td>
</tr>
</table>
<div class="renpy-doc">
<p>Returns the filename of the music playing on the given <i>channel</i>, 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.</p>
</div>
<p><br /></p>
<p><a id="Sound_Effect_Functions" name="Sound_Effect_Functions"></a></p>
<h3><span class="mw-headline">Sound Effect Functions</span></h3>
<p>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.</p>
<p><br />
<span id="renpy.sound.play" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.sound.play.html" title="renpy/doc/reference/functions/renpy.sound.play">renpy.sound.play</a></b></td>
<td valign="top">(filename, channel=0, fadeout=0, fadein=0, tight=False):</td>
</tr>
</table>
<div class="renpy-doc">
<p>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.</p>
<p>The filename may be that of a file in an archive.</p>
<p>If tight is True, then a fadeout of this sound will continue into the next-queued sound.</p>
</div>
<p><br /></p>
<p><span id="renpy.play" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.play.html" title="renpy/doc/reference/functions/renpy.play">renpy.play</a></b></td>
<td valign="top">(filename, channel=0, fadeout=0, fadein=0, tight=False):</td>
</tr>
</table>
<div class="renpy-doc">
<p>This is an alias for <a href="../reference/functions/renpy.sound.play.html" title="renpy/doc/reference/functions/renpy.sound.play">renpy.sound.play</a></p>
<p>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.</p>
<p>The filename may be that of a file in an archive.</p>
<p>If tight is True, then a fadeout of this sound will continue into the next-queued sound.</p>
</div>
<p><br /></p>
<p><span id="renpy.sound.queue" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.sound.queue.html" title="renpy/doc/reference/functions/renpy.sound.queue">renpy.sound.queue</a></b></td>
<td valign="top">(filename, channel=0, clear_queue=True, fadein=0, tight=False):</td>
</tr>
</table>
<div class="renpy-doc">
<p>This causes the named file to be queued to be played on the given channel. If <i>clear_queue</i> 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.</p>
</div>
<p><br /></p>
<p><span id="renpy.sound.stop" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.sound.stop.html" title="renpy/doc/reference/functions/renpy.sound.stop">renpy.sound.stop</a></b></td>
<td valign="top">(channel=0, fadeout=0):</td>
</tr>
</table>
<div class="renpy-doc">
<p>This dequeues everything from the given channel, and stops the currently playing sound. If <i>fadeout</i> is 0, the sound is stopped immediately. Otherwise, it is interpreted as a number of seconds to fadeout for.</p>
</div>
<p><br /></p>
<p><span id="renpy.sound.is_playing" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.sound.is_playing.html" title="renpy/doc/reference/functions/renpy.sound.is playing">renpy.sound.is_playing</a></b></td>
<td valign="top">(channel=0):</td>
</tr>
</table>
<div class="renpy-doc">
<p>Returns True if the channel is currently playing a sound, False if it is not, or if the sound system isn't working.</p>
<p>This works with both sound and music channels, although it's intended for the former.</p>
</div>
<p><br /></p>
<p><span id="renpy.sound.set_volume" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.sound.set_volume.html" title="renpy/doc/reference/functions/renpy.sound.set volume">renpy.sound.set_volume</a></b></td>
<td valign="top">(volume, channel=0):</td>
</tr>
</table>
<div class="renpy-doc">
<p>Sets the volume of this channel, as a fraction of the volume of the mixer controlling the channel.</p>
<p>This volume is not persisted or rolled-back, as are volumes set with <a href="../reference/functions/renpy.music.set_volume.html" title="renpy/doc/reference/functions/renpy.music.set volume">renpy.music.set_volume</a> for music channels.</p>
</div>
<p><br /></p>
<p><span id="renpy.sound.set_mixer" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.sound.set_mixer.html" title="renpy/doc/reference/functions/renpy.sound.set mixer">renpy.sound.set_mixer</a></b></td>
<td valign="top">(channel, mixer):</td>
</tr>
</table>
<div class="renpy-doc">
<p>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.</p>
<p>This function should only be called in an init block.</p>
</div>
<p><br /></p>
<p><span id="renpy.sound.set_queue_empty_callback" /></p>
<table>
<tr>
<td valign="top">Function:</td>
<td valign="top"><b><a href="../reference/functions/renpy.sound.set_queue_empty_callback.html" title="renpy/doc/reference/functions/renpy.sound.set queue empty callback">renpy.sound.set_queue_empty_callback</a></b></td>
<td valign="top">(callback, channel=0):</td>
</tr>
</table>
<div class="renpy-doc">
<p>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.</p>
<p>The callback is called with no parameters. It can queue sounds by calling <a href="../reference/functions/renpy.sound.queue.html" title="renpy/doc/reference/functions/renpy.sound.queue">renpy.sound.queue</a> 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.</p>
</div>
<div class="visualClear" />
<hr /><p class="docnav"><a href="../index.html">documentation index</a> ◦ <a href="Reference_Manual.html">reference manual</a> ◦ <a href="Function_Index.html">function index</a></p></div>
</body></html>
|
