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.

In Forge, the play event's drawing is the whole file. Drag its side grips to keep one section, and a looping cue repeats just that section. This scene ends the cue with a cut or a fade whenever playback leaves, including an early jump or choice. Across is the default; Default, Loop and Once separately control whether the cue repeats.

A cue that plays once stops at its end point with no fade. An exit fade begins only as the scene is left, and it may overlap the next scene. A later play of the same file with a different section restarts it. 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 Forge the audio inspector's repeat control (Default / Loop / 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. 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 - `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.
from	number	no	-	Optional `from(S)` modifier on `play` - `sound play rain from(2.5)` starts the cue 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` - `sound play rain to(8)` ends the cue 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 cue repeats only the section between the two, and a cue 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 - `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, 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 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. 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 - `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` / `from(S)` / `to(S)` / `this-scene` / `exit-fade(N)` modifiers, before any `with fade(...)` clause.

Canonical example

Folio

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)

Ren'Py

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 1

Notes

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.

Trimming

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

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

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 when leaving; drag the top right corner of the drawing inward to fade out instead. 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 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. 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) requires this-scene and only controls departure. Use an explicit sound stop for a precise beat inside a scene. Neither This scene nor Incoming audio inserts stop events.