Ren'Py Audio Guide: Music, Sound Effects, and Voice

What makes or breaks immersion in a visual novel isn't the text or the art — it's the audio. A BGM that cuts out abruptly or a misplaced sound effect pulls you right out of the experience.

This guide covers how to work with BGM, sound effects, and voice in Ren'Py 8.5.2 from the ground up.

Choosing Audio Formats

Ren'Py supports several audio formats, but not all are equal.

WAV is uncompressed, so file sizes are large. Using it for BGM bloats your distribution. It's fine for short effects like door sounds or footsteps.

Playing Music, Sound Effects, and Voice

Ren'Py has three playback statements.

play music — Play BGM

# Play BGM (loops by default)
play music "audio/main_theme.ogg"

# Crossfade to a new track
play music "audio/battle.ogg" fadeout 1.0 fadein 0.5

# Play once without looping
play music "audio/ending.ogg" noloop

# Don't restart if the same track is already playing
play music "audio/main_theme.ogg" if_changed

play music uses the music channel. It loops by default.

play sound — Play Sound Effects

# Play a sound effect (once)
play sound "audio/explosion.ogg"

# Adjust volume
play sound "audio/rain.ogg" volume 0.3

# Loop a sound effect (ambient sounds)
play sound "audio/rain.ogg" loop

play sound uses the sound channel. It doesn't loop by default.

voice — Play Voice Lines

voice "voice/001.ogg"
e "Hello."

voice "voice/002.ogg"
e "Nice weather today."

voice uses the voice channel. It stops automatically at the next interaction (when the player advances text). For voiced games, write one voice line before each dialogue line.

Stopping Audio

# Stop BGM
stop music

# Fade out then stop
stop music fadeout 2.0

# Stop sound effects
stop sound

# Stop voice
stop voice

How Channels Work

Ren'Py manages audio through channels. Each channel plays, stops, and controls volume independently.

Default Channels

Playing a new track on the music channel automatically stops the previous one. To play two tracks simultaneously, create a custom channel.

The audio channel is special — each play audio call creates a new channel automatically, allowing multiple sounds to play at once. However, queue audio and stop audio are not supported. If you need simultaneous playback with stop control, use a custom channel instead.

Creating Custom Channels

To control ambient sounds (rain, wind) independently from BGM, register a custom channel.

init python:
    renpy.music.register_channel("ambient", "sfx", loop=True)

label start:
    play music "audio/main_theme.ogg"
    play ambient "audio/rain.ogg"

    "The journey continues through the rain."

    stop ambient fadeout 2.0

    "The rain has stopped."

The second argument to register_channel is the mixer name. Using "sfx" means the preferences screen's SFX volume slider controls this channel.

Queuing the Next Track

# Play the next track after the current one ends
play music "audio/intro.ogg" noloop
queue music "audio/main_theme.ogg"

queue starts the next track when the currently playing one finishes. Use it for intro → main theme transitions.

Fades and Loop Points

Fade In and Fade Out

# Fade out current BGM over 2s, fade in new BGM over 1s
play music "audio/battle.ogg" fadeout 2.0 fadein 1.0

# Fade out and stop BGM over 3s
stop music fadeout 3.0

fadeout applies to the currently playing track. fadein applies to the new track. Getting this distinction wrong leads to unexpected results.

Setting Loop Points

Many BGM tracks have an "intro → loop section" structure. Setting a loop point plays the intro once, then repeats only the loop section.

# Loop from 6.333 seconds (everything before is the intro, played once)
play music "<loop 6.333>audio/main_theme.ogg"

# Play only a specific section
play music "<from 5.0 to 30.0>audio/long_track.ogg"

Dynamic Volume Control

# Change channel volume (fade over 1 second)
$ renpy.music.set_volume(0.3, delay=1.0, channel="music")

# Set relative volume for a specific file
play sound "audio/loud_explosion.ogg" volume 0.5

renpy.music.set_volume() changes the overall channel volume. The volume keyword sets relative volume for an individual file.

Organizing Audio Files

As your file count grows, writing paths directly gets tedious. Create aliases in the audio namespace with define for easier management.

The audio Namespace

define audio.main_theme = "audio/bgm/main_theme.ogg"
define audio.battle = "audio/bgm/battle.ogg"
define audio.click = "audio/se/click.ogg"
define audio.explosion = "audio/se/explosion.ogg"

label start:
    play music main_theme
    play sound click

    "The adventure begins."

    play music battle fadeout 1.0
    play sound explosion

Aliases defined in the audio namespace can be used directly in play statements. No need to write file paths every time, and typos are caught early.

Folder Structure Example

game/
└── audio/
    ├── bgm/
    │   ├── main_theme.ogg
    │   ├── battle.ogg
    │   └── ending.ogg
    ├── se/
    │   ├── click.ogg
    │   ├── explosion.ogg
    │   └── door_open.ogg
    └── voice/
        ├── 001.ogg
        ├── 002.ogg
        └── 003.ogg

Separating BGM, SFX, and voice into subfolders keeps things organized. Ren'Py auto-detects files in game/audio/ and its subdirectories.

Wrapping Up

What we covered:

• Format selection: Use OGG or Opus for BGM. Avoid MP3 due to loop gaps
• Playback statements: play music (BGM), play sound (SFX), voice (voice lines)
• Channels: music / sound / voice / audio — four defaults. Custom channels for ambient sounds
• Fades and loop points: fadeout/fadein parameters, <loop> syntax for intro + loop
• File organization: define audio.xxx aliases in the audio namespace

For Ren'Py basics, see the getting started guide. For image display, see the image basics guide. For UI, see the screen language guide.

Official resources:

• Audio — official audio reference
• Voice — voice feature details
• Audio Formats Guide — format comparison (VNDev Wiki)
• r/RenPy — community