au_v2_adapter.hpp

Go to the documentation of this file.

#pragma once
 
// The AU v2 effect adapter wraps Apple's AudioUnitSDK (Apple-only,
// developer-supplied). The whole header is gated on __APPLE__ so it stays
// self-contained — an empty no-op — on the Linux header-hygiene check and any
// non-Apple TU.
#if defined(__APPLE__)
 
#include <AudioUnitSDK/AUMIDIEffectBase.h>
#include <AudioToolbox/AudioUnitProperties.h>  // AUMIDIOutputCallbackStruct
 
#include <pulp/format/contract_editor_session.hpp>
#include <pulp/format/au_v2_common.hpp>
#include <pulp/format/processor.hpp>
#include <pulp/runtime/trace_session.hpp>
#include <pulp/format/adapter_boundary.hpp>
#include <pulp/format/host_quirks.hpp>
#include <pulp/midi/buffer.hpp>
#include <pulp/midi/message.hpp>
#include <pulp/runtime/spsc_queue.hpp>
#include <pulp/runtime/alive_token.hpp>
#include <pulp/state/parameter_event_queue.hpp>
 
#include <array>
#include <atomic>
#include <cstdint>
#include <limits>
#include <memory>
#include <string_view>
#include <vector>
 
namespace pulp::format::au {


inline UInt32 build_channel_info(const PluginDescriptor& desc,
                                 AUChannelInfo* out) noexcept {
    if (!desc.supported_bus_layouts.empty()) {
        UInt32 count = 0;
        for (const auto& layout : desc.supported_bus_layouts) {
            const int in_w = layout.inputs.empty() ? 0 : layout.inputs.front();
            const int out_w = layout.outputs.empty() ? 0 : layout.outputs.front();
            if (in_w < 0 || out_w <= 0 || in_w > std::numeric_limits<SInt16>::max() ||
                out_w > std::numeric_limits<SInt16>::max()) continue;
            bool duplicate = false;
            for (UInt32 i = 0; i < count; ++i) {
                duplicate |= out[i].inChannels == in_w && out[i].outChannels == out_w;
            }
            if (duplicate) continue;
            if (count == kMaxChannelInfoPairs) break;
            out[count++] = {static_cast<SInt16>(in_w), static_cast<SInt16>(out_w)};
        }
        return count;
    }
    // Clamp the declared widths into the supported {1, 2} flex range; a declared
    // width of 0 means "no bus" (instrument input) and stays 0.
    auto clamp_width = [](int n) -> int {
        if (n <= 0) return 0;
        return n >= 2 ? 2 : 1;
    };
    const int in_w = clamp_width(desc.default_input_channels());
    const int out_w = clamp_width(desc.default_output_channels());
 
    UInt32 count = 0;
    // An instrument whose main input is optional must also validate with that
    // input unconnected (a host that offers no audio to a synth still has to
    // initialize it), so its table carries the no-input rows ahead of the
    // connected pairs. Effects are unchanged: their main input is required.
    const bool optional_input = in_w > 0 && desc.category == PluginCategory::Instrument &&
                                !desc.input_buses.empty() && desc.input_buses[0].optional;
    if (in_w == 0 || optional_input) {
        // No input bus (instrument / generator): 0 in, each output width up to
        // the declared maximum.
        for (int w = 1; w <= out_w && count < kMaxChannelInfoPairs; ++w) {
            out[count].inChannels = 0;
            out[count].outChannels = static_cast<SInt16>(w);
            ++count;
        }
    }
    if (in_w == 0) {
        // Nothing else to advertise without an input bus.
    } else if (in_w == out_w) {
        // Symmetric effect: matching in==out pairs up to the declared width.
        for (int w = 1; w <= in_w && count < kMaxChannelInfoPairs; ++w) {
            out[count].inChannels = static_cast<SInt16>(w);
            out[count].outChannels = static_cast<SInt16>(w);
            ++count;
        }
    } else if (count < kMaxChannelInfoPairs) {
        // Asymmetric effect: report the exact declared pair (e.g. {1,2}).
        out[count].inChannels = static_cast<SInt16>(in_w);
        out[count].outChannels = static_cast<SInt16>(out_w);
        ++count;
    }
    return count;
}

inline constexpr AudioUnitElement kSidechainInputElement = 1;

inline constexpr const char* kSidechainElementName = "Side Chain";

inline bool effect_has_sidechain_element(const PluginDescriptor& desc) noexcept {
    return desc.input_buses.size() > 1 && desc.input_buses[0].default_channels > 0 &&
           desc.input_buses[1].default_channels > 0;
}

inline UInt32 effect_input_element_count(const PluginDescriptor& desc) noexcept {
    return effect_has_sidechain_element(desc) ? 2u : 1u;
}

inline UInt32 instrument_input_element_count(const PluginDescriptor& desc) noexcept {
    if (desc.input_buses.empty() || desc.input_buses[0].default_channels <= 0)
        return 0u;
    return effect_input_element_count(desc);
}

inline UInt32 sidechain_element_default_channels(const PluginDescriptor& desc) noexcept {
    if (!effect_has_sidechain_element(desc)) return 0;
    const auto declared = desc.input_buses[1].default_channels;
    const auto cap = static_cast<int>(boundary::kBoundaryMaxChannels);
    return static_cast<UInt32>(declared > cap ? cap : declared);
}

inline std::size_t build_input_bus_infos(const PluginDescriptor& desc,
                                         ProcessBusBufferInfo* out,
                                         std::size_t cap) noexcept {
    if (cap == 0) return 0;
    std::size_t n = 0;
    out[n].name = desc.input_buses.empty()
                      ? std::string_view{"Audio In"}
                      : std::string_view{desc.input_buses[0].name};
    out[n].index = 0;
    out[n].direction = BusDirection::Input;
    out[n].role = BusRole::Main;
    out[n].declared_channels = desc.default_input_channels();
    // A declared-optional main input (an instrument that can also process
    // audio) stays optional; a 0-channel input is optional by construction.
    out[n].optional = desc.default_input_channels() == 0 ||
                      (!desc.input_buses.empty() && desc.input_buses[0].optional);
    out[n].active = true;  // adapter overwrites from live channel count
    ++n;
    if (desc.input_buses.size() > 1 && n < cap) {
        out[n].name = desc.input_buses[1].name;
        out[n].index = 1;
        out[n].direction = BusDirection::Input;
        out[n].role = BusRole::Sidechain;
        out[n].declared_channels = desc.input_buses[1].default_channels;
        out[n].optional = true;
        out[n].active = false;  // adapter activates it once element 1 is pulled
        ++n;
    }
    return n;
}

inline UInt32 resolve_sidechain_channels(const AudioBufferList* list,
                                         UInt32 expected_channels,
                                         UInt32 frame_offset,
                                         UInt32 frames,
                                         const float** out,
                                         std::size_t cap) noexcept {
    if (list == nullptr || expected_channels == 0 || expected_channels > cap) return 0;
    if (list->mNumberBuffers != expected_channels) return 0;
    const std::uint64_t needed_bytes =
        (static_cast<std::uint64_t>(frame_offset) + frames) * sizeof(float);
    for (UInt32 ch = 0; ch < expected_channels; ++ch) {
        const AudioBuffer& buffer = list->mBuffers[ch];
        if (buffer.mNumberChannels != 1 || buffer.mData == nullptr ||
            buffer.mDataByteSize < needed_bytes)
            return 0;
    }
    for (UInt32 ch = 0; ch < expected_channels; ++ch) {
        out[ch] = static_cast<const float*>(list->mBuffers[ch].mData) + frame_offset;
    }
    return expected_channels;
}
 
class PulpAUEffect : public ausdk::AUMIDIEffectBase {
public:
    explicit PulpAUEffect(AudioComponentInstance ci);
    // Multi-plugin-bundle ctor: the component is bound to its own factory
    // lexically (no global registry lookup). The single-arg ctor delegates
    // here with the legacy `registered_factory()` for single-plugin bundles.
    PulpAUEffect(AudioComponentInstance ci, ProcessorFactory factory);
 
