studio
FolioTier 1
sound
Control the SFX channel - play or stop a sound effect.
Use sound for effects and ambience on a channel separate from the score. The default sfx channel plays once. Give looping rain, crickets, or machinery its own named channel so a short effect does not replace it.
The play event's Playback range controls whether a cue belongs to This scene or continues Across scenes. This scene can cut or fade whenever playback leaves, including an early jump or choice. Across scenes is the default; loop separately controls whether the cue repeats.
An exit fade begins as the scene is left and may overlap the next scene. Incoming audio settings on the destination can cut or fade that channel before its own events play. A stopped cue does not restart when a call returns, and a conditional play that is skipped leaves the previous sound alone. Use an explicit stop for a precise beat within a scene.
Parameters
| Parameter | Kind | Required | Default | Notes |
|---|---|---|---|---|
| action | identifier | yes | - | One of `play`, `stop`, or `volume`. `play` triggers a one-shot SFX; `stop` stops the SFX channel; `volume <0-100>` sets the channel volume from that point on without touching playback (Ren'Py's `renpy.sound.set_volume`). |
| reference | identifier | no | - | Audio reference registered in the project's audio table. Required for `play`; omit for `stop`. Quoted form accepted for references with non-identifier characters. |
| once | identifier | no | - | Optional `play` modifier - `sound play rain-loop once` plays the cue a single time without looping (Ren'Py's `noloop`). The `sfx`, `ambient`, and other custom channels play once by default; `music` and `bgm` channels loop. `once` explicitly keeps the cue one-shot on either kind. Exclusive with `loop`. |
| loop | identifier | no | - | Optional `play` modifier - `sound play crickets loop on ambient` repeats the cue until the channel is stopped, even though `sound` channels play once by default (Ren'Py's `play sound "crickets.ogg" loop` - the ambient crickets / TV hum / boiling-pan idiom). It sits in the same slot as `once`, right after the reference; the two are exclusive (a line with both is an error). Omit both for the channel default. In Studio the audio inspector's Loop control (Channel default / Loop / Play once) writes it. |
| volume | number | no | - | Optional `play` modifier - `sound play door-knock volume(60)` sets the per-cue volume to 60%. Accepts 0-100; multiplies with the listener's master volume and the channel's per-source slider. Omit to use the channel default. |
| muted | identifier | no | - | Optional `play` flag - `sound play door-knock muted` plays the cue at zero volume. Useful when a creator wants the channel state to follow the script without audible playback. Combines with `volume()`; mute wins. |
| this-scene | identifier | no | - | Optional `play` modifier - `sound play rain loop this-scene on ambient` stops the cue 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 cue up from silence over N seconds (Ren'Py's `fadein N`), which is how a long ambient bed eases in rather than slamming on; on `stop` it fades the SFX/ambient channel gain down over N seconds before releasing it (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 - `sound volume 70 on ambient` sets that channel to 70% from here on. Required for `volume`, bare number 0-100 (out-of-range values clamp with a warning). Playing audio keeps playing at the new level. |
| on | identifier | no | sfx | Optional channel override. `sound` lines default to the `sfx` channel - pass `on <channel>` to route to an additional channel, such as `on ambient` for loops separate from one-shot SFX. 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
sound play door-knock
sound play heartbeat on ambient
sound play rain-loop once on ambient
sound play crickets loop on ambient
sound play storm-bed on ambient with fade(3)
sound volume 70 on ambient
sound stop on ambient with fade(1)play sound "door-knock.ogg"
play audio "heartbeat.ogg" channel "ambient"
play audio "rain-loop.ogg" noloop channel "ambient"
play audio "crickets.ogg" loop channel "ambient"
play audio "storm-bed.ogg" channel "ambient" fadein 3
$ renpy.sound.set_volume(0.7, channel="ambient")
stop audio fadeout 1Notes
The default sfx channel plays each cue once. Put an ambient bed on
its own channel, such as sound play rain loop on ambient, so a
door knock does not replace it. loop and once are mutually
exclusive; omitting both uses the channel default. The music and
bgm channels loop, while other channels play once.
Ren'Py's play sound and play audio import as sound play, with
on <channel> when the source names another channel.
Playback range
In Forge, choose This scene or Across scenes on the play
event. This scene offers Cut or Fade out when leaving.
For rain that belongs to an outdoor scene, use
sound play rain loop this-scene exit-fade(1) on ambient.
The fade starts on departure and may overlap the next scene.
This works on early jumps, choices, calls, and returns as well as the scene's end. Returning from a call does not restart a stopped cue. A one-shot can still finish before departure, and a conditional play that is skipped leaves the previous cue alone.
Across scenes is the default and adds no modifier. To silence incoming ambience regardless of its source, open Scene settings > Incoming audio and select Cut or Fade out for its channel. The rule applies before the new scene's events, so those events can start fresh sound. An incoming cut or fade overrides a departing cue's fade; Keep playing does not prolong 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) requires this-scene and only controls departure.
Use an explicit sound stop for a precise beat inside a scene.
Neither Playback range nor Incoming audio inserts stop events.
The play-line order is
sound play <ref> [once|loop] [volume(N)] [muted] [this-scene [exit-fade(N)]] [on <channel>] [with fade(N)] [if <condition>].
Stop uses sound stop [on <channel>] [with fade(N)] [if <condition>].