FolioTier 1
sound
Control the SFX channel — play, queue, or stop a sound effect.
Parameters
| Parameter | Kind | Required | Default | Notes |
|---|---|---|---|---|
| action | identifier | yes | — | One of `play`, `queue`, or `stop`. `play` triggers a one-shot SFX; `queue` schedules one to play after the currently-playing sound on the channel finishes; `stop` stops the SFX channel. |
| reference | identifier | no | — | Audio reference registered in the project's audio table. Required for `play` and `queue`; omit for `stop`. Quoted form accepted for references with non-identifier characters. |
| once | identifier | no | — | Optional `play`/`queue` modifier — `sound play rain-loop once` plays the cue a single time without looping (Ren'Py's `noloop`). Most SFX channels don't loop by default, but ambient channels often do — `once` forces a one-shot. |
| fade | number | no | — | Optional `stop` modifier — `sound stop fade=1` fades the SFX/ambient channel gain down over 1 second before releasing it (Ren'Py's `fadeout 1`). Bare `sound stop` hard-cuts. |
| on | identifier | no | sfx | Optional channel override. `sound` lines default to the `sfx` channel — pass `on <channel>` to route to an additional channel (e.g. `on ambient` for layered ambient loops separate from one-shot SFX). |
Canonical example
sound play door-knock
sound play heartbeat on ambient
sound play rain-loop once on ambient
sound stop fade=1 on ambientplay sound "door-knock.ogg"
play audio "heartbeat.ogg" channel "ambient"
play audio "rain-loop.ogg" noloop channel "ambient"
stop audio fadeout 1sound is the SFX verb. The action grammar mirrors music — play,
queue, stop — but the default channel is sfx so one-shot effects
don't fight with the music channel. Use a different channel for
layered ambient loops that should keep running while other SFX fire
(sound play rain-loop on ambient).
Notes
sound and music are intentionally separate verbs even though the
parser routes both through the same parseAudioLine function — the
split keeps creator intent explicit and lets the runtime apply
per-type mixing (SFX ducks under voice, music ducks under SFX, etc.)
without inspecting channel names.
Ren'Py's play sound "..." and play audio "..." channel "<name>"
both lower to this verb during import. The default channel for
sound is sfx; the importer leaves the on clause off when the
Ren'Py source used the default channel implicitly.
Modifiers
The same two modifiers as music apply (shared parser):
once— appended toplayorqueue. Plays the cue a single time without looping (Ren'Pynoloop). Important for ambient channels that loop by default and need an explicit one-shot.fade=N— appended tostop(seconds, integer or decimal). Fades the gain down overNseconds before releasing the channel (Ren'Pyfadeout N). Baresound stophard-cuts.