onelobby 0.0.0-stage → 0.2.0

package/dist/voice-browser.js

@@ -0,0 +1,151 @@
+/* Browser implementations of the voice seams: WebCodecs Opus, AudioWorklet mic capture, WebAudio playback. */
+import { FRAME_SAMPLES, SAMPLE_RATE } from "./voice-core.js";
+export function webCodecsOpusAvailable() {
+    return typeof AudioEncoder !== "undefined" && typeof AudioDecoder !== "undefined" && typeof AudioData !== "undefined";
+}
+/** Opus through WebCodecs (not Baseline: Chromium/Edge/Safari; check `webCodecsOpusAvailable()`). */
+export const webCodecsOpus = {
+    createEncoder(opts, onFrame) {
+        let ts = 0;
+        const enc = new AudioEncoder({
+            output: (chunk) => {
+                const out = new Uint8Array(chunk.byteLength);
+                chunk.copyTo(out);
+                onFrame(out);
+            },
+            error: (e) => console.error("onelobby: AudioEncoder", e),
+        });
+        enc.configure({
+            codec: "opus",
+            sampleRate: SAMPLE_RATE,
+            numberOfChannels: 1,
+            bitrate: opts.bitrate,
+            opus: { frameDuration: 20000, application: "voip", useinbandfec: true, usedtx: false, packetlossperc: 10 },
+        });
+        return {
+            encode(pcm) {
+                const data = new AudioData({
+                    format: "f32",
+                    sampleRate: SAMPLE_RATE,
+                    numberOfFrames: pcm.length,
+                    numberOfChannels: 1,
+                    timestamp: ts,
+                    data: pcm,
+                });
+                ts += 20000;
+                enc.encode(data);
+                data.close();
+            },
+            close() {
+                if (enc.state !== "closed")
+                    enc.close();
+            },
+        };
+    },
+    createDecoder(onPcm) {
+        let ts = 0;
+        const dec = new AudioDecoder({
+            output: (audio) => {
+                const pcm = new Float32Array(audio.numberOfFrames);
+                audio.copyTo(pcm, { planeIndex: 0, format: "f32-planar" });
+                audio.close();
+                onPcm(pcm);
+            },
+            error: (e) => console.error("onelobby: AudioDecoder", e),
+        });
+        dec.configure({ codec: "opus", sampleRate: SAMPLE_RATE, numberOfChannels: 1 });
+        return {
+            decode(opus) {
+                if (opus === null) {
+                    onPcm(new Float32Array(FRAME_SAMPLES)); // WebCodecs has no PLC hook: conceal with silence
+                    return;
+                }
+                dec.decode(new EncodedAudioChunk({ type: "key", timestamp: ts, data: opus }));
+                ts += 20000;
+            },
+            close() {
+                if (dec.state !== "closed")
+                    dec.close();
+            },
+        };
+    },
+};
+const WORKLET_SRC = `
+class OneLobbyCapture extends AudioWorkletProcessor {
+  constructor() { super(); this.buf = new Float32Array(${FRAME_SAMPLES}); this.n = 0; }
+  process(inputs) {
+    const ch = inputs[0] && inputs[0][0];
+    if (ch) {
+      for (let i = 0; i < ch.length; i++) {
+        this.buf[this.n++] = ch[i];
+        if (this.n === ${FRAME_SAMPLES}) {
+          const out = this.buf; this.buf = new Float32Array(${FRAME_SAMPLES}); this.n = 0;
+          this.port.postMessage(out, [out.buffer]);
+        }
+      }
+    }
+    return true;
+  }
+}
+registerProcessor('onelobby-capture', OneLobbyCapture);
+`;
+/** getUserMedia + AudioWorklet producing 960-sample frames at 48 kHz. Must be started from a user gesture. */
+export class WorkletMic {
+    ctx = null;
+    stream = null;
+    async start(onFrame) {
+        this.stream = await navigator.mediaDevices.getUserMedia({
+            audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true, autoGainControl: true },
+        });
+        this.ctx = new AudioContext({ sampleRate: SAMPLE_RATE });
+        const url = URL.createObjectURL(new Blob([WORKLET_SRC], { type: "text/javascript" }));
+        try {
+            await this.ctx.audioWorklet.addModule(url);
+        }
+        finally {
+            URL.revokeObjectURL(url);
+        }
+        const src = this.ctx.createMediaStreamSource(this.stream);
+        const node = new AudioWorkletNode(this.ctx, "onelobby-capture", { numberOfInputs: 1, numberOfOutputs: 0 });
+        node.port.onmessage = (e) => onFrame(e.data);
+        src.connect(node);
+        if (this.ctx.state === "suspended")
+            await this.ctx.resume();
+    }
+    stop() {
+        for (const t of this.stream?.getTracks() ?? [])
+            t.stop();
+        void this.ctx?.close();
+        this.stream = null;
+        this.ctx = null;
+    }
+}
+/** Plays decoded PCM per speaker, scheduled back to back on an AudioContext. */
+export class WebAudioSink {
+    ctx = new AudioContext({ sampleRate: SAMPLE_RATE });
+    next = new Map();
+    constructor() {
+        void this.ctx.resume();
+    }
+    play(peerId, pcm, gain) {
+        if (pcm.length === 0)
+            return;
+        const buf = this.ctx.createBuffer(1, pcm.length, SAMPLE_RATE);
+        buf.copyToChannel(pcm, 0);
+        const src = this.ctx.createBufferSource();
+        src.buffer = buf;
+        const g = this.ctx.createGain();
+        g.gain.value = gain;
+        src.connect(g).connect(this.ctx.destination);
+        const now = this.ctx.currentTime;
+        let at = this.next.get(peerId) ?? 0;
+        if (at < now + 0.01)
+            at = now + 0.02; // (re)started: small lead so scheduling never lands in the past
+        src.start(at);
+        this.next.set(peerId, at + pcm.length / SAMPLE_RATE);
+    }
+    close() {
+        void this.ctx.close();
+    }
+}
+//# sourceMappingURL=voice-browser.js.map

