audio_focus.hpp

Go to the documentation of this file.

#pragma once
 
// Cross-platform audio-focus registry.
//
// Android's AudioManager.OnAudioFocusChangeListener fires lost / duck /
// gained / lost-transient events when another app grabs the speaker
// (phone call, navigation prompt, another DAW). The plugin / app needs
// to pause output on full loss, attenuate on duck, and resume on gain.
//
// AndroidManifest-level wiring lives in android/app/src/main/kotlin/
// com/pulp/audio/PulpAudioFocus.kt, which forwards events over JNI
// (core/platform/src/android/jni_bridge.cpp) into this registry.
//
// Listeners subscribe with an RAII token. The publish path is lock-free
// on the hot side (atomic snapshot); subscribe/unsubscribe take a mutex
// but neither is ever called from the audio thread.
//
// Shape mirrors pulp::platform::Environment so clients see a consistent
// observer pattern across system-signal surfaces. iOS support uses
// AVAudioSession interruption notifications when that backend is present;
// on platforms without an OS-level audio-focus concept (desktop
// macOS/Linux/Windows) the registry stays idle and reports `gained`.
 
#include <atomic>
#include <cstdint>
#include <functional>
#include <mutex>
#include <vector>
 
namespace pulp::audio {

enum class AudioFocusState : std::uint8_t {
    gained = 0,
    duck = 1,
    lost = 2,
    lost_transient = 3,
};
 
class AudioFocusRegistry {
public:
    using Callback = std::function<void(AudioFocusState)>;

    class Token {
    public:
        Token() = default;
        explicit Token(int id) : id_(id) {}
        Token(Token&& other) noexcept : id_(other.id_) { other.id_ = 0; }
        Token& operator=(Token&& other) noexcept {
            if (this != &other) {
                reset();
                id_ = other.id_;
                other.id_ = 0;
            }
            return *this;
        }
        Token(const Token&) = delete;
        Token& operator=(const Token&) = delete;
        ~Token() { reset(); }
        void reset() noexcept;
        int id() const noexcept { return id_; }
    private:
        int id_ = 0;
    };
 
    static AudioFocusRegistry& instance();

    Token subscribe(Callback cb);

    void publish(AudioFocusState state);

    AudioFocusState current() const noexcept {
        return static_cast<AudioFocusState>(
            current_.load(std::memory_order_acquire));
    }

    void reset_for_test();
 
private:
    friend class Token;
    void unsubscribe(int id) noexcept;
 
    AudioFocusRegistry() = default;
 
    mutable std::mutex mtx_;
    int next_id_ = 1;
    std::vector<std::pair<int, Callback>> cbs_;
    std::atomic<std::uint8_t> current_{
        static_cast<std::uint8_t>(AudioFocusState::gained)};
};
 
} // namespace pulp::audio