Skip to content

Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more

29.3 KB
Raw Blame
#include "include/CoreAudioCaptureSupport.h"

#include <dispatch/dispatch.h>
#include <limits.h>
#include <mach/mach_time.h>
#include <pthread.h>
#include <stdatomic.h>
#include <stdlib.h>
#include <string.h>

// 64 hardware cycles provides ample scheduling headroom while keeping the
// realtime producer strictly allocation-free.
#define FV_RING_CAPACITY 64u
#define FV_MAX_FRAMES_PER_PACKET 8192u
#define FV_AUDIO_TOPOLOGY_TRACE_CAPACITY 8192u

typedef struct {
    float samples[FV_MAX_FRAMES_PER_PACKET];
    uint32_t frameCount;
    uint64_t inputHostTime;
    int64_t inputSampleTime;
    uint64_t sequence;
} FVPacketSlot;

typedef struct {
    AudioObjectID deviceID;
    AudioStreamID streamID;
    AudioDeviceIOProcID ioProcID;
    AudioStreamBasicDescription format;
    uint32_t bufferFrameSize;
    uint32_t bytesPerSample;
    dispatch_semaphore_t packetSemaphore;
    _Atomic uint64_t writeIndex;
    _Atomic uint64_t readIndex;
    _Atomic uint64_t droppedPackets;
    _Atomic bool running;
    _Atomic bool formatDirty;
    _Atomic bool packetGateOpen;
    FVPacketSlot slots[FV_RING_CAPACITY];
} FVCapture;

typedef struct {
    _Atomic uint64_t publishedSequence;
    _Atomic uint64_t sequence;
    _Atomic uint64_t continuousTime;
    _Atomic uint64_t generation;
    _Atomic uint32_t event;
    _Atomic uint32_t owner;
    _Atomic uint32_t objectID;
    _Atomic uint32_t selector;
    _Atomic uint32_t scope;
    _Atomic uint32_t element;
    _Atomic uint32_t queueRole;
    _Atomic uint32_t phase;
    _Atomic uint32_t transport;
    _Atomic uint32_t isMainThread;
    _Atomic int32_t status;
} FVAudioTopologyTraceSlot;

static _Atomic bool fvAudioTopologyTraceEnabled = false;
static _Atomic uint64_t fvAudioTopologyTraceSequence = 0;
static _Atomic uint64_t fvAudioTopologyMainHeartbeat = 0;
static FVAudioTopologyTraceSlot
    fvAudioTopologyTraceSlots[FV_AUDIO_TOPOLOGY_TRACE_CAPACITY];

void fv_audio_topology_trace_set_enabled(bool enabled) {
    atomic_store_explicit(
        &fvAudioTopologyTraceEnabled,
        enabled,
        memory_order_release
    );
}

bool fv_audio_topology_trace_is_enabled(void) {
    return atomic_load_explicit(
        &fvAudioTopologyTraceEnabled,
        memory_order_acquire
    );
}

