AudioBuffer Resource class and built-in plugin

[kaoskorobase]

Summary

Implement the AudioBuffer Resource class — a multi-channel sample-data Resource for Synth-side recording and playback — as the first concrete consumer of the generic resource system landed in #147. Adds a public C header, a C++ convenience wrapper, a built-in Plugin, and an OSC-driven example.

Depends on

• Generic RT/NRT shared resource system (with MultiChannelBuffer as first class) #147 — generic resource system (engine pool, OSC verbs, RT acquire/release, perform_with_resources, ResourceRef<T> / ResourceDef<R,O> C++ wrappers). All shipped in Add generic RT/NRT shared resource system (#147) #152.

Scope

Public C header — include/methcla/plugins/audio_buffer.h

#define METHCLA_AUDIO_BUFFER_URI METHCLA_PLUGINS_URI "/audio-buffer"

typedef struct AudioBuffer {
    size_t  num_channels;
    size_t  num_frames;
    size_t  sample_rate;
    float** data;   // num_channels pointers, each to num_frames samples
} AudioBuffer;

extern const Methcla_ResourceDef methcla_audio_buffer_def;

METHCLA_EXPORT Methcla_Library*
methcla_plugins_audio_buffer(Methcla_Host* host, const char* bundlePath);

Public C++ wrapper — include/methcla/plugins/audio_buffer.hpp

A thin wrapper class with static constexpr const char* uri() and using c_type = ::AudioBuffer;, so Methcla::Plugin::ResourceRef<Methcla::Plugin::AudioBuffer> works with the wrappers added in #147. Exposes numChannels(), numFrames(), sampleRate(), channel(i), data(), and zero().

Built-in Plugin — plugins/audio_buffer.cpp

• Mutability: kMethcla_Mutable.
• Implementation class derives from ::AudioBuffer so a void* instance from construct casts cleanly on the consumer side.
• Options: i:num_channels i:num_frames i:sample_rate.
• Construct allocates the AudioBuffer struct + channel-pointer array + SIMD-aligned sample storage via methcla_host_alloc_aligned. Destructor frees them.
• Registers via Methcla::Plugin::ResourceDef<AudioBufferImpl, AudioBufferOptions>()(host, METHCLA_AUDIO_BUFFER_URI, kMethcla_Mutable).

Build wiring

File	Change
plugins/audio_buffer.cpp	New — AudioBuffer Resource implementation
include/methcla/plugins/audio_buffer.h	New — public C header
include/methcla/plugins/audio_buffer.hpp	New — public C++ wrapper
tests/audio_buffer_tests.cpp	New — construct / destroy / perform_with_resources round-trip
CMakeLists.txt	Add audio_buffer.cpp to plugin targets
CHANGELOG.md	Entry under [Unreleased]
docs/usage.md	New "Resources" section showing alloc → bind → use → free of an AudioBuffer

Tests

• Allocate via /resource/new METHCLA_AUDIO_BUFFER_URI i:numChannels i:numFrames i:sampleRate, wait for /resource/ready.
• Verify field values via perform_with_resources callback.
• Free, wait for /resource/destroyed.
• Error path: zero or negative dimensions → /resource/error with kMethcla_ArgumentError.

Out of scope

• Synth-side kMethcla_ResourcePort integration — tracked in Synth resource port integration (kMethcla_ResourcePort) #151. Once that lands, the existing disksampler / sampler Plugins can grow AudioBuffer input ports.
• MultiChannelBuffer is engine-internal and unchanged by this issue; AudioBuffer is the Plugin-facing ABI contract.

Origin

Originally Layer 4 of #147; split into a separate issue so #147 / #152 ship the generic infrastructure alone.