feat: external PCM feed/tap API (vc_stream_feed_pcm + vc_set_pcm_sink)

Promotes vc_test_inject_capture (mono-only, TEST-ONLY) to a public,
stereo-capable production API and adds a symmetric PCM tap on the
receive side. Enables ReplayKit (iOS), ScreenCaptureKit (macOS), bots,
soundboards, and custom clients — all without a hardware audio device.

Core C++:
- voicecat.h: new vc_stream_feed_pcm, vc_pcm_sink_cb typedef,
  vc_set_pcm_sink; vc_test_inject_capture kept as deprecated alias
- audio_engine: stereo-aware inject_capture (channels param + ring
  reset on channel-count change); atomic pcm_sink_ fired per decoded
  frame in on_playback; RemoteStream carries user_id/stream_id for
  RT-safe sink metadata; init_recv_stream takes user_id+stream_id
- client.cpp: stream_feed_pcm / set_pcm_sink implementations;
  sync_remote_streams passes user_id/stream_id to init_recv_stream
- voicecat.cpp: trampolines + channels=1/2 validation

Tests: test_external_pcm (headless, 3 sub-tests: mono round-trip,
stereo feed L≠R, sink metadata+disable). ctest 23/23.

Swift: feedPcm / setPcmSink in VoiceCatClient.swift + 4 XCTest
smoke tests (ExternalPcmTests.swift).

C#: StreamFeedPcm / SetPcmSink in VoiceCatClient.cs + NativeMethods.cs
(vc_stream_feed_pcm unsafe P/Invoke, VcPcmSinkCallback delegate,
vc_set_pcm_sink via nint) + 4 xUnit smoke tests (ExternalPcmTests.cs).

Docs: architecture.md §4 new subsection, voice.md §9 updated
(macOS/iOS now reference vc_stream_feed_pcm), protocol.md §8 explicit
no-protocol-change note, roadmap.md M5 entry.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

clients/apple/Sources/VoiceCatCore/VoiceCatClient.swift

@@ -309,6 +309,46 @@ public final class VoiceCatClient {
         VoiceCatResult(vc_set_capture_channels(handle, streamId, channels))
     }
 