    OSStatus GetParameterList(AudioUnitScope inScope,
                              AudioUnitParameterID* outParameterList,
                              UInt32& outNumParameters) override;
    OSStatus GetParameterInfo(AudioUnitScope inScope,
                              AudioUnitParameterID inParameterID,
                              AudioUnitParameterInfo& outParameterInfo) override;
    OSStatus GetParameterValueStrings(AudioUnitScope inScope,
                                      AudioUnitParameterID inParameterID,
                                      CFArrayRef* outStrings) override;
 
    // Single-source-of-truth parameter access. The plugin's
    // StateStore IS the parameter store: the host reads it via GetParameter and
    // writes it via SetParameter, so there is no separate AUElement/Globals
    // copy to reconcile each block (that split caused the UI snap-back / render
    // stalls). process() reads the same store; UI edits notify the host via a
    // main-thread listener. See the au_v2_adapter.cpp definitions.
    OSStatus GetParameter(AudioUnitParameterID inID, AudioUnitScope inScope,
                          AudioUnitElement inElement, Float32& outValue) override;
    OSStatus SetParameter(AudioUnitParameterID inID, AudioUnitScope inScope,
                          AudioUnitElement inElement, Float32 inValue,
                          UInt32 inBufferOffsetInFrames) override;
    OSStatus ScheduleParameter(const AudioUnitParameterEvent* events,
                               UInt32 num_events) override;
 