uint64_t fv_audio_topology_trace_record(
    uint32_t event,
    uint32_t owner,
    AudioObjectID objectID,
    AudioObjectPropertySelector selector,
    AudioObjectPropertyScope scope,
    AudioObjectPropertyElement element,
    uint32_t queueRole,
    uint32_t phase,
    uint32_t transport,
    int32_t status,
    uint64_t generation
) {
    if (!atomic_load_explicit(
            &fvAudioTopologyTraceEnabled,
            memory_order_relaxed
        )) {
        return 0;
    }

    const uint64_t sequence = atomic_fetch_add_explicit(
        &fvAudioTopologyTraceSequence,
        1,
        memory_order_relaxed
    ) + 1;
    FVAudioTopologyTraceSlot *slot =
        &fvAudioTopologyTraceSlots[(sequence - 1) % FV_AUDIO_TOPOLOGY_TRACE_CAPACITY];

    // Zero marks the slot as being mutated. A reader that races this write
    // discards the copy after its second acquire load.
    atomic_store_explicit(&slot->publishedSequence, 0, memory_order_release);
    atomic_store_explicit(&slot->sequence, sequence, memory_order_relaxed);
    atomic_store_explicit(&slot->continuousTime, mach_continuous_time(), memory_order_relaxed);
    atomic_store_explicit(&slot->generation, generation, memory_order_relaxed);
    atomic_store_explicit(&slot->event, event, memory_order_relaxed);
    atomic_store_explicit(&slot->owner, owner, memory_order_relaxed);
    atomic_store_explicit(&slot->objectID, objectID, memory_order_relaxed);
    atomic_store_explicit(&slot->selector, selector, memory_order_relaxed);
    atomic_store_explicit(&slot->scope, scope, memory_order_relaxed);
    atomic_store_explicit(&slot->element, element, memory_order_relaxed);
    atomic_store_explicit(&slot->queueRole, queueRole, memory_order_relaxed);
    atomic_store_explicit(&slot->phase, phase, memory_order_relaxed);
    atomic_store_explicit(&slot->transport, transport, memory_order_relaxed);
    atomic_store_explicit(&slot->isMainThread, pthread_main_np() != 0, memory_order_relaxed);
    atomic_store_explicit(&slot->status, status, memory_order_relaxed);
    atomic_store_explicit(
        &slot->publishedSequence,
        sequence,
        memory_order_release
    );
    return sequence;
}

uint32_t fv_audio_topology_trace_snapshot(
    uint64_t afterSequence,
    FVAudioTopologyTraceEvent *events,
    uint32_t capacity,
    uint64_t *latestSequence
) {
    const uint64_t latest = atomic_load_explicit(
        &fvAudioTopologyTraceSequence,
        memory_order_acquire
    );
    if (latestSequence != NULL) {
        *latestSequence = latest;
    }
    if (events == NULL || capacity == 0 || latest <= afterSequence) {
        return 0;
    }

    const uint64_t oldestAvailable =
        latest > FV_AUDIO_TOPOLOGY_TRACE_CAPACITY
            ? latest - FV_AUDIO_TOPOLOGY_TRACE_CAPACITY + 1
            : 1;
    uint64_t sequence = afterSequence + 1;
    if (sequence < oldestAvailable) {
        sequence = oldestAvailable;
    }

    uint32_t copied = 0;
    for (; sequence <= latest && copied < capacity; ++sequence) {
        FVAudioTopologyTraceSlot *slot =
            &fvAudioTopologyTraceSlots[(sequence - 1) % FV_AUDIO_TOPOLOGY_TRACE_CAPACITY];
        const uint64_t publishedBefore = atomic_load_explicit(
            &slot->publishedSequence,
            memory_order_acquire
        );
        if (publishedBefore != sequence) {
            continue;
        }
        const FVAudioTopologyTraceEvent candidate = {
            .sequence = atomic_load_explicit(&slot->sequence, memory_order_relaxed),
            .continuousTime = atomic_load_explicit(&slot->continuousTime, memory_order_relaxed),
            .generation = atomic_load_explicit(&slot->generation, memory_order_relaxed),
            .event = atomic_load_explicit(&slot->event, memory_order_relaxed),
            .owner = atomic_load_explicit(&slot->owner, memory_order_relaxed),
            .objectID = atomic_load_explicit(&slot->objectID, memory_order_relaxed),
            .selector = atomic_load_explicit(&slot->selector, memory_order_relaxed),
            .scope = atomic_load_explicit(&slot->scope, memory_order_relaxed),
            .element = atomic_load_explicit(&slot->element, memory_order_relaxed),
            .queueRole = atomic_load_explicit(&slot->queueRole, memory_order_relaxed),
            .phase = atomic_load_explicit(&slot->phase, memory_order_relaxed),
            .transport = atomic_load_explicit(&slot->transport, memory_order_relaxed),
            .isMainThread = atomic_load_explicit(&slot->isMainThread, memory_order_relaxed),
            .status = atomic_load_explicit(&slot->status, memory_order_relaxed),
        };
        atomic_thread_fence(memory_order_acquire);
        const uint64_t publishedAfter = atomic_load_explicit(
            &slot->publishedSequence,
            memory_order_acquire
        );
        if (publishedAfter != sequence || candidate.sequence != sequence) {
            continue;
        }
        events[copied++] = candidate;
    }
    return copied;
}

