JavaFX MediaPlayer播放本地音频必须用File.toURI().toString()转合法URI，路径需存在且可读；必须在FX线程中创建和操作；OpenJDK需额外添加原生媒体库才支持MP3。
JavaFX MediaPlayer 播放本地音频文件必须用 File 转 URI 再转 Media
直接传入相对路径字符串（如 "music.mp3"）或绝对路径字符串（如 "C:\audio\bgm.wav"）会抛 MediaException: ERROR_UNKNOWN，因为 Media 构造器只接受合法 URI 字符串。Windows 路径中的反斜杠、空格、中文都会导致解析失败。
正确做法是用 File.toURI().toString() 标准化路径：
File audioFile = new File("res/bgm.mp3");
Media media = new Media(audioFile.toURI().toString());
MediaPlayer player = new MediaPlayer(media);
- 必须确保文件存在且可读，否则构造
Media时不会报错，但后续调用player.play()会静默失败或抛运行时异常 - 路径推荐放在
src/main/resources下，打包后可通过getClass().getResource("/bgm.mp3")获取 URL，再用url.toExternalForm()得到 URI 字符串 - 不建议用
new Media("file:///C:/a/b.mp3")手动拼 URI —— 不跨平台，Linux/macOS 会挂
MediaPlayer 必须在 JavaFX Application Thread 中创建和调用
在普通线程或 Swing/AWT 线程里 new MediaPlayer，或者调用 play()/stop()，会触发 IllegalStateException: Not on FX application thread。这不是音频格式问题，是 JavaFX 的线程安全强制要求。
常见错误场景：从按钮点击事件外启动播放、在 Task 后台线程里调用 player.play()。
立即学习“Java免费学习笔记（深入）”；
- 所有
MediaPlayer相关操作（包括setOnEndOfMedia回调里的逻辑）都应包裹进Platform.runLater() - 如果播放逻辑来自非 UI 线程（如网络下载完成），务必用
Platform.runLater(() -> player.play()) - 初始化
MediaPlayer可以提前做，但首次play()前必须确保 JavaFX 已启动（即launch()已执行）
MP3 播放失败？优先检查 JDK 版本与音频编码兼容性
OpenJDK 11+ 默认不包含 MP3 解码器，MediaPlayer 加载 MP3 会卡在 READY 状态以下（如 UNKNOWN 或 ERROR），且无明确异常。这是最隐蔽的“没声音”原因。
- 确认是否使用 Oracle JDK（自带 Java Media Framework）；若用 OpenJDK，需额外添加
javafx-media的平台原生库（如libjfxmedia.so或jfxmedia.dll），并确保其路径在java.library.path中 - 更稳妥方案：改用 WAV（PCM 编码，JavaFX 原生支持）测试通路，例如
AudioSystem.getAudioFileFormat()可验证文件编码 - 避免使用带 DRM、VBR（可变比特率）或特殊 ID3 标签的 MP3，这些容易触发解码失败
循环播放、音量控制、播放进度监听的典型写法
基础播放只是开始，实际项目中常需控制行为。注意这些 API 的生效时机和副作用：
player.setCycleCount(MediaPlayer.INDEFINITE); // 循环播放（不是 setAutoPlay(true)）
player.setVolume(0.7); // 0.0 ~ 1.0，非分贝值
player.currentTimeProperty().addListener((obs, oldTime, newTime) -> {
System.out.println("当前播放位置：" + newTime.toSeconds());
});
-
setCycleCount()必须在player处于READY状态后设置才有效；状态未就绪就设，循环不会触发 -
setVolume()对已开始播放的媒体实时生效，但对尚未加载完成的Media设置无效 -
currentTimeProperty()监听器在播放开始后才持续触发，暂停期间不更新；如需拖动进度条，要用player.seek()并手动同步 UI
真正麻烦的从来不是写几行播放代码，而是路径处理、线程约束、编解码依赖这三处细节——漏掉任意一个，程序就静默失败，连日志都不给。
