YYKA 音频管理套件（yyka-audio-kit）
一套「好用、简单」的 Cocos Creator 音频管理扩展：编辑器侧统一管理音频，运行时侧用一行代码播放，并联动 TTS 语音合成。装好 → 导入 → 复制一段代码，即可在游戏里播放 BGM / 音效 / 语音。
✨ 功能特性
- 音频资源统一管理：BGM / 音效 / 语音 / UI 归档（按文件夹自动归类 + 面板里可手动改分类），一键导入到
assets/resources/audio（确保构建打包、运行时可加载），导入后自动生成AudioKey枚举，代码里用稳定键引用音频，告别脆弱路径。 - 音量分层控制器：主音量 × BGM × 音效 × 语音 乘法增益链，每层独立静音，调音台拖动实时试听，预设可保存/导入导出。
- BGM 跨场景续播 + 淡入淡出：切场景不断音；同曲重入不重启，换曲自动交叉淡入淡出。
- 音效对象池（防爆音）：短音效复用预建实例，播放/停止带极小淡入淡出，从根上消除「咔哒 / 爆音」；复音数可调（1–64）。
- 音频事件标记：在音频时间线打点，播放到某秒触发回调（切动画 / 扣血 / 播台词），可视化编辑、按资产持久化、一键生成代码。
- 3D 空间音频：按与听者距离自动衰减，
setListener+playSfx3D两行搞定有方位感的音效。 - TTS 语音联动：语音层专承载合成语音，可与 yyka-ai-agent-mcp 联动，AI 生成的语音直接推进游戏播放。
- 音频转码：本地 ffmpeg.wasm 把 wav→mp3/ogg 压缩体积、可批量剪首尾静音/降噪，保留引用不失效。
- 引用审计：一键扫描全工程，找出未使用 / 超大 / 偏长 / 损坏的音频，清理包体。
- 上手指南 + 示例 Demo：内置「🧭 上手指南」页，4 步流程 + 可复制的接入代码 + 功能地图；附示例场景，按 1~0 体验全部 API。
📋 使用说明
4 步接入（面板「上手指南」一键引导）：
-
装运行时：安装扩展后打开面板，点「安装运行时代码」装进工程（含示例 Demo）。
-
导入音频：「资源」页导入你的音频（自动放入
assets/resources/audio并生成AudioKey）；也可先点「装示例音频」立刻试听。 -
复制代码接入游戏：在游戏启动处引入一次，之后任意位置调用：
ts// 启动处引入一次（已自动初始化，无需手动 init） import { YYKAAudioKit, AudioKey } from './yyka-audio-kit/audio-bootstrap'; // 之后任意位置调用 YYKAAudioKit.playBgm(AudioKey.BGM_TOWN, { loop: true, fadeInSec: 1 }); YYKAAudioKit.playSfx(AudioKey.SFX_CLICK); YYKAAudioKit.playVoice(AudioKey.VOICE_NARRATION); YYKAAudioKit.playSfx3D(AudioKey.SFX_GUNSHOT, { x: 6, y: 0, z: 0 }, { minDist: 2, maxDist: 30 }); -
预览验证：编辑器工具栏点 ▶ 预览运行游戏，即可听到声音。
📖 想了解更多 / 更详细的使用文档（完整 API 参考、进阶用法、视频教程），请关注公众号 「智能运营咖」 获取。
⚙️ 引擎与环境要求
- Cocos Creator 3.8.8 及以上（扩展声明
editor: ">=3.8.8"）。 - 项目使用 TypeScript 脚本（运行时为 TS 源码，装入工程后由 Cocos 编译）。
- 安装扩展需要能访问 npm（扩展含
vue、@ffmpeg/core依赖，安装时自动拉取）。 - Web / H5 预览受浏览器自动播放策略限制：首次发声需在用户手势内（点击按钮播放时插件已自动恢复音频上下文）。
🖥️ 平台支持情况
- 运行时基于 Cocos 引擎的
AudioSource/ 音频系统，支持 Cocos Creator 发布的主流平台：Web / H5、微信小游戏等小游戏平台、Android、iOS、Windows、macOS 等。 - 各平台最终音频能力以对应平台与引擎版本为准；小游戏平台需平台自身的音频适配。
- 编辑器面板仅在 Cocos Creator 编辑器内可用（资源管理 / 调音台 / 转码 / 审计等）。
📜 更新日志
1.0.0
- 首发：音频分类管理、音量分层、SFX 对象池、BGM 跨场景续播 + 淡入淡出、自动生成
AudioKey枚举、引用审计、清单导出、MCP 批量重命名、TTS 联动。 - 迭代修复与增强：
- 修复运行时没声（音频改存
assets/resources/audio，避免构建剔除 / 404）；导入后自动生成枚举。 - 修复根节点 / AudioSource 未创建导致的静默不播。
- 运行时代码规范为
import { ... } from 'cc'。 - 新增「上手指南」独立页（默认首页）、一键示例音频、编辑器加载时自动装运行时。
- 可操作的中文报错提示；发布 zip 结构修正、随包分发文档。
- 修复运行时没声（音频改存
❓ 常见问题 FAQ
- 点了播放却没声音？
- 确认音频在
assets/resources/audio/<分类>/下（用面板「资源」页导入会自动放对；放在其它assets/目录可能被构建剔除导致 404）。 - Web 预览需在用户手势内首次发声——点按钮播放即可（插件已自动恢复音频上下文）。
- 用
YYKAAudioKit.debugAudio()查看音频上下文与播放状态。
- 确认音频在
- 支持哪些音频格式？ mp3 / wav / ogg / m4a 等 Cocos 支持的音频格式；可用「转码」页批量压缩。
- 怎么在游戏里播放？ 引入一次
audio-bootstrap，再YYKAAudioKit.playBgm/playSfx/...，详见docs/USAGE.zh-CN.md。 - BGM 切场景会断吗？ 默认跨场景续播；可用
setBgmCrossScene(false)关闭。 - 如何调音量 / 静音？
setLayerVolume('bgm', 0.6)、setLayerMute('sfx', true)，或在「调音台」页可视化调整。 - 增删了音频文件？ 回「资源」页刷新，会自动重新生成
AudioKey枚举。
⚠️ 购买须知
本产品为付费虚拟插件商品，一经购买成功概不退款，请支付前谨慎确认购买内容。
购买后获得对应版本授权，仅限授权范围内使用；
插件仅支持标注的 Cocos Creator 版本，请确认引擎版本符合要求再下单；
不包含定制开发服务，如有定制需求可单独咨询；
严禁二次分发、转售、反编译本插件。
📞 联系我们
如遇问题、有定制需求或希望增加功能，欢迎联系作者：
官网：https://www.yyka.cn
邮箱：yykacn@qq.com
公众号：智能运营咖
关键词
Cocos Creator 音频管理、BGM 管理、音效池、音量分层、音频枚举生成、跨场景 BGM、淡入淡出、3D 空间音频、音频事件回调、TTS 语音、音频转码压缩、引用审计、yyka-audio-kit
感谢用户的内容
感谢你选择 YYKA 音频管理套件！希望它能让你的游戏音频「接入简单、播放稳定、管理省心」。使用中如有建议或想要的功能，欢迎通过上面的方式联系我——每一条反馈都会被认真对待。祝开发顺利 🎧