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.

In Forge, the play event's drawing is the whole track. Drag its side grips to keep one section of the file, and a looping track repeats just that section. Choose This scene when a track belongs to this scene alone: it cuts or fades when playback leaves, including through an early branch or call. Across is the default for a score that should continue into later scenes.

A track that plays once stops at its end point with no fade, because an exit fade runs only when playback leaves the scene. A later play of the same file with a different section restarts it. 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 Forge the audio inspector's repeat control (Default / Loop / 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. In Forge, the top-edge grip of the play event's drawing and the fader beside it write it.
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.
from	number	no	-	Optional `from(S)` modifier on `play` - `music play theme from(12.5)` starts the track S seconds into the file. S is a non-negative decimal with up to 3 decimal places. `from(0)` means the same as leaving it out and is not written back. It may appear alone or with `to(S)`, and is not valid on `stop`. In Forge, the left side grip of the play event's drawing writes it.
to	number	no	-	Optional `to(S)` modifier on `play` - `music play theme to(48)` ends the track S seconds into the file, counted from the start of the file and not from `from(S)`. S has up to 3 decimal places and must be greater than `from(S)`, or greater than 0 when it appears alone. A looping track repeats only the section between the two, and a track that plays once stops there with no fade. It is not valid on `stop`. In Forge, the right side grip of the play event's drawing writes it.
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, the This scene and Across options choose between them 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. In Forge, the top right corner of the play event's drawing writes it.
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. In Forge, the top left corner of the play event's drawing writes the `play` fade and the corner of the Stop drawing writes the `stop` fade.
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` / `from(S)` / `to(S)` / `this-scene` / `exit-fade(N)` modifiers, before any `with fade(...)` clause.

Canonical example

Folio

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)

Ren'Py

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 1

Notes

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.

Trimming

from(S) and to(S) play one section of the file, counted in seconds from the start of the file: music play theme from(12.5) to(48). In Forge, the play event's drawing is the whole track. Drag a side grip, or click it and type a time such as 1:05, 1:05.5 or 65.

A looping track repeats only that section. Because the browser decodes the whole file first, a trimmed loop can start a moment after its event. A track that plays once stops at to with no fade, because exit-fade(N) runs only when playback leaves the scene. To fade out before the end, place a music stop with fade(N) at that beat.

to past the end of the file means the end of the file, and from at or past the end plays from the start. A later play of the same file with a different trim restarts it. Replacing the file in Forge clears the trim. Ren'Py's <from X to Y> file prefix has the same meaning.

Playback range

In Forge, choose This scene or Across on the play event. This scene cuts on departure; drag the top right corner of the drawing inward to fade out instead. Neither adds 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, 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. In Forge, drag the top left corner of the play event's drawing, or the corner of the Stop event's drawing, and read the length from the pill beside the fade: fades there are drawn at a fixed scale, not at track time. 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.