[FEATURE] Mods: document the 4-concurrent-clip limit of $.audio.play

Status Open
Reported on v2.1.296
Maintainer reply None cached
Activity 0 comments · opened Oct 13, 2026

The mod API docs for $.audio.play say "clips are not queued, so two calls play together", but the engine refuses a fifth concurrent clip per plugin (refused: 4 plays are going at once). The docs don't mention this, so a mod that plays short overlapping clips (e.g. a piano) silently loses notes when the user plays fast.

Suggestions

  • Document the limit in the type docs for $.audio.play.
  • Expose it (e.g. $.audio.limits), or make it configurable.
  • Optionally offer a voice-stealing mode that stops the oldest clip instead of refusing the new one.

Environment

  • Claude Code 2.1.296, macOS (desktop app, Code tab)
  • Workaround used in the mod: keep at most 4 clips going and abort the oldest (via PlayOptions.signal) before playing a new one.

View original on GitHub ↗