@mediaway/decoder 0.1.6 → 0.2.1

package/README.md

@@ -1,13 +1,40 @@
 # @mediaway/decoder
 
-Automatic hardware video decode + Opus audio decode over Mediaway's C ABI.
+Automatic hardware video decode + Opus and AAC audio decode over Mediaway's C ABI.
 Split out of `@mediaway/encoder` (previously buried as an undiscoverable
 `decode.ts`) into its own peer package — decode and encode are siblings,
 mirroring the Rust `mediaway-decoder`/`mediaway-encoder` crate split.
 
 Windows is the verified platform for `DecodeSession` (WMF backend). Opus
 audio decode (`AudioDecodeSession`) is cross-platform — `mediaway-sw`, no OS
-dependency.
+dependency, identical output on every host.
+
+**AAC decode** (`AudioDecodeSession.open({ codec: "aac", ... })`, ABI v7) is the
+*operating system's* decoder: Media Foundation on Windows (run-verified) and
+AudioToolbox on macOS/iOS (**compile-checked only — not run yet**); other platforms
+answer status 4 (unsupported). Unlike Opus, its samples **can differ between hosts and OS
+versions**. It needs the raw `AudioSpecificConfig` as `extraData` (an MP4's `esds`
+DecoderSpecificInfo) — an empty one is refused (`MediawayError` status 5) rather than guessed,
+because a synthesised default would decode SBR/PS streams to quietly wrong output. Raw AAC
+only: strip ADTS headers first. An empty packet is also refused for AAC (it is Opus's
+loss-concealment hint, and means nothing here).
+
+```ts
+import { AudioDecodeSession, decoderSupport } from "@mediaway/decoder";
+
+if ((await decoderSupport("aac")) === "supported") {
+  const aac = await AudioDecodeSession.open({
+    codec: "aac",
+    sampleRate: 48_000,
+    channels: 2,
+    extraData: audioSpecificConfig, // required; timeBase defaults to 1/sampleRate
+  });
+  for (const packet of aacPackets) await aac.pushPacket({ pts: packet.pts, payload: packet.data });
+  await aac.flush();
+  for (let f; (f = await aac.pollFrame()); ) consume(f.data); // interleaved f32le PCM
+  aac.close();
+}
+```
 
 ## Install
 
@@ -57,7 +84,9 @@ session.close(); // always safe — no consumption trap
 | --- | --- |
 | `DecodeSession.open(config)` | resolves a hardware video decoder or throws `DecoderUnavailableError` |
 | `DecodeSession.pushPacket(packet)` / `pollFrame()` | may produce zero or more frames per pushed packet |
-| `AudioDecodeSession.open(sampleRate, channels, timeBase)` | Opus only today; cross-platform |
+| `AudioDecodeSession.open(sampleRate, channels, timeBase)` | Opus (the original positional form); cross-platform |
+| `AudioDecodeSession.open({ codec, sampleRate, channels, timeBase?, extraData? })` | `"opus"` (needs `timeBase`) or `"aac"` (needs `extraData`; OS decoder) |
+| `decoderSupport(codec)` | async, **costly** (opens a throwaway session); `"supported" \| "not-implemented" \| "no-device"` — how to learn whether AAC decode exists here |
 
 ## License
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @mediaway/decoder — pipeline capability: auto video decode + Opus audio decode.
+ * @mediaway/decoder — pipeline capability: auto video decode + Opus and AAC audio decode.
  *
  * Implements the DX contract in bindings/nodejs/README.md over the
  * mediaway-ffi C ABI (via @mediaway/ffi). Split out of @mediaway/encoder into
