[FEATURE] Mods: document the 4-concurrent-clip limit of $.audio.play
Status Open
Reported on v2.1.296
Maintainer reply None cached
Workaround ✓ Mentioned in description ↑
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.