音频与视频

本页属于 GenPy Ren'Py 学习路线。教程内容面向 Ren'Py 8.x，并在页面末尾连接到 GenPy 的对应工作流。

学习目标

• 了解“音频与视频”在 Ren'Py 项目中的用途。
• 能在一个最小项目里验证本章相关语法或工作流。
• 知道发布前需要检查的常见风险，并能在 GenPy 中继续维护。

核心语法

• play music
• play sound
• voice
• queue
• stop
• Movie

可运行示例

define audio.town = "audio/town_theme.ogg"
define audio.woof = "audio/woof.mp3"

label start:
    play music town
    play sound woof

教程正文

Ren'Py 通过**通道（channel）**管理声音。默认通道：music（音乐）、sound（音效）、 voice（语音），还有可同时播多个的特殊通道 audio。

1. 播放音乐 / 音效

play music "audio/theme.ogg"            # 在 music 通道循环播放
play sound "audio/click.ogg"            # 在 sound 通道播一次
play music "bgm.ogg" fadeout 1.0 fadein 1.0   # 旧曲淡出 1s、新曲淡入 1s

• 推荐音频格式：OGG Vorbis（体积小、跨平台）、Opus，也支持 MP3/WAV/FLAC。
• music 通道默认循环，sound 通道默认播一次。

可选子句

play music "a.ogg" fadein 2.0 loop          # 强制循环
play sound "se.ogg" noloop                  # 强制只播一次
play music "b.ogg" volume 0.5               # 相对音量
play music [ "a.ogg", "b.ogg" ] fadeout 1.0 # 列表：依次播放

2. 停止与排队

stop music                    # 停止音乐
stop music fadeout 2.0        # 淡出 2 秒后停止
queue music "next.ogg"        # 当前曲播完后接着播（不打断）
queue sound "se2.ogg"

play 会打断当前曲；queue 不打断、排到队尾。

3. 定义音频别名

用 define audio.xxx 给文件起短名，便于复用：

define audio.town = "audio/town_theme.ogg"
define audio.woof = "audio/woof.mp3"

label start:
    play music town
    play sound woof

4. 角色配音（Voice）

逐句语音用 voice，通常写在台词前：

voice "audio/voice/e_001.ogg"
e "你好，欢迎回来。"

自动语音（按文件命名）

启用 config.auto_voice 可按对话 id 自动匹配语音文件，省去逐句写 voice：

init python:
    config.auto_voice = "voice/{id}.ogg"

语音标签与静音

给角色加 voice_tag，便于在偏好里按角色开关配音：

define e = Character("艾琳", voice_tag="eileen")

voice_sustain 可让语音跨句持续。

5. 音量与偏好

• 玩家在游戏菜单的 Preferences 里分别调 Music / Sound / Voice 音量。
• 程序内可用 renpy.music.set_volume(0.5, channel="music") 临时设置。
• 混音定位（声道/相对音量）可用 register_channel。

6. 自定义通道

init python:
    renpy.music.register_channel("ambient", mixer="sfx", loop=True)
label start:
    play ambient "audio/rain.ogg"

7. 视频 / 过场动画（Movie）

全屏过场视频

label opening:
    $ renpy.movie_cutscene("movies/intro.webm")
    "（过场结束）"

作为可显示物的视频（可叠加在场景里）

image ed_movie = Movie(play="movies/ending.webm")
label ending:
    scene black
    show ed_movie
    pause

• 推荐视频格式：WebM（VP8/VP9），跨平台兼容性最好；也支持部分 MPEG-4。
• 视频做动态背景时配合 Movie(loop=True)。

常见坑

• 音频路径相对 game/；建议统一放 game/audio/。
• 跨平台优先 OGG/WebM；某些平台对 MP3/MP4 支持不一致。
• play music 同名文件默认不会重复打断（已在放则忽略）；想强制重播可先 stop。
• 语音建议用 voice_tag + 偏好开关，方便玩家关闭特定角色配音。

官方参考

• 音频：https://www.renpy.org/doc/html/audio.html
• 配音：https://www.renpy.org/doc/html/voice.html
• 视频：https://www.renpy.org/doc/html/movie.html

在 GenPy 里怎么做

• 在 GenPy 的代码模式中维护相关 .rpy 文件，先保持语法清晰，再逐步加入本章功能。
• 用故事图谱、变量、校验或演出编辑器把“能运行”提升到“可维护”。
• 导出前结合 Ren'Py Lint 和 GenPy 校验结果，确认脚本、素材和发布路径一致。

推荐继续阅读：

• 演出编辑器
• 资源库与素材管理
• 导出与下载