dewdrop-sdk 0.4.1 → 0.5.1

package/README.md

@@ -1,67 +1,10 @@
 # dewdrop-sdk
 
-The package that builds a three.js game for Dewdrop and runs it locally: the
-Vite plugin, model calls, multiplayer and saves.
+Build a three.js game for Dewdrop and run it locally: the Vite plugin, model
+calls, multiplayer, saves and voice.
 
-## Set up
-
-In a Vite 6 or later project:
-
-```sh
-npm install -D dewdrop-sdk
-npm install --save-exact three@0.185.1
-```
-
-```js
-// vite.config.js
-import dew from 'dewdrop-sdk/vite';
-export default { plugins: [dew()] };
-```
-
-`npx dewctl init` sets up a new game this way, with the Dewdrop CLI beside it.
-To update a project, run `npm install -D dewdrop-sdk@latest`; saves need 0.4.0
-or later.
-
-## Saves locally
-
-On Dewdrop, `localStorage` and IndexedDB aren't local: nothing your game
-writes to them is stored in the player's browser or on their device, and they
-start empty each time a player opens your game. `saves.save()` keeps what they
-hold in Dewdrop's storage for that player, and `saves.load()` puts it back,
-in later uploads of your game too. A game with a `backend.js` keeps no saves:
-its state is its rooms', and both calls refuse with `NotSupportedError`.
-`npm run dev` does the same in your browser: every page load starts with
-`localStorage` and IndexedDB empty, and saves are kept in the browser, in a
-database named `dewdrop-saves` your game doesn't see, for the game
-`dewdrop.json` names and the player `?player=` names, across your edits. Tabs
-of one dev server share the browser's storage, so loading one empties the
-others'.
-
-## Rooms locally
-
-`npm run dev` runs your `backend.js` for each room the tabs join: `?room=`
-names the room, `?player=` the player, and `?players=` how many players a
-room the tab opens seats, 100 unless it says 1 to 100, as Dewdrop's rooms
-do; `?players=1` is singleplayer. A player is counted once however many tabs
-they play from, and a tab past a full room is refused, with the reason in
-the console. In the backend, `clients.capacity` is the room's size.
-
-## Sessions that end
-
-On Dewdrop a session can end ahead of time: for maintenance, or a newer
-version of your game published. Its player sees a countdown and reconnects
-on their own, and your game hears of it first, up to fifteen minutes
-before: `session.ending` from `dewdrop-sdk` is `{at, reason}`, `at` in
-milliseconds as `Date.now()` counts and `reason` `'restart'` or `'update'`,
-and an `ending` event fires each time it changes, its withdrawal to `null`
-included. Call `saves.save()` then to keep what the player has done. `npm
-run dev` ends no session ahead of time, so `session.ending` stays `null`
-there.
-
-## Docs
-
-How to build your game, from the look to model calls, multiplayer, saves and
-what works on Dewdrop, is in the docs: https://alpha.dewdrop.world/docs
+How to set up a project and everything the SDK does is in the docs:
+https://alpha.dewdrop.world/docs
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dewdrop-sdk",
-  "version": "0.4.1",
-  "description": "Build a three.js game for Dewdrop: the Vite plugin, model calls, multiplayer and saves.",
+  "version": "0.5.1",
+  "description": "Build a three.js game for Dewdrop: the Vite plugin, model calls, multiplayer, saves and voice.",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/index.js

@@ -5,11 +5,13 @@
 // runs, `clients`, in that backend, over its port back, and `saves` into
 // the browser's own storage, which the plugin's script empties as each
 // page loads; `session` says when a session ends ahead of time, which here
-// none does.
+// none does; and `voice` reads the microphone through the browser's own
+// audio worklet, into the chunks a game gets on Dewdrop.
 export { llm } from './llm.js';
 export { backend } from './backend.js';
 export { clients } from './clients.js';
 export { session } from './session.js';
+export { voice } from './voice.js';
 import { attachBackend, joining } from './backend.js';
 import { load, save } from './saves.js';
 

package/src/session.js

@@ -1,10 +1,11 @@
 // `session` on a developer's machine. On Dewdrop a session can end ahead of
-// time — for maintenance, or a newer version of its game published — and
-// hears of it first, up to fifteen minutes before: `session.ending` is
+// time — for maintenance, a newer version of its game published, or its
+// player idle for fifteen minutes — and hears of it first, up to fifteen
+// minutes before, a minute for an idle player: `session.ending` is
 // `{at, reason}`, `at` in milliseconds since the epoch as `Date.now()` counts
-// and `reason` `'restart'` or `'update'`, and an `ending` event fires each
-// time it changes, its withdrawal to null included, so a game can save and
-// say so. `npm run dev` ends no session ahead of time, so here `ending`
+// and `reason` `'restart'`, `'update'` or `'idle'`, and an `ending` event
+// fires each time it changes, its withdrawal to null included, so a game can
+// save and say so. `npm run dev` ends no session ahead of time, so here `ending`
 // stays null and the event never fires; a game tries its handler by calling
 // it.
 import { defineHandlers } from './net.js';

package/src/voice.js