uint32_t fv_audio_topology_trace_capacity(void) {
    return FV_AUDIO_TOPOLOGY_TRACE_CAPACITY;
}

uint64_t fv_audio_topology_trace_latest_sequence(void) {
    return atomic_load_explicit(
        &fvAudioTopologyTraceSequence,
        memory_order_acquire
    );
}

void fv_audio_topology_trace_main_heartbeat(void) {
    if (!atomic_load_explicit(
            &fvAudioTopologyTraceEnabled,
            memory_order_relaxed
        )) {
        return;
    }
    atomic_store_explicit(
        &fvAudioTopologyMainHeartbeat,
        mach_continuous_time(),
        memory_order_release
    );
}

uint64_t fv_audio_topology_trace_last_main_heartbeat(void) {
    return atomic_load_explicit(
        &fvAudioTopologyMainHeartbeat,
        memory_order_acquire
    );
}

void fv_audio_topology_trace_reset(void) {
    atomic_store_explicit(&fvAudioTopologyTraceEnabled, false, memory_order_release);
    atomic_store_explicit(&fvAudioTopologyTraceSequence, 0, memory_order_release);
    atomic_store_explicit(&fvAudioTopologyMainHeartbeat, 0, memory_order_release);
    for (uint32_t index = 0; index < FV_AUDIO_TOPOLOGY_TRACE_CAPACITY; ++index) {
        atomic_store_explicit(
            &fvAudioTopologyTraceSlots[index].publishedSequence,
            0,
            memory_order_release
        );
        FVAudioTopologyTraceSlot *slot = &fvAudioTopologyTraceSlots[index];
        atomic_store_explicit(&slot->sequence, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->continuousTime, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->generation, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->event, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->owner, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->objectID, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->selector, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->scope, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->element, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->queueRole, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->phase, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->transport, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->isMainThread, 0, memory_order_relaxed);
        atomic_store_explicit(&slot->status, 0, memory_order_relaxed);
    }
}

static OSStatus fv_get_input_stream_format(
    AudioObjectID deviceID,
    AudioStreamID *streamID,
    AudioStreamBasicDescription *format
) {
    AudioObjectPropertyAddress streamsAddress = {
        kAudioDevicePropertyStreams,
        kAudioObjectPropertyScopeInput,
        kAudioObjectPropertyElementMain,
    };
    UInt32 streamsSize = 0;
    OSStatus status = AudioObjectGetPropertyDataSize(
        deviceID,
        &streamsAddress,
        0,
        NULL,
        &streamsSize
    );
    if (status != noErr || streamsSize != sizeof(AudioStreamID)) {
        // Multiple independent input streams can have different formats. Let
        // AVAudioEngine handle those uncommon devices instead of guessing.
        return status != noErr ? status : kAudioHardwareUnsupportedOperationError;
    }

    AudioStreamID resolvedStreamID = kAudioObjectUnknown;
    status = AudioObjectGetPropertyData(
        deviceID,
        &streamsAddress,
        0,
        NULL,
        &streamsSize,
        &resolvedStreamID
    );
    if (status != noErr || resolvedStreamID == kAudioObjectUnknown) {
        return status != noErr ? status : kAudioHardwareBadObjectError;
    }
    if (streamID != NULL) {
        *streamID = resolvedStreamID;
    }

    AudioObjectPropertyAddress formatAddress = {
        kAudioStreamPropertyVirtualFormat,
        kAudioObjectPropertyScopeGlobal,
        kAudioObjectPropertyElementMain,
    };
    UInt32 formatSize = sizeof(*format);
    return AudioObjectGetPropertyData(
        resolvedStreamID,
        &formatAddress,
        0,
        NULL,
        &formatSize,
        format
    );
}

