Clap Review

CLAP Plugin Review

CLAP's threading model is explicit by design — every host method and extension entry point is tagged with a thread requirement. Violations are silent at compile time and often only surface under specific host implementations.

Step 0 — Run universal checks first

Invoke audio-dsp-review and audio-numerics-review before this skill. This skill adds CLAP-specific spec compliance checks on top; it does not replace realtime-safety or numerics reviews.

Step 1 — Identify plugin structure

Locate and characterize the plugin's registered interfaces:

| Item | What to check | |------|--------------| | clap_plugin_t | process, activate, deactivate, start_processing, stop_processing implemented | | Extensions returned by get_extension | Which of: audio-ports, params, state, gui, note-ports, log, timer-support, posix-fd-support | | Host extensions queried in init | Which host callbacks are cached; which thread they may be called from | | clap_plugin_descriptor_t | id is stable and reverse-DNS formatted; features declared correctly |

Step 2 — Scan for CLAP-specific violations

| Violation | Where | Risk | |-----------|-------|------| | Holding clap_event_* pointer after callback returns | process() | Use-after-free — events are host-owned, lifetime ends when process() returns | | Calling a host method from the wrong thread context | audio↔main boundary | Spec violation — obey each method's [main-thread], [audio-thread], or [thread-safe] tag | | State save/restore doing I/O on wrong thread | save/load in state extension | Thread safety violation — state methods run on main thread, not audio thread | | Extension methods not guarded by thread_check | any extension handler | Data race — extensions have per-method thread requirements; check each one | | process() returning wrong clap_process_status | process() | Host misinterprets plugin state — CLAP_PROCESS_SLEEP vs CLAP_PROCESS_CONTINUE affects scheduling | | Param IDs not stable across save/load cycles | params extension | Broken parameter recall — param IDs must be stable for the lifetime of the plugin ID | | Audio port channel counts mismatched at runtime vs declared | audio-ports extension | Buffer overread/underwrite — host allocates buffers based on declared port config | | Calling host params->request_flush() from process() | params extension | Spec violation — request_flush is [thread-safe, !audio-thread]; emit output events during process() instead | | Querying plugin extensions before plugin->init() | host/plugin setup | Spec violation — get_extension() is forbidden before init, but allowed during and after init | | Not handling CLAP_EVENT_TRANSPORT when transport-aware | process() | Incorrect playback position — transport events must be consumed each process call |

Step 3 — Write the review

## CLAP Plugin Review: `[file / plugin id]`

### Verdict
[Spec-compliant | Has critical violations | Warnings only] — [one sentence summary]

### Critical Violations
**[Category]: [description]**
`file:line` — `offending code`
Why: [one sentence on the spec / thread safety risk]
Fix: [concrete CLAP-idiomatic suggestion]

### Warnings
[same format]

### What's Done Well
[correct patterns — proper event copying, thread_check guards, correct status codes, etc.]

### Recommended Fixes (priority order)
1. ...

Quick fix table

| Violation | Fix | |-----------|-----| | Storing clap_event_* pointer | Copy the event struct by value before process() returns | | Host call from wrong thread | Use only methods allowed for the current thread, or queue host->request_callback() and handle main-thread work in on_main_thread() | | Wrong clap_process_status | Return CLAP_PROCESS_SLEEP only when all voices are done; CLAP_PROCESS_CONTINUE otherwise | | Unstable param IDs | Use a fixed enum or stable hash derived from param name, never an index | | Port count mismatch | Validate audio_inputs_count / audio_outputs_count in process() against declared ports | | Missing thread_check guard | Wrap host calls with host_thread_check->is_main_thread(host) before calling |

For the full CLAP audit checklist organized by extension, threading rules, and BAD/GOOD code patterns see references/clap-spec-checklist.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kunitoki
• Source: kunitoki/sonic-skills
• License: Unlicense

Install and usage instructions live in the source repository linked above.