@@ -0,0 +1,135 @@
+// `voice` on a developer's machine: the player's microphone a chunk at a
+// time, as a game gets it on Dewdrop, where Dewdrop carries no voice
+// between players and plays none itself: a game sends what it captures
+// to its backend through its messages, the backend sends it on to the
+// players it chooses, and their games play it through their own audio
+// graphs. Here the browser's own audio worklet reads the microphone and
+// hands the game the same chunks, so a game captures in `npm run dev` as
+// it captures on Dewdrop.
+
+// The chunks as Dewdrop hands them to a game: the rate of their samples,
+// the samples in one chunk, 1/60 s, and the chunks that wait for a game
+// that reads late, the newest kept.
+export const SAMPLE_RATE = 48000;
+export const VOICE_CHUNK_SAMPLES = 800;
+export const VOICE_CHUNKS_HELD = 8;
+
+// The processor that reads the microphone in the browser's audio thread:
+// it takes the microphone's frames at the context's rate, steps through
+// them at SAMPLE_RATE, and posts each VOICE_CHUNK_SAMPLES of them as 16-bit
+// samples, the buffer handed over rather than copied. Its output is
+// silence, so it can hang off the destination, which is what has it run.
+export const CAPTURE_PROCESSOR = 'dew-voice-capture';
+export const CAPTURE_WORKLET = `
+class DewVoiceCapture extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.chunk = new Int16Array(${VOICE_CHUNK_SAMPLES});
+    this.at = 0;
+    // The microphone's frames per sample, and where in the block the next
+    // sample falls.
+    this.step = sampleRate / ${SAMPLE_RATE};
+    this.phase = 0;
+  }
+  process(inputs) {
+    const frames = inputs[0][0];
+    if (frames === undefined) return true;
+    while (this.phase < frames.length) {
+      const i = Math.floor(this.phase);
+      const next = i + 1 < frames.length ? frames[i + 1] : frames[i];
+      const sample = frames[i] + (next - frames[i]) * (this.phase - i);
+      const clamped = sample < -1 ? -1 : sample > 1 ? 1 : sample;
+      this.chunk[this.at++] = Math.round(clamped * 32767);
+      if (this.at === this.chunk.length) {
+        this.port.postMessage(this.chunk, [this.chunk.buffer]);
+        this.chunk = new Int16Array(${VOICE_CHUNK_SAMPLES});
+        this.at = 0;
+      }
+      this.phase += this.step;
+    }
+    this.phase -= frames.length;
+    return true;
+  }
+}
+registerProcessor('${CAPTURE_PROCESSOR}', DewVoiceCapture);
+`;
+
+// The capture under way, if any.
+let capturing = null;
+
+// A stream with a live audio track, as `getUserMedia` resolves one.
+function liveMicrophone(stream) {
+  return stream !== null && typeof stream === 'object' && typeof stream.getAudioTracks === 'function'
+    && stream.getAudioTracks().some((track) => track.readyState === 'live');
+}
+
+// The player's microphone, a chunk at a time: given the stream
+// `getUserMedia` resolved, while its track is live, hands back the
+// capture, whose `read()` returns the chunks that arrived since the last
+// read — each an Int16Array of VOICE_CHUNK_SAMPLES samples, mono, at
+// SAMPLE_RATE, in order, the newest VOICE_CHUNKS_HELD kept when the game
+// reads late — and whose `stop()` ends it, closing the context at once.
+// One at a time. The browser's own graph reads the stream: a context at
+// the sample rate where the browser allows one, the worklet between the
+// stream and the destination.
+function capture(stream) {
+  if (!liveMicrophone(stream)) {
+    throw new TypeError('voice.capture: stream is not a live microphone stream from navigator.mediaDevices.getUserMedia');
+  }
+  if (capturing !== null) throw new DOMException('voice.capture: the microphone is captured already; stop that first', 'InvalidStateError');
+  if (typeof AudioContext === 'undefined' || typeof AudioWorkletNode === 'undefined') {
+    throw new DOMException('voice.capture is unavailable here: the browser has no AudioWorklet', 'NotSupportedError');
+  }
+  let context;
+  try {
+    context = new AudioContext({ sampleRate: SAMPLE_RATE });
+  } catch {
+    context = new AudioContext();
+  }
+  let chunks = [];
+  let live = true;
+  const worklet = URL.createObjectURL(new Blob([CAPTURE_WORKLET], { type: 'text/javascript' }));
+  const ready = context.audioWorklet.addModule(worklet).then(() => {
+    URL.revokeObjectURL(worklet);
+    if (!live) return undefined;
+    const node = new AudioWorkletNode(context, CAPTURE_PROCESSOR, {
+      numberOfInputs: 1, numberOfOutputs: 1, outputChannelCount: [1], channelCount: 1, channelCountMode: 'explicit',
+    });
+    node.port.onmessage = ({ data }) => {
+      if (!live) return;
+      chunks.push(data);
+      if (chunks.length > VOICE_CHUNKS_HELD) chunks.splice(0, chunks.length - VOICE_CHUNKS_HELD);
+    };
+    context.createMediaStreamSource(stream).connect(node).connect(context.destination);
+    // A context the browser keeps suspended until the player's next
+    // gesture starts then; nothing here waits on it.
+    context.resume().catch(() => {});
+  });
+  // A worklet the browser refuses leaves the capture silent; the reason
+  // goes to the console, where the developer is.
+  ready.catch((error) => console.error('voice.capture: the microphone could not be read: ' + error.message));
+  const mine = Object.freeze({
+    read() {
+      if (capturing !== mine || chunks.length === 0) return [];
+      const read = chunks;
+      chunks = [];
+      return read;
+    },
+    stop() {
+      if (capturing !== mine) return;
+      capturing = null;
+      live = false;
+      chunks = [];
+      // Closed at once, whether or not the worklet has loaded or the
+      // context ever ran: a setup still to come finds `live` false and
+      // makes nothing.
+      context.close().catch(() => {});
+    },
+  });
+  capturing = mine;
+  return mine;
+}
+
+// SAMPLE_RATE is the chunks' rate, for the buffers a game plays them
+// through.
+export const voice = Object.freeze({ capture, SAMPLE_RATE });