static OSStatus fv_get_buffer_frame_size(AudioObjectID deviceID, uint32_t *frameSize) {
    AudioObjectPropertyAddress address = {
        kAudioDevicePropertyBufferFrameSize,
        kAudioObjectPropertyScopeGlobal,
        kAudioObjectPropertyElementMain,
    };
    UInt32 size = sizeof(*frameSize);
    return AudioObjectGetPropertyData(deviceID, &address, 0, NULL, &size, frameSize);
}

static OSStatus fv_get_maximum_buffer_frame_size(
    AudioObjectID deviceID,
    uint32_t fallbackFrameSize,
    uint32_t *maximumFrameSize
) {
    AudioObjectPropertyAddress address = {
        kAudioDevicePropertyUsesVariableBufferFrameSizes,
        kAudioObjectPropertyScopeGlobal,
        kAudioObjectPropertyElementMain,
    };
    if (!AudioObjectHasProperty(deviceID, &address)) {
        *maximumFrameSize = fallbackFrameSize;
        return noErr;
    }
    UInt32 size = sizeof(*maximumFrameSize);
    OSStatus status = AudioObjectGetPropertyData(
        deviceID,
        &address,
        0,
        NULL,
        &size,
        maximumFrameSize
    );
    if (status == noErr && *maximumFrameSize == 0) {
        *maximumFrameSize = fallbackFrameSize;
    }
    return status;
}

static bool fv_format_is_supported(
    const AudioStreamBasicDescription *format,
    uint32_t *bytesPerSample
) {
    if (format->mFormatID != kAudioFormatLinearPCM ||
        format->mSampleRate <= 0.0 ||
        format->mChannelsPerFrame == 0 ||
        format->mBytesPerFrame == 0 ||
        (format->mFormatFlags & kAudioFormatFlagIsBigEndian) != 0) {
        return false;
    }

    const bool nonInterleaved =
        (format->mFormatFlags & kAudioFormatFlagIsNonInterleaved) != 0;
    const uint32_t channelDivisor = nonInterleaved ? 1u : format->mChannelsPerFrame;
    if (channelDivisor == 0 || format->mBytesPerFrame % channelDivisor != 0) {
        return false;
    }

    const uint32_t sampleBytes = format->mBytesPerFrame / channelDivisor;
    const bool isFloat = (format->mFormatFlags & kAudioFormatFlagIsFloat) != 0;
    const bool isSignedInteger =
        (format->mFormatFlags & kAudioFormatFlagIsSignedInteger) != 0;
    const bool isPacked = (format->mFormatFlags & kAudioFormatFlagIsPacked) != 0;

    if (isFloat && format->mBitsPerChannel == 32 && sampleBytes == sizeof(float)) {
        *bytesPerSample = sampleBytes;
        return true;
    }
    if (isSignedInteger && isPacked &&
        ((format->mBitsPerChannel == 16 && sampleBytes == 2) ||
         (format->mBitsPerChannel == 24 && sampleBytes == 3) ||
         (format->mBitsPerChannel == 32 && sampleBytes == 4))) {
        *bytesPerSample = sampleBytes;
        return true;
    }
    return false;
}

static inline float fv_read_sample(
    const uint8_t *bytes,
    const AudioStreamBasicDescription *format
) {
    if ((format->mFormatFlags & kAudioFormatFlagIsFloat) != 0) {
        float sample;
        memcpy(&sample, bytes, sizeof(sample));
        return sample;
    }

    switch (format->mBitsPerChannel) {
    case 16: {
        int16_t sample;
        memcpy(&sample, bytes, sizeof(sample));
        return (float) sample / 32768.0f;
    }
    case 24: {
        int32_t sample =
            ((int32_t) bytes[0]) |
            ((int32_t) bytes[1] << 8) |
            ((int32_t) bytes[2] << 16);
        if ((sample & 0x00800000) != 0) {
            sample |= (int32_t) 0xFF000000;
        }
        return (float) sample / 8388608.0f;
    }
    case 32: {
        int32_t sample;
        memcpy(&sample, bytes, sizeof(sample));
        return (float) ((double) sample / 2147483648.0);
    }
    default:
        return 0.0f;
    }
}

