@daugasauron/dolly-host-audio 0.0.0-stage → 0.1.4-rc.1

package/README.md

@@ -1,3 +1,4 @@
-# Temporary Holding Version
+# @daugasauron/dolly-host-audio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Dolly's `audio@0` host module: stereo PCM playback. Give the URL of its
+`module.json` to `boot()`'s `modules`; @daugasauron/dolly's README says how.

package/abi.mjs

@@ -0,0 +1,18 @@
+// Generated from host/audio/dolly-audio-0.wat, host/audio/audio.h, include/dolly/process.h.
+export const DOLLY_AUDIO_VERSION = 0;
+export const DOLLY_AUDIO_PROCESS_OP = 129;
+export const DOLLY_AUDIO_SLOTS = 4;
+export const DOLLY_AUDIO_REPLY_BYTES = 16;
+export const DOLLY_AUDIO_PACKET_BYTES = 32808;
+export const DOLLY_AUDIO_RATE = 48000;
+export const DOLLY_AUDIO_CHANNELS = 2;
+export const DOLLY_AUDIO_MIN_FRAMES = 128;
+export const DOLLY_AUDIO_MAX_FRAMES = 4096;
+export const DOLLY_AUDIO_QUEUE_FRAMES = 48000;
+export const DOLLY_AUDIO_MAX_BUFFERS = 64;
+export const DOLLY_AUDIO_OPEN = 1;
+export const DOLLY_AUDIO_WRITE = 2;
+export const DOLLY_AUDIO_STATUS = 3;
+export const DOLLY_AUDIO_CLOSE = 4;
+export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });
+export const DOLLY_AUDIO_ABI_DIGEST = "bf9f97c6945174f9788f03091ca6e1c982f5b8c80488c1b5526804ceb84a1046";

package/audio.mjs

@@ -0,0 +1,52 @@
+import { createAudioProvider } from "./provider.mjs";
+import * as A from "./abi.mjs";
+import { DOLLY_ERRNO as E } from "./abi.mjs";
+export { DOLLY_AUDIO_ABI_DIGEST as digest } from "./abi.mjs";
+
+// The device as the lease bridge sees it.
+export const lease = { type: "audio", slots: A.DOLLY_AUDIO_SLOTS, packetBytes: A.DOLLY_AUDIO_PACKET_BYTES,
+  replyBytes: A.DOLLY_AUDIO_REPLY_BYTES, open: A.DOLLY_AUDIO_OPEN, close: A.DOLLY_AUDIO_CLOSE };
+
+export function check() {
+  return typeof globalThis.AudioContext === "function" ? null : "Web Audio playback is unavailable in this browser";
+}
+
+export function browser({ send }) {
+  const provider = createAudioProvider();
+  const resume = event => { if (event.isTrusted) provider.resume(); };
+  window.addEventListener("keydown", resume, { capture: true });
+  window.addEventListener("pointerdown", resume, { capture: true });
+  return {
+    get status() { return provider.status(); },
+    page: { get audio() { return provider.status(); } },
+    messages: {
+      "audio-request"(message) {
+        const result = provider.dispatch(message.packet);
+        send({ type: "audio-complete", scope: message.scope, sequence: message.sequence, ...result },
+          [result.bytes.buffer]);
+      },
+      "audio-revoke"(message) {
+        provider.release(message.scope);
+        send({ type: "audio-complete", scope: message.scope, revoked: true });
+      },
+    },
+    dispose() {
+      window.removeEventListener("keydown", resume, { capture: true });
+      window.removeEventListener("pointerdown", resume, { capture: true });
+      void provider.close();
+    },
+  };
+}
+
+export function worker({ send, get }) {
+  let bridge;
+  return {
+    bindings: { "env.dolly_audio_dispatch": (address, bytes) =>
+      bridge ? bridge.dispatch({ address, bytes }) : -E.ENOSYS },
+    start({ kernel }) {
+      bridge = get("runtime").leaseBridge(lease, Number(kernel.dolly_audio_mailbox_address()), send);
+    },
+    messages: { "audio-complete": message => bridge?.acknowledge(message) },
+    dispose() { bridge?.dispose(); bridge = undefined; },
+  };
+}