+    // MARK: - External PCM feed / tap
+
+    /// External PCM feed — drives a local stream's encode pipeline with caller-supplied PCM
+    /// instead of (or in addition to) a hardware capture device. Intended for ReplayKit
+    /// Broadcast Extension (iOS), ScreenCaptureKit (macOS), bots, and soundboard use cases.
+    ///
+    /// - Parameters:
+    ///   - streamId: The stream returned by `startStream`. Must be active.
+    ///   - pcm: Raw int16 PCM pointer. Caller must keep the buffer alive for the duration of the call.
+    ///   - samplesPerChannel: Samples per channel (e.g. 960 for 20 ms @ 48 kHz).
+    ///   - channels: 1 (mono) or 2 (stereo interleaved L/R).
+    @discardableResult
+    public func feedPcm(streamId: UInt32, pcm: UnsafePointer<Int16>,
+                        samplesPerChannel: Int, channels: UInt32) -> VoiceCatResult {
+        VoiceCatResult(vc_stream_feed_pcm(handle, streamId, pcm,
+                                         UInt(samplesPerChannel), channels))
+    }
+
+    /// Convenience overload for feeding from a Swift `[Int16]` array.
+    @discardableResult
+    public func feedPcm(streamId: UInt32, pcm: [Int16],
+                        samplesPerChannel: Int, channels: UInt32) -> VoiceCatResult {
+        pcm.withUnsafeBufferPointer {
+            feedPcm(streamId: streamId, pcm: $0.baseAddress!,
+                    samplesPerChannel: samplesPerChannel, channels: channels)
+        }
+    }
+
+    /// External PCM tap — receive decoded per-stream audio as raw int16 PCM before it
+    /// reaches the hardware mix. Fires once per decoded Opus frame per remote stream.
+    ///
+    /// The callback is a C function pointer (`@convention(c)`) receiving:
+    ///   `(user, userId, streamId, pcm, samplesPerChannel, channels, sampleRate)`
+    ///
+    /// Pass `nil` to disable (default). The callback MUST NOT block or allocate.
+    @discardableResult
+    public func setPcmSink(_ cb: vc_pcm_sink_cb?, user: UnsafeMutableRawPointer?) -> VoiceCatResult {
+        VoiceCatResult(vc_set_pcm_sink(handle, cb, user))
+    }
+
     @discardableResult
     public func setInputMode(_ mode: VoiceCatInputMode) -> VoiceCatResult {
         VoiceCatResult(vc_set_input_mode(handle, mode.cValue))

clients/apple/Tests/VoiceCatCoreTests/ExternalPcmTests.swift

@@ -0,0 +1,68 @@
+// ExternalPcmTests — Swift wrapper smoke tests for vc_stream_feed_pcm / vc_set_pcm_sink.
+//
+// These tests verify that the Swift API surface compiles, is callable, and returns expected
+// results at the C-ABI boundary — without requiring a live server or audio hardware.
+// Full end-to-end relay / decode verification is covered by tests/test_external_pcm.cpp
+// (C++ ctest), which runs headlessly on all platforms.
+
+import XCTest
+@testable import VoiceCatCore
+
+final class ExternalPcmTests: XCTestCase {
+
+    // MARK: - feedPcm: API surface smoke
+
+    /// Calling feedPcm without a connected client or active stream must return .invalidArg
+    /// (not crash). Proves the Swift→C bridge compiles and handles the error path.
+    func testFeedPcm_noActiveStream_returnsInvalidArg() {
+        let client = VoiceCatClient(config: VoiceCatConfig(
+            clientName: "ext-pcm-test",
+            clientVersion: "0.1",
+            logLevel: .off
+        ))
+        let sine = [Int16](repeating: 0, count: 960)
+        // Stream 0 doesn't exist — the core must return invalidArg, not crash.
+        let result = client.feedPcm(streamId: 0, pcm: sine, samplesPerChannel: 960, channels: 1)
+        XCTAssertEqual(result, .invalidArg)
+    }
+
+    /// Calling feedPcm with channels=3 (invalid) must return .invalidArg.
+    func testFeedPcm_invalidChannels_returnsInvalidArg() {
+        let client = VoiceCatClient(config: VoiceCatConfig(
+            clientName: "ext-pcm-test",
+            clientVersion: "0.1",
+            logLevel: .off
+        ))
+        let pcm = [Int16](repeating: 0, count: 960 * 3)
+        let result = client.feedPcm(streamId: 0, pcm: pcm, samplesPerChannel: 960, channels: 3)
+        XCTAssertEqual(result, .invalidArg)
+    }
+
+    // MARK: - setPcmSink: API surface smoke
+
+    /// setPcmSink(nil) on a freshly-created client must succeed (nil = disable, which is the
+    /// default state — a no-op that must still return .ok).
+    func testSetPcmSink_nil_returnsOk() {
+        let client = VoiceCatClient(config: VoiceCatConfig(
+            clientName: "ext-pcm-test",
+            clientVersion: "0.1",
+            logLevel: .off
+        ))
+        let result = client.setPcmSink(nil, user: nil)
+        XCTAssertEqual(result, .ok)
+    }
+
+    /// Calling setPcmSink with a @convention(c) function and then immediately disabling it
+    /// with nil must both succeed. Verifies the C-ABI function-pointer round-trip.
+    func testSetPcmSink_enableThenDisable_bothSucceed() {
+        let client = VoiceCatClient(config: VoiceCatConfig(
+            clientName: "ext-pcm-test",
+            clientVersion: "0.1",
+            logLevel: .off
+        ))
+
+        let mySink: vc_pcm_sink_cb = { _, _, _, _, _, _, _ in }
+        XCTAssertEqual(client.setPcmSink(mySink, user: nil), .ok)
+        XCTAssertEqual(client.setPcmSink(nil, user: nil), .ok)
+    }
+}

clients/windows/VoiceCat.Interop.Tests/ExternalPcmTests.cs

@@ -0,0 +1,55 @@
+using System.Runtime.InteropServices;
+using VoiceCat.Interop;
+
+namespace VoiceCat.Interop.Tests;
+
+/// <summary>
+/// API-surface smoke tests for StreamFeedPcm / SetPcmSink through the P/Invoke layer.
+/// These tests need voicecat.dll but NOT a running server — they verify the C# wrapper
+/// compiles, is callable, and the error paths work at the C-ABI boundary. Full E2E relay
+/// verification is handled by tests/test_external_pcm.cpp (C++ ctest).
+/// </summary>
+public sealed class ExternalPcmTests
+{
+    [Fact]
+    public void StreamFeedPcm_NoActiveStream_ReturnsInvalidArg()
+    {
+        using var client = new VoiceCatClient("ext-pcm-test", "0.1", VcLogLevel.Off);
+        var pcm = new short[960];
+        // Stream 0 doesn't exist — core must return InvalidArg, not crash.
+        var result = client.StreamFeedPcm(0, pcm, 960, channels: 1);
+        Assert.Equal(VcResult.InvalidArg, result);
+    }
+
+    [Fact]
+    public void StreamFeedPcm_InvalidChannels_ReturnsInvalidArg()
+    {
+        using var client = new VoiceCatClient("ext-pcm-test", "0.1", VcLogLevel.Off);
+        var pcm = new short[960 * 3];
+        // channels=3 is not supported — trampoline rejects before touching audio state.
+        var result = client.StreamFeedPcm(0, pcm, 960, channels: 3);
+        Assert.Equal(VcResult.InvalidArg, result);
+    }
+
+    [Fact]
+    public void SetPcmSink_Zero_ReturnsOk()
+    {
+        using var client = new VoiceCatClient("ext-pcm-test", "0.1", VcLogLevel.Off);
+        // IntPtr.Zero = disable — default state, must be a no-op that returns Ok.
+        var result = client.SetPcmSink(IntPtr.Zero, IntPtr.Zero);
+        Assert.Equal(VcResult.Ok, result);
+    }
+
+    [Fact]
+    public void SetPcmSink_EnableThenDisable_BothSucceed()
+    {
+        using var client = new VoiceCatClient("ext-pcm-test", "0.1", VcLogLevel.Off);
+
+        // Keep the delegate alive until after we unregister it (not just until the P/Invoke call).
+        NativeMethods.VcPcmSinkCallback sink = static (_, _, _, _, _, _, _) => { };
+        nint fp = Marshal.GetFunctionPointerForDelegate(sink);
+        Assert.Equal(VcResult.Ok, client.SetPcmSink(fp, IntPtr.Zero));
+        Assert.Equal(VcResult.Ok, client.SetPcmSink(IntPtr.Zero, IntPtr.Zero));
+        GC.KeepAlive(sink);
+    }
+}

clients/windows/VoiceCat.Interop/NativeMethods.cs

@@ -98,6 +98,25 @@ internal static partial class NativeMethods
     internal static unsafe partial VcResult vc_test_inject_capture(nint c, uint streamId,
         short* pcm, nuint samples);
 
+    // ── External PCM feed / tap ──────────────────────────────────────────────────────────
+
+    [LibraryImport(LibName)]
+    internal static unsafe partial VcResult vc_stream_feed_pcm(nint c, uint streamId,
+        short* pcm, nuint samplesPerChannel, uint channels);
+
+    // Delegate type for the PCM sink callback — callers convert to a native function
+    // pointer via Marshal.GetFunctionPointerForDelegate (for instance members) or by casting
+    // a static lambda to delegate* unmanaged<> (for [UnmanagedCallersOnly] statics).
+    // Keep the delegate alive for the lifetime of the sink registration.
+    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
+    public delegate void VcPcmSinkCallback(IntPtr user, uint userId, uint streamId,
+        IntPtr pcm, nuint samplesPerChannel, uint channels, uint sampleRate);
+
+    // cb is a raw function pointer (IntPtr.Zero = disable). Use
+    // Marshal.GetFunctionPointerForDelegate(sinkDelegate) to convert from VcPcmSinkCallback.
+    [LibraryImport(LibName)]
+    internal static partial VcResult vc_set_pcm_sink(nint c, nint cb, IntPtr user);
+
     // ── Text ─────────────────────────────────────────────────────────────────────────────
     [LibraryImport(LibName, StringMarshalling = StringMarshalling.Utf8)]
     internal static partial VcResult vc_send_text(nint c, VcTextScope scope, uint targetId,

clients/windows/VoiceCat.Interop/VoiceCatClient.cs

@@ -225,6 +225,20 @@ public sealed class VoiceCatClient : IDisposable
         return (r, r == VcResult.Ok ? Marshaling.ToManaged(in native) : null);
     }
 
+    // ── External PCM feed / tap ─────────────────────────────────────────────────────────
+    public unsafe VcResult StreamFeedPcm(uint streamId, ReadOnlySpan<short> pcm,
+        int samplesPerChannel, uint channels)
+    {
+        fixed (short* p = pcm)
+            return NativeMethods.vc_stream_feed_pcm(_handle.DangerousGetHandle(),
+                streamId, p, (nuint)samplesPerChannel, channels);
+    }
+
+    // Pass Marshal.GetFunctionPointerForDelegate(cb) for a managed delegate, or
+    // IntPtr.Zero to disable. Keep the delegate alive for the lifetime of the registration.
+    public VcResult SetPcmSink(nint cb, IntPtr user) =>
+        NativeMethods.vc_set_pcm_sink(_handle.DangerousGetHandle(), cb, user);
+
     // ── M5: Moderation & admin ───────────────────────────────────────────────────────────
     public VcResult KickUser(uint userId, string? reason = null) =>
         NativeMethods.vc_kick_user(_handle.DangerousGetHandle(), userId, reason);