    OSStatus GetPropertyInfo(AudioUnitPropertyID inID, AudioUnitScope inScope,
                             AudioUnitElement inElement, UInt32& outDataSize,
                             bool& outWritable) override;
    OSStatus GetProperty(AudioUnitPropertyID inID, AudioUnitScope inScope,
                         AudioUnitElement inElement, void* outData) override;
    OSStatus SetProperty(AudioUnitPropertyID inID, AudioUnitScope inScope,
                         AudioUnitElement inElement, const void* inData,
                         UInt32 inDataSize) override;

    UInt32 SupportedNumChannels(const AUChannelInfo** outInfo) override;
 
    OSStatus Initialize() override;
    void Cleanup() override;

    void CreateExtendedElements() override;

    OSStatus Render(AudioUnitRenderActionFlags& ioActionFlags,
                    const AudioTimeStamp& inTimeStamp, UInt32 nFrames) override;

    bool ValidFormat(AudioUnitScope inScope, AudioUnitElement inElement,
                     const AudioStreamBasicDescription& inNewFormat) override;

    OSStatus ChangeStreamFormat(AudioUnitScope inScope, AudioUnitElement inElement,
                                const AudioStreamBasicDescription& inPrevFormat,
                                const AudioStreamBasicDescription& inNewFormat) override;
 
    OSStatus ProcessBufferLists(AudioUnitRenderActionFlags& ioActionFlags,
                                const AudioBufferList& inBuffer,
                                AudioBufferList& outBuffer,
                                UInt32 inFramesToProcess) override;

    OSStatus GetPresets(CFArrayRef* outData) const override;

    OSStatus NewFactoryPresetSet(const AUPreset& inNewFactoryPreset) override;

    FactoryPresetTable& factory_preset_table() noexcept {
        return factory_presets_;
    }
 
    OSStatus SaveState(CFPropertyListRef* outData) override;
    OSStatus RestoreState(CFPropertyListRef plist) override;
 
    bool SupportsTail() override;
    Float64 GetTailTime() override;
    Float64 GetLatency() override;

    ParamEventsOptOutMonitor& param_events_monitor() {
        return param_events_monitor_;
    }
 
  protected:
    void queue_scheduled_events(const ParameterEventList& events, UInt32 frames_to_process);
    void write_scheduled_end_values(ParameterEventList& events, UInt32 frames_to_process);
    OSStatus ProcessForScheduledParams(ParameterEventList& events, UInt32 frames_to_process,
                                       void* user_data) override;
    OSStatus ProcessScheduledSlice(void* user_data,
                                   UInt32 start_frame_in_buffer,
                                   UInt32 slice_frames,
                                   UInt32 total_buffer_frames) override;

    void publish_parameter_display_changes();

    // NB: AudioUnitSDK declares these as `AUSDK_RTSAFE` (which expands to
    // `[[clang::nonblocking]]`). Propagating that attribute into an
    // `override` declaration compiles under older Xcode but Xcode 16.4 /
    // Clang 17+ rejects the attribute position with
    // "expected ';' at end of declaration list". The attribute is a
    // static-analysis hint only — dropping it has no runtime effect, and
    // matches the pattern used by `PulpAUInstrument::HandleNoteOn/Off`.
    OSStatus HandleMIDIEvent(UInt8 inStatus, UInt8 inChannel,
                             UInt8 inData1, UInt8 inData2,
                             UInt32 inStartFrame) override;

    OSStatus HandleSysEx(const UInt8* inData, UInt32 inLength) override;
 
private:
    // Declared FIRST so it is destroyed LAST: the final detach cancels and joins
    // the tracing auto-flush timer and writes the .pftrace, and that must happen
    // after every span this instance can still emit. Tracing used to be wired
    // into VST3 ONLY, so a Perfetto capture of an AU/CLAP/AAX/standalone session
    // recorded nothing while the API happily claimed to be process-global.
    // No-op unless PULP_TRACING=ON.
    runtime::ScopedTracingAttachment tracing_;