package/module.json

@@ -0,0 +1,15 @@
+{
+  "name": "audio",
+  "version": 0,
+  "gives": "stereo PCM playback",
+  "dependencies": ["runtime@0"],
+  "phase": "kernel",
+  "imports": ["env.dolly_audio_dispatch"],
+  "host": "audio.mjs",
+  "contracts": ["dolly-audio-0.wat"],
+  "process": [],
+  "headers": ["audio.h", "audio-abi.h"],
+  "kernel": ["kernel.c"],
+  "client": ["client.c"],
+  "package": "libdolly-audio"
+}

package/package.json

@@ -1,6 +1,14 @@
 {
+  "version": "0.1.4-rc.1",
+  "type": "module",
   "name": "@daugasauron/dolly-host-audio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "license": "MIT",
+  "dependencies": {
+    "@daugasauron/dolly": "0.1.4-rc.1"
+  },
+  "description": "Dolly's audio@0 host module: stereo PCM playback.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daugasauron/dolly.git"
+  }
+}

package/provider.mjs

@@ -0,0 +1,120 @@
+import * as A from "./abi.mjs";
+import { DOLLY_ERRNO as E } from "./abi.mjs";
+
+const fail = errno => { throw Object.assign(new Error("Audio request failed"), {errno}); };
+const response = size => new Uint8Array(size);
+
+export function createAudioProvider() {
+  const streams = new Map(), generations = new Uint32Array(A.DOLLY_AUDIO_SLOTS);
+  let context, resumePending = false;
+
+  function finish(stream, node) {
+    if (!stream.nodes.delete(node)) return;
+    node.source.disconnect();
+    stream.played += node.frames;
+  }
+  function queued(stream) {
+    const now = context.currentTime;
+    let frames = 0;
+    for (const node of stream.nodes) {
+      if (now >= node.end) finish(stream, node);
+      else frames += node.frames - Math.max(0, Math.floor((now - node.start) * A.DOLLY_AUDIO_RATE));
+    }
+    return frames;
+  }
+  function status() {
+    let queuedFrames = 0, buffers = 0;
+    for (const stream of streams.values()) { queuedFrames += queued(stream); buffers += stream.nodes.size; }
+    return {activeScopes: streams.size, queuedFrames, buffers, state: context?.state ?? "closed"};
+  }
+  function resume() {
+    if (!resumePending && context?.state === "suspended" && streams.size &&
+        navigator.userActivation?.hasBeenActive) {
+      resumePending = true;
+      const settled = () => { resumePending = false; };
+      void context.resume().then(settled, settled);
+    }
+  }
+  function release(scope) {
+    const stream = streams.get(scope);
+    if (!stream) return;
+    streams.delete(scope);
+    for (const node of stream.nodes) { node.source.onended = null; node.source.stop(); node.source.disconnect(); }
+    stream.nodes.clear();
+  }
+  function dispatch(packet) {
+    try {
+      if (!(packet instanceof Uint8Array) || packet.byteLength < 32 || packet.byteLength > A.DOLLY_AUDIO_PACKET_BYTES) fail(E.EINVAL);
+      packet = packet.slice();
+      const view = new DataView(packet.buffer, packet.byteOffset, packet.byteLength);
+      const op = view.getUint32(4, true), scope = view.getUint32(8, true), sequence = view.getUint32(16, true);
+      if (view.getUint32(0, true) !== A.DOLLY_AUDIO_VERSION || view.getUint32(12, true) || view.getUint32(20, true) ||
+          !scope || !sequence || view.getUint32(24, true) !== packet.length - 32 || view.getUint32(28, true)) fail(E.EINVAL);
+      const slot = (scope - 1) % A.DOLLY_AUDIO_SLOTS;
+      let stream = streams.get(scope), result;
+      if (op === A.DOLLY_AUDIO_OPEN) {
+        if (packet.length !== 32) fail(E.EINVAL);
+        if (scope <= generations[slot]) fail(E.ESTALE);
+        if ([...streams.keys()].some(key => (key - 1) % A.DOLLY_AUDIO_SLOTS === slot)) fail(E.EBUSY);
+        if (!context) {
+          if (typeof AudioContext !== "function") fail(E.ENOSYS);
+          context = new AudioContext({sampleRate: A.DOLLY_AUDIO_RATE, latencyHint: "interactive"});
+        }
+        if (context.state === "closed") fail(E.EIO);
+        stream = {scope, sequence, nodes: new Set(), end: context.currentTime, played: 0};
+        streams.set(scope, stream); generations[slot] = scope;
+        result = response(16);
+        const output = new DataView(result.buffer);
+        output.setBigUint64(0, BigInt(scope), true);
+        output.setUint32(8, A.DOLLY_AUDIO_RATE, true); output.setUint32(12, A.DOLLY_AUDIO_CHANNELS, true);
+        resume();
+      } else {
+        if (!stream) fail(E.EBADF);
+        if (sequence <= stream.sequence) fail(E.ESTALE);
+        stream.sequence = sequence;
+        if (op === A.DOLLY_AUDIO_WRITE) {
+          if (packet.length < 40) fail(E.EINVAL);
+          const frames = view.getUint32(32, true);
+          if (frames < A.DOLLY_AUDIO_MIN_FRAMES || frames > A.DOLLY_AUDIO_MAX_FRAMES ||
+              view.getUint32(36, true) || packet.length !== 40 + frames * 8) fail(E.EINVAL);
+          for (let at = 40; at < packet.length; at += 4) if (!Number.isFinite(view.getFloat32(at, true))) fail(E.EINVAL);
+          const pending = queued(stream);
+          if (pending + frames > A.DOLLY_AUDIO_QUEUE_FRAMES || stream.nodes.size >= A.DOLLY_AUDIO_MAX_BUFFERS) fail(E.EAGAIN);
+          const buffer = context.createBuffer(A.DOLLY_AUDIO_CHANNELS, frames, A.DOLLY_AUDIO_RATE);
+          for (let channel = 0; channel < A.DOLLY_AUDIO_CHANNELS; ++channel) {
+            const data = buffer.getChannelData(channel);
+            for (let i = 0; i < frames; ++i) data[i] = Math.max(-1, Math.min(1, view.getFloat32(40 + (i * 2 + channel) * 4, true)));
+          }
+          const source = context.createBufferSource(); source.buffer = buffer;
+          source.connect(context.destination);
+          const now = context.currentTime, start = Math.max(stream.end, now + 0.01);
+          const node = {source, frames, start, end: start + frames / A.DOLLY_AUDIO_RATE};
+          source.onended = () => finish(stream, node);
+          source.start(start); stream.end = node.end; stream.nodes.add(node);
+          result = response(4); new DataView(result.buffer).setUint32(0, frames, true);
+        } else if (op === A.DOLLY_AUDIO_STATUS) {
+          if (packet.length !== 32) fail(E.EINVAL);
+          const pending = queued(stream);
+          let played = stream.played;
+          for (const node of stream.nodes) played += Math.min(node.frames, Math.max(0, Math.floor((context.currentTime - node.start) * A.DOLLY_AUDIO_RATE)));
+          result = response(16);
+          const output = new DataView(result.buffer);
+          output.setUint32(0, pending, true); output.setUint32(4, context.state === "running" ? 1 : 2, true);
+          output.setBigUint64(8, BigInt(played), true);
+        } else if (op === A.DOLLY_AUDIO_CLOSE) {
+          if (packet.length !== 32) fail(E.EINVAL);
+          release(scope); result = response(0);
+        } else fail(E.ENOSYS);
+      }
+      return {bytes: result, error: 0};
+    } catch (error) {
+      if (!error.errno) console.warn("Dolly audio:", error);
+      return {bytes: response(0), error: error.errno ?? E.EIO};
+    }
+  }
+  async function close() {
+    for (const scope of [...streams.keys()]) release(scope);
+    if (context && context.state !== "closed") await context.close();
+  }
+  return {dispatch, release, resume, status, close};
+}