![[MV/MZ Plugin] YXIO MusicDirector – Adaptive Music, Intensity Layers & Beat-Synced Transitions](https://external-preview.redd.it/b-1CSlxwaUpAC4JBSwf4BsKpnhXQ3-i-yVyGOHQmXQk.png?width=140&height=111&auto=webp&s=6fbdce121b39190a56ac2f55e34933f25ddf099d)
[MV/MZ Plugin] YXIO MusicDirector – Adaptive Music, Intensity Layers & Beat-Synced Transitions
YXIO MusicDirector
Let your music react to the game.
让音乐真正跟随游戏发生变化。
Hi everyone! We are Candlehart Studio（烛鹿工坊）, and today we'd like to introduce another plugin in our YXIO Audio Series: YXIO MusicDirector.
大家好，我们是 Candlehart Studio（烛鹿工坊）。今天想向大家介绍 YXIO 音频系列的新插件：YXIO MusicDirector。
YXIO MusicDirector is an adaptive music and dynamic score control system designed for RPG Maker MV and MZ.
YXIO MusicDirector 是一套面向 RPG Maker MV 与 MZ 的自适应音乐与动态配乐控制系统。
Instead of treating BGM as a single track that simply starts, stops, and gets replaced, MusicDirector lets you organize music into reusable Music Profiles, change musical intensity during gameplay, build synchronized Stem layers, and schedule transitions around Beats, Bars, or Phrases.
它不再把 BGM 仅仅视为一首“播放、停止、然后被另一首音乐替换”的音频，而是让你通过可复用的 音乐配置（Music Profiles） 管理配乐，并根据游戏状态改变音乐强度、控制同步 Stem 分层音轨，以及让切换发生在下一拍、下一小节或下一乐句。
At its simplest, you can still use one normal BGM per Profile.
If you need more, the same system can grow into layered battle music, boss phases, tension systems, exploration states, and other reactive soundtracks.
最简单的情况下，你仍然可以让一个音乐配置只播放一首普通 BGM。
而当项目需要更复杂的音乐表现时，同一套系统还可以继续扩展为分层战斗音乐、Boss 阶段变化、紧张度系统、探索状态以及其他动态响应式配乐。
────────────────
Why MusicDirector? / 为什么做这个插件？
RPG Maker's normal BGM workflow works well when a map or scene only needs one piece of music.
如果一个地图或场景只需要播放一首固定 BGM，那么 RPG Maker 原本的音乐系统已经足够使用。
But things become more complicated when the music itself needs to react to gameplay.
但当音乐本身需要响应游戏状态时，事情就会变得复杂。
For example:
例如：
• Exploration music should smoothly transition into battle music instead of cutting at an arbitrary point.
• 探索音乐进入战斗时，希望能够平滑衔接，而不是在任意位置直接切断。
• A battle theme should become more intense when the situation becomes dangerous.
• 当战斗进入危险状态时，希望同一套配乐能够逐渐提高强度。
• A boss theme may begin with only a few instruments, then add drums, strings, or choir as new phases begin.
• Boss 战开始时可能只有少量乐器，而随着阶段推进，再逐渐加入鼓组、弦乐或合唱。
• A new track may sound much more natural if it begins on the next Bar instead of immediately.
• 某些音乐如果等待到下一小节再进行切换，会比立即播放自然得多。
• A boss reveal may need a short musical accent without interrupting the current score.
• Boss 登场时可能需要一段短促的音乐强调，但又不希望因此中断当前配乐。
YXIO MusicDirector was built around these kinds of situations.
YXIO MusicDirector 正是围绕这些使用场景设计的。
The basic idea is intentionally simple:
核心概念刻意保持得很简单：
Music Profile = What should play.
音乐配置 = 播放什么。
Transition = How it should change.
音乐切换 = 如何发生变化。
────────────────
Key Features / 核心功能
◆ Music Profiles
◆ 音乐配置系统
MusicDirector organizes music into reusable Music Profiles.
MusicDirector 使用可复用的 音乐配置（Music Profiles） 来管理游戏中的配乐。
A Profile can be as simple as:
一个最基础的配置只需要：
Profile ID: Explore
Playback Mode: Track
Base BGM: Field01
Transition: Smart
Then activate it whenever your game enters that musical state.
之后只需要在游戏进入对应状态时启用这个 Profile。
This makes it easier to think in terms of musical states such as:
这样可以直接按照游戏中的音乐状态进行设计，例如：
• Exploration
• 探索
• Battle
• 战斗
• Danger
• 危险
• Boss
• Boss 战
• Victory
• 胜利
• Stealth
• 潜行
• Story or emotional scenes
• 剧情或情绪场景
────────────────
◆ Track & Layered Stem Modes
◆ 普通曲目与分层 Stem 模式
MusicDirector supports two main playback approaches.
MusicDirector 提供两种主要的音乐播放方式。
Track Mode / 普通曲目模式
Use one normal BGM as the Profile's music.
直接使用一首普通 BGM 作为当前音乐配置的基础配乐。
This is the recommended starting point and works well for projects that mainly need better music transitions or several intensity variants.
这是最适合快速开始的模式，也非常适合主要需要音乐平滑切换或多个音乐强度版本的项目。
Layered Stems / 分层音轨模式
Advanced projects can divide one composition into synchronized Stem files.
进阶项目可以把一首音乐拆分成多条同步 Stem 音轨。
For example:
例如：
Base
Drums
Strings
Choir
All active Stem layers stay on the same musical timeline, while Intensity changes control their target volume.
所有启用的 Stem 会保持在同一条音乐时间线上，而音乐强度变化只负责调整不同 Stem 的目标音量。
For example:
例如：
Intensity 0
Base
Intensity 1
Base + Drums
Intensity 2
Base + Drums + Strings
Intensity 3
Base + Drums + Strings + Choir
This allows the music to grow or calm down without restarting the entire composition.
这样可以在不重新开始整首音乐的情况下，让配乐逐渐增强或减弱。
For best results, Stem files should share the same start point, length, BPM, and musical structure.
为了获得正确的同步效果，Stem 音轨应使用相同的起点、长度、BPM 与音乐结构。
────────────────
◆ Dynamic Intensity
◆ 动态音乐强度
Each Music Profile can define multiple numeric Intensity Levels.
每个音乐配置都可以定义多个数字形式的音乐强度等级。
During gameplay, you can change Intensity through Plugin Commands or the Script API.
在游戏运行过程中，可以通过插件指令或脚本 API 动态改变当前音乐强度。
In Track Mode, different Intensity Levels can select different complete BGM files.
在普通曲目模式下，不同强度等级可以切换到不同的完整 BGM。
For example:
例如：
Level 0 → Battle_Low
Level 2 → Battle_High
In Stem Mode, Intensity changes the volume of synchronized layers instead.
而在 Stem 模式中，音乐强度控制的是同步分层音轨的音量。
If the exact requested level does not exist, MusicDirector automatically resolves to a valid configured level using deterministic fallback rules.
如果请求的强度等级并未配置，MusicDirector 会按照确定的规则自动选择最合适的已配置等级。
────────────────
◆ Smart, Crossfade & Immediate Transitions
◆ 智能、交叉淡化与立即切换
Different situations need different kinds of music transitions.
不同的游戏场景需要不同的音乐切换方式。
MusicDirector provides:
MusicDirector 提供：
Smart
Uses the configured smooth transition behavior. Recommended for simple setups.
智能切换
使用当前配置的平滑切换方式，适合大多数基础项目。
Crossfade
The previous music fades down while the new Profile fades in.
交叉淡化
旧音乐逐渐降低音量，同时新音乐逐渐进入。
Immediate
Stops the previous music and starts the next Profile immediately.
立即切换
立即停止旧音乐并开始播放新的音乐配置。
Each Profile can define its normal transition behavior, while individual commands can temporarily override it.
每个音乐配置都可以设置自己的默认切换方式，同时也可以在某一次插件指令中临时覆盖该设置。
────────────────
◆ Beat / Bar / Phrase Synchronized Transitions
◆ 下一拍 / 下一小节 / 下一乐句同步切换
MusicDirector can also perform Musical Sync transitions.
MusicDirector 还支持音乐同步切换（Musical Sync）。
Instead of changing tracks immediately, the system can wait for a musical boundary:
系统可以不立即切换，而是等待指定的音乐节点：
Next Beat
下一拍
Next Bar
下一小节
Next Phrase
下一乐句
For example, if your current battle music is running at 120 BPM, you can tell MusicDirector to wait until the next Bar before beginning the Boss Profile transition.
例如，如果当前战斗音乐为 120 BPM，你可以让 MusicDirector 等待到下一小节，再开始切换至 Boss 音乐配置。
This can make transitions feel much more intentional than simply changing BGM at the exact frame an event occurs.
相比于事件触发的那一帧就直接更换 BGM，这种方式可以让音乐衔接听起来更自然。
Musical Sync uses BPM and timing information from the currently playing Profile.
音乐同步功能会根据当前播放配置中的 BPM 与节拍信息计算切换时间。
If valid timing information or playback position is unavailable, MusicDirector safely falls back to a normal Crossfade instead of breaking playback.
如果当前无法取得有效的音乐时序或播放位置，MusicDirector 会安全回退到普通交叉淡化，而不会因此中断音乐系统。
────────────────
◆ Stingers
◆ 音乐提示段
MusicDirector supports one-shot musical accents called Stingers.
MusicDirector 支持用于音乐强调的一次性 Stinger（音乐提示段）。
A Stinger can be played manually or assigned as the Enter Stinger of a Music Profile.
Stinger 可以通过指令手动播放，也可以设置为某个音乐配置的进入提示段。
For example:
例如：
• Boss reveal
• Boss 登场
• Battle victory accent
• 战斗胜利强调
• Discovery moment
• 发现重要内容
• Phase transition
• Boss 阶段变化
• Story reveal
• 剧情揭示
The Stinger plays over the current music instead of replacing it.
Stinger 会叠加在当前音乐上播放，而不是替换当前配乐。
────────────────
◆ RPG Maker MV & MZ Support
◆ RPG Maker MV / MZ 双兼容
One MusicDirector runtime supports both RPG Maker MV and RPG Maker MZ.
同一套 MusicDirector 运行时代码同时支持 RPG Maker MV 与 RPG Maker MZ。
RPG Maker MZ
Visual Plugin Commands are included.
提供可视化插件指令。
RPG Maker MV
Matching text-based Plugin Commands are supported.
提供对应的文本插件指令。
For example:
例如：
YXIO_MusicDirector SetMusicProfile Explore
YXIO_MusicDirector SetIntensity 2 600
YXIO_MusicDirector SetMusicProfile Battle musical bar 400
YXIO_MusicDirector PlayStinger BossReveal 90
YXIO_MusicDirector StopMusic 800
────────────────
◆ Runtime Control & Script API
◆ 运行时控制与脚本 API
During gameplay you can:
游戏运行过程中可以：
• Enable or disable MusicDirector
• 启用或禁用 MusicDirector
• Change the current Music Profile
• 更改当前音乐配置
• Change Music Intensity
• 更改当前音乐强度
• Override transition behavior
• 临时覆盖音乐切换方式
• Request Beat / Bar / Phrase synchronized transitions
• 请求下一拍 / 下一小节 / 下一乐句同步切换
• Play Stingers
• 播放 Stinger
• Fade and stop MusicDirector music
• 淡出并停止 MusicDirector 音乐
• Query the current Profile and Intensity
• 查询当前音乐配置和音乐强度
• Print runtime status for debugging
• 输出当前运行状态用于调试
A public Script API is also included for custom systems and plugin integration.
同时提供公开 Script API，方便自定义系统和其他插件进行联动。
────────────────
◆ Save-State Support
◆ 存档状态支持
MusicDirector can save its runtime state together with the game.
MusicDirector 可以将运行状态随游戏存档一起保存。
This includes:
包括：
• Enabled state
• 插件启用状态
• Current Music Profile
• 当前音乐配置
• Current Intensity
• 当前音乐强度
• Approximate playback position when available
• 在可获取时保存近似音乐播放位置
Old saves without MusicDirector data safely return to plugin defaults.
旧存档中没有 MusicDirector 数据时，会安全使用插件默认设置。
────────────────
◆ Native BGM Compatibility
◆ 原生 BGM 协作机制
MusicDirector does not permanently take control away from RPG Maker's normal BGM system.
MusicDirector 不会永久接管 RPG Maker 原本的 BGM 系统。
When MusicDirector starts a Profile, it stops the currently managed native BGM to prevent duplicate playback.
当 MusicDirector 开始播放音乐配置时，会停止当前原生 BGM，避免两套音乐同时播放。
If another event or plugin later uses RPG Maker's normal BGM playback, MusicDirector yields control and stops its own active sessions.
如果之后某个事件或其他插件重新调用 RPG Maker 原生 BGM 播放，MusicDirector 会主动让出控制并停止自己的活动音乐 Session。
This means normal Change BGM events can still remain part of your project.
因此项目中原有的 更改 BGM（Change BGM） 事件仍然可以继续使用。
────────────────
◆ Optional YXIO AudioBus Integration
◆ 可选 YXIO AudioBus 联动
YXIO MusicDirector works completely standalone.
YXIO MusicDirector 可以完全独立运行。
No Core plugin is required.
无需安装任何 Core 前置插件。
If YXIO AudioBus is installed, MusicDirector can optionally integrate with its Music Bus and External Source system.
如果同时安装了 YXIO AudioBus，MusicDirector 可以选择接入它的 Music Bus 与 External Source 系统。
This allows MusicDirector sessions to participate in:
这样可以进一步让 MusicDirector 的音乐参与：
• Bus volume control
• 音频总线音量控制
• Bus mute state
• 总线静音
• Mix Snapshots
• 混音快照
• Source-Bus Ducking
• Source-Bus Ducking 自动压低
If AudioBus is missing or the requested Bus does not exist, MusicDirector continues playing normally in standalone mode.
即使没有安装 AudioBus，或者指定的 Bus 不存在，MusicDirector 仍会继续以独立模式正常播放音乐。
────────────────
English / 中文 / 日本語
YXIO MusicDirector includes Plugin Manager metadata for English, Simplified Chinese, and Japanese.
YXIO MusicDirector 为英文、简体中文和日语提供对应的插件管理器语言数据。
Parameter names, descriptions, options, Plugin Commands, and nested Music Profile settings are localized for the RPG Maker editor.
插件参数、说明、选项、插件指令以及音乐配置中的嵌套设置都会根据 RPG Maker 编辑器语言显示对应内容。
Runtime warnings and diagnostic messages also support automatic language selection.
运行时警告与调试信息同样支持自动语言选择。
────────────────
Practical Examples / 实际使用场景
Exploration → Battle
探索 → 战斗
Use an Explore Profile while walking around the map.
地图探索时启用 Explore 配置。
When combat begins, switch to Battle using Smart or Crossfade.
战斗开始后，通过 Smart 或 Crossfade 切换到 Battle 配置。
────────────────
Dynamic Battle Intensity
动态战斗强度
Start battle at Intensity 0.
战斗开始时使用强度 0。
Increase to Intensity 1 when stronger enemies appear.
强敌出现时提高到强度 1。
Increase to Intensity 2 when HP becomes critical or a new phase begins.
进入危险状态或新阶段后提高到强度 2。
────────────────
Layered Boss Theme
分层 Boss 配乐
Prepare synchronized:
准备同步的：
Base
Drums
Strings
Choir
Then gradually activate more layers as the boss fight progresses.
之后随着 Boss 战推进逐渐加入更多音乐层。
The song continues on the same timeline instead of restarting every time the intensity changes.
每次改变音乐强度时不会重新开始整首音乐，而是在同一时间线上继续播放。
────────────────
Next-Bar Boss Transition
下一小节进入 Boss 配乐
Configure the current Profile with BPM and Beats Per Bar.
为当前音乐配置设置 BPM 与每小节拍数。
Trigger the Boss Profile using Musical Sync → Next Bar.
使用“音乐同步 → 下一小节”进入 Boss 配置。
MusicDirector calculates the next Bar boundary and begins the transition there.
MusicDirector 会计算下一小节的时间点，并在那里开始音乐切换。
────────────────
Boss Reveal Stinger
Boss 登场 Stinger
Assign a BossReveal ME as the Boss Profile's Enter Stinger.
将 BossReveal ME 设置为 Boss 音乐配置的进入 Stinger。
When the Boss Profile actually starts, the Stinger plays over the new music.
当 Boss 配置真正开始播放时，Stinger 会叠加在新的配乐上出现。
────────────────
Quick Setup / 快速安装
- Copy
YXIO_MusicDirector.jsinto your project'sjs/plugins/folder. 将YXIO_MusicDirector.js放入项目的js/plugins/文件夹。 - Enable it in the RPG Maker Plugin Manager. 在 RPG Maker 插件管理器中启用插件。
- Create a Music Profile. 创建一个音乐配置（Music Profile）。
- For the simplest setup, choose Track Mode and select one Base BGM. 最简单的使用方式是选择普通曲目模式，然后指定一首基础 BGM。
- Leave the Transition Mode on Smart. 将音乐切换方式保持为智能切换（Smart）。
- Activate the Profile with Set Music Profile. 使用**设置音乐配置（Set Music Profile）**插件指令启用它。
That's enough to start using MusicDirector.
这样就已经可以开始使用 MusicDirector。
Intensity, Layered Stems, BPM synchronization, and Stingers can be added later only when your project needs them.
音乐强度、分层 Stem、BPM 同步和 Stinger 都可以在项目真正需要时再逐步加入。
────────────────
Get YXIO MusicDirector / 获取插件
YXIO MusicDirector is available now on itch.io:
YXIO MusicDirector 现已在 itch.io 发布：
https://candlehart-studio.itch.io/yxio-musicdirector
Regular Price: $6.99
Launch Price: $4.19
原价：$6.99
首发价：$4.19
We are currently offering a limited-time 40% launch discount.
目前提供限时六折首发优惠。
If you're building an RPG with dynamic battles, boss phases, exploration states, tension changes, stealth sections, or any situation where music should respond to gameplay instead of simply restarting another BGM, we hope MusicDirector can make that part of development easier.
如果你正在制作包含动态战斗、Boss 阶段、探索状态、紧张度变化、潜行场景，或者任何需要“让音乐响应游戏，而不只是重新播放另一首 BGM”的 RPG，希望 MusicDirector 能让这部分开发变得更加简单。
────────────────
Feedback & Compatibility Reports / 反馈与兼容性报告
Feedback and compatibility reports are very welcome.
非常欢迎大家提供实际使用反馈与兼容性报告。
If you encounter a problem, please include your:
如果遇到问题，建议尽量提供：
• RPG Maker version
• RPG Maker 版本
• YXIO MusicDirector version
• YXIO MusicDirector 版本
• Other relevant audio or BGM plugins
• 相关音频或 BGM 插件
• Plugin load order
• 插件加载顺序
• Reproduction steps
• 问题复现步骤
• Console error messages, if available
• 如果能够获取，请附上控制台报错信息
Stem-related issues are especially helpful to report with information about the source files, BPM, track length, and synchronization setup.
如果问题与 Stem 分层音轨有关，也建议同时提供源音频文件的 BPM、长度以及同步配置方式。
Plugins that completely replace RPG Maker's BGM or WebAudio behavior may require additional compatibility work.
如果其他插件完整替换了 RPG Maker 的 BGM 或 WebAudio 处理流程，可能需要进行额外兼容。
We will continue improving compatibility and usability based on real project feedback.
我们也会继续根据实际项目中的使用反馈优化兼容性与使用体验。
────────────────
YXIO MusicDirector v0.1.2
Adaptive Music & Dynamic Score Control for RPG Maker MV/MZ
RPG Maker MV/MZ 自适应音乐与动态配乐系统
Developed by
枫间落羽 / Candlehart Studio（烛鹿工坊）
Copyright © 2026 枫间落羽 and Candlehart Studio（烛鹿工坊）.
All rights reserved.