    bool plugin_produces_midi() const noexcept;
 
    // The store is declared before the Processor so it is destroyed after it.
    // `Processor::state()` dereferences a pointer to this store, and a Processor
    // may read it from its destructor or from a worker thread that destructor is
    // about to join. Reversing these two lines hands that thread a freed store.
    state::StateStore store_;
    std::unique_ptr<Processor> processor_;
    // Panic requests (Processor::request_panic), serviced before each block.
    std::shared_ptr<PanicState> panic_state_;
    // Factory presets, bound to store_ in the constructor. Declared after
    // store_ so reverse member destruction retires the PresetManager while the
    // store it holds a reference to is still alive.
    FactoryPresetTable factory_presets_;
    // kAudioUnitProperty_RenderContextObserver; bound once the processor
    // exists, advertised only for an AudioWorkgroupClient processor.
    RenderContextObserverProperty render_context_;
    // Keeps a host class-info restore off the processor while Render() is
    // inside it. Declared after processor_ so it outlives every render that
    // consults it.
    StateRestoreGate state_restore_gate_;
    // Declared after processor_ so reverse member destruction retires retained
    // editor handles before either referenced object is released.
    runtime::AliveToken owner_alive_;
    // Contract editors the host still holds. Declared after processor_ so its
    // destruction invalidates them while the processor and store_ exist.
    ContractSessionRegistry contract_sessions_;
 
    // Immutable plugin metadata, cached once in the constructor so the render
    // path can view its bus-name strings without copying the descriptor per
    // block (which would allocate std::string members on the audio thread).
    PluginDescriptor descriptor_{};
 
    // Main-thread listener that pushes editor parameter edits to the host
    // (AudioUnitSetParameter), kept alive for the adapter's lifetime so host
    // param writes/notifications never run on the render thread. See ctor.
    state::ListenerToken ui_push_listener_;
    ParameterDisplayNamePublisher parameter_display_names_;
 
    // Parameter-event sidecar, set on the Processor each block. During a
    // scheduled AU render slice it contains slice-relative immediate/ramp
    // events translated from AudioUnitParameterEvent; otherwise it is empty.
    state::ParameterEventQueue param_events_;
    bool scheduled_slice_active_ = false;
    // Processor::wants_sample_accurate_parameters(), asked at construction.
    // False: scheduled automation renders the buffer in one call.
    bool sample_accurate_params_ = false;
    // Records an opted-out processor reading param_events(); see processor.hpp.
    ParamEventsOptOutMonitor param_events_monitor_;
    // Processor::wants_au_scheduled_parameter_slices(): render one call per
    // scheduled slice instead of one call per buffer.
    bool slice_scheduled_params_ = false;
 
    // One scheduled render: the time-sorted event list, how far its
    // immediates have been applied, and its ramps (by index, reserved in
    // Initialize()), so each slice touches only what changes at its start
    // instead of rescanning and rewriting every event.
    struct ScheduledRamp {
        std::uint32_t index = 0;
        bool superseded = false; // a later immediate set the same parameter
    };
    const ParameterEventList* scheduled_events_ = nullptr;
    std::size_t scheduled_cursor_ = 0;
    std::vector<ScheduledRamp> scheduled_ramps_;
    bool scheduled_ramps_overflowed_ = false;
    std::vector<AudioUnitParameterEvent> scheduled_sort_scratch_;
    // Block-rate path: per store parameter, the latest scheduled event seen
    // this render (event < 0 when none), and which parameters were touched.
    struct LatestScheduledEvent {
        SInt32 offset = 0;
        std::int32_t event = -1;
    };
    std::vector<LatestScheduledEvent> scheduled_latest_;
    std::vector<std::uint32_t> scheduled_touched_;
    std::vector<state::StateStore::ParamWrite> scheduled_writes_;
    std::vector<std::uint32_t> scheduled_offset_counts_;
 
    // Per-block MIDI I/O. Hoisted to members (not constructed per render call)
    // and given reserved, realtime-capacity-limited storage in Initialize() so
    // the drain loop's add()/add_sysex_copy() never grows a vector on the audio
    // thread. Reset with clear()+clear_sysex() each block. Capacities match the
    // VST3 adapter so behavior is uniform across formats.
    static constexpr std::size_t kMaxEventsPerBlock = kMaxMidiEventsPerBlock;
    static constexpr std::size_t kMaxSysexPerBlock = 64;
    static constexpr std::size_t kMaxSysexPayloadBytes = 512;
    midi::MidiBuffer midi_in_;
    midi::MidiBuffer midi_out_;
 