package/dist/voice-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-browser.js","sourceRoot":"","sources":["../src/voice-browser.ts"],"names":[],"mappings":"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","sourcesContent":["/* Browser implementations of the voice seams: WebCodecs Opus, AudioWorklet mic capture, WebAudio playback. */\nimport { FRAME_SAMPLES, SAMPLE_RATE } from \"./voice-core.js\";\nimport type { AudioSink, FrameSource, VoiceCodec, VoiceDecoderHandle, VoiceEncoderHandle } from \"./voice-types.js\";\n\nexport function webCodecsOpusAvailable(): boolean {\n  return typeof AudioEncoder !== \"undefined\" && typeof AudioDecoder !== \"undefined\" && typeof AudioData !== \"undefined\";\n}\n\n/** Opus through WebCodecs (not Baseline: Chromium/Edge/Safari; check `webCodecsOpusAvailable()`). */\nexport const webCodecsOpus: VoiceCodec = {\n  createEncoder(opts, onFrame): VoiceEncoderHandle {\n    let ts = 0;\n    const enc = new AudioEncoder({\n      output: (chunk) => {\n        const out = new Uint8Array(chunk.byteLength);\n        chunk.copyTo(out);\n        onFrame(out);\n      },\n      error: (e) => console.error(\"onelobby: AudioEncoder\", e),\n    });\n    enc.configure({\n      codec: \"opus\",\n      sampleRate: SAMPLE_RATE,\n      numberOfChannels: 1,\n      bitrate: opts.bitrate,\n      opus: { frameDuration: 20000, application: \"voip\", useinbandfec: true, usedtx: false, packetlossperc: 10 },\n    } as AudioEncoderConfig);\n    return {\n      encode(pcm) {\n        const data = new AudioData({\n          format: \"f32\",\n          sampleRate: SAMPLE_RATE,\n          numberOfFrames: pcm.length,\n          numberOfChannels: 1,\n          timestamp: ts,\n          data: pcm as unknown as Float32Array<ArrayBuffer>,\n        });\n        ts += 20000;\n        enc.encode(data);\n        data.close();\n      },\n      close() {\n        if (enc.state !== \"closed\") enc.close();\n      },\n    };\n  },\n  createDecoder(onPcm): VoiceDecoderHandle {\n    let ts = 0;\n    const dec = new AudioDecoder({\n      output: (audio) => {\n        const pcm = new Float32Array(audio.numberOfFrames);\n        audio.copyTo(pcm, { planeIndex: 0, format: \"f32-planar\" } as AudioDataCopyToOptions);\n        audio.close();\n        onPcm(pcm);\n      },\n      error: (e) => console.error(\"onelobby: AudioDecoder\", e),\n    });\n    dec.configure({ codec: \"opus\", sampleRate: SAMPLE_RATE, numberOfChannels: 1 });\n    return {\n      decode(opus) {\n        if (opus === null) {\n          onPcm(new Float32Array(FRAME_SAMPLES)); // WebCodecs has no PLC hook: conceal with silence\n          return;\n        }\n        dec.decode(new EncodedAudioChunk({ type: \"key\", timestamp: ts, data: opus }));\n        ts += 20000;\n      },\n      close() {\n        if (dec.state !== \"closed\") dec.close();\n      },\n    };\n  },\n};\n\nconst WORKLET_SRC = `\nclass OneLobbyCapture extends AudioWorkletProcessor {\n  constructor() { super(); this.buf = new Float32Array(${FRAME_SAMPLES}); this.n = 0; }\n  process(inputs) {\n    const ch = inputs[0] && inputs[0][0];\n    if (ch) {\n      for (let i = 0; i < ch.length; i++) {\n        this.buf[this.n++] = ch[i];\n        if (this.n === ${FRAME_SAMPLES}) {\n          const out = this.buf; this.buf = new Float32Array(${FRAME_SAMPLES}); this.n = 0;\n          this.port.postMessage(out, [out.buffer]);\n        }\n      }\n    }\n    return true;\n  }\n}\nregisterProcessor('onelobby-capture', OneLobbyCapture);\n`;\n\n/** getUserMedia + AudioWorklet producing 960-sample frames at 48 kHz. Must be started from a user gesture. */\nexport class WorkletMic implements FrameSource {\n  private ctx: AudioContext | null = null;\n  private stream: MediaStream | null = null;\n\n  async start(onFrame: (pcm: Float32Array) => void): Promise<void> {\n    this.stream = await navigator.mediaDevices.getUserMedia({\n      audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true, autoGainControl: true },\n    });\n    this.ctx = new AudioContext({ sampleRate: SAMPLE_RATE });\n    const url = URL.createObjectURL(new Blob([WORKLET_SRC], { type: \"text/javascript\" }));\n    try {\n      await this.ctx.audioWorklet.addModule(url);\n    } finally {\n      URL.revokeObjectURL(url);\n    }\n    const src = this.ctx.createMediaStreamSource(this.stream);\n    const node = new AudioWorkletNode(this.ctx, \"onelobby-capture\", { numberOfInputs: 1, numberOfOutputs: 0 });\n    node.port.onmessage = (e) => onFrame(e.data as Float32Array);\n    src.connect(node);\n    if (this.ctx.state === \"suspended\") await this.ctx.resume();\n  }\n\n  stop(): void {\n    for (const t of this.stream?.getTracks() ?? []) t.stop();\n    void this.ctx?.close();\n    this.stream = null;\n    this.ctx = null;\n  }\n}\n\n/** Plays decoded PCM per speaker, scheduled back to back on an AudioContext. */\nexport class WebAudioSink implements AudioSink {\n  private ctx = new AudioContext({ sampleRate: SAMPLE_RATE });\n  private next = new Map<number, number>();\n\n  constructor() {\n    void this.ctx.resume();\n  }\n\n  play(peerId: number, pcm: Float32Array, gain: number): void {\n    if (pcm.length === 0) return;\n    const buf = this.ctx.createBuffer(1, pcm.length, SAMPLE_RATE);\n    buf.copyToChannel(pcm as unknown as Float32Array<ArrayBuffer>, 0);\n    const src = this.ctx.createBufferSource();\n    src.buffer = buf;\n    const g = this.ctx.createGain();\n    g.gain.value = gain;\n    src.connect(g).connect(this.ctx.destination);\n    const now = this.ctx.currentTime;\n    let at = this.next.get(peerId) ?? 0;\n    if (at < now + 0.01) at = now + 0.02; // (re)started: small lead so scheduling never lands in the past\n    src.start(at);\n    this.next.set(peerId, at + pcm.length / SAMPLE_RATE);\n  }\n\n  close(): void {\n    void this.ctx.close();\n  }\n}\n"]}

