动画上下文
由以下方式触发的音频属于动画上下文:
- 动画内的音效关键帧
- 动画内的命令关键帧 Molang
- 脚本控制器 Molang
自动停止时机:动画结束或进入下一轮循环时自动停止。

约 1953 字大约 7 分钟
2025-01-28
2.3.0 版本起,Yes Steve Model 模组支持在动画里调用音频了,但是有一些注意事项:
我该如何转换音频?
音频转换的工具很多,常用的有格式工厂和 Adobe Audition。格式工厂简单易用,方便新手使用。
Adobe Audition 是专业音频制作软件,上手有门槛,但是功能更为强大!
当然,您也可以使用其他转换工具,例如:Audacity、FFmpeg 等,只要能转换为 ogg 格式即可。
新建音频文件夹
文件夹名为固定名称:sounds

添加 .ogg 文件
仅能使用 ogg 格式,其他格式(wav 或者 mp3 等需要转换)

在 BlockBench 内为动画添加音频

如果你的音频路径是 sounds/啊哈哈哈.ogg,那么你只需要在基岩版动画的音频关键帧里填写 啊哈哈哈 即可,不需要加 sounds 前缀和 ogg 后缀。
我想换个文件夹放音频,能自定义么?
可以,首先你需要给你的 ysm.json 的 files 字段中新增 sound_path 字段,填写你想放置音频的文件夹路径。
写法参考如下:
{
"files": {
// 支持任意字符
// 后续基岩版动画里音频关键帧填写的名称和上述一致,不需要添加此文件夹前缀和 ogg 后缀
"sound_path": "声音文件夹"
}
}如果你在基岩版动画的音频关键帧里填写的是原版音频的 ID(类似于:minecraft:block.anvil.hit),那么会调用原版音频进行播放。
原版资源包也可以添加额外的音频文件,并且支持音频随机播放和权重设置,详情可查看官方相关教程:
音效和音乐包教程:Minecraft Wiki
提示
我们强烈建议您使用原版资源包来添加音频,这样可以减少模型文件的大小,还能避免在某些情况下可能出现的版权问题。
本节说明 2.5.3 之后音频系统的两个关键变化:
stop 默认能停止哪一类声音。BlockBench 中在动画控制器里附加的音效已支持。 音效会在进入该状态时触发:先执行“进入时”的 Molang,再开始播放该音效。

从 2.5.3 起,每个播放实例都会归属到某个播放上下文,并按对应规则自动停止。
你可以把每一次播放理解为创建了一个“播放实例”。
动画上下文
由以下方式触发的音频属于动画上下文:
自动停止时机:动画结束或进入下一轮循环时自动停止。

动画控制器上下文
由以下方式触发的音频属于动画控制器上下文:
自动停止时机:当前动画控制器切换到其他状态时自动停止。
全局上下文
由以下方式触发的音频属于全局上下文:
自动停止时机:不会自动停止。
但在以下情况会强制停止所有播放实例:切换模型、实体被移除、传送到其他维度。
常见注意事项
set_animation 或 reset 之后再创建播放实例,否则播放实例可能会立刻被重置。ysm.sync 触发 sync 事件创建的播放实例属于全局上下文(不属于 ysm.sync 调用点所在的上下文)。除了“播放完毕后停止”和“上下文自动停止”之外,还可以使用 Molang 主动停止:ysm.stop_sound 与 ysm.stop_all_sounds。
从 2.5.3 起,这两个函数默认只会停止当前上下文内的播放实例(对其他上下文无效)。
ysm.stop_sound(id, global?)ysm.stop_all_sounds(global?)其中可选参数 global:
global = 1:停止全局上下文的播放实例global = 0 或不写:停止当前上下文的播放实例示例:
ysm.stop_sound('fx', 1)ysm.stop_all_sounds(0)ysm.stop_all_sounds旧版本音频相关 Molang 如下表所示;2.5.3 在保持兼容的同时扩展了参数能力:
| Molang | 描述 |
|---|---|
ysm.play_sound('id', 'sound_name', boolean, volume, pitch) | 播放音频,id为该音频的标识 |
ysm.stop_sound('id') | 停止音频,id为该音频的标识 |
ysm.stop_all_sounds | 停止所有 molang 添加而播放的音频 |
ysm.play_sound(id, name, flags?) 的第三个参数在旧版本常被当作 boolean(0/1)。
从 2.5.3 起,它更准确的含义是 flags(整数标志位,可叠加):
+1:强制重播(有同名播放实例时,停止旧的并创建新的)+2:按全局上下文创建播放实例(忽略当前上下文)+4:循环播放你可以只取其中一项,也可以叠加:
ysm.play_sound('fx', 'sample', 1) // 强制重播ysm.play_sound('fx', 'sample', 2) // 全局上下文ysm.play_sound('fx', 'sample', 4) // 循环播放ysm.play_sound('fx', 'sample', 7) // 1+2+4:强制 + 全局 + 循环ysm.play_sound 的 id 参数旧版本只能是字符串;新版本也可以是不小于 0 的数值:
ysm.play_sound(1, 'sample') // 创建并命名为 1
ysm.stop_sound(1) // 停止 id 为 1 的播放实例2.5.3 引入“匿名播放实例”:当 id = 0 时,每次调用都会创建新的播放实例,允许多个同名声音同时存在(此时“强制重播”无效)。
注意:
ysm.stop_sound 无法停止匿名播放实例。ysm.stop_all_sounds 会停止所有匿名播放实例。2.5.3 改进了 Opus 解码器,以获得更好的播放效果。
Opus 相比常见的 Vorbis 通常能在相同体积下提供更好的音质。你可以在这里下载适用于 YSM 的 Opus 编码工具(仍然输出为 .ogg 文件):