[Bug] 循环播放音频报错

[iouter]

模块范围

Audio（音频）

严重程度

Broken feature（功能不可用）

发生了什么？

我尝试循环播放bgm，代码是这样的：

var loop = GameAudioService.Shared.PlayLoop(
            AudioSource.Event(path),
            new AudioPlaybackOptions
            {
                Volume = volume,
                Pitch = pitch,
            }
        );

没有效果，并爆出日志（见下面的日志部分）。

复现步骤

执行代码：

var loop = GameAudioService.Shared.PlayLoop(
            AudioSource.Event(path),
            new AudioPlaybackOptions
            {
                Volume = volume,
                Pitch = pitch,
            }
        );

期望行为

我想要循环播放音频

或者循环播放音乐，替换本身的背景音乐也行。其他的api好像都不能实现循环播放？

日志 / 堆栈

ERROR: Cannot set parameter loop to value 0.000000void __cdecl godot::FmodEvent::set_parameter_by_name(const class godot::String &,float) constsrc\studio\fmod_event.cpp69
   at: push_error (core/variant/variant_utility.cpp:1024)
   C# backtrace (most recent call first):
       [0] Godot.Variant Godot.NativeCalls.godot_icall_2_875(nint, nint, Godot.NativeInterop.godot_string_name, System.ReadOnlySpan`1[Godot.Variant], Godot.NativeInterop.godot_string_name)
       [1] Godot.Variant Godot.GodotObject.Call(Godot.StringName, Godot.Variant[])
       [2] bool STS2RitsuLib.Audio.AudioHandleBase.TryCall(string, Godot.Variant[]) (F:\Github\sts-2-opencode\sts-2-ritsulib\src\Audio\AudioHandleBase.cs:225)
       [3] bool STS2RitsuLib.Audio.AudioHandleBase.TrySetParameter(string, float) (F:\Github\sts-2-opencode\sts-2-ritsulib\src\Audio\AudioHandleBase.cs:154)
       [4] STS2RitsuLib.Audio.AudioPlayResult STS2RitsuLib.Audio.GameAudioService.AttachStudioLoop(STS2RitsuLib.Audio.AudioSource, Godot.GodotObject, STS2RitsuLib.Audio.AudioPlaybackOptions) (F:\Github\sts-2-opencode\sts-2-ritsulib\src\Audio\GameAudioService.cs:182)
       [5] STS2RitsuLib.Audio.AudioPlayResult STS2RitsuLib.Audio.GameAudioService.PlayStudioLoop(STS2RitsuLib.Audio.StudioEventSource, STS2RitsuLib.Audio.AudioPlaybackOptions) (F:\Github\sts-2-opencode\sts-2-ritsulib\src\Audio\GameAudioService.cs:155)
       [6] STS2RitsuLib.Audio.AudioLoopHandle STS2RitsuLib.Audio.GameAudioService.PlayLoop(STS2RitsuLib.Audio.AudioSource, STS2RitsuLib.Audio.AudioPlaybackOptions) (F:\Github\sts-2-opencode\sts-2-ritsulib\src\Audio\GameAudioService.cs:73)
       [7] void LexNinja2.LexNinja2Code.Api.NinjaAudio.PlayLooped(string, float, float) (.\LexNinja2Code\Api\NinjaAudio.cs:31)
       [8] void LexNinja2.LexNinja2Code.Cards.Events.AlanWalker+<OnPlay>d__5.MoveNext() (.\LexNinja2Code\Cards\Events\AlanWalker.cs:31)
       [9] void System.Threading.ExecutionContext.RunInternal(System.Threading.ExecutionContext, System.Threading.ContextCallback, object)
       [10] void System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1.MoveNext(System.Threading.Thread)
       [11] void System.Threading.Tasks.AwaitTaskContinuation.RunCallback(System.Threading.ContextCallback, object, System.Threading.Tasks.Task&)
       [12] void System.Threading.Tasks.Task.RunContinuations(object)
       [13] bool System.Threading.Tasks.Task`1.TrySetResult(TResult)
       [14] void System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1.SetExistingTaskResult(System.Threading.Tasks.Task`1[TResult], TResult)
       [15] void System.Runtime.CompilerServices.AsyncTaskMethodBuilder.SetResult()
       [16] void MegaCrit.Sts2.Core.Commands.Cmd+<Wait>d__1.MoveNext()
       [17] void System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1.ExecutionContextCallback(object)
       [18] void System.Threading.ExecutionContext.RunInternal(System.Threading.ExecutionContext, System.Threading.ContextCallback, object)
       [19] void System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1.MoveNext(System.Threading.Thread)
       [20] void System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1.MoveNext()
       [21] void System.Threading.Tasks.AwaitTaskContinuation.RunCallback(System.Threading.ContextCallback, object, System.Threading.Tasks.Task&)
       [22] void System.Threading.Tasks.Task.RunContinuations(object)
       [23] bool System.Threading.Tasks.Task.TrySetResult()
       [24] bool System.Threading.Tasks.TaskCompletionSource.TrySetResult()
       [25] void MegaCrit.Sts2.Core.Commands.Cmd+<>c__DisplayClass2_0.<WaitInternal>g__Receive|0()
       [26] void Godot.Callable.<From>g__Trampoline|1_0(object, Godot.NativeInterop.NativeVariantPtrArgs, Godot.NativeInterop.godot_variant&)
       [27] void Godot.DelegateUtils.InvokeWithVariantArgs(nint, System.Void*, Godot.NativeInterop.godot_variant**, int, Godot.NativeInterop.godot_variant*)

RitsuLib 版本

0.4.41

运行环境

No response

[ritsukage-local-analyzer]

Warning

此分析由 AI 自动生成，仅供开发者参考，最终判断请以人工确认为准。如有疑问建议结合本地环境进一步复现确认。

摘要

GameAudioService.Shared.PlayLoop(AudioSource.Event(path)) 在 0.4.41 中会默认按“原版 loop 参数约定”给 Studio event 写入 loop = 0，而日志显示目标 FMOD event 可能没有名为 loop 的参数，因此底层 FmodEvent.set_parameter_by_name 报错。影响集中在用 Studio event path 做循环播放/背景音时；建议先用 UsesLoopParameter = false 规避，并由维护者调整高层 API 对 loop 参数的默认处理或失败策略。

重点结论

项目	结论
简单介绍	调用高层循环播放 API 后没有听到循环音频，并出现 Cannot set parameter loop to value 0.000000。
可能原因	高置信：AudioPlaybackOptions.UsesLoopParameter 默认 true，AttachStudioLoop 无条件尝试设置 loop 参数；目标 event 不支持该参数时触发 FMOD/Godot 错误。中等置信：高层 AudioLoopHandle 的停止语义与原版 usesLoopParam 语义未完全对齐，可能让“loop 参数控制型事件”和“直接 stop 型事件”混在一起。
可能解决方案	调用侧可先设置 UsesLoopParameter = false，或对背景音乐改用 PlayMusic(AudioSource.Event(path)) / AudioSource.StreamingMusic(...) 视资源类型选择。维护侧建议避免在 PlayLoop 启动阶段默认写 loop = 0，或仅在明确请求且参数存在时写入，并补充文档说明。
需要补充	还需要确认 path 指向的 FMOD event 是否实际含 loop 参数、是否已加载对应 bank/GUID mapping，以及运行环境（游戏版本/平台/资源来源）。

展开详细分析、证据与验证

问题描述

期望行为

循环播放音频，或以某种方式循环/替换背景音乐。

实际行为

调用 PlayLoop(AudioSource.Event(path), new AudioPlaybackOptions { Volume = volume, Pitch = pitch }) 后没有效果，并输出 FMOD/Godot 错误：无法设置 loop 参数为 0。

复现步骤

1. 在 RitsuLib 0.4.41 中执行：

   var loop = GameAudioService.Shared.PlayLoop(
       AudioSource.Event(path),
       new AudioPlaybackOptions
       {
           Volume = volume,
           Pitch = pitch,
       });

2. 观察播放结果与日志。

环境与版本

• RitsuLib：0.4.41
• 模块范围：Audio（音频）
• 运行环境：issue 中为 _No response_

日志、附件与原文摘录

• 原文：

  ERROR: Cannot set parameter loop to value 0.000000
godot::FmodEvent::set_parameter_by_name ... src\studio\fmod_event.cpp69
  要点：底层失败点是给 FMOD event 设置名为 loop 的参数。

• 原文：

  GameAudioService.AttachStudioLoop(...) (src\Audio\GameAudioService.cs:182)
AudioHandleBase.TrySetParameter(...) (src\Audio\AudioHandleBase.cs:154)
  要点：堆栈与本仓库的高层循环播放路径一致。

详细分析依据

• GameAudioService.PlayLoop 对 StudioEventSource 走 PlayStudioLoop，随后进入 AttachStudioLoop：src/Audio/GameAudioService.cs:75、src/Audio/GameAudioService.cs:164、src/Audio/GameAudioService.cs:180。
• AttachStudioLoop 会先应用调用方参数，然后在 options.UsesLoopParameter 为真时执行 handle.TrySetParameter("loop", 0)，再根据 AutoPlay 调用 TryPlay()：src/Audio/GameAudioService.cs:190–src/Audio/GameAudioService.cs:198。
• AudioPlaybackOptions.UsesLoopParameter 默认值是 true，注释说明它对应“原版循环参数约定”：src/Audio/AudioPlaybackOptions.cs:69–src/Audio/AudioPlaybackOptions.cs:73。
• AudioHandleBase.TrySetParameter 实际调用底层 Godot 对象的 set_parameter_by_name：src/Audio/AudioHandleBase.cs:152–src/Audio/AudioHandleBase.cs:155、src/Audio/AudioHandleBase.cs:218–src/Audio/AudioHandleBase.cs:231。这与日志中的 FmodEvent::set_parameter_by_name 对上。
• 当前文档的循环示例直接使用 PlayLoop(AudioSource.Event(...), new AudioPlaybackOptions { ... })，未提示目标 event 必须具有 loop 参数，也未展示 UsesLoopParameter = false：docs/pages/guide/fmod-and-audio.md:61–docs/pages/guide/fmod-and-audio.md:70、docs/pages/guide/fmod-and-audio.md:84–docs/pages/guide/fmod-and-audio.md:93。
• 同仓库还保留 GameFmod.Studio.PlayLoop(eventPath, bool usesLoopParam = true) 这类原版转发 API，usesLoopParam 是显式参数：src/Audio/GameFmodAudioService.cs:45–src/Audio/GameFmodAudioService.cs:47、src/Audio/IFmodLoopPlayback.cs:9–src/Audio/IFmodLoopPlayback.cs:13。上游 STS2 代码中也能看到有些 loop 调用会传 usesLoopParam: false，说明并非所有循环事件都应使用 loop 参数。
• 因此最可能的解释不是 Volume/Pitch 本身导致，而是高层 API 默认替调用方写入了目标 event 不支持的 loop 参数。由于 issue 未提供具体 path 和 FMOD event 参数定义，暂不能断定播放“没有效果”是由该错误直接中断、事件本身未循环、bank 未加载，还是路径/资源类型不匹配叠加造成。

反馈规范性提醒

维度	状态
复现步骤	已提供：包含最小调用片段，但缺少具体 path 值。
期望/实际	已提供：期望循环播放，实际无声并报 loop 参数错误。
环境与版本	含糊：RitsuLib 版本已给出，运行环境为 _No response_。
日志/附件	已提供：堆栈足以定位到 AttachStudioLoop / TrySetParameter。
标题与背景	已提供：标题与 Audio 模块、日志内容匹配。

详细验证建议

• 用同一个 path 测试：在 AudioPlaybackOptions 中加入 UsesLoopParameter = false，确认是否不再出现 Cannot set parameter loop，以及是否能正常播放。
• 检查该 FMOD event 的参数列表，确认是否存在名为 loop 的参数；若不存在，应避免走 loop-parameter 模式。
• 分别测试 GameFmod.Studio.PlayLoop(path, usesLoopParam: false)、GameAudioService.Shared.PlayMusic(AudioSource.Event(path))，区分“循环 SFX”和“背景音乐替换”两个用例。
• 若 path 指向散装音频文件而非 Studio event，改测 AudioSource.StreamingMusic(absolutePath) 或 AudioSource.StreamingResourceMusic(resourcePath)。
• 回归文档示例中的 PlayLoop(AudioSource.Event(...))：至少覆盖“event 有 loop 参数”和“event 无 loop 参数”两类情况。

风险与未决

• 如果简单把 UsesLoopParameter 默认改为 false，可能影响依赖原版 loop 参数停止/收尾的事件；更稳妥的是显式区分两种 loop 模式或在文档中要求调用方选择。
• AudioLoopHandle.TryStop() 当前走底层 stop，并不体现 usesLoopParam 的“停止时写 loop = 1”语义；若目标事件依赖该参数退出循环，需要维护者确认是否应扩展 handle 状态。
• 缺少具体 event path、bank 加载方式和运行环境，无法判断“没有效果”是否还包含路径不存在、bank 未加载或资源类型选择错误。

---

English translation

Summary

In 0.4.41, GameAudioService.Shared.PlayLoop(AudioSource.Event(path)) defaults to the “vanilla loop parameter convention” and writes loop = 0 to the Studio event. The log suggests the target FMOD event may not have a parameter named loop, so the underlying FmodEvent.set_parameter_by_name call errors. This mainly affects Studio event path loop/background-audio usage; callers can first try UsesLoopParameter = false, while maintainers should adjust the high-level API’s default loop parameter behavior or failure handling.

Key Takeaways

Item	Conclusion
Brief description	Calling the high-level loop playback API produces no audible loop and logs Cannot set parameter loop to value 0.000000.
Likely cause	High confidence: AudioPlaybackOptions.UsesLoopParameter defaults to true, and AttachStudioLoop unconditionally attempts to set the loop parameter; FMOD/Godot reports an error when the target event does not support that parameter. Medium confidence: high-level AudioLoopHandle stop semantics are not fully aligned with vanilla usesLoopParam semantics, so “loop parameter controlled” events and direct-stop events may be conflated.
Possible fix	On the caller side, set UsesLoopParameter = false, or use PlayMusic(AudioSource.Event(path)) / AudioSource.StreamingMusic(...) depending on the resource type for background music. On the maintainer side, avoid writing loop = 0 by default during PlayLoop startup, or only write it when explicitly requested and the parameter exists; also update docs.
More info needed	Confirm whether the path FMOD event actually has a loop parameter, whether the relevant bank/GUID mapping is loaded, and the runtime environment (game version/platform/resource origin).

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

Loop audio playback, or some way to loop/replace background music.

Actual Behavior

Calling PlayLoop(AudioSource.Event(path), new AudioPlaybackOptions { Volume = volume, Pitch = pitch }) has no effect and emits an FMOD/Godot error saying it cannot set the loop parameter to 0.

Reproduction Steps

1. In RitsuLib 0.4.41, run:

   var loop = GameAudioService.Shared.PlayLoop(
       AudioSource.Event(path),
       new AudioPlaybackOptions
       {
           Volume = volume,
           Pitch = pitch,
       });

2. Observe playback and the log output.

Environment and Versions

• RitsuLib: 0.4.41
• Module scope: Audio
• Runtime environment: _No response_ in the issue

Logs, Attachments, and Original Excerpts

• Original:

  ERROR: Cannot set parameter loop to value 0.000000
godot::FmodEvent::set_parameter_by_name ... src\studio\fmod_event.cpp69
  Key point: the native failure occurs while setting an FMOD event parameter named loop.

• Original:

  GameAudioService.AttachStudioLoop(...) (src\Audio\GameAudioService.cs:182)
AudioHandleBase.TrySetParameter(...) (src\Audio\AudioHandleBase.cs:154)
  Key point: the stack matches this repository’s high-level loop playback path.

Detailed Analysis Basis

• GameAudioService.PlayLoop routes StudioEventSource through PlayStudioLoop, then into AttachStudioLoop: src/Audio/GameAudioService.cs:75, src/Audio/GameAudioService.cs:164, src/Audio/GameAudioService.cs:180.
• AttachStudioLoop first applies caller parameters, then if options.UsesLoopParameter is true, it executes handle.TrySetParameter("loop", 0), and then calls TryPlay() when AutoPlay is enabled: src/Audio/GameAudioService.cs:190–src/Audio/GameAudioService.cs:198.
• AudioPlaybackOptions.UsesLoopParameter defaults to true, with comments describing it as the “vanilla loop parameter convention”: src/Audio/AudioPlaybackOptions.cs:69–src/Audio/AudioPlaybackOptions.cs:73.
• AudioHandleBase.TrySetParameter calls the underlying Godot object’s set_parameter_by_name: src/Audio/AudioHandleBase.cs:152–src/Audio/AudioHandleBase.cs:155, src/Audio/AudioHandleBase.cs:218–src/Audio/AudioHandleBase.cs:231. This matches the log’s FmodEvent::set_parameter_by_name failure.
• The current loop documentation uses PlayLoop(AudioSource.Event(...), new AudioPlaybackOptions { ... }) without warning that the target event must have a loop parameter and without showing UsesLoopParameter = false: docs/pages/guide/fmod-and-audio.md:61–docs/pages/guide/fmod-and-audio.md:70, docs/pages/guide/fmod-and-audio.md:84–docs/pages/guide/fmod-and-audio.md:93.
• The repository still exposes GameFmod.Studio.PlayLoop(eventPath, bool usesLoopParam = true) as a vanilla-forwarding API with an explicit usesLoopParam: src/Audio/GameFmodAudioService.cs:45–src/Audio/GameFmodAudioService.cs:47, src/Audio/IFmodLoopPlayback.cs:9–src/Audio/IFmodLoopPlayback.cs:13. Upstream STS2 code also includes loop calls with usesLoopParam: false, which indicates not every loop event should use the loop parameter.
• Therefore, the most likely explanation is not Volume or Pitch itself, but that the high-level API writes a loop parameter that the target event does not support. Because the issue does not include the exact path or FMOD event parameter definition, it is not yet possible to say whether the “no effect” result is directly caused by that error, by the event not looping, by an unloaded bank, or by a path/resource-type mismatch.

Feedback Quality Reminder

Dimension	Status
Reproduction steps	Provided: includes a minimal call snippet, but not the concrete path value.
Expected/actual	Provided: expected loop playback; actual no sound plus loop parameter error.
Environment and versions	Ambiguous: RitsuLib version is provided, runtime environment is _No response_.
Logs/attachments	Provided: stack is enough to locate AttachStudioLoop / TrySetParameter.
Title and background	Provided: title matches the Audio module and log content.

Detailed Verification Suggestions

• Test the same path with UsesLoopParameter = false in AudioPlaybackOptions; confirm whether Cannot set parameter loop disappears and whether playback starts.
• Inspect the FMOD event parameter list and confirm whether a parameter named loop exists; if it does not, avoid loop-parameter mode.
• Test GameFmod.Studio.PlayLoop(path, usesLoopParam: false) and GameAudioService.Shared.PlayMusic(AudioSource.Event(path)) separately to distinguish “looping SFX” from “background music replacement”.
• If path points to a loose audio file rather than a Studio event, test AudioSource.StreamingMusic(absolutePath) or AudioSource.StreamingResourceMusic(resourcePath) instead.
• Regression-test the documented PlayLoop(AudioSource.Event(...)) example against both event types: one with a loop parameter and one without it.

Risks and Open Questions

• Simply changing the default UsesLoopParameter to false may affect events that rely on the vanilla loop parameter for stopping/tail behavior; explicitly separating the two loop modes or requiring caller choice in docs would be safer.
• AudioLoopHandle.TryStop() currently uses the underlying stop path and does not express the usesLoopParam behavior of “set loop = 1 on stop”; maintainers should decide whether the handle needs to carry that mode.
• The exact event path, bank loading method, and runtime environment are missing, so path-not-found, bank-not-loaded, or wrong source-type issues cannot be ruled out.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#72 · 退出码 0 · 进程 273.84s
• gpt-5.5(high) · API 272847ms · 25 轮 · ↓70272 ↑6874 · 缓存读307712 写0 · $0.6771
• MCP available: management tools exposed to Claude.

[iouter]

这是我用fmod做的东西有问题？

[BAKAOLC]

这是我用fmod做的东西有问题？

对的，游戏中使用一个自定义的 loop 参数作为控制是否循环的判定条件
它要求你的 event 有配置这个参数，并且将其用于 timeline 的流程控制中
我待会会做个参考

[iouter]

这是我用fmod做的东西有问题？

对的，游戏中使用一个自定义的 loop 参数作为控制是否循环的判定条件 它要求你的 event 有配置这个参数，并且将其用于 timeline 的流程控制中 我待会会做个参考

话说能配置淡出时间吗？

[iouter]

有没有什么fmod的推荐资料？

[BAKAOLC]

淡出时间这些可能需要自己参照游戏内的fmod事件这些做处理，这块属于音频专业领域，我也只会基础的编辑。

timeline 可以加这个东西，这是循环节 将其覆盖为你希望循环的段落，然后点击它，下方有个这种东西 这样创建一个parameter

然后你将其的判定范围设置为下限 0，至于上限随意，我比较推荐 0.5
然后根据原版约定，loop 为 0 会循环，因此按这样的范围它就会在播放时在这个区段循环
当它不需要循环而离开这个循环节的时候，将 loop 参数设置为 1，它就会在播放到末尾后继续播放而不是保持循环

你可以通过在 fmod 里面播放，然后调整右边的这个值来测试它的行为

其他更复杂的事件和过渡变换这些都类似这些，需要你自己根据需求设计
至于推荐资料啥的，fmod 官方有提供许多参考文件，我很多 fmod 知识来自于另一个社区 —— Celeste
你可以看出来这个 bank 的加载逻辑其实和那边 Everest 的行为很接近
fmod 官网上有 celeste 原版的完整 fmod 工程放出，是个非常有价值的参考工程
虽然那个项目是基于 1.x 的（所以需要 1.x 的编辑器才能打开）
但是很多制作手段和事件行为这些值得学习

其他的资料我也了解不是很多，我个人还是更主要在代码上研究，而非在这些资源层面，很抱歉我可能帮不上更多的忙