package/dist/voice-core.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure voice building blocks (DESIGN s.9a): packetizer, PTT/VAD gate, jitter buffer, host relay policy.
+ * No audio APIs here, so all of it is unit-testable.
+ */
+export declare const SAMPLE_RATE = 48000;
+export declare const FRAME_MS = 20;
+export declare const FRAME_SAMPLES: number;
+export declare const FRAMES_PER_PACKET = 2;
+export declare const MAX_VOICE_PACKET_BYTES = 1024;
+export declare const MAX_SPEAKERS = 8;
+export declare const MAX_PACKETS_PER_SEC = 30;
+export declare const JITTER_MS = 60;
+export declare const VAD_HANGOVER_MS = 300;
+export declare const FLAG_END_OF_BURST = 1;
+export interface VoicePacket {
+    seq: number;
+    flags: number;
+    frames: Uint8Array[];
+}
+/** Batches encoded 20 ms frames into 40 ms packets; `endBurst()` flushes the remainder with the end flag. */
+export declare class VoicePacketizer {
+    private framesPerPacket;
+    private seq;
+    private buf;
+    constructor(framesPerPacket?: number);
+    push(frame: Uint8Array): VoicePacket | null;
+    /** Wrap already-encoded frames in the next packet (no batching). */
+    packet(frames: Uint8Array[], flags: number): VoicePacket;
+    /** Always emits a packet (possibly with zero frames) carrying the end-of-burst flag. */
+    endBurst(): VoicePacket;
+    get buffered(): number;
+    private take;
+}
+export declare function rms(pcm: Float32Array): number;
+export type VoiceMode = "pushToTalk" | "voiceActivity";
+/** Decides, per captured 20 ms frame, whether it is transmitted. VAD uses an RMS gate with a 300 ms hangover. */
+export declare class VoiceGate {
+    mode: VoiceMode;
+    ptt: boolean;
+    vadThreshold: number;
+    private lastLoud;
+    private open;
+    /** Returns { send, edge } where edge is 'open' | 'close' | null on a transition. */
+    update(level: number, nowMs: number): {
+        send: boolean;
+        edge: "open" | "close" | null;
+    };
+    get isOpen(): boolean;
+}
+/** u16 sequence comparison with wraparound: positive when a is after b. */
+export declare function seqDiff(a: number, b: number): number;
+export type PullResult = {
+    kind: "frame";
+    opus: Uint8Array;
+} | {
+    kind: "plc";
+} | {
+    kind: "wait";
+} | {
+    kind: "idle";
+};
+/**
+ * Per-speaker jitter buffer. Reorders by `seq`, prefills 60 ms (3 frames) before playing, reports a lost packet as
+ * PLC frames when a later packet is already here, and flushes on the end-of-burst flag.
+ * `pull()` is called once per 20 ms by the playout clock.
+ */
+export declare class JitterBuffer {
+    private framesPerPacket;
+    private packets;
+    private expected;
+    private ready;
+    private playing;
+    private endSeq;
+    private waitTicks;
+    readonly prefillFrames: number;
+    constructor(jitterMs?: number, framesPerPacket?: number);
+    push(p: VoicePacket): void;
+    private get ended();
+    private bufferedFrames;
+    private newerThanExpected;
+    pull(): PullResult;
+    private refill;
+    reset(): void;
+    get active(): boolean;
+}
+/**
+ * Host-side policy for forwarding voice (s.9a): <= 8 concurrent speakers (9th burst silently dropped), packets <= 1 KiB,
+ * <= 30 packets/s per peer.
+ */
+export declare class VoiceRelayPolicy {
+    private speakers;
+    private windows;
+    /** A burst with no packet for this long counts as over even if its end flag was lost. */
+    burstTimeoutMs: number;
+    accept(from: number, size: number, flags: number, now: number): boolean;
+    get activeSpeakers(): number;
+    forget(peerId: number): void;
+}