uint32_t fv_core_audio_buffer_bytes_per_frame(
    uint32_t bytesPerSample,
    uint32_t channelCount
) {
    if (bytesPerSample == 0 || channelCount == 0 ||
        bytesPerSample > UINT32_MAX / channelCount) {
        return 0;
    }
    return bytesPerSample * channelCount;
}

uint32_t fv_core_audio_buffer_frame_count(
    uint32_t dataByteSize,
    uint32_t bytesPerSample,
    uint32_t channelCount
) {
    const uint32_t bytesPerFrame =
        fv_core_audio_buffer_bytes_per_frame(bytesPerSample, channelCount);
    return bytesPerFrame == 0 ? 0 : dataByteSize / bytesPerFrame;
}

static uint32_t fv_frame_count(
    const FVCapture *capture,
    const AudioBufferList *inputData
) {
    uint32_t frameCount = UINT_MAX;
    const AudioBuffer *buffers = inputData->mBuffers;
    for (UInt32 index = 0; index < inputData->mNumberBuffers; ++index) {
        const AudioBuffer *buffer = &buffers[index];
        if (buffer->mData == NULL || buffer->mDataByteSize == 0) {
            continue;
        }
        // Derive the stride from the actual AudioBuffer layout. Core Audio can
        // expose one buffer per channel even when the device's virtual ASBD
        // temporarily reports the stream-wide interleaved byte stride during
        // a route change. Using ASBD.mBytesPerFrame in that state turns a
        // 512-frame, 3-buffer callback into 170 frames and speeds audio up 3x.
        const uint32_t frames = fv_core_audio_buffer_frame_count(
            buffer->mDataByteSize,
            capture->bytesPerSample,
            buffer->mNumberChannels
        );
        if (frames == 0) {
            continue;
        }
        if (frames < frameCount) {
            frameCount = frames;
        }
    }
    return frameCount == UINT_MAX ? 0u : frameCount;
}

