/usr/share/doc/renpy/html/audio.html is in renpy-doc 6.17.6-1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 | <!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Audio — Ren'Py Documentation</title>
<link rel="stylesheet" href="_static/screen.css" type="text/css" media="screen, projection"/>
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" media="print" />
<!--[if lt IE 8]>
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" media="screen, projection"/>
<![endif]-->
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '6.18.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Ren'Py Documentation" href="index.html" />
<link rel="next" title="Movie" href="movie.html" />
<link rel="prev" title="Conditional Statements" href="conditional.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="movie.html" title="Movie"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="conditional.html" title="Conditional Statements"
accesskey="P">previous</a> |</li>
<li> <img src="_static/logo.png" width=19 height=21 align=center>
<li> <a href="http://www.renpy.org/">Ren'Py Home</a> |
<li><a href="index.html">Ren'Py Documentation</a></li>
</ul>
</div>
<div class="container">
<div class="span4">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Audio</a><ul>
<li><a class="reference internal" href="#play-statement">Play Statement</a></li>
<li><a class="reference internal" href="#stop-statement">Stop Statement</a></li>
<li><a class="reference internal" href="#queue-statement">Queue Statement</a></li>
<li><a class="reference internal" href="#functions">Functions</a></li>
<li><a class="reference internal" href="#sound-functions">Sound Functions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="conditional.html"
title="previous chapter">Conditional Statements</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="movie.html"
title="next chapter">Movie</a></p>
<h4>Search</h4>
<div id="cse-search-form" style="width: 100%;"></div>
<div class="copydata">
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
<br>
</div>
</div>
</div>
</div>
<div class="document span20 last">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="audio">
<h1>Audio<a class="headerlink" href="#audio" title="Permalink to this headline">¶</a></h1>
<p>Ren'Py supports playing music and sound effects in the background,
using the following audio file formats</p>
<ul class="simple">
<li>OGG Vorbis</li>
<li>MP3</li>
<li>WAV (uncompressed PCM only)</li>
</ul>
<p>Ren'Py supports an arbitrary number of audio channels.
Three are defined by default:</p>
<ul class="simple">
<li>music - A channel for music playback.</li>
<li>sound - A channel for sound effects.</li>
<li>voice - A channel for voice.</li>
</ul>
<p>New channels can be registered with <a class="reference internal" href="#renpy.music.register_channel" title="renpy.music.register_channel"><tt class="xref py py-func docutils literal"><span class="pre">renpy.music.register_channel()</span></tt></a>.</p>
<p>The 'Music Volume', 'Sound Volume', and 'Voice Volume' settings
of the in-game preferences menu are used to set individual
volumes for these channels.</p>
<p>Sounds can also be set to play when buttons, menu choices, or
imagemaps enter their hovered or activated states. See
<a class="reference internal" href="style_properties.html#button-style-properties"><em>Button Style Properties</em></a>. Two configuration
variables, <a class="reference internal" href="config.html#var-config.main_menu_music"><tt class="xref std std-var docutils literal"><span class="pre">config.main_menu_music</span></tt></a> and <a class="reference internal" href="config.html#var-config.game_menu_music"><tt class="xref std std-var docutils literal"><span class="pre">config.game_menu_music</span></tt></a> allow
for the given music files to be played as the main and game menu music,
respectively.</p>
<p>In-game, the usual way to play music and sound in Ren'Py is using
the three music/sound statements.</p>
<div class="section" id="play-statement">
<h2>Play Statement<a class="headerlink" href="#play-statement" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>The name of a channel is expected following keyword <tt class="docutils literal"><span class="pre">play</span></tt>,
(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.</p>
<p>The <tt class="docutils literal"><span class="pre">fadein</span></tt> and <tt class="docutils literal"><span class="pre">fadeout</span></tt> 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.</p>
<p>The <tt class="docutils literal"><span class="pre">loop</span></tt> and <tt class="docutils literal"><span class="pre">noloop</span></tt> 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.</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">play</span> <span class="n">music</span> <span class="s">"mozart.ogg"</span>
<span class="k">play</span> <span class="na">sound</span> <span class="s">"woof.mp3"</span>
<span class="k">play</span> <span class="n">myChannel</span> <span class="s">"punch.wav"</span> <span class="c"># 'myChannel' needs to be defined with renpy.music.register_channel().</span>
<span class="s">"We can also play a list of sounds, or music."</span>
<span class="k">play</span> <span class="n">music</span> <span class="p">[</span> <span class="s">"a.ogg"</span><span class="p">,</span> <span class="s">"b.ogg"</span> <span class="p">]</span> <span class="n">fadeout</span> <span class="mf">1.0</span> <span class="n">fadein</span> <span class="mf">1.0</span>
</pre></div>
</div>
</div>
<div class="section" id="stop-statement">
<h2>Stop Statement<a class="headerlink" href="#stop-statement" title="Permalink to this headline">¶</a></h2>
<p>The stop statement begin with keyword <tt class="docutils literal"><span class="pre">stop</span></tt>, followed by the the name of a
channel to stop sound on. It may optionally have a <tt class="docutils literal"><span class="pre">fadeout</span></tt>
clause.</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">stop</span> <span class="na">sound</span>
<span class="k">stop</span> <span class="n">music</span> <span class="n">fadeout</span> <span class="mf">1.0</span>
</pre></div>
</div>
</div>
<div class="section" id="queue-statement">
<h2>Queue Statement<a class="headerlink" href="#queue-statement" title="Permalink to this headline">¶</a></h2>
<p>The queue statement is used to queue up audio files. They will be played when
the channel finishes playing the currently playing file.</p>
<p>The queue statement begin with keyword <tt class="docutils literal"><span class="pre">queue</span></tt>, followed by the the name of a
channel to play sound on. It optionally takes the <tt class="docutils literal"><span class="pre">loop</span></tt> and <tt class="docutils literal"><span class="pre">noloop</span></tt> clauses.</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">queue</span> <span class="na">sound</span> <span class="s">"woof.ogg"</span>
<span class="k">queue</span> <span class="n">music</span> <span class="p">[</span> <span class="s">"a.ogg"</span><span class="p">,</span> <span class="s">"b.ogg"</span> <span class="p">]</span>
</pre></div>
</div>
<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>
</div>
<div class="section" id="functions">
<h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="renpy.seen_audio">
<tt class="descclassname">renpy.</tt><tt class="descname">seen_audio</tt><big>(</big><em>filename</em><big>)</big><a class="headerlink" href="#renpy.seen_audio" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns True if the given filename has been played at least once on the current
user's system.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.music.get_playing">
<tt class="descclassname">renpy.music.</tt><tt class="descname">get_playing</tt><big>(</big><em>channel='music'</em><big>)</big><a class="headerlink" href="#renpy.music.get_playing" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns true if the given channel is playing.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.music.is_playing">
<tt class="descclassname">renpy.music.</tt><tt class="descname">is_playing</tt><big>(</big><em>channel='music'</em><big>)</big><a class="headerlink" href="#renpy.music.is_playing" title="Permalink to this definition">¶</a></dt>
<dd><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>
</dd></dl>
<dl class="function">
<dt id="renpy.music.play">
<tt class="descclassname">renpy.music.</tt><tt class="descname">play</tt><big>(</big><em>filenames</em>, <em>channel='music'</em>, <em>loop=None</em>, <em>fadeout=None</em>, <em>synchro_start=False</em>, <em>fadein=0</em>, <em>tight=None</em>, <em>if_changed=False</em><big>)</big><a class="headerlink" href="#renpy.music.play" title="Permalink to this definition">¶</a></dt>
<dd><p>This stops the music currently playing on the numbered channel, dequeues
any queued music, and begins playing the specified file or files.</p>
<dl class="docutils">
<dt><cite>filenames</cite></dt>
<dd>This may be a single file, or a list of files to be played.</dd>
<dt><cite>channel</cite></dt>
<dd>The channel to play the sound on.</dd>
<dt><cite>loop</cite></dt>
<dd>If this is True, the tracks will loop while they are the last thing
in the queue.</dd>
<dt><cite>fadeout</cite></dt>
<dd>If not None, this is a time in seconds to fade for. Otherwise the
fadeout time is taken from config.fade_music.</dd>
<dt><cite>synchro_start</cite></dt>
<dd>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.</dd>
<dt><cite>fadein</cite></dt>
<dd>This is the number of seconds to fade the music in for, on the
first loop only.</dd>
<dt><cite>tight</cite></dt>
<dd>If this is True, then fadeouts will span into the next-queued sound.</dd>
<dt><cite>if_changed</cite></dt>
<dd>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.)</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="renpy.music.queue">
<tt class="descclassname">renpy.music.</tt><tt class="descname">queue</tt><big>(</big><em>filenames</em>, <em>channel='music'</em>, <em>loop=None</em>, <em>clear_queue=True</em>, <em>fadein=0</em>, <em>tight=None</em><big>)</big><a class="headerlink" href="#renpy.music.queue" title="Permalink to this definition">¶</a></dt>
<dd><p>This queues the given filenames on the specified channel.</p>
<dl class="docutils">
<dt><cite>filenames</cite></dt>
<dd>This may be a single file, or a list of files to be played.</dd>
<dt><cite>channel</cite></dt>
<dd>The channel to play the sound on.</dd>
<dt><cite>loop</cite></dt>
<dd>If this is True, the tracks will loop while they are the last thing
in the queue.</dd>
<dt><cite>clear_queue</cite></dt>
<dd>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.</dd>
<dt><cite>fadein</cite></dt>
<dd>This is the number of seconds to fade the music in for, on the
first loop only.</dd>
<dt><cite>tight</cite></dt>
<dd>If this is True, then fadeouts will span into the next-queued sound.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="renpy.music.register_channel">
<tt class="descclassname">renpy.music.</tt><tt class="descname">register_channel</tt><big>(</big><em>name</em>, <em>mixer=None</em>, <em>loop=None</em>, <em>stop_on_mute=True</em>, <em>tight=False</em>, <em>file_prefix=''</em>, <em>file_suffix=''</em>, <em>buffer_queue=True</em><big>)</big><a class="headerlink" href="#renpy.music.register_channel" title="Permalink to this definition">¶</a></dt>
<dd><p>This registers a new audio channel named <cite>name</cite>. Audio can then be
played on the channel by supplying the channel name to the play or
queue statements.</p>
<dl class="docutils">
<dt><cite>mixer</cite></dt>
<dd>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.</dd>
<dt><cite>loop</cite></dt>
<dd>If true, sounds on this channel loop by default.</dd>
<dt><cite>stop_on_mute</cite></dt>
<dd>If true, music on the channel is stopped when the channel is muted.</dd>
<dt><cite>tight</cite></dt>
<dd>If true, sounds will loop even when fadeout is occuring. This should
be set to True for a sound effects or seamless music channel, and False
if the music fades out on its own.</dd>
<dt><cite>file_prefix</cite></dt>
<dd>A prefix that is prepended to the filenames of the sound files being
played on this channel.</dd>
<dt><cite>file_suffix</cite></dt>
<dd>A suffix that is appended to the filenames of the sound files being
played on this channel.</dd>
<dt><cite>buffer_queue</cite></dt>
<dd>Should we buffer the first second or so of a queued file? This should
be True for audio, and False for movie playback.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="renpy.music.set_pan">
<tt class="descclassname">renpy.music.</tt><tt class="descname">set_pan</tt><big>(</big><em>pan</em>, <em>delay</em>, <em>channel='music'</em><big>)</big><a class="headerlink" href="#renpy.music.set_pan" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets the pan of this channel.</p>
<dl class="docutils">
<dt><cite>pan</cite></dt>
<dd>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.</dd>
<dt><cite>delay</cite></dt>
<dd>The amount of time it takes for the panning to occur.</dd>
<dt><cite>channel</cite></dt>
<dd>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.</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="renpy.music.set_queue_empty_callback">
<tt class="descclassname">renpy.music.</tt><tt class="descname">set_queue_empty_callback</tt><big>(</big><em>callback</em>, <em>channel='music'</em><big>)</big><a class="headerlink" href="#renpy.music.set_queue_empty_callback" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<p>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.</p>
</dd></dl>
<dl class="function">
<dt id="renpy.music.set_volume">
<tt class="descclassname">renpy.music.</tt><tt class="descname">set_volume</tt><big>(</big><em>volume</em>, <em>delay=0</em>, <em>channel='music'</em><big>)</big><a class="headerlink" href="#renpy.music.set_volume" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets the volume of this channel, as a fraction of the volume of the
mixer controlling the channel.</p>
<dl class="docutils">
<dt><cite>volume</cite></dt>
<dd>This is a number between 0.0 and 1.0, and is interpreted as a fraction
of the mixer volume for the channel.</dd>
<dt><cite>delay</cite></dt>
<dd>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.</dd>
<dt><cite>channel</cite></dt>
<dd>The channel to be set</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="renpy.music.stop">
<tt class="descclassname">renpy.music.</tt><tt class="descname">stop</tt><big>(</big><em>channel='music'</em>, <em>fadeout=None</em><big>)</big><a class="headerlink" href="#renpy.music.stop" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<p>This sets the last queued file to None.</p>
<dl class="docutils">
<dt><cite>channel</cite></dt>
<dd>The channel to stop the sound on.</dd>
<dt><cite>fadeout</cite></dt>
<dd>If not None, this is a time in seconds to fade for. Otherwise the
fadeout time is taken from config.fade_music.</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="sound-functions">
<h2>Sound Functions<a class="headerlink" href="#sound-functions" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="movie.html" title="Movie"
>next</a> |</li>
<li class="right" >
<a href="conditional.html" title="Conditional Statements"
>previous</a> |</li>
<li> <img src="_static/logo.png" width=19 height=21 align=center>
<li> <a href="http://www.renpy.org/">Ren'Py Home</a> |
<li><a href="index.html">Ren'Py Documentation</a></li>
</ul>
</div>
</body>
</html>
|