package/dist/voice-core.js

@@ -0,0 +1,233 @@
+/**
+ * Pure voice building blocks (DESIGN s.9a): packetizer, PTT/VAD gate, jitter buffer, host relay policy.
+ * No audio APIs here, so all of it is unit-testable.
+ */
+export const SAMPLE_RATE = 48000;
+export const FRAME_MS = 20;
+export const FRAME_SAMPLES = (SAMPLE_RATE * FRAME_MS) / 1000; // 960
+export const FRAMES_PER_PACKET = 2;
+export const MAX_VOICE_PACKET_BYTES = 1024;
+export const MAX_SPEAKERS = 8;
+export const MAX_PACKETS_PER_SEC = 30;
+export const JITTER_MS = 60;
+export const VAD_HANGOVER_MS = 300;
+export const FLAG_END_OF_BURST = 1;
+/** Batches encoded 20 ms frames into 40 ms packets; `endBurst()` flushes the remainder with the end flag. */
+export class VoicePacketizer {
+    framesPerPacket;
+    seq = 0;
+    buf = [];
+    constructor(framesPerPacket = FRAMES_PER_PACKET) {
+        this.framesPerPacket = framesPerPacket;
+    }
+    push(frame) {
+        this.buf.push(frame);
+        if (this.buf.length < this.framesPerPacket)
+            return null;
+        return this.take(0);
+    }
+    /** Wrap already-encoded frames in the next packet (no batching). */
+    packet(frames, flags) {
+        const p = { seq: this.seq, flags, frames };
+        this.seq = (this.seq + 1) & 0xffff;
+        return p;
+    }
+    /** Always emits a packet (possibly with zero frames) carrying the end-of-burst flag. */
+    endBurst() {
+        return this.take(FLAG_END_OF_BURST);
+    }
+    get buffered() {
+        return this.buf.length;
+    }
+    take(flags) {
+        const p = { seq: this.seq, flags, frames: this.buf };
+        this.seq = (this.seq + 1) & 0xffff;
+        this.buf = [];
+        return p;
+    }
+}
+export function rms(pcm) {
+    if (pcm.length === 0)
+        return 0;
+    let s = 0;
+    for (let i = 0; i < pcm.length; i++)
+        s += pcm[i] * pcm[i];
+    return Math.sqrt(s / pcm.length);
+}
+/** Decides, per captured 20 ms frame, whether it is transmitted. VAD uses an RMS gate with a 300 ms hangover. */
+export class VoiceGate {
+    mode = "pushToTalk";
+    ptt = false;
+    vadThreshold = 0.02;
+    lastLoud = -Infinity;
+    open = false;
+    /** Returns { send, edge } where edge is 'open' | 'close' | null on a transition. */
+    update(level, nowMs) {
+        let want;
+        if (this.mode === "pushToTalk") {
+            want = this.ptt;
+        }
+        else {
+            if (level >= this.vadThreshold)
+                this.lastLoud = nowMs;
+            want = nowMs - this.lastLoud <= VAD_HANGOVER_MS;
+        }
+        const edge = want === this.open ? null : want ? "open" : "close";
+        this.open = want;
+        return { send: want, edge };
+    }
+    get isOpen() {
+        return this.open;
+    }
+}
+/** u16 sequence comparison with wraparound: positive when a is after b. */
+export function seqDiff(a, b) {
+    const d = (a - b) & 0xffff;
+    return d >= 0x8000 ? d - 0x10000 : d;
+}
+/**
+ * Per-speaker jitter buffer. Reorders by `seq`, prefills 60 ms (3 frames) before playing, reports a lost packet as
+ * PLC frames when a later packet is already here, and flushes on the end-of-burst flag.
+ * `pull()` is called once per 20 ms by the playout clock.
+ */
+export class JitterBuffer {
+    framesPerPacket;
+    packets = new Map();
+    expected = null;
+    ready = [];
+    playing = false;
+    endSeq = null;
+    waitTicks = 0;
+    prefillFrames;
+    constructor(jitterMs = JITTER_MS, framesPerPacket = FRAMES_PER_PACKET) {
+        this.framesPerPacket = framesPerPacket;
+        this.prefillFrames = Math.max(1, Math.round(jitterMs / FRAME_MS));
+    }
+    push(p) {
+        if (this.expected === null) {
+            this.expected = p.seq;
+        }
+        else if (seqDiff(p.seq, this.expected) < 0) {
+            return; // late: already played or skipped
+        }
+        this.packets.set(p.seq, p);
+        if (p.flags & FLAG_END_OF_BURST)
+            this.endSeq = p.seq;
+        else if (this.endSeq !== null && seqDiff(p.seq, this.endSeq) > 0)
+            this.endSeq = null; // a new burst began
+    }
+    get ended() {
+        return this.endSeq !== null;
+    }
+    bufferedFrames() {
+        let n = this.ready.length;
+        for (const p of this.packets.values())
+            n += p.frames.length;
+        return n;
+    }
+    newerThanExpected() {
+        for (const s of this.packets.keys())
+            if (this.expected !== null && seqDiff(s, this.expected) > 0)
+                return true;
+        return false;
+    }
+    pull() {
+        if (this.expected === null)
+            return { kind: "idle" };
+        if (!this.playing) {
+            if (this.bufferedFrames() >= this.prefillFrames || (this.ended && this.packets.size > 0))
+                this.playing = true;
+            else
+                return { kind: "wait" };
+        }
+        if (this.ready.length === 0)
+            this.refill();
+        const f = this.ready.shift();
+        if (f) {
+            this.waitTicks = 0;
+            return f.length === 0 ? { kind: "plc" } : { kind: "frame", opus: f };
+        }
+        // nothing playable
+        if (this.ended && this.packets.size === 0) {
+            this.reset();
+            return { kind: "idle" };
+        }
+        if (++this.waitTicks > 12) {
+            // 240 ms of silence without an end flag: the burst is over (flag lost). Flush.
+            this.reset();
+            return { kind: "idle" };
+        }
+        return { kind: "wait" };
+    }
+    refill() {
+        if (this.expected === null)
+            return;
+        const p = this.packets.get(this.expected);
+        if (p) {
+            this.packets.delete(this.expected);
+            this.expected = (this.expected + 1) & 0xffff;
+            for (const fr of p.frames)
+                this.ready.push(fr);
+            return;
+        }
+        if (this.newerThanExpected()) {
+            // The packet never arrived but later ones did: conceal it (empty array = PLC marker).
+            this.expected = (this.expected + 1) & 0xffff;
+            for (let i = 0; i < this.framesPerPacket; i++)
+                this.ready.push(new Uint8Array(0));
+        }
+    }
+    reset() {
+        this.packets.clear();
+        this.ready = [];
+        this.expected = null;
+        this.playing = false;
+        this.endSeq = null;
+        this.waitTicks = 0;
+    }
+    get active() {
+        return this.expected !== null;
+    }
+}
+/**
+ * Host-side policy for forwarding voice (s.9a): <= 8 concurrent speakers (9th burst silently dropped), packets <= 1 KiB,
+ * <= 30 packets/s per peer.
+ */
+export class VoiceRelayPolicy {
+    speakers = new Map(); // peerId -> last packet time
+    windows = new Map();
+    /** A burst with no packet for this long counts as over even if its end flag was lost. */
+    burstTimeoutMs = 500;
+    accept(from, size, flags, now) {
+        if (size > MAX_VOICE_PACKET_BYTES)
+            return false;
+        // rate cap
+        let w = this.windows.get(from);
+        if (!w)
+            this.windows.set(from, (w = []));
+        while (w.length && now - w[0] >= 1000)
+            w.shift();
+        if (w.length >= MAX_PACKETS_PER_SEC)
+            return false;
+        // speaker cap
+        for (const [p, t] of this.speakers)
+            if (now - t > this.burstTimeoutMs)
+                this.speakers.delete(p);
+        if (!this.speakers.has(from) && this.speakers.size >= MAX_SPEAKERS)
+            return false;
+        w.push(now);
+        if (flags & FLAG_END_OF_BURST)
+            this.speakers.delete(from);
+        else
+            this.speakers.set(from, now);
+        return true;
+    }
+    get activeSpeakers() {
+        return this.speakers.size;
+    }
+    forget(peerId) {
+        this.speakers.delete(peerId);
+        this.windows.delete(peerId);
+    }
+}
+//# sourceMappingURL=voice-core.js.map

