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)
+    }
+}