799 lines
54 KiB
HTML
799 lines
54 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<title>Audio — Ren'Py Documentation</title>
|
||
|
|
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" />
|
||
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
|
||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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>
|
||
|
|
<script type="text/javascript" src="_static/language_data.js"></script>
|
||
|
|
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
|
||
|
|
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
|
||
|
|
<script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
|
||
|
|
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
|
||
|
|
<link rel="index" title="Index" href="genindex.html" />
|
||
|
|
<link rel="search" title="Search" href="search.html" />
|
||
|
|
<link rel="next" title="Movie" href="movie.html" />
|
||
|
|
<link rel="prev" title="Conditional Statements" href="conditional.html" />
|
||
|
|
<meta charset='utf-8'>
|
||
|
|
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
|
||
|
|
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
|
||
|
|
<meta name="apple-mobile-web-app-capable" content="yes">
|
||
|
|
|
||
|
|
</head><body>
|
||
|
|
|
||
|
|
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
|
||
|
|
<div class="container">
|
||
|
|
<div class="navbar-header">
|
||
|
|
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
|
||
|
|
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
|
||
|
|
<span class="icon-bar"></span>
|
||
|
|
<span class="icon-bar"></span>
|
||
|
|
<span class="icon-bar"></span>
|
||
|
|
</button>
|
||
|
|
<a class="navbar-brand" href="index.html">
|
||
|
|
Ren'Py Documentation</a>
|
||
|
|
<span class="navbar-text navbar-version pull-left"><b>7.5.3</b></span>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="collapse navbar-collapse nav-collapse">
|
||
|
|
<ul class="nav navbar-nav">
|
||
|
|
|
||
|
|
<li><a href="https://www.renpy.org">Home Page</a></li>
|
||
|
|
<li><a href="https://www.renpy.org/doc/html/">Online Documentation</a></li>
|
||
|
|
|
||
|
|
|
||
|
|
<li class="dropdown globaltoc-container">
|
||
|
|
<a role="button"
|
||
|
|
id="dLabelGlobalToc"
|
||
|
|
data-toggle="dropdown"
|
||
|
|
data-target="#"
|
||
|
|
href="index.html">Site <b class="caret"></b></a>
|
||
|
|
<ul class="dropdown-menu globaltoc"
|
||
|
|
role="menu"
|
||
|
|
aria-labelledby="dLabelGlobalToc"><ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="gui.html">GUI Customization Guide</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul class="current">
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="language_basics.html">Language Basics</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="label.html">Labels & Control Flow</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="dialogue.html">Dialogue and Narration</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="displaying_images.html">Displaying Images</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="menus.html">In-Game Menus</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="python.html">Python Statements</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="conditional.html">Conditional Statements</a></li>
|
||
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="#">Audio</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="movie.html">Movie</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="voice.html">Voice</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="text.html">Text</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="translation.html">Translation</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="displayables.html">Displayables</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="transforms.html">Transforms</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="transitions.html">Transitions</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="atl.html">Animation and Transformation Language</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="matrixcolor.html">Matrixcolor</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="layeredimage.html">Layered Images</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="3dstage.html">3D Stage</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="live2d.html">Live2D Cubism</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="style.html">Styles</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="style_properties.html">Style Properties</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="screens.html">Screens and Screen Language</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="screen_actions.html">Screen Actions, Values, and Functions</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="screen_special.html">Special Screen Names</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="screen_optimization.html">Screen Language Optimization</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="config.html">Configuration Variables</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="preferences.html">Preference Variables</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="store_variables.html">Store Variables</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="mouse.html">Custom Mouse Cursors</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="launcher.html">Launcher</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="developer_tools.html">Developer Tools</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="director.html">Interactive Director</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="nvl_mode.html">NVL-Mode Tutorial</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="input.html">Text Input</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="side_image.html">Side Images</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="rooms.html">Image Gallery, Music Room, and Replay Actions</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="drag_drop.html">Drag and Drop</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="sprites.html">Sprites</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="keymap.html">Customizing the Keymap</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="achievement.html">Achievements</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="history.html">Dialogue History</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="multiple.html">Multiple Character Dialogue</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="splashscreen_presplash.html">Splashscreen and Presplash</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="statement_equivalents.html">Statement Equivalents</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="save_load_rollback.html">Saving, Loading, and Rollback</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="persistent.html">Persistent Data</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="trans_trans_python.html">Transforms and Transitions in Python</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="gui_advanced.html">Advanced GUI</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="screen_python.html">Screens and Python</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="modes.html">Modes</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="cdd.html">Creator-Defined Displayables</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="cds.html">Creator-Defined Statements</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="custom_text_tags.html">Custom Text Tags</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="character_callbacks.html">Character Callbacks</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="file_python.html">File Access</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="color_class.html">Color Class</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="matrix.html">Matrix</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="model.html">Model-Based Rendering</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="other.html">Other Functions and Variables</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="build.html">Building Distributions</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="updater.html">Web Updater</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="android.html">Android</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="chromeos.html">Chrome OS/Chromebook</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="ios.html">iOS</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="iap.html">In-App Purchasing</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="gesture.html">Gestures</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="raspi.html">Raspberry Pi</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="problems.html">Dealing with Problems</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="environment_variables.html">Environment Variables</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="self_voicing.html">Self-Voicing</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="editor.html">Text Editor Integration</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="skins.html">Skins</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="translating_renpy.html">Translating Ren'Py</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog (Ren'Py 7.x-)</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="changelog6.html">Changelog (Ren'Py 6.11 - 6.99)</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="incompatible.html">Incompatible Changes</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="distributor.html">Distributor Notes</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="credits.html">Credits</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="sponsors.html">Ren'Py Development Sponsors</a></li>
|
||
|
|
</ul>
|
||
|
|
<ul>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="thequestion.html">Script of The Question</a></li>
|
||
|
|
<li class="toctree-l1"><a class="reference internal" href="thequestion_nvl.html">NVL-mode script for The Question</a></li>
|
||
|
|
</ul>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<form class="navbar-form navbar-right" action="search.html" method="get">
|
||
|
|
<div class="form-group">
|
||
|
|
<input type="text" name="q" class="form-control" placeholder="Search" />
|
||
|
|
</div>
|
||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
||
|
|
<input type="hidden" name="area" value="default" />
|
||
|
|
</form>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="container">
|
||
|
|
<div class="row">
|
||
|
|
<div class="col-md-3">
|
||
|
|
<div id="sidebar" class="bs-sidenav" role="complementary"><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="#partial-playback">Partial Playback</a></li>
|
||
|
|
<li><a class="reference internal" href="#sync-start-position">Sync Start Position</a></li>
|
||
|
|
<li><a class="reference internal" href="#volume">Volume</a></li>
|
||
|
|
<li><a class="reference internal" href="#playing-silence">Playing Silence</a></li>
|
||
|
|
<li><a class="reference internal" href="#audio-namespace">Audio Namespace</a></li>
|
||
|
|
<li><a class="reference internal" href="#actions">Actions</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>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="col-md-9 content">
|
||
|
|
|
||
|
|
<div class="section" id="audio">
|
||
|
|
<span id="id1"></span><h1>Audio<a class="headerlink" href="#audio" title="Permalink to this headline"> link</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>Opus</li>
|
||
|
|
<li>Ogg Vorbis</li>
|
||
|
|
<li>MP3</li>
|
||
|
|
<li>MP2</li>
|
||
|
|
<li>FLAC</li>
|
||
|
|
<li>WAV (uncompressed 16-bit signed PCM only)</li>
|
||
|
|
</ul>
|
||
|
|
<p>On the web browser, Ren'Py will check a list of audio formats, and
|
||
|
|
enable a mode that is faster and less prone to skipping if the web
|
||
|
|
browser supports all modes on the list. If your game is using only
|
||
|
|
mp3s, and skips on Safari, then consider changing <a class="reference internal" href="config.html#var-config.webaudio_required_types"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.webaudio_required_types</span></code></a>.</p>
|
||
|
|
<p>Ren'Py supports an arbitrary number of audio channels. There are three
|
||
|
|
normal channels defined by default:</p>
|
||
|
|
<ul class="simple">
|
||
|
|
<li><code class="docutils literal notranslate"><span class="pre">music</span></code> - A channel for music playback.</li>
|
||
|
|
<li><code class="docutils literal notranslate"><span class="pre">sound</span></code> - A channel for sound effects.</li>
|
||
|
|
<li><code class="docutils literal notranslate"><span class="pre">voice</span></code> - A channel for voice.</li>
|
||
|
|
</ul>
|
||
|
|
<p>Normal channels support playing and queueing audio, but only play back
|
||
|
|
one audio file at a time. New normal channels can be registered with
|
||
|
|
<a class="reference internal" href="#renpy.music.register_channel" title="renpy.music.register_channel"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.music.register_channel()</span></code></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. See <a class="reference internal" href="#volume"><span class="std std-ref">Volume</span></a> for more information.</p>
|
||
|
|
<p>In addition to the normal channel, there is one special channel, <code class="docutils literal notranslate"><span class="pre">audio</span></code>.
|
||
|
|
The audio channel supports playing back multiple audio files at one time,
|
||
|
|
but does not support queueing sound or stopping playback.</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"><span class="std std-ref">Button Style Properties</span></a>. Two configuration
|
||
|
|
variables, <a class="reference internal" href="config.html#var-config.main_menu_music"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.main_menu_music</span></code></a> and <a class="reference internal" href="config.html#var-config.game_menu_music"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.game_menu_music</span></code></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"> link</a></h2>
|
||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">play</span></code> 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.</p>
|
||
|
|
<p>The name of a channel is expected following the keyword <code class="docutils literal notranslate"><span class="pre">play</span></code>.
|
||
|
|
(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.</p>
|
||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">fadein</span></code> and <code class="docutils literal notranslate"><span class="pre">fadeout</span></code> 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, <a class="reference internal" href="config.html#var-config.fade_music"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.fade_music</span></code></a>
|
||
|
|
is used.</p>
|
||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">loop</span></code> and <code class="docutils literal notranslate"><span class="pre">noloop</span></code> clauses are also optional. The loop clause causes
|
||
|
|
the music to loop, while noloop causes it to play only once. If neither of them are
|
||
|
|
given, the default of the channel is used.</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">music</span> <span class="s2">"mozart.ogg"</span>
|
||
|
|
<span class="k">play</span> <span class="k">sound</span> <span class="s2">"woof.mp3"</span>
|
||
|
|
<span class="k">play</span> <span class="n">myChannel</span> <span class="s2">"punch.wav"</span> <span class="c1"># 'myChannel' needs to be defined with renpy.music.register_channel().</span>
|
||
|
|
|
||
|
|
<span class="s2">"We can also play a list of sounds, or music."</span>
|
||
|
|
<span class="k">play</span> <span class="k">music</span> <span class="p">[</span> <span class="s2">"a.ogg"</span><span class="p">,</span> <span class="s2">"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>
|
||
|
|
<p>When the <code class="docutils literal notranslate"><span class="pre">if_changed</span></code> clause is provided, and if the given track is currently playing
|
||
|
|
on the channel, the play instruction doesn't interrupt it.</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">market_side</span><span class="p">:</span>
|
||
|
|
<span class="k">play</span> <span class="k">music</span> <span class="n">market</span>
|
||
|
|
<span class="s2">"We're entering the market."</span>
|
||
|
|
<span class="k">jump</span> <span class="n">market_main</span>
|
||
|
|
|
||
|
|
<span class="k">label</span> <span class="n">market_main</span><span class="p">:</span>
|
||
|
|
<span class="k">play</span> <span class="k">music</span> <span class="n">market</span> <span class="n">if_changed</span>
|
||
|
|
<span class="s2">"Maybe we just entered the market, maybe we were already there."</span>
|
||
|
|
<span class="s2">"If we were already there, the music didn't stop and start over, it just continued."</span>
|
||
|
|
<span class="k">jump</span> <span class="n">market_main</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">volume</span></code> clause is also optional, and specifies a relative volume for
|
||
|
|
the track, between 0.0 and 1.0. This makes it possible to adjust the volume a
|
||
|
|
track is played at, each time it's played.</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">sound</span> <span class="s2">"woof.mp3"</span> <span class="n">volume</span> <span class="mf">0.5</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>On the audio channel, multiple play statements play multiple sounds at the same
|
||
|
|
time:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="n">audio</span> <span class="s2">"sfx1.opus"</span>
|
||
|
|
<span class="k">play</span> <span class="n">audio</span> <span class="s2">"sfx2.opus"</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>A variable may be used instead of a string here. If a variable exists in the
|
||
|
|
<a class="reference internal" href="#audio-namespace"><span class="std std-ref">audio namespace</span></a>, it's used in preference to the default namespace:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">music</span> <span class="n">illurock</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>Files placed into the audio namespace may automatically define variables that can
|
||
|
|
be used like this.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="stop-statement">
|
||
|
|
<h2>Stop Statement<a class="headerlink" href="#stop-statement" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">stop</span></code> statement begins with the keyword <code class="docutils literal notranslate"><span class="pre">stop</span></code>, followed by the the name of a
|
||
|
|
channel to stop sound on. It may optionally have a <code class="docutils literal notranslate"><span class="pre">fadeout</span></code>
|
||
|
|
clause.</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">stop</span> <span class="k">sound</span>
|
||
|
|
<span class="k">stop</span> <span class="k">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"> link</a></h2>
|
||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">queue</span></code> 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 begins with keyword <code class="docutils literal notranslate"><span class="pre">queue</span></code>, followed by the the name of a
|
||
|
|
channel to play sound on. It optionally takes the <code class="docutils literal notranslate"><span class="pre">fadein</span></code>, <code class="docutils literal notranslate"><span class="pre">loop</span></code> and <code class="docutils literal notranslate"><span class="pre">noloop</span></code> clauses.</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">queue</span> <span class="k">sound</span> <span class="s2">"woof.mp3"</span>
|
||
|
|
<span class="k">queue</span> <span class="k">music</span> <span class="p">[</span> <span class="s2">"a.ogg"</span><span class="p">,</span> <span class="s2">"b.ogg"</span> <span class="p">]</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>Queue also takes the <code class="docutils literal notranslate"><span class="pre">volume</span></code> clause.</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">sound</span> <span class="s2">"woof.mp3"</span> <span class="n">volume</span> <span class="mf">0.25</span>
|
||
|
|
<span class="k">queue</span> <span class="k">sound</span> <span class="s2">"woof.mp3"</span> <span class="n">volume</span> <span class="mf">0.5</span>
|
||
|
|
<span class="k">queue</span> <span class="k">sound</span> <span class="s2">"woof.mp3"</span> <span class="n">volume</span> <span class="mf">0.75</span>
|
||
|
|
<span class="k">queue</span> <span class="k">sound</span> <span class="s2">"woof.mp3"</span> <span class="n">volume</span> <span class="mf">1.0</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>When multiple queue statements are given without an interaction between them,
|
||
|
|
all sound files are added to the queue. After an interaction has occurred, the
|
||
|
|
first queue statement clears the queue, unless it has already been cleared by
|
||
|
|
a play or stop statement.</p>
|
||
|
|
<p>A variable may be used instead of a string here. If a variable exists in the
|
||
|
|
<a class="reference internal" href="#audio-namespace"><span class="std std-ref">audio namespace</span></a>, it's used in preference to the default namespace:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">audio</span><span class="o">.</span><span class="n">woof</span> <span class="o">=</span> <span class="s2">"woof.mp3"</span>
|
||
|
|
|
||
|
|
<span class="c1"># ...</span>
|
||
|
|
|
||
|
|
<span class="k">play</span> <span class="k">sound</span> <span class="n">woof</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="partial-playback">
|
||
|
|
<span id="id2"></span><h2>Partial Playback<a class="headerlink" href="#partial-playback" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>The values are always interpreted as seconds from the start of the file.
|
||
|
|
The three properties are:</p>
|
||
|
|
<dl class="docutils">
|
||
|
|
<dt><code class="docutils literal notranslate"><span class="pre">from</span></code></dt>
|
||
|
|
<dd>Specifies the position in the file at which the first play-through
|
||
|
|
begins playing. (This defaults to 0.0 seconds.)</dd>
|
||
|
|
<dt><code class="docutils literal notranslate"><span class="pre">to</span></code></dt>
|
||
|
|
<dd>Specifies the position in the file at which the file ends playing.
|
||
|
|
(This defaults to the full duration of the file.)</dd>
|
||
|
|
<dt><code class="docutils literal notranslate"><span class="pre">loop</span></code></dt>
|
||
|
|
<dd>Specifies the position in the file at which the second and later
|
||
|
|
play-throughs begin playing. (This defaults to the start time
|
||
|
|
given by <code class="docutils literal notranslate"><span class="pre">from</span></code> if specified, or to the start of the file.)</dd>
|
||
|
|
</dl>
|
||
|
|
<p>For example:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">music</span> <span class="s2">"<from 5 to 15.5>waves.opus"</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>will play 10.5 seconds of waves.opus, starting at the 5 second mark. The statement:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">music</span> <span class="s2">"<loop 6.333>song.opus"</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>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.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="sync-start-position">
|
||
|
|
<span id="sync-start"></span><h2>Sync Start Position<a class="headerlink" href="#sync-start-position" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<p>The position in the file at which the clip begins playing can also be synced to
|
||
|
|
another channel with a currently-playing track using a filename like
|
||
|
|
"<sync channelname>track.opus", where channelname is the name of the channel,
|
||
|
|
which could be music, sound, or any other registered channels.</p>
|
||
|
|
<p>This can be used to sync multi-layered looping tracks together. For example:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="n">music_2</span> <span class="p">[</span> <span class="s2">"<sync music_1>layer_2.opus"</span><span class="p">,</span> <span class="s2">"layer_2.opus"</span> <span class="p">]</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>Will play layer_2.opus with the start time synced to the current track in
|
||
|
|
channel music_1 in the first iteration, before playing the whole track in
|
||
|
|
subsequent iterations. (By default, the layer_2.opus start time will remain
|
||
|
|
modified even in subsequent iterations in the loop.)</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="volume">
|
||
|
|
<span id="id3"></span><h2>Volume<a class="headerlink" href="#volume" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<p>The volume at which a given track is going to be played depends on a number
|
||
|
|
of variables:</p>
|
||
|
|
<ul class="simple">
|
||
|
|
<li>the "main" mixer's volume</li>
|
||
|
|
<li>the volume of the mixer which the channel relates to</li>
|
||
|
|
<li>the volume of the channel</li>
|
||
|
|
<li>the relative volume of the track itself</li>
|
||
|
|
</ul>
|
||
|
|
<p>These four volumes are values between 0 and 1, and their multiplication results
|
||
|
|
in the volume the track will be played at.</p>
|
||
|
|
<p>For example, if the main volume is 80% (or 0.8), the mixer's volume is 100%,
|
||
|
|
the channel volume is 50% (0.5) and the track's relative volume is 25% (0.25),
|
||
|
|
the resulting volume is .8*1.*.5*.25 = .1, so 10%.</p>
|
||
|
|
<p>The mixers' volumes can be set using <a class="reference internal" href="preferences.html#preferences.set_volume" title="preferences.set_volume"><code class="xref py py-func docutils literal notranslate"><span class="pre">preferences.set_volume()</span></code></a>, using the
|
||
|
|
<a class="reference internal" href="screen_actions.html#SetMixer" title="SetMixer"><code class="xref py py-func docutils literal notranslate"><span class="pre">SetMixer()</span></code></a> action, or using the <a class="reference internal" href="screen_actions.html#Preference" title="Preference"><code class="xref py py-func docutils literal notranslate"><span class="pre">Preference()</span></code></a> action with the
|
||
|
|
"mixer <mixer> volume" key.
|
||
|
|
The "audio" and "sound" channels relate to the "sfx" mixer, the "music" channel
|
||
|
|
to the "music" mixer and the "voice" channel to the "voice" mixer.
|
||
|
|
Every channel additionally relates to the "main" mixer, as shown above.</p>
|
||
|
|
<p>A channel's volume can be set using <a class="reference internal" href="#renpy.music.set_volume" title="renpy.music.set_volume"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.music.set_volume()</span></code></a>. It is only
|
||
|
|
useful when several channels use the same mixer. The <code class="docutils literal notranslate"><span class="pre">mixer</span></code> parameter of the
|
||
|
|
<a class="reference internal" href="#renpy.music.register_channel" title="renpy.music.register_channel"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.music.register_channel()</span></code></a> function sets to which mixer the registered
|
||
|
|
channel relates, creating it in the process if it doesn't already exist.</p>
|
||
|
|
<p>A track's relative volume is set with the <code class="docutils literal notranslate"><span class="pre">volume</span></code> clause of the <span class="xref std std-ref">play-statement</span>.</p>
|
||
|
|
<p>In addition to these volume values, there is the mute flag of the mixer which
|
||
|
|
the channel relates to. If enabled, it will reduce the played volume to 0.
|
||
|
|
They can be set using the <a class="reference internal" href="screen_actions.html#SetMute" title="SetMute"><code class="xref py py-func docutils literal notranslate"><span class="pre">SetMute()</span></code></a> or <a class="reference internal" href="screen_actions.html#ToggleMute" title="ToggleMute"><code class="xref py py-func docutils literal notranslate"><span class="pre">ToggleMute()</span></code></a> actions, or
|
||
|
|
using the <a class="reference internal" href="screen_actions.html#Preference" title="Preference"><code class="xref py py-func docutils literal notranslate"><span class="pre">Preference()</span></code></a> action with the "mixer <mixer> mute" key, or using
|
||
|
|
the <a class="reference internal" href="preferences.html#preferences.set_mute" title="preferences.set_mute"><code class="xref py py-func docutils literal notranslate"><span class="pre">preferences.set_mute()</span></code></a> function.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="playing-silence">
|
||
|
|
<span id="silence"></span><h2>Playing Silence<a class="headerlink" href="#playing-silence" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<p>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:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="n">audio</span> <span class="p">[</span> <span class="s2">"<silence .5>"</span><span class="p">,</span> <span class="s2">"boom.opus"</span> <span class="p">]</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>Will play silence for half a second, and then an explosion sound.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="audio-namespace">
|
||
|
|
<span id="id4"></span><h2>Audio Namespace<a class="headerlink" href="#audio-namespace" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">play</span></code> and <code class="docutils literal notranslate"><span class="pre">queue</span></code> 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.</p>
|
||
|
|
<p>For example, one can write:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">audio</span><span class="o">.</span><span class="n">sunflower</span> <span class="o">=</span> <span class="s2">"music/sun-flower-slow-jam.ogg"</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>and then use:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">music</span> <span class="n">sunflower</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>Ren'Py will also automatically place sound files in the audio namespace,
|
||
|
|
if found in the <code class="docutils literal notranslate"><span class="pre">game/audio</span></code> directory. Files in this directory with a
|
||
|
|
supported extension (currently, .wav, .mp2, .mp3, .ogg, and .opus) have the
|
||
|
|
extension stripped, the rest of the filename forced to lower case, and are
|
||
|
|
placed into the audio namespace.</p>
|
||
|
|
<p>Note that just because a file is placed into the audio namespace, that doesn't
|
||
|
|
mean it can be used. So while you could play a file named "opening_song.ogg"
|
||
|
|
by writing:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">play</span> <span class="k">music</span> <span class="n">opening_song</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>Some filenames can't be accessed this way, as their names are not expressable
|
||
|
|
as Python variables. For example, "my song.mp3", "8track.opus", and
|
||
|
|
"this-is-a-song.ogg" won't work.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="actions">
|
||
|
|
<h2>Actions<a class="headerlink" href="#actions" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<p>See <a class="reference internal" href="screen_actions.html#audio-actions"><span class="std std-ref">Audio Actions</span></a>.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="functions">
|
||
|
|
<h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline"> link</a></h2>
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="AudioData">
|
||
|
|
<code class="descname">AudioData</code><span class="sig-paren">(</span><em>data</em>, <em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#AudioData" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>This class wraps a bytes object containing audio data, so it can be
|
||
|
|
passed to the audio playback system. The audio data should be contained
|
||
|
|
in some format Ren'Py supports. (For examples RIFF WAV format headers,
|
||
|
|
not unadorned samples.)</p>
|
||
|
|
<dl class="docutils">
|
||
|
|
<dt><cite>data</cite></dt>
|
||
|
|
<dd>A bytes object containing the audio file data.</dd>
|
||
|
|
<dt><cite>filename</cite></dt>
|
||
|
|
<dd>A synthetic filename associated with this data. It can be used to
|
||
|
|
suggest the format <cite>data</cite> is in, and is reported as part of
|
||
|
|
error messages.</dd>
|
||
|
|
</dl>
|
||
|
|
<p>Once created, this can be used wherever an audio filename is allowed. For
|
||
|
|
example:</p>
|
||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">audio</span><span class="o">.</span><span class="n">easteregg</span> <span class="o">=</span> <span class="n">AudioData</span><span class="p">(</span><span class="sa">b</span><span class="s1">'...'</span><span class="p">,</span> <span class="s1">'sample.wav'</span><span class="p">)</span>
|
||
|
|
<span class="k">play</span> <span class="k">sound</span> <span class="n">easteregg</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.mark_audio_seen">
|
||
|
|
<code class="descclassname">renpy.</code><code class="descname">mark_audio_seen</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.mark_audio_seen" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Marks the given filename as if it has been already played on the current user's
|
||
|
|
system.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.mark_audio_unseen">
|
||
|
|
<code class="descclassname">renpy.</code><code class="descname">mark_audio_unseen</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.mark_audio_unseen" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Marks the given filename as if it has not been played on the current user's
|
||
|
|
system yet.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.play">
|
||
|
|
<code class="descclassname">renpy.</code><code class="descname">play</code><span class="sig-paren">(</span><em>filename</em>, <em>channel=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.play" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Plays a sound effect. If <cite>channel</cite> is None, it defaults to
|
||
|
|
<a class="reference internal" href="config.html#var-config.play_channel"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.play_channel</span></code></a>. This is used to play sounds defined in
|
||
|
|
styles, <a class="reference internal" href="style_properties.html#style-property-hover_sound"><code class="xref std std-propref docutils literal notranslate"><span class="pre">hover_sound</span></code></a> and <a class="reference internal" href="style_properties.html#style-property-activate_sound"><code class="xref std std-propref docutils literal notranslate"><span class="pre">activate_sound</span></code></a>.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.seen_audio">
|
||
|
|
<code class="descclassname">renpy.</code><code class="descname">seen_audio</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.seen_audio" title="Permalink to this definition"> link</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_duration">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">get_duration</code><span class="sig-paren">(</span><em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.get_duration" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Returns the duration of the audio or video file on <cite>channel</cite>. Returns
|
||
|
|
0.0 if no file is playing on <cite>channel</cite>, or the duration is unknown.
|
||
|
|
Some formats - notably MP3 - do not include duration information in a
|
||
|
|
format Ren'Py can access.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.get_loop">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">get_loop</code><span class="sig-paren">(</span><em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.get_loop" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Return a list of filenames that are being looped on <cite>channel</cite>, or None
|
||
|
|
if no files are being looped. In the case where a loop is queued, but
|
||
|
|
is not yet playing, the loop is returned, not the currently playing
|
||
|
|
music.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.get_pause">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">get_pause</code><span class="sig-paren">(</span><em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.get_pause" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Returns the pause flag for <cite>channel</cite>.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.get_playing">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">get_playing</code><span class="sig-paren">(</span><em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.get_playing" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>If the given channel is playing, returns the playing file name.
|
||
|
|
Otherwise, returns None.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.get_pos">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">get_pos</code><span class="sig-paren">(</span><em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.get_pos" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Returns the current position of the audio or video file on <cite>channel</cite>, in
|
||
|
|
seconds. Returns None if no audio is playing on <cite>channel</cite>.</p>
|
||
|
|
<p>As this may return None before a channel starts playing, or if the audio
|
||
|
|
channel involved has been muted, callers of this function should
|
||
|
|
always handle a None value.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.is_playing">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">is_playing</code><span class="sig-paren">(</span><em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.is_playing" title="Permalink to this definition"> link</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">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">play</code><span class="sig-paren">(</span><em>filenames</em>, <em>channel=u'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>, <em>relative_volume=1.0</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.play" title="Permalink to this definition"> link</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. This is ignored if
|
||
|
|
the channel is paused when the music is played.</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. If
|
||
|
|
None, this is true when loop is True, and false otherwise.</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>
|
||
|
|
<dt><cite>relative_volume</cite></dt>
|
||
|
|
<dd>This is the volume relative to the current channel volume.
|
||
|
|
The specified file will be played at that relative volume. If not
|
||
|
|
specified, it will always default to 1.0, which plays the file at the
|
||
|
|
original volume as determined by the mixer, channel and secondary volume.</dd>
|
||
|
|
</dl>
|
||
|
|
<p>This clears the pause flag for <cite>channel</cite>.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.queue">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">queue</code><span class="sig-paren">(</span><em>filenames</em>, <em>channel=u'music'</em>, <em>loop=None</em>, <em>clear_queue=True</em>, <em>fadein=0</em>, <em>tight=None</em>, <em>relative_volume=1.0</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.queue" title="Permalink to this definition"> link</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. If
|
||
|
|
None, this is true when loop is True, and false otherwise.</dd>
|
||
|
|
<dt><cite>relative_volume</cite></dt>
|
||
|
|
<dd>This is the volume relative to the current channel volume.
|
||
|
|
The specified file will be played at that relative volume. If not
|
||
|
|
specified, it will always default to 1.0, which plays the file at the
|
||
|
|
original volume as determined by the mixer, channel and secondary volume.</dd>
|
||
|
|
</dl>
|
||
|
|
<p>This clears the pause flag for <cite>channel</cite>.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.register_channel">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">register_channel</code><span class="sig-paren">(</span><em>name</em>, <em>mixer</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>, <em>movie=False</em>, <em>framedrop=True</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.register_channel" title="Permalink to this definition"> link</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>name</cite></dt>
|
||
|
|
<dd>The name of the channel.</dd>
|
||
|
|
<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,
|
||
|
|
and will create the mixer if it doesn't already exist, but making new
|
||
|
|
mixers reachable by the player requires 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 occurring. 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>
|
||
|
|
<dt><cite>movie</cite></dt>
|
||
|
|
<dd>If true, this channel will be set up to play back videos.</dd>
|
||
|
|
<dt><cite>framedrop</cite></dt>
|
||
|
|
<dd>This controls what a video does when lagging. If true, frames will
|
||
|
|
be dropped to keep up with realtime and the soundtrack. If false,
|
||
|
|
Ren'Py will display frames late rather than dropping them.</dd>
|
||
|
|
</dl>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.set_pan">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">set_pan</code><span class="sig-paren">(</span><em>pan</em>, <em>delay</em>, <em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.set_pan" title="Permalink to this definition"> link</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_pause">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">set_pause</code><span class="sig-paren">(</span><em>value</em>, <em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.set_pause" title="Permalink to this definition"> link</a></dt>
|
||
|
|
<dd><p>Sets the pause flag for <cite>channel</cite> to <cite>value</cite>. If True, the channel
|
||
|
|
will pause, otherwise it will play normally.</p>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="function">
|
||
|
|
<dt id="renpy.music.set_queue_empty_callback">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">set_queue_empty_callback</code><span class="sig-paren">(</span><em>callback</em>, <em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.set_queue_empty_callback" title="Permalink to this definition"> link</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">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">set_volume</code><span class="sig-paren">(</span><em>volume</em>, <em>delay=0</em>, <em>channel=u'music'</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.set_volume" title="Permalink to this definition"> link</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">
|
||
|
|
<code class="descclassname">renpy.music.</code><code class="descname">stop</code><span class="sig-paren">(</span><em>channel=u'music'</em>, <em>fadeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.music.stop" title="Permalink to this definition"> link</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. This is ignored if
|
||
|
|
the channel is paused.</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"> link</a></h2>
|
||
|
|
<p>Most <code class="docutils literal notranslate"><span class="pre">renpy.music</span></code> functions have aliases in <code class="docutils literal notranslate"><span class="pre">renpy.sound</span></code>. 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>
|
||
|
|
<footer class="footer">
|
||
|
|
<div class="container">
|
||
|
|
<p class="pull-right">
|
||
|
|
<a href="#">Back to top</a>
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
© Copyright 2012-2022, Tom Rothamel.<br/>
|
||
|
|
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.6.<br/>
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
</footer>
|
||
|
|
</body>
|
||
|
|
</html>
|