本文讨论在 JVM 桌面应用中嵌入原生 C 媒体引擎（示例为 mpv）时的顺序与线程归属问题。资料未提供该页面的官方介绍文本，以下内容依据所给资料整理。
一、用途与整体模型
原生 C 媒体引擎通常向外暴露句柄、属性包、命令通道和事件流。JVM 侧的工作主要在于安排调用顺序与确定线程归属：哪些设置必须在 initialize 之前完成、哪些对象必须在第一次 load 之前创建、哪个线程可以操作句柄。安排不当会导致失败出现得晚、复现率低，并且容易被归因到错误的代码上。
全文采用的模型是：每个媒体项一个句柄（因此切换过程中会同时存在两个句柄），每个句柄一个事件泵线程，另有一个应用线程负责全部句柄变更。
二、主要陷阱与要点
-
在 initialize 之前、所有分支上显式固定输出驱动。引擎在 initialize 阶段选择输出驱动；未设置时会自动探测，而在无窗口的 JVM 进程中，自动探测可能命中非预期驱动（文中示例为终端图形驱动，导致普通音频播放时整个进程停止）。initialize 之后再创建渲染上下文，并不能追溯更改已选定的驱动。固定失败应视为致命错误：拒绝创建播放器是可恢复的，而原生层面的硬停止不可恢复。文中给出 Kotlin 代码片段示意 audioOnly 分支设置 vid=no 与 vo=null，否则设置 requiredOption("vo", "<embedding-driver>")，固定失败则 terminate_destroy 并返回 null。
-
在 initialize 之后、第一次 load 之前创建渲染上下文。提供嵌入渲染 API 的引擎一般要求如此：视频初始化会失败，或引擎回退到会自行开窗的驱动。initialize 只应用选项，视频输出是在加载带视频的文件时才实例化，因此两步之间是正确时机。若无法创建渲染上下文，应直接禁用视频解码（运行时属性），而不是留下一个背后无物的固定嵌入驱动。
-
将所有属性写入限制在同一个线程，该线程同时负责释放句柄。isReleased 之类的检查不能提供保护：句柄可能在检查与原生调用之间被释放。做法是同步设置字段（使 getter 立即读回），仅把原生调用投递到拥有线程，从而在结构上关闭该窗口。文中以 volume 的 Kotlin 实现为例：setter 内先同步 coerceIn 并保存，再在单线程 scope 中重新读取并换算为百分比后对每个活动句柄调用 setMasterVolume，最后通知监听器。seek、播放速度和任何淡入淡出增益同样需要这次线程跳转。
-
当引擎自身的事件线程也写入时，单一线程不够。泵线程处理“音频输出被重建”之类事件时会重新应用电平，因此也会发起写入且无法跳转。任何读取多个字段并发出多次原生写入的例程都需要对整段读写加锁，否则两个写入者交错，设备可能停在双方都无意设置的组合上。volatile 字段能防止撕裂读取，但不能防止调用对交错。
-
每个播放级设置都必须到达每个活动句柄。在每项一句柄的模型下，速度、音量和淡入淡出增益属于应用而非句柄。最容易被漏掉的是切换中的新句柄：它通常在提升前已从预缓存集合中移除，因而不属于任何集合。应保留一个统一辅助方法枚举当前、新进入和预缓存的句柄，并让所有设置经由它下发。若引擎的设备级电平是进程级而非每句柄，漏掉的句柄不仅保持错误值，还会在下次重配置时重新声明其旧电平，抵消其他句柄的设置。
-
新建句柄从引擎默认值开始。应在其可听之前推送当前电平，并把两个相关电平放在一次调用中推送：逐个设置会发布中间组合，在进程级设备电平下，该中间值会在正在播放的内容上被听到。
-
对可选选项做特性检测；当选项用于关闭某功能时，“选项不存在”即为成功。未构建某子系统的引擎从未拥有该选项，且已处于所需状态。此时发出警告会在每个新建句柄上把已达标报告为问题。文中给出 optionalOption 的 Kotlin 片段：返回 ERROR_OPTION_NOT_FOUND 时记录 Logger.d 说明该构建中选项缺失、已关闭无需处理；其他负返回值记录 Logger.w 及 error_string。可选滤镜同理：应检查引擎实际接受了什么并降级，而不是驱动不在链中的滤镜，否则这些命令会在每个动画步上失败。
-
两侧都用 C 区域格式化数字。Java 侧：引擎解析器只接受点号，使用逗号的默认区域设置会被静默拒绝，setter 返回无人读取的失败，功能始终不动；应使用 String.format(Locale.ROOT, "%.4f", value)。原生侧：JVM 启动时会根据环境设置进程区域，引擎继承用户区域后可能根本无法启动；应只把数字类别重置回 C，不影响应用其他部分的日期、排序和货币。该类别常量不可移植，需按平台验证，不能复用同一个数字。
-
按序关闭，join 不设超时。销毁核心前先停止泵并 join：泵可能正处于对该句柄的调用中（其事件处理器会回调引擎），有界 join 恰好在核心最忙于拆除时放弃。销毁核心前释放渲染上下文，整个阻塞序列在播放线程之外运行。泵循环应在唤醒后重新检查停止标志，确保关闭开始后不再发起新调用，并显式唤醒而非等待轮询超时。
三、验证方式
从仓库根目录运行，使 core/media/media-jvm/... 路径可解析。
第一组 grep 检查视频输出在 mpv_initialize 之前固定（固定失败为致命而非警告），渲染上下文在 initialize 之后、首次 loadFile 之前创建，命令为： grep -n 'requiredOption("vo"|Refusing to initialize mpv without a pinned video output|mpv_initialize(ctx)|MpvVideoFrameSource()|fun loadFile' core/media/media-jvm/src/main/java/com/simpmusic/media_jvm/mpv/MpvPlayer.kt 通过条件：两个 requiredOption("vo", ...) 分支和拒绝消息都出现在 mpv_initialize 之前；MpvVideoFrameSource() 与 loadFile 都出现在其后，且顺序为前者在先。
第二组检查特性检测与 C 区域重置是真实代码： grep -n -A3 "MPV_ERROR_OPTION_NOT_FOUND" core/media/media-jvm/src/main/java/com/simpmusic/media_jvm/mpv/MpvPlayer.kt grep -n "forceCNumericLocale()|val INSTANCE" core/media/media-jvm/src/main/java/com/simpmusic/media_jvm/mpv/MpvLibrary.kt grep -n "MpvLibrary.INSTANCE|lib.mpv_create()" core/media/media-jvm/src/main/java/com/simpmusic/media_jvm/mpv/MpvPlayer.kt 通过条件：第一条匹配后的代码显示 Logger.d 而非 Logger.w；第二条显示 forceCNumericLocale() 位于 lazy INSTANCE 初始化器内；第三条显示 MpvPlayer 在调用 mpv_create() 的前一行读取同一 INSTANCE，即重置已经执行。
四、适用场景与限制
适用场景为在 JVM 桌面应用中嵌入原生 C 媒体引擎并进行播放控制、音量与速度管理、视频渲染上下文接入和生命周期管理的开发工作。限制方面：资料以 mpv 为具体示例，选项名和错误码具有引擎特定性；未提供安装命令、依赖版本、支持平台、收费信息或性能数据，相关内容暂未提供。