studio
FolioTier 1
music
Control the music channel - play or stop a background track.
Use music to start a background track, stop it, or change its channel volume while it plays. The default music channel loops; a new play replaces the track on that channel. Route another layer to a separate channel when both should sound together.
Choose This scene in the play event's Playback range when a track belongs to this scene alone. It can cut or fade when playback leaves, including through an early branch or call. Across scenes is the default for a score that should continue into later scenes.
A scene's Incoming audio settings can cut or fade a channel regardless of where its track began. They run before the scene's events, so the scene can start its own music afterward. Keep playing leaves the incoming cue's playback range intact. These settings do not add stop events; use an explicit stop for silence at a particular beat.
Parameters
| Parameter | Kind | Required | Default | Notes |
|---|---|---|---|---|
| action | identifier | yes | - | One of `play`, `stop`, or `volume`. `play` starts a new track immediately; `stop` stops the music channel without starting anything new; `volume <0-100>` sets the channel volume from that point on without touching playback (Ren'Py's `renpy.music.set_volume`). |
| reference | identifier | no | - | Audio reference registered in the project's audio table. Required for `play`; omit for `stop` (a `music stop` with a reference is a parse error). Quoted form is accepted when the reference contains characters outside the identifier pattern. |
| once | identifier | no | - | Optional `play` modifier - `music play stinger once` plays the track a single time without looping (Ren'Py's `noloop`). Omit for the default looping behavior on the music channel. Exclusive with `loop`. |
| loop | identifier | no | - | Optional `play` modifier - `music play theme loop` pins looping explicitly (Ren'Py's `play music "theme.ogg" loop`). The `music` / `bgm` channels already loop by default, so on a music line it changes nothing; it exists so an explicit Ren'Py `loop` round-trips honestly and so a music line routed `on` a custom one-shot channel can still repeat. Same slot as `once`; the two are exclusive. In Studio the audio inspector's Loop control (Channel default / Loop / Play once) writes it. |
| volume | number | no | - | Optional `play` modifier - `music play theme volume(60)` sets the per-cue volume to 60%. Accepts 0-100; multiplies with the listener's master + music-channel sliders. Omit to use the channel default. |
| muted | identifier | no | - | Optional `play` flag - `music play theme muted` plays the cue at zero volume. Useful when a creator wants the channel state to follow the script (save-load behavior) without audible playback. Combines with `volume()`; mute wins. |
| this-scene | identifier | no | - | Optional `play` modifier - `music play theme this-scene` stops the track when playback leaves this scene, including an early jump, choice, call, or return. Cuts by default; combine with `exit-fade(N)` to fade out. Omit to allow playback across scenes. In Forge, Playback range selects This scene or Across scenes without adding a stop event. |
| exit-fade | number | no | - | Optional `exit-fade(N)` modifier on a `play` with `this-scene`. Starts a fade-out when the scene is left; N is a finite, non-negative duration in seconds. Omitted or zero cuts. The fade may continue into the next scene. Put it before `on <channel>` and `with fade(N)`, which separately controls the fade-in. |
| fade | number | no | - | Optional `with fade(N)` clause, on both actions. On `play` it ramps the track up from silence over N seconds (Ren'Py's `fadein N`); on `stop` it fades the music gain down over N seconds before releasing the channel (Ren'Py's `fadeout N`). It rides last, after any `on <channel>`. Bare `play` starts at full volume and bare `stop` hard-cuts; `fade(0)` spells either one explicitly. |
| level | number | no | - | The `volume` action's argument - `music volume 40` sets the music channel to 40% from here on. Required for `volume`, bare number 0-100 (out-of-range values clamp with a warning). The playing track keeps playing at the new level. |
| on | identifier | no | music | Optional channel override. `music` lines default to the `music` channel - pass `on <channel>` to route to a different one, such as a second background layer. The channel is a single identifier (letters, digits, `. - _`); it follows the cue and any `once` / `loop` / `volume()` / `muted` / `this-scene` / `exit-fade(N)` modifiers, before any `with fade(...)` clause. |
Canonical example
music play kitchen-theme
music play stinger once
music play tense-bed volume(60)
music play dread-bed with fade(2)
music volume 40
music stop with fade(1)play music "kitchen-theme.ogg"
play music "stinger.ogg" noloop
play music "tense-bed.ogg"
play music "dread-bed.ogg" fadein 2
$ renpy.music.set_volume(0.4)
stop music fadeout 1Notes
Music loops by default on the music and bgm channels. Use once
for a stinger, or on <channel> to keep a second layer separate.
loop and once are mutually exclusive. Ren'Py's queue music
imports as music play.
Playback range
In Forge, choose This scene or Across scenes on the play
event. This scene offers Cut or Fade out on departure;
it changes the event's playback rule without adding a stop event.
The Folio equivalents are music play theme this-scene and
music play theme this-scene exit-fade(1.5).
The rule applies when playback leaves the scene, even through an early choice, jump, call, or return. Jumping back to the same scene starts a fresh visit. Returning from a call does not restart music that stopped on departure. A fade starts at departure and may continue into the next scene; it does not delay the story.
Omit this-scene for Across scenes, the default. Music then
continues until a stop, a replacement play on its channel, an
incoming-audio rule, or the episode ending. In Scene settings >
Incoming audio, choose Keep playing, Cut, or Fade out per
channel. This affects audio brought into a fresh scene, before its
events play; it does not suppress that scene's own music. An incoming
cut or fade takes precedence over the departing cue's fade. Keep playing
does not extend a cue set to This scene.
Fades and explicit stops
with fade(N) fades in on play and fades out on stop.
exit-fade(N) is separate: it fades a this-scene cue when the
scene is left. For silence at a particular beat within a scene,
place music stop or music stop with fade(N) at that beat.
A skipped conditional play does not stop audio already playing.
The play-line order is
music play <ref> [once|loop] [volume(N)] [muted] [this-scene [exit-fade(N)]] [on <channel>] [with fade(N)] [if <condition>].
Stop uses music stop [on <channel>] [with fade(N)] [if <condition>].