音频播放器

音频播放器

通过FMOD播放外部音频文件的简易API。

[center][size=5][color=#ffff00]此模组是一个依赖项。它扩展了游戏功能,但本身不执行任何操作。仅当其他模组需要它并明确要求你安装时才下载。[/color][/size][/center]
[line]

[size=6][b]AudioPlayer[/b][/size]

[size=4]原生 [b]RED4ext[/b] 插件,提供:[/size]
[list]
[]一个精简的、由 [b]FMOD 支持[/b]的外部文件音频播放 API。[/]
[]一个固定的 [b]64 个通道[/b]池外加一个预览通道,用于并行播放。[/]
[]完全[b]异步[/b]流式传输:调用立即返回,一旦 FMOD 报告流已就绪,加载就会在游戏线程上提升。[/]
[/list]可与最新的 [b]RED4ext[/b] 配合使用。所有原生函数均可从 [b]REDscript[/b] 和 [b]CET[/b] 访问。

[line]
[size=5][b]功能[/b][/size]

[b][size=4]1) 歌曲长度探测[/size][/b]

以流的方式打开文件,读取其时长,然后释放。适用于在决定播放之前验证文件是否为有效、可解码的音频源。
[quote][code]public native class AudioPlayer extends IScriptable {
public static native func GetSongLength(path: String) -> Int32[/code][/quote]语义:
[list]
[]返回以[b]毫秒[/b]为单位的时长,如果文件无法打开或解码则返回 [color=#6fa8dc]0[/color]。[/]
[]支持的格式:[color=#f9cb9c].mp3[/color]、[color=#f9cb9c].mp2[/color]、[color=#f9cb9c].flac[/color]、[color=#f9cb9c].ogg[/color]、[color=#f9cb9c].wav[/color]、[color=#f9cb9c].wax[/color]、[color=#f9cb9c].wma[/color]、[color=#f9cb9c].opus[/color]、[color=#f9cb9c].aiff[/color]、[color=#f9cb9c].aif[/color]、[color=#f9cb9c].aifc[/color](即 FMOD Core 能理解的任何格式)。[/]
[/list][b][size=4]2) 播放控制[/size][/b]

在给定通道上启动、停止和设置音量。
[quote][code] public static native func Play(channelID: Int32, path: String, startPos: Int32, volume: Float, fade: Float)
public static native func Stop(channelID: Int32)
public static native func SetVolume(channelID: Int32, volume: Float)
}[/code][/quote][b]说明:[/b]
[list]
[][b]Play[/b]:[color=#f9cb9c]channelID[/color] 指向 [color=#6fa8dc]0..63[/color] 中的槽位,或 [color=#6fa8dc]-1[/color] 表示预览通道。[color=#f9cb9c]startPos[/color] 是以[b]毫秒[/b]为单位的起始偏移量。[color=#f9cb9c]volume[/color] 是线性增益([color=#6fa8dc]1.0[/color] = 100%)。[color=#f9cb9c]fade[/color] 是以[b]秒[/b]为单位的淡入持续时间([color=#6fa8dc]0[/color] 禁用淡入)。[/]
[][b]Stop[/b]:停止并释放通道。对空闲槽位是幂等的。[color=#f9cb9c]channelID[/color] = [color=#6fa8dc]-1[/color] 会停止[b]所有[/b]通道(包括待处理的异步加载)。[/]
[][b]SetVolume[/b]:通道上的线性增益。[color=#f9cb9c]channelID[/color] = [color=#6fa8dc]-1[/color] 将音量应用到[b]每个[/b]通道。对空闲通道是安全的。[/]
[/list]
[size=4][b]REDscript 示例:[/b][/size]
[quote][code]let ms: Int32 = AudioPlayer.GetSongLength("%r6%\\audioware\\MyMod\\track.mp3");
AudioPlayer.Play(0, "%r6%\\audioware\\MyMod\\track.mp3", 0, 0.7, 0.5);
AudioPlayer.SetVolume(-1, 0.0); // 全部静音
AudioPlayer.Stop(-1); // 全部停止[/code][/quote][line]
[size=5][b]路径解析[/b][/size]

传递给 [color=#93c47d]GetSongLength[/color] 和 [color=#93c47d]Play[/color] 的所有路径都[b]相对于包含 [color=#f9cb9c]Cyberpunk2077.exe[/color] 的目录[/b]——即 [color=#f9cb9c]<Cyberpunk 2077>\bin\x64\[/color],而非游戏根目录。这对你编写的每个相对路径都很重要:
[list]
[][color=#f9cb9c]plugins\cyber_engine_tweaks\mods\<YourMod>\<file.mp3>[/color] 解析为
[quote][code]<Cyberpunk 2077>\bin\x64\plugins\cyber_engine_tweaks\mods\<YourMod>\<file.mp3>[/code][/quote][/
]
[][color=#f9cb9c]..\..\r6\audioware\<YourMod>\<file.mp3>[/color] 会爬出 [color=#f9cb9c]bin\x64\[/color] 并解析为
[quote][code]<Cyberpunk 2077>\r6\audioware\<YourMod>\<file.mp3>[/code][/quote][/
]
[][color=#f9cb9c]..\..\mods\<YourMod>\<file.mp3>[/color] 解析为
[quote][code]<Cyberpunk 2077>\mods\<YourMod>\<file.mp3>[/code][/quote][/
]
[/list]如果这感觉脆弱,请使用下面的[b]路径变量[/b]——它们无需 [color=#f9cb9c]..\..[/color] 的繁琐操作就能生成相同的最终位置。


[b]路径变量[/b]

为方便起见,路径可以以下列标记之一开头。该标记会在与 bin 目录拼接之前展开,因此无论游戏安装在何处,最终位置始终是明确定义的。

[list]
[][color=#f9cb9c]%game%[/color] – 游戏根目录([color=#f9cb9c]<Cyberpunk 2077>\[/color])。[/]
[][color=#f9cb9c]%cet%[/color] – CET 模组文件夹([color=#f9cb9c]<Cyberpunk 2077>\bin\x64\plugins\cyber_engine_tweaks\mods\[/color])。[/]
[][color=#f9cb9c]%r6%[/color] – R6 根目录([color=#f9cb9c]<Cyberpunk 2077>\r6\[/color])。[/]
[/list]示例:
[quote][code]AudioPlayer.Play(0, "%cet%\\MyMod\\track.mp3", 0, 1.0, 0.0);
AudioPlayer.Play(1, "%r6%\\audioware\\MyMod\\intro.ogg", 0, 1.0, 0.0);
AudioPlayer.Play(2, "%game%\\mods\\MyMod\\sfx.wav", 0, 1.0, 0.0);[/code][/quote]只识别路径[b]开头[/b]的标记;未知标记会原样传递。

作为 [color=#93c47d]Play[/color] 中的特殊情况,将 [color=#f9cb9c]startPos[/color] = [color=#6fa8dc]-1[/color] 传入会将 [color=#f9cb9c]path[/color] 标记为[b]流 URL[/b] 并跳过 bin 目录拼接(字符串原样交给 FMOD,不进行 [color=#f9cb9c]%var%[/color] 展开)。

[line]
[size=5][b]CET (Lua) 示例[/b][/size]

[quote][code]local path = "%cet%\\MyMod\\track.mp3"
local length = AudioPlayer.GetSongLength(path)
if length > 0 then
AudioPlayer.Play(-1, path, 0, 0.7, 0.5)
end[/code][/quote][line]
[size=5][b]需求[/b][/size]

必需
[list]
[]Cyberpunk 2077([b]版本 2.5[/b])[/]
[][url=https://www.nexusmods.com/cyberpunk2077/mods/2380]RED4ext[/url](加载器)[/]
[][url=https://www.nexusmods.com/cyberpunk2077/mods/1511]REDscript[/url](库)[/]
[/list]可选
[list]
[][url=https://www.nexusmods.com/cyberpunk2077/mods/107]Cyber Engine Tweaks[/url] 用于快速测试[/]
[/list][line]
[size=5][b]安装[/b][/size]

1. 将构建的 DLL 和 FMOD 运行时放入
[quote][code]<Cyberpunk 2077>\red4ext\plugins\AudioPlayer\AudioPlayer.dll
<Cyberpunk 2077>\red4ext\plugins\AudioPlayer\fmod.dll[/code][/quote]2. 启动游戏。检查日志:
[quote][code]<Cyberpunk 2077>\red4ext\logs\AudioPlayer-<timestamp>.log[/code][/quote][line]
[size=5][b]CET (Lua) 烟雾测试(可选)[/b][/size]

[quote][code]print("SongLength:", AudioPlayer.GetSongLength("C:\\users\\<YourName>\\Music\\track.mp3"))[/code][/quote][line]
[size=5][b]日志[/b][/size]

插件使用 [b]RED4ext 日志记录器[/b]。你可以在以下位置找到消息:
[quote][code]<CP2077>\red4ext\logs\AudioPlayer-<timestamp>.log[/code][/quote]关键条目:
[list]
[][color=#ea9999]FMOD::System_Create / FMOD::System::init[/color] – FMOD 初始化失败;所有原生调用被禁用。[/]
[][color=#ea9999]createSound: <error>. Path: <path>[/color] – [color=#93c47d]GetSongLength[/color] 无法打开文件。[/]
[][color=#ea9999]FMOD::System::createStream[/color] – [color=#93c47d]Play[/color] 无法排队流。[/]
[][color=#ea9999]Failed to load '<path>' (attempt N).[/color] – 异步加载报告 [color=#f9cb9c]FMOD_OPENSTATE_ERROR[/color];在文件被列入黑名单之前最多重试三次。[/]
[][color=#ea9999]Invalid channel ID: N[/color] – [color=#f9cb9c]channelID[/color] 超出 [color=#6fa8dc]-1..64[/color]。[/]
[/list][line]
[size=5][b]故障排除[/b][/size]

[list]
[][b]没有声音 / [color=#93c47d]Play[/color] 静默无操作:[/b]验证路径。[color=#93c47d]Play[/color] 没有返回值——请先检查 [color=#93c47d]GetSongLength(path)[/color] > [color=#6fa8dc]0[/color]。[/]
[][b]插件加载失败:[/b]确认 [color=#f9cb9c]fmod.dll[/color] 与 [color=#f9cb9c]AudioPlayer.dll[/color] 一起位于 [color=#f9cb9c]red4ext\plugins\AudioPlayer\[/color] 中。[/]
[][b]所有通道无响应:[/b]检查日志中是否有 [color=#ea9999]FMOD init failed[/color];初始化失败会禁用所有原生调用。[/]
[][b]特定文件始终无法播放:[/b]查找 [color=#ea9999]Failed to load '<path>' (attempt N).[/color] – 三次尝试后文件会被列入黑名单,直到游戏重启。[/]
[/list][line]
[size=5][b]版本说明[/b][/size]

- 面向[b]最新[/b]的 [url=https://www.nexusmods.com/cyberpunk2077/mods/2380]RED4ext[/url] 加载器和当前游戏版本。
- [url=https://www.fmod.com/]FMOD Core API[/url] 在次要版本之间二进制稳定;任何近期的 2.x 运行时均可使用。

[line]
[size=5][b]致谢[/b][/size]

特别感谢 [url=https://www.nexusmods.com/profile/NexusGuy999]keanuWheeze[/url] 和 [url=https://www.nexusmods.com/cyberpunk2077/mods/4591]RadioExt[/url] 项目,为 [url=https://www.fmod.com/]FMOD[/url] 集成提供了宝贵的见解并帮助节省了开发时间。虽然 [url=https://www.nexusmods.com/profile/NexusGuy999]keanuWheeze[/url] 和 [url=https://www.nexusmods.com/cyberpunk2077/mods/4591]RadioExt[/url] 项目均未直接参与本项目,但他们的工作是有帮助的参考。部分方法使用了相似的名称和参数,以使 API 更易于使用、更直观。