    // Host accommodations, resolved once in the constructor via the
    // runtime policy.
    HostQuirks host_quirks_{};
 
    // Cached ParamID of the "Bypass" parameter (plugin-declared or
    // synthesized by host-quirk policy). 0 when none is available, so
    // ProcessBufferLists never short-circuits to pass-through.
    state::ParamID bypass_param_id_ = 0;
    // Dry-delay line for the bypass pass-through. Sized to the processor's
    // reported latency in Initialize(); keeps the bypassed dry signal aligned
    // with the host's plugin-delay-compensation instead of arriving `latency`
    // samples early (a zero latency leaves it a no-op zero-copy passthrough).
    boundary::LatencyCompensatedBypass bypass_;
    std::vector<const float*> input_ptrs_;
    std::vector<float*> output_ptrs_;
 
    // Side-chain input element state. `has_sidechain_element_` is fixed at
    // construction from the descriptor. `sidechain_pulled_` points at input
    // element 1's buffer list only while Render() is on the stack and only when
    // that pull succeeded; null means "not connected" for the block.
    // `slice_frame_offset_` is the start of the current scheduled-parameter
    // slice within the pulled block (AUEffectBase advances only the main
    // buffers between slices). Pointer storage is fixed-size so building the
    // side-chain view never allocates on the audio thread.
    bool has_sidechain_element_ = false;
    const AudioBufferList* sidechain_pulled_ = nullptr;
    UInt32 slice_frame_offset_ = 0;
    std::array<const float*, boundary::kBoundaryMaxChannels> sidechain_ptrs_{};
 
    // Previous-block transport snapshot used to derive change flags on
    // `ProcessContext`. Default-constructed so the first process() call
    // after init reports no changes.
    detail::PlayheadSnapshot playhead_prev_{};
    // Set while Initialize() runs ProcessBufferLists() once on silence to fault
    // in the validation and buffer-wiring path. The render returns right after
    // wiring: before the bypass check, the MIDI queue drain, host callbacks and
    // the Processor, so nothing host- or plug-in-visible moves.
    bool warming_render_path_ = false;
    void warm_render_path();
 
    // Host offline-render intent (kAudioUnitProperty_OfflineRender), written by
    // the host before a faster-than-realtime bounce and read each render block.
    OfflineRenderProperty offline_render_;
 
    // MIDI input path — AU v2 effects that declare accepts_midi are packaged as
    // aumf (kAudioUnitType_MusicEffect). The host routes inbound MIDI through
    // AUMIDIBase::MIDIEvent / SysEx → HandleMIDIEvent / HandleSysEx. Those are
    // LOCK-FREE single-producer (host MIDI/render thread) queues drained by the
    // single consumer (ProcessBufferLists) — no mutex on the audio thread, the
    // same atomic/wait-free discipline as the parameter store. Short messages
    // are allocation-free; under flood, excess events are dropped rather than
    // blocking the render (lossy, like the RT parameter notify path). aufx
    // effects never receive MIDI, so the queues stay empty.
    runtime::SpscQueue<midi::MidiEvent, 1024> midi_in_queue_;
    struct SysexChunk {
        std::array<uint8_t, 512> bytes{};
        uint16_t length = 0;
    };
    runtime::SpscQueue<SysexChunk, 32> sysex_in_queue_;
 
    // MIDI OUTPUT path. A plugin that declares `produces_midi` (aumf MIDI effect
    // or an instrument routed back to MIDI) emits events into midi_out_ during
    // process(). AU v2 delivers them through kAudioUnitProperty_MIDIOutputCallback:
    // the host writes a callback (SetProperty) and reads the output name list
    // (kAudioUnitProperty_MIDIOutputCallbackInfo). The render path packs midi_out_
    // into a MIDIPacketList and calls the host callback. The publisher owns the
    // main-thread → render-thread handoff of the (callback, userData) pair.
    MidiOutputCallbackPublisher midi_output_callback_;
    // Pre-reserved packet-list storage so the render-path build never allocates.
    MidiOutputPacketBuilder midi_out_packet_builder_;
 
    // Per-instance channel-config table filled by SupportedNumChannels. Member
    // (not call-local) so the pointer handed to the host outlives the call.
    std::array<AUChannelInfo, kMaxChannelInfoPairs> channel_info_{};
};
 
} // namespace pulp::format::au
 
#endif // defined(__APPLE__)