package/dist/voice-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-core.js","sourceRoot":"","sources":["../src/voice-core.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure voice building blocks (DESIGN s.9a): packetizer, PTT/VAD gate, jitter buffer, host relay policy.\n * No audio APIs here, so all of it is unit-testable.\n */\n\nexport const SAMPLE_RATE = 48000;\nexport const FRAME_MS = 20;\nexport const FRAME_SAMPLES = (SAMPLE_RATE * FRAME_MS) / 1000; // 960\nexport const FRAMES_PER_PACKET = 2;\nexport const MAX_VOICE_PACKET_BYTES = 1024;\nexport const MAX_SPEAKERS = 8;\nexport const MAX_PACKETS_PER_SEC = 30;\nexport const JITTER_MS = 60;\nexport const VAD_HANGOVER_MS = 300;\nexport const FLAG_END_OF_BURST = 1;\n\nexport interface VoicePacket {\n  seq: number;\n  flags: number;\n  frames: Uint8Array[];\n}\n\n/** Batches encoded 20 ms frames into 40 ms packets; `endBurst()` flushes the remainder with the end flag. */\nexport class VoicePacketizer {\n  private seq = 0;\n  private buf: Uint8Array[] = [];\n  constructor(private framesPerPacket = FRAMES_PER_PACKET) {}\n\n  push(frame: Uint8Array): VoicePacket | null {\n    this.buf.push(frame);\n    if (this.buf.length < this.framesPerPacket) return null;\n    return this.take(0);\n  }\n\n  /** Wrap already-encoded frames in the next packet (no batching). */\n  packet(frames: Uint8Array[], flags: number): VoicePacket {\n    const p: VoicePacket = { seq: this.seq, flags, frames };\n    this.seq = (this.seq + 1) & 0xffff;\n    return p;\n  }\n\n  /** Always emits a packet (possibly with zero frames) carrying the end-of-burst flag. */\n  endBurst(): VoicePacket {\n    return this.take(FLAG_END_OF_BURST);\n  }\n\n  get buffered(): number {\n    return this.buf.length;\n  }\n\n  private take(flags: number): VoicePacket {\n    const p: VoicePacket = { seq: this.seq, flags, frames: this.buf };\n    this.seq = (this.seq + 1) & 0xffff;\n    this.buf = [];\n    return p;\n  }\n}\n\nexport function rms(pcm: Float32Array): number {\n  if (pcm.length === 0) return 0;\n  let s = 0;\n  for (let i = 0; i < pcm.length; i++) s += pcm[i] * pcm[i];\n  return Math.sqrt(s / pcm.length);\n}\n\nexport type VoiceMode = \"pushToTalk\" | \"voiceActivity\";\n\n/** Decides, per captured 20 ms frame, whether it is transmitted. VAD uses an RMS gate with a 300 ms hangover. */\nexport class VoiceGate {\n  mode: VoiceMode = \"pushToTalk\";\n  ptt = false;\n  vadThreshold = 0.02;\n  private lastLoud = -Infinity;\n  private open = false;\n\n  /** Returns { send, edge } where edge is 'open' | 'close' | null on a transition. */\n  update(level: number, nowMs: number): { send: boolean; edge: \"open\" | \"close\" | null } {\n    let want: boolean;\n    if (this.mode === \"pushToTalk\") {\n      want = this.ptt;\n    } else {\n      if (level >= this.vadThreshold) this.lastLoud = nowMs;\n      want = nowMs - this.lastLoud <= VAD_HANGOVER_MS;\n    }\n    const edge = want === this.open ? null : want ? \"open\" : \"close\";\n    this.open = want;\n    return { send: want, edge };\n  }\n\n  get isOpen(): boolean {\n    return this.open;\n  }\n}\n\n/** u16 sequence comparison with wraparound: positive when a is after b. */\nexport function seqDiff(a: number, b: number): number {\n  const d = (a - b) & 0xffff;\n  return d >= 0x8000 ? d - 0x10000 : d;\n}\n\nexport type PullResult =\n  | { kind: \"frame\"; opus: Uint8Array }\n  | { kind: \"plc\" }\n  | { kind: \"wait\" }\n  | { kind: \"idle\" };\n\n/**\n * Per-speaker jitter buffer. Reorders by `seq`, prefills 60 ms (3 frames) before playing, reports a lost packet as\n * PLC frames when a later packet is already here, and flushes on the end-of-burst flag.\n * `pull()` is called once per 20 ms by the playout clock.\n */\nexport class JitterBuffer {\n  private packets = new Map<number, VoicePacket>();\n  private expected: number | null = null;\n  private ready: Uint8Array[] = [];\n  private playing = false;\n  private endSeq: number | null = null;\n  private waitTicks = 0;\n  readonly prefillFrames: number;\n\n  constructor(jitterMs = JITTER_MS, private framesPerPacket = FRAMES_PER_PACKET) {\n    this.prefillFrames = Math.max(1, Math.round(jitterMs / FRAME_MS));\n  }\n\n  push(p: VoicePacket): void {\n    if (this.expected === null) {\n      this.expected = p.seq;\n    } else if (seqDiff(p.seq, this.expected) < 0) {\n      return; // late: already played or skipped\n    }\n    this.packets.set(p.seq, p);\n    if (p.flags & FLAG_END_OF_BURST) this.endSeq = p.seq;\n    else if (this.endSeq !== null && seqDiff(p.seq, this.endSeq) > 0) this.endSeq = null; // a new burst began\n  }\n\n  private get ended(): boolean {\n    return this.endSeq !== null;\n  }\n\n  private bufferedFrames(): number {\n    let n = this.ready.length;\n    for (const p of this.packets.values()) n += p.frames.length;\n    return n;\n  }\n\n  private newerThanExpected(): boolean {\n    for (const s of this.packets.keys()) if (this.expected !== null && seqDiff(s, this.expected) > 0) return true;\n    return false;\n  }\n\n  pull(): PullResult {\n    if (this.expected === null) return { kind: \"idle\" };\n    if (!this.playing) {\n      if (this.bufferedFrames() >= this.prefillFrames || (this.ended && this.packets.size > 0)) this.playing = true;\n      else return { kind: \"wait\" };\n    }\n    if (this.ready.length === 0) this.refill();\n    const f = this.ready.shift();\n    if (f) {\n      this.waitTicks = 0;\n      return f.length === 0 ? { kind: \"plc\" } : { kind: \"frame\", opus: f };\n    }\n    // nothing playable\n    if (this.ended && this.packets.size === 0) {\n      this.reset();\n      return { kind: \"idle\" };\n    }\n    if (++this.waitTicks > 12) {\n      // 240 ms of silence without an end flag: the burst is over (flag lost). Flush.\n      this.reset();\n      return { kind: \"idle\" };\n    }\n    return { kind: \"wait\" };\n  }\n\n  private refill(): void {\n    if (this.expected === null) return;\n    const p = this.packets.get(this.expected);\n    if (p) {\n      this.packets.delete(this.expected);\n      this.expected = (this.expected + 1) & 0xffff;\n      for (const fr of p.frames) this.ready.push(fr);\n      return;\n    }\n    if (this.newerThanExpected()) {\n      // The packet never arrived but later ones did: conceal it (empty array = PLC marker).\n      this.expected = (this.expected + 1) & 0xffff;\n      for (let i = 0; i < this.framesPerPacket; i++) this.ready.push(new Uint8Array(0));\n    }\n  }\n\n  reset(): void {\n    this.packets.clear();\n    this.ready = [];\n    this.expected = null;\n    this.playing = false;\n    this.endSeq = null;\n    this.waitTicks = 0;\n  }\n\n  get active(): boolean {\n    return this.expected !== null;\n  }\n}\n\n/**\n * Host-side policy for forwarding voice (s.9a): <= 8 concurrent speakers (9th burst silently dropped), packets <= 1 KiB,\n * <= 30 packets/s per peer.\n */\nexport class VoiceRelayPolicy {\n  private speakers = new Map<number, number>(); // peerId -> last packet time\n  private windows = new Map<number, number[]>();\n  /** A burst with no packet for this long counts as over even if its end flag was lost. */\n  burstTimeoutMs = 500;\n\n  accept(from: number, size: number, flags: number, now: number): boolean {\n    if (size > MAX_VOICE_PACKET_BYTES) return false;\n    // rate cap\n    let w = this.windows.get(from);\n    if (!w) this.windows.set(from, (w = []));\n    while (w.length && now - w[0] >= 1000) w.shift();\n    if (w.length >= MAX_PACKETS_PER_SEC) return false;\n    // speaker cap\n    for (const [p, t] of this.speakers) if (now - t > this.burstTimeoutMs) this.speakers.delete(p);\n    if (!this.speakers.has(from) && this.speakers.size >= MAX_SPEAKERS) return false;\n    w.push(now);\n    if (flags & FLAG_END_OF_BURST) this.speakers.delete(from);\n    else this.speakers.set(from, now);\n    return true;\n  }\n\n  get activeSpeakers(): number {\n    return this.speakers.size;\n  }\n\n  forget(peerId: number): void {\n    this.speakers.delete(peerId);\n    this.windows.delete(peerId);\n  }\n}\n"]}

