`usePackedAudio` — audio-tuned packed-resource hook

(no submodules)

Purpose

usePackedAudio is the audio analogue of usePackedImage. It binds a packed audio asset URL to a React component's lifecycle, defaults to caching the underlying bytes (audio cues are typically re-triggered), and narrows the manager's MIME allow-list to audio/-prefixed types so misconfigured archives serving non-audio bytes fail fast at the loader rather than at <audio> decode time.

The return shape matches UsePackedResourceReturn so callers swap between variant hooks without touching downstream rendering code.

Features

cache: true default; opt out per call.
allowedMimePrefixes: ["audio/"] default.
Forwards verifyKey, verifyChecksum, and signal to the underlying generic hook.
Identical return shape to usePackedResource.

Usage: Basic

import { usePackedAudio } from "@suaveplan/react-packer";

function CueButton({ cue }: { cue: string | null }) {
    const { url, loading } = usePackedAudio(cue);
    if (loading || url === null) return <button disabled>…</button>;
    return (
        <button type="button" onClick={() => new Audio(url).play()}>
            Play
        </button>
    );
}

Usage: Advanced

import { usePackedAudio } from "@suaveplan/react-packer";

function SignedCue({
    cue,
    verifyKey,
}: {
    cue: string;
    verifyKey: Uint8Array;
}) {
    const { url, error, reload } = usePackedAudio(cue, {
        verifyChecksum: true,
        verifyKey,
        allowedMimePrefixes: ["audio/ogg", "audio/webm"],
    });
    if (error !== null) return <button onClick={reload}>Retry</button>;
    return url !== null ? <audio controls src={url} /> : null;
}

API Reference

usePackedAudio(packedUrl, options?): UsePackedResourceReturn
Defaults differ from usePackedResource:
- cache defaults to true.
- allowedMimePrefixes defaults to ["audio/"].
All other options pass through.

Implementation Notes

Explicit caller options always win. Passing { cache: false } disables caching for that hook instance; passing { allowedMimePrefixes: [] } opts out of MIME enforcement entirely.
The default MIME prefix is checked against the response's Content-Type by the loader; the hook itself does not parse MIME.
Audio decoding remains the consumer's responsibility — the hook only produces the Blob URL.

2.4 KiB Raw Blame History

usePackedAudio — audio-tuned packed-resource hook