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.