package/dist/voice-types.d.ts

@@ -0,0 +1,35 @@
+/** Pluggable audio seams for voice: codec (WebCodecs or a WASM Opus), mic source, speaker sink. */
+export interface VoiceError {
+    message: string;
+    cause?: unknown;
+}
+export interface VoiceEncoderHandle {
+    /** Encode one 20 ms mono 48 kHz frame (960 samples, float -1..1). Output arrives through the callback. */
+    encode(pcm: Float32Array): void;
+    close(): void;
+}
+export interface VoiceDecoderHandle {
+    /** Decode one Opus frame; `null` asks for packet-loss concealment of one 20 ms frame. */
+    decode(opus: Uint8Array | null): void;
+    close(): void;
+}
+/**
+ * Opus codec seam. The default implementation uses WebCodecs `AudioEncoder`/`AudioDecoder`; a WASM libopus build
+ * can implement this interface for browsers without WebCodecs Opus.
+ */
+export interface VoiceCodec {
+    createEncoder(opts: {
+        bitrate: number;
+    }, onFrame: (opus: Uint8Array) => void): VoiceEncoderHandle;
+    createDecoder(onPcm: (pcm: Float32Array) => void): VoiceDecoderHandle;
+}
+/** Microphone: delivers 960-sample frames. */
+export interface FrameSource {
+    start(onFrame: (pcm: Float32Array) => void): Promise<void>;
+    stop(): void;
+}
+/** Speaker output for decoded PCM (mono 48 kHz). `gain` is 0..2. */
+export interface AudioSink {
+    play(peerId: number, pcm: Float32Array, gain: number): void;
+    close(): void;
+}