static OSStatus fv_io_proc(
    AudioObjectID inDevice,
    const AudioTimeStamp *inNow,
    const AudioBufferList *inInputData,
    const AudioTimeStamp *inInputTime,
    AudioBufferList *outOutputData,
    const AudioTimeStamp *inOutputTime,
    void *inClientData
) {
    (void) inDevice;
    (void) inNow;
    (void) outOutputData;
    (void) inOutputTime;

    FVCapture *capture = (FVCapture *) inClientData;
    if (capture == NULL || inInputData == NULL ||
        !atomic_load_explicit(&capture->running, memory_order_relaxed) ||
        atomic_load_explicit(&capture->formatDirty, memory_order_acquire) ||
        !atomic_load_explicit(&capture->packetGateOpen, memory_order_acquire)) {
        return noErr;
    }

    uint32_t frameCount = fv_frame_count(capture, inInputData);
    if (frameCount == 0) {
        return noErr;
    }
    if (frameCount > FV_MAX_FRAMES_PER_PACKET) {
        atomic_fetch_add_explicit(&capture->droppedPackets, 1, memory_order_relaxed);
        return noErr;
    }

    const uint64_t writeIndex =
        atomic_load_explicit(&capture->writeIndex, memory_order_relaxed);
    const uint64_t readIndex =
        atomic_load_explicit(&capture->readIndex, memory_order_acquire);
    if (writeIndex - readIndex >= FV_RING_CAPACITY) {
        atomic_fetch_add_explicit(&capture->droppedPackets, 1, memory_order_relaxed);
        return noErr;
    }

    FVPacketSlot *slot = &capture->slots[writeIndex % FV_RING_CAPACITY];
    memset(slot->samples, 0, frameCount * sizeof(float));

    uint32_t availableChannels = 0;
    const AudioBuffer *buffers = inInputData->mBuffers;
    for (UInt32 bufferIndex = 0; bufferIndex < inInputData->mNumberBuffers; ++bufferIndex) {
        const AudioBuffer *buffer = &buffers[bufferIndex];
        if (buffer->mData == NULL || buffer->mDataByteSize == 0 ||
            buffer->mNumberChannels == 0) {
            continue;
        }

        const uint8_t *data = (const uint8_t *) buffer->mData;
        const uint32_t channelCount = buffer->mNumberChannels;
        const uint32_t bufferBytesPerFrame =
            fv_core_audio_buffer_bytes_per_frame(capture->bytesPerSample, channelCount);
        for (uint32_t frame = 0; frame < frameCount; ++frame) {
            const uint8_t *frameData = data + frame * bufferBytesPerFrame;
            float sum = 0.0f;
            for (uint32_t channel = 0; channel < channelCount; ++channel) {
                sum += fv_read_sample(
                    frameData + channel * capture->bytesPerSample,
                    &capture->format
                );
            }
            slot->samples[frame] += sum;
        }
        availableChannels += channelCount;
    }

    if (availableChannels == 0) {
        return noErr;
    }
    const float channelScale = 1.0f / (float) availableChannels;
    for (uint32_t frame = 0; frame < frameCount; ++frame) {
        slot->samples[frame] *= channelScale;
    }

    slot->frameCount = frameCount;
    slot->inputHostTime =
        inInputTime != NULL &&
        (inInputTime->mFlags & kAudioTimeStampHostTimeValid) != 0
            ? inInputTime->mHostTime
            : mach_absolute_time();
    slot->inputSampleTime =
        inInputTime != NULL &&
        (inInputTime->mFlags & kAudioTimeStampSampleTimeValid) != 0
            ? (int64_t) inInputTime->mSampleTime
            : -1;
    slot->sequence = writeIndex;

    atomic_store_explicit(&capture->writeIndex, writeIndex + 1, memory_order_release);
    dispatch_semaphore_signal(capture->packetSemaphore);
    return noErr;
}

int32_t fv_core_audio_capture_create(
    AudioObjectID deviceID,
    FVCoreAudioCaptureRef *outCapture
) {
    if (outCapture == NULL || deviceID == kAudioObjectUnknown) {
        return kAudioHardwareBadObjectError;
    }
    *outCapture = NULL;

    FVCapture *capture = (FVCapture *) calloc(1, sizeof(FVCapture));
    if (capture == NULL) {
        return kAudioHardwareUnspecifiedError;
    }
    capture->deviceID = deviceID;

    OSStatus status = fv_get_input_stream_format(
        deviceID,
        &capture->streamID,
        &capture->format
    );
    if (status == noErr &&
        !fv_format_is_supported(&capture->format, &capture->bytesPerSample)) {
        status = kAudioHardwareUnsupportedOperationError;
    }
    if (status == noErr) {
        status = fv_get_buffer_frame_size(deviceID, &capture->bufferFrameSize);
    }
    uint32_t maximumBufferFrameSize = capture->bufferFrameSize;
    if (status == noErr) {
        status = fv_get_maximum_buffer_frame_size(
            deviceID,
            capture->bufferFrameSize,
            &maximumBufferFrameSize
        );
    }
    if (status == noErr &&
        (capture->bufferFrameSize == 0 ||
         maximumBufferFrameSize > FV_MAX_FRAMES_PER_PACKET)) {
        status = kAudioHardwareUnsupportedOperationError;
    }
    if (status != noErr) {
        free(capture);
        return status;
    }

    capture->packetSemaphore = dispatch_semaphore_create(0);
    if (capture->packetSemaphore == NULL) {
        free(capture);
        return kAudioHardwareUnspecifiedError;
    }
    atomic_init(&capture->writeIndex, 0);
    atomic_init(&capture->readIndex, 0);
    atomic_init(&capture->droppedPackets, 0);
    atomic_init(&capture->running, false);
    atomic_init(&capture->formatDirty, false);
    atomic_init(&capture->packetGateOpen, false);

    status = AudioDeviceCreateIOProcID(
        deviceID,
        fv_io_proc,
        capture,
        &capture->ioProcID
    );
    if (status != noErr) {
#if !OS_OBJECT_USE_OBJC
        dispatch_release(capture->packetSemaphore);
#endif
        free(capture);
        return status;
    }

    *outCapture = (FVCoreAudioCaptureRef) capture;
    return noErr;
}