@@ -40,8 +40,10 @@ export interface DecodePacket {
     dts?: number;
     duration?: number;
     keyframe?: boolean;
-    /** For audio: an empty payload is Opus's packet-loss-concealment hint for
-     * a lost frame, not an error — pass it whenever a frame is known lost. */
+    /** For Opus audio: an empty payload is the packet-loss-concealment hint for
+     * a lost frame, not an error — pass it whenever a frame is known lost. For
+     * AAC an empty payload is refused (`MediawayError` status 5): AAC has no
+     * such convention. */
     payload: Buffer;
 }
 export interface DecodedVideoFrame {
@@ -82,23 +84,52 @@ export declare class DecodeSession {
     /** Always safe — no handle-consumption trap on this surface. */
     close(): void;
 }
+/** Audio codecs `AudioDecodeSession` opens. */
+export type AudioDecodeCodec = "opus" | "aac";
 /**
- * An Opus audio decode session — the handle IS the decoder (adr/pipeline/0006,
- * mirrors `DecodeSession`'s video shape; no muxer to wire, no consumption
- * trap). Cross-platform (mediaway-sw, no OS dependency), unlike
- * `DecodeSession`'s Windows-only WMF backend.
+ * Config for `AudioDecodeSession.open()`.
+ *
+ * **Opus** is the software decoder: identical output on every host, no `extraData`, and
+ * `timeBase` (the frame duration, also the per-frame sample cap) is required.
+ *
+ * **AAC** is the *operating system's* decoder (Media Foundation on Windows, AudioToolbox on
+ * macOS/iOS; `DecoderUnavailableError` elsewhere), so its samples **can differ between hosts and
+ * OS versions**. `extraData` — the raw AudioSpecificConfig, e.g. an MP4's `esds`
+ * DecoderSpecificInfo — is **required**: an empty one is refused (`MediawayError` status 5)
+ * because a synthesised default would decode SBR/PS streams to quietly wrong output. Raw AAC
+ * only; strip ADTS headers first (`@mediaway/container`'s ADTS demuxer). `timeBase` defaults to
+ * `1 / sampleRate`, so packet and frame `pts`/`duration` are sample counts. The Apple decode path
+ * is compile-checked but has not been run yet.
+ */
+export interface AudioDecodeConfig {
+    codec: AudioDecodeCodec;
+    sampleRate: number;
+    channels: number;
+    timeBase?: Rational;
+    /** AAC: the AudioSpecificConfig. Ignored for Opus. */
+    extraData?: Buffer;
+}
+/**
+ * An audio decode session (Opus or AAC) — the handle IS the decoder (adr/pipeline/0006 and
+ * adr/pipeline/0007, mirrors `DecodeSession`'s video shape; no muxer to wire, no consumption
+ * trap). Opus is cross-platform (mediaway-sw, no OS dependency); AAC needs the OS decoder — see
+ * `AudioDecodeConfig`, and `decoderSupport("aac")` to learn whether it exists here.
  */
 export declare class AudioDecodeSession {
+    readonly codec: AudioDecodeCodec;
     readonly sampleRate: number;
     readonly channels: number;
     private handle;
     private constructor();
-    /** Open an Opus decode session. Throws DecoderUnavailableError when no
+    /** Open an audio decode session. Throws DecoderUnavailableError when no
      * decode backend exists on this machine. */
+    static open(config: AudioDecodeConfig): Promise<AudioDecodeSession>;
+    /** Open an Opus decode session (the original positional form). */
     static open(sampleRate: number, channels: number, timeBase: Rational): Promise<AudioDecodeSession>;
-    /** Push one compressed Opus packet. An empty payload is Opus's
-     * packet-loss-concealment hint for a lost frame, not an error. May produce
-     * zero or more frames (drain via pollFrame()). */
+    /** Push one compressed packet. For Opus an empty payload is the
+     * packet-loss-concealment hint for a lost frame, not an error; for AAC an
+     * empty payload is refused (status 5). May produce zero or more frames
+     * (drain via pollFrame()). */
     pushPacket(packet: DecodePacket): Promise<void>;
     /** Pull the next decoded PCM frame, if one is ready. null is a valid
      * "nothing ready" result, not an error. */
@@ -108,3 +139,17 @@ export declare class AudioDecodeSession {
     /** Always safe — no handle-consumption trap on this surface. */
     close(): void;
 }
+/** A codec `decoderSupport()` accepts. */
+export type DecodeProbeCodec = VideoCodec | "aac" | "opus";
+/** Whether decoding a codec is usable right now. */
+export type DecodeSupportState = "supported" | "not-implemented" | "no-device" | "unknown";
+/**
+ * Whether decoding `codec` is usable on this machine right now.
+ *
+ * Decode has one implementation per platform, so this is one state, not a list. It is how a
+ * caller learns whether AAC decode exists here (`"aac"`) without opening a session.
+ *
+ * **Costly:** it opens a throwaway session. Call it when a settings screen opens, never per
+ * frame or in a loop.
+ */
+export declare function decoderSupport(codec: DecodeProbeCodec): Promise<DecodeSupportState>;

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * @mediaway/decoder — pipeline capability: auto video decode + Opus audio decode.
+ * @mediaway/decoder — pipeline capability: auto video decode + Opus and AAC audio decode.
  *
  * Implements the DX contract in bindings/nodejs/README.md over the
  * mediaway-ffi C ABI (via @mediaway/ffi). Split out of @mediaway/encoder into
@@ -10,7 +10,7 @@
  * single-step shape (the handle IS the decoder, no consumption trap);
  * `NO_BACKEND` throws `DecoderUnavailableError`, an expected/graceful outcome.
  */
-import { pipeline, copyBytes, } from "@mediaway/ffi";
+import { PIPELINE_CODEC, pipeline, copyBytes, } from "@mediaway/ffi";
 import { MediawayError } from "@mediaway/container";
 export { MediawayError } from "@mediaway/container";
 /** No decoder backend is openable for this config — expected on machines
@@ -26,7 +26,7 @@ function checkPipeline(status, noBackendError = DecoderUnavailableError) {
         1: "invalid argument",
         2: "handle poisoned by an earlier panic",
         4: "codec/pixel-format/geometry not supported",
-        5: "bad dimensions, rates, or frame metadata",
+        5: "bad dimensions, rates, codec config (e.g. an empty AAC AudioSpecificConfig) or frame metadata",
         6: "encoder backend OS/API failure",
         7: "session already finished or not open",
         8: "muxer rejected the encoder's stream info",
@@ -113,36 +113,49 @@ export class DecodeSession {
     }
 }
 /**
- * An Opus audio decode session — the handle IS the decoder (adr/pipeline/0006,
- * mirrors `DecodeSession`'s video shape; no muxer to wire, no consumption
- * trap). Cross-platform (mediaway-sw, no OS dependency), unlike
- * `DecodeSession`'s Windows-only WMF backend.
+ * An audio decode session (Opus or AAC) — the handle IS the decoder (adr/pipeline/0006 and
+ * adr/pipeline/0007, mirrors `DecodeSession`'s video shape; no muxer to wire, no consumption
+ * trap). Opus is cross-platform (mediaway-sw, no OS dependency); AAC needs the OS decoder — see
+ * `AudioDecodeConfig`, and `decoderSupport("aac")` to learn whether it exists here.
  */
 export class AudioDecodeSession {
+    codec;
     sampleRate;
     channels;
     handle;
-    constructor(handle, sampleRate, channels) {
+    constructor(handle, codec, sampleRate, channels) {
         this.handle = handle;
+        this.codec = codec;
         this.sampleRate = sampleRate;
         this.channels = channels;
     }
-    /** Open an Opus decode session. Throws DecoderUnavailableError when no
-     * decode backend exists on this machine. */
-    static async open(sampleRate, channels, timeBase) {
-        const raw = pipeline.audioDecodeConfigOpus(sampleRate, channels, {
-            num: BigInt(timeBase.num),
-            den: timeBase.den,
-        });
+    static async open(first, channels, timeBase) {
+        const config = typeof first === "number"
+            ? { codec: "opus", sampleRate: first, channels: channels ?? 0, timeBase }
+            : first;
+        const tb = config.timeBase ?? (config.codec === "aac" ? { num: 1, den: config.sampleRate } : undefined);
+        if (!tb)
+            throw new MediawayError(5, "Opus decode needs a timeBase (the frame duration)");
+        const rawTimeBase = { num: BigInt(tb.num), den: tb.den };
+        const raw = config.codec === "aac"
+            ? pipeline.audioDecodeConfigAac(config.sampleRate, config.channels, rawTimeBase, null, 0)
+            : pipeline.audioDecodeConfigOpus(config.sampleRate, config.channels, rawTimeBase);
+        if (config.codec === "aac" && config.extraData && config.extraData.length > 0) {
+            // The ASC is BORROWED by native code for the open() call only. Assigning the Buffer here
+            // (rather than passing it to the constructor) lets koffi pin it for exactly that call.
+            raw.extra_data = config.extraData;
+            raw.extra_data_len = config.extraData.length;
+        }
         const out = [null];
         checkPipeline(pipeline.audioDecodeSessionOpen(raw, out), DecoderUnavailableError);
         if (!out[0])
             throw new MediawayError(11, "audio decode session open returned no handle");
-        return new AudioDecodeSession(out[0], sampleRate, channels);
+        return new AudioDecodeSession(out[0], config.codec, config.sampleRate, config.channels);
     }
-    /** Push one compressed Opus packet. An empty payload is Opus's
-     * packet-loss-concealment hint for a lost frame, not an error. May produce
-     * zero or more frames (drain via pollFrame()). */
+    /** Push one compressed packet. For Opus an empty payload is the
+     * packet-loss-concealment hint for a lost frame, not an error; for AAC an
+     * empty payload is refused (status 5). May produce zero or more frames
+     * (drain via pollFrame()). */
     async pushPacket(packet) {
         const raw = {
             stream_id: 0,
@@ -186,3 +199,22 @@ export class AudioDecodeSession {
         }
     }
 }
+const SUPPORT_STATES = {
+    0: "supported",
+    1: "not-implemented",
+    2: "no-device",
+};
+/**
+ * Whether decoding `codec` is usable on this machine right now.
+ *
+ * Decode has one implementation per platform, so this is one state, not a list. It is how a
+ * caller learns whether AAC decode exists here (`"aac"`) without opening a session.
+ *
+ * **Costly:** it opens a throwaway session. Call it when a settings screen opens, never per
+ * frame or in a loop.
+ */
+export async function decoderSupport(codec) {
+    const out = [255];
+    checkPipeline(pipeline.decoderSupport(PIPELINE_CODEC[codec], out));
+    return SUPPORT_STATES[out[0]] ?? "unknown";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaway/decoder",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Rust-based, lightweight, fast — automatic hardware video decode + Opus audio decode for Node.js",
   "type": "module",
   "main": "./dist/index.js",