package/dist/voice-types.js

@@ -0,0 +1,3 @@
+/** Pluggable audio seams for voice: codec (WebCodecs or a WASM Opus), mic source, speaker sink. */
+export {};
+//# sourceMappingURL=voice-types.js.map

package/dist/voice-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-types.js","sourceRoot":"","sources":["../src/voice-types.ts"],"names":[],"mappings":"AAAA,mGAAmG","sourcesContent":["/** Pluggable audio seams for voice: codec (WebCodecs or a WASM Opus), mic source, speaker sink. */\n\nexport interface VoiceError {\n  message: string;\n  cause?: unknown;\n}\n\nexport interface VoiceEncoderHandle {\n  /** Encode one 20 ms mono 48 kHz frame (960 samples, float -1..1). Output arrives through the callback. */\n  encode(pcm: Float32Array): void;\n  close(): void;\n}\n\nexport interface VoiceDecoderHandle {\n  /** Decode one Opus frame; `null` asks for packet-loss concealment of one 20 ms frame. */\n  decode(opus: Uint8Array | null): void;\n  close(): void;\n}\n\n/**\n * Opus codec seam. The default implementation uses WebCodecs `AudioEncoder`/`AudioDecoder`; a WASM libopus build\n * can implement this interface for browsers without WebCodecs Opus.\n */\nexport interface VoiceCodec {\n  createEncoder(opts: { bitrate: number }, onFrame: (opus: Uint8Array) => void): VoiceEncoderHandle;\n  createDecoder(onPcm: (pcm: Float32Array) => void): VoiceDecoderHandle;\n}\n\n/** Microphone: delivers 960-sample frames. */\nexport interface FrameSource {\n  start(onFrame: (pcm: Float32Array) => void): Promise<void>;\n  stop(): void;\n}\n\n/** Speaker output for decoded PCM (mono 48 kHz). `gain` is 0..2. */\nexport interface AudioSink {\n  play(peerId: number, pcm: Float32Array, gain: number): void;\n  close(): void;\n}\n"]}

package/dist/voice.d.ts

@@ -0,0 +1,68 @@
+import type { VoiceError } from "./voice-types.js";
+import { Emitter } from "./emitter.js";
+import type { Hub } from "./hub.js";
+import type { Message } from "./codec.js";
+import { type VoiceMode, type VoicePacket } from "./voice-core.js";
+import type { AudioSink, FrameSource, VoiceCodec } from "./voice-types.js";
+export type VoiceEvents = {
+    speaking: [peerId: number, talking: boolean];
+    error: [VoiceError];
+    /** Every voice packet that reached this peer (after the host's validity checks), before mute/enable filtering. */
+    packet: [speaker: number, seq: number, flags: number, frames: Uint8Array[]];
+};
+export interface VoiceDeps {
+    codec: VoiceCodec | null;
+    /** Creates the mic capture; resolved on `enabled = true`. */
+    createSource: (() => FrameSource) | null;
+    createSink: (() => AudioSink) | null;
+}
+/** Voice chat (DESIGN s.9a): Opus frames on the `voice` channel, star-routed through the host, never in a frame. */
+export declare class Voice extends Emitter<VoiceEvents> {
+    private hub;
+    private deps;
+    mode: VoiceMode;
+    /** Master mute for capture (self). */
+    muted: boolean;
+    /** 0..1 RMS of the last captured frame. */
+    inputLevel: number;
+    bitrate: number;
+    private _enabled;
+    private gate;
+    private packetizer;
+    private relay;
+    private speakers;
+    private peerMuted;
+    private gains;
+    private encoder;
+    private source;
+    private sink;
+    private cancelPlayout;
+    private endTimer;
+    private sending;
+    constructor(hub: Hub, deps: VoiceDeps);
+    get enabled(): boolean;
+    set enabled(v: boolean);
+    pushToTalk(down: boolean): void;
+    isMutedPeer(peerId: number): boolean;
+    setMuted(peerId: number, muted: boolean): void;
+    setVolume(peerId: number, gain: number): void;
+    volumeOf(peerId: number): number;
+    private start;
+    private stop;
+    /** Feed one 20 ms mono 48 kHz frame (called by the mic source; exposed so tests and custom sources can drive it). */
+    onCapturedFrame(pcm: Float32Array, nowMs: number): void;
+    private closeBurst;
+    /** Send already-encoded Opus frames as one packet (no codec involved); used by tools and conformance. */
+    sendEncoded(frames: Uint8Array[], endOfBurst?: boolean): void;
+    /** Encoded frame from the encoder (also the test entry point for packetization). */
+    onEncoded(opus: Uint8Array): void;
+    private sendPacket;
+    handle(from: number, route: number, msg: Message): void;
+    /** Local playback path for one speaker's packet (after host forwarding). */
+    receivePacket(speaker: number, p: VoicePacket, now: number): void;
+    private playoutTick;
+    onPeerLeft(peerId: number): void;
+    close(): void;
+    /** For tests: expose the end-of-burst flag constant. */
+    static readonly END = 1;
+}