`hooks/use-audio-engine`

(no submodules)

Purpose

useAudioEngine() returns the full resolved ProviderState bundle — the adapter, the TimelineEngine, the Transport, the ProviderBusRegistry, the PluginRegistry, the consumer-supplied preset store (or undefined), and the configured sampleRateHz. It throws REACT_AUDIO.NO_PROVIDER outside the provider and REACT_AUDIO.PROVIDER_PENDING during the async init window. It is the escape hatch for code that needs the entire bundle at once; prefer the narrower hooks (useTransport, useTimeline, …) when you only need one entity, as they minimise re-render scope.

Features

Returns ProviderState — a readonly bundle.
Throws REACT_AUDIO.NO_PROVIDER outside <AudioProvider>.
Throws REACT_AUDIO.PROVIDER_PENDING while engine init is in flight.
Stable reference across re-renders within a single ready phase.

Usage: Basic

import { useAudioEngine } from "@suaveplan/react-audio";

function Diagnostics() {
    const { engine, transport, sampleRateHz } = useAudioEngine();
    return (
        <pre>
            engine.lookAhead = {engine.lookAhead}; transport.state ={" "}
            {transport.state}; ui-sampleRate = {sampleRateHz} Hz
        </pre>
    );
}

Usage: Advanced

import { useAudioEngine } from "@suaveplan/react-audio";

function useRegisterPlugin(): (type: string, factory: () => AudioFxPlugin) => void {
    const { registry } = useAudioEngine();
    return (type, factory) => registry.register(type, factory);
}

API Reference

useAudioEngine(): ProviderState.

Implementation Notes

The hook delegates to useProviderStateOrThrow, which performs the two structured-error checks. The returned ProviderState is the frozen object the provider published — consumers can stash it in a ref without cloning. Identity is stable across renders within a single ready phase; if the provider remounts (Strict Mode or genuine remount) the bundle's identity changes, which is the correct cue for downstream useEffects keyed on engine/transport to re-bind. Prefer the focused hooks (useTransport, useTimeline, …) for the common case of "I only need one entity"; the broader bundle returned here triggers re-renders only when the provider itself re-publishes state (the focused hooks emit narrower subscriptions). Consumers that want to forward the engine bundle into child components without re-render bloat should destructure here, then memoise the sub-references they pass downstream.

2.5 KiB Raw Blame History

hooks/use-audio-engine