int32_t fv_core_audio_capture_start(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL || capture->ioProcID == NULL) {
        return kAudioHardwareBadObjectError;
    }
    if (atomic_load_explicit(&capture->running, memory_order_acquire)) {
        return noErr;
    }

    atomic_store_explicit(&capture->packetGateOpen, false, memory_order_release);
    atomic_store_explicit(&capture->running, true, memory_order_release);
    OSStatus status = AudioDeviceStart(capture->deviceID, capture->ioProcID);
    if (status != noErr) {
        atomic_store_explicit(&capture->running, false, memory_order_release);
        dispatch_semaphore_signal(capture->packetSemaphore);
    }
    return status;
}

int32_t fv_core_audio_capture_stop(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL || capture->ioProcID == NULL) {
        return kAudioHardwareBadObjectError;
    }
    if (!atomic_load_explicit(&capture->running, memory_order_acquire)) {
        dispatch_semaphore_signal(capture->packetSemaphore);
        return noErr;
    }

    // Close publication before synchronizing with the IOProc. The consumer
    // still drains every packet already committed to the ring.
    atomic_store_explicit(&capture->packetGateOpen, false, memory_order_release);
    OSStatus status = AudioDeviceStop(capture->deviceID, capture->ioProcID);
    atomic_store_explicit(&capture->running, false, memory_order_release);
    dispatch_semaphore_signal(capture->packetSemaphore);
    return status;
}

int32_t fv_core_audio_capture_destroy(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL) {
        return noErr;
    }
    if (atomic_load_explicit(&capture->running, memory_order_acquire)) {
        OSStatus stopStatus = fv_core_audio_capture_stop(captureRef);
        if (stopStatus != noErr) {
            return stopStatus;
        }
    }
    if (capture->ioProcID != NULL) {
        OSStatus destroyStatus = AudioDeviceDestroyIOProcID(
            capture->deviceID,
            capture->ioProcID
        );
        if (destroyStatus != noErr) {
            return destroyStatus;
        }
        capture->ioProcID = NULL;
    }
#if !OS_OBJECT_USE_OBJC
    dispatch_release(capture->packetSemaphore);
#endif
    free(capture);
    return noErr;
}

bool fv_core_audio_capture_wait(
    FVCoreAudioCaptureRef captureRef,
    uint32_t timeoutMilliseconds
) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL) {
        return false;
    }
    dispatch_time_t timeout = dispatch_time(
        DISPATCH_TIME_NOW,
        (int64_t) timeoutMilliseconds * NSEC_PER_MSEC
    );
    return dispatch_semaphore_wait(capture->packetSemaphore, timeout) == 0;
}

bool fv_core_audio_capture_peek(
    FVCoreAudioCaptureRef captureRef,
    FVCoreAudioPacket *packet
) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL || packet == NULL ||
        atomic_load_explicit(&capture->formatDirty, memory_order_acquire)) {
        return false;
    }
    const uint64_t readIndex =
        atomic_load_explicit(&capture->readIndex, memory_order_relaxed);
    const uint64_t writeIndex =
        atomic_load_explicit(&capture->writeIndex, memory_order_acquire);
    if (readIndex == writeIndex) {
        return false;
    }

    const FVPacketSlot *slot = &capture->slots[readIndex % FV_RING_CAPACITY];
    packet->samples = slot->samples;
    packet->frameCount = slot->frameCount;
    packet->sampleRate = capture->format.mSampleRate;
    packet->inputHostTime = slot->inputHostTime;
    packet->inputSampleTime = slot->inputSampleTime;
    packet->sequence = slot->sequence;
    return true;
}

void fv_core_audio_capture_consume(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL) {
        return;
    }
    const uint64_t readIndex =
        atomic_load_explicit(&capture->readIndex, memory_order_relaxed);
    const uint64_t writeIndex =
        atomic_load_explicit(&capture->writeIndex, memory_order_acquire);
    if (readIndex != writeIndex) {
        atomic_store_explicit(&capture->readIndex, readIndex + 1, memory_order_release);
    }
}

void fv_core_audio_capture_clear(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL || atomic_load_explicit(&capture->running, memory_order_acquire)) {
        return;
    }
    const uint64_t writeIndex =
        atomic_load_explicit(&capture->writeIndex, memory_order_acquire);
    atomic_store_explicit(&capture->readIndex, writeIndex, memory_order_release);
    atomic_store_explicit(&capture->droppedPackets, 0, memory_order_relaxed);
    while (dispatch_semaphore_wait(capture->packetSemaphore, DISPATCH_TIME_NOW) == 0) {
        // Remove stale per-packet wakeups from the previous stopped session.
    }
}

void fv_core_audio_capture_wake(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture != NULL) {
        dispatch_semaphore_signal(capture->packetSemaphore);
    }
}

bool fv_core_audio_capture_is_running(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    return capture != NULL &&
        atomic_load_explicit(&capture->running, memory_order_acquire);
}

void fv_core_audio_capture_mark_format_dirty(FVCoreAudioCaptureRef captureRef) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL) {
        return;
    }
    atomic_store_explicit(&capture->formatDirty, true, memory_order_release);
    atomic_store_explicit(&capture->packetGateOpen, false, memory_order_release);
}

bool fv_core_audio_capture_open_packet_gate_if_clean(
    FVCoreAudioCaptureRef captureRef
) {
    FVCapture *capture = (FVCapture *) captureRef;
    if (capture == NULL ||
        !atomic_load_explicit(&capture->running, memory_order_acquire) ||
        atomic_load_explicit(&capture->formatDirty, memory_order_acquire)) {
        return false;
    }

    atomic_store_explicit(&capture->packetGateOpen, true, memory_order_release);
    if (atomic_load_explicit(&capture->formatDirty, memory_order_acquire)) {
        atomic_store_explicit(&capture->packetGateOpen, false, memory_order_release);
        return false;
    }
    return true;
}

bool fv_core_audio_capture_copy_stream_format(
    FVCoreAudioCaptureRef captureRef,
    AudioStreamID *streamID,
    AudioStreamBasicDescription *format
) {
    const FVCapture *capture = (const FVCapture *) captureRef;
    if (capture == NULL || streamID == NULL || format == NULL) {
        return false;
    }
    *streamID = capture->streamID;
    *format = capture->format;
    return true;
}

double fv_core_audio_capture_sample_rate(FVCoreAudioCaptureRef captureRef) {
    const FVCapture *capture = (const FVCapture *) captureRef;
    return capture == NULL ? 0.0 : capture->format.mSampleRate;
}

uint32_t fv_core_audio_capture_buffer_frame_size(FVCoreAudioCaptureRef captureRef) {
    const FVCapture *capture = (const FVCapture *) captureRef;
    return capture == NULL ? 0u : capture->bufferFrameSize;
}

uint64_t fv_core_audio_capture_dropped_packet_count(FVCoreAudioCaptureRef captureRef) {
    const FVCapture *capture = (const FVCapture *) captureRef;
    return capture == NULL
        ? 0u
        : atomic_load_explicit(&capture->droppedPackets, memory_order_relaxed);
}