nixamp 0.28.44 → 0.29.1

package/src/live-voice.ts

@@ -1,306 +1,8 @@
-/** ElevenLabs Flash for live captions. The key stays on the account server. */
-import { createHash, randomBytes } from "node:crypto";
-import { SpeechError, decodeWav, encodeWav, quietSamples } from "./speech.ts";
-import { speakerTurns, type ScribeResult, type SpeakerTranscript } from "./speaker-turns.ts";
-import type { VoiceProfile } from "./voice-profile.ts";
-import { Guard } from "./guard.ts";
-import type { TranslationMeter } from "./translation-passes.ts";
-import type { Queryable } from "./follows.ts";
-import { voiceProviderFailure } from "./voice-provider.ts";
+/** ElevenLabs Flash/Scribe for live captions, from @profullstack/live-translate.
+ * nixamp keeps its `nxd_` grant tokens: captions.ts and older pages expect them. */
+import { LiveVoice as Base } from "@profullstack/live-translate";
+export { LIVE_VOICE_MODEL, LIVE_VOICE_RATE, LIVE_VOICE_LANGUAGES, type LiveVoiceChoice, type VoiceRequest } from "@profullstack/live-translate";
 
-export const LIVE_VOICE_MODEL = "eleven_flash_v2_5";
-export const LIVE_VOICE_RATE = 16_000;
-export const LIVE_VOICE_LANGUAGES = new Set("en ja zh de hi fr ko pt it es id nl tr fil pl sv bg ro ar cs el fi hr ms sk da ta uk ru hu no vi".split(" "));
-export interface LiveVoiceChoice { id: string; name: string; gender: string; language: string; }
-export interface VoiceRequest { text: string; language: string; voice?: string; profile?: VoiceProfile; channel?: string; speaker?: string; }
-const HEADERS = { "content-type": "audio/pcm", "cache-control": "no-store", "x-audio-sample-rate": String(LIVE_VOICE_RATE) };
-const budget = (value: number | undefined, fallback: number): number => Number.isFinite(value) && value! >= 0 ? Math.floor(value!) : fallback;
-
-export class LiveVoice {
-  private readonly key: string;
-  private readonly fetcher: typeof fetch;
-  private readonly now: () => number;
-  private catalog: Promise<LiveVoiceChoice[]> | null = null;
-  private catalogUntil = 0;
-  private readonly cache = new Map<string, { until: number; bytes: Uint8Array }>();
-  private readonly pending = new Map<string, Promise<Uint8Array>>();
-  private readonly usage = new Map<string, { minute: number; chars: number }>();
-  private readonly charsPerMinute: number;
-  private readonly requests: Guard;
-  private readonly grants = new Map<string, { by: string; channel: string; expires: number; remaining: number }>();
-  private readonly activeBy = new Map<string, number>();
-  private readonly db?: Queryable;
-  private readonly billing?: TranslationMeter;
-  private schema: Promise<unknown> | null = null;
-  private readonly dailyChars: number;
-  private cleanupAt = 0;
-  private readonly hearing = new Set<string>();
-  private readonly dailyAudioSeconds: number;
-  private readonly userDailyChars: number;
-  private readonly userDailyAudioSeconds: number;
-  private providerPause: { until: number; error: SpeechError } | null = null;
-
-  private checkProvider(): void {
-    if (this.providerPause && this.providerPause.until > this.now()) throw this.providerPause.error;
-  }
-
-  private async providerFailed(response: Response, operation: string): Promise<never> {
-    const failure = await voiceProviderFailure(response);
-    const until = this.now() + failure.cooldownMs;
-    // Another in-flight response must not shorten an existing billing pause.
-    if (!this.providerPause || this.providerPause.until < until) this.providerPause = { until, error: failure.error };
-    console.error(JSON.stringify({ event: "voice_provider_failure", provider: "elevenlabs", operation, status: response.status, code: failure.code, cooldownMs: failure.cooldownMs }));
-    throw failure.error;
-  }
-
-  constructor(options: { apiKey?: string; fetcher?: typeof fetch; now?: () => number; charsPerMinute?: number; dailyChars?: number; dailyAudioSeconds?: number; userDailyChars?: number; userDailyAudioSeconds?: number; db?: Queryable; billing?: TranslationMeter } = {}) {
-    this.key = options.apiKey ?? process.env["ELEVENLABS_API_KEY"] ?? "";
-    this.fetcher = options.fetcher ?? fetch;
-    this.now = options.now ?? Date.now;
-    this.charsPerMinute = budget(options.charsPerMinute, 3000);
-    this.dailyChars = budget(options.dailyChars, 200_000);
-    this.dailyAudioSeconds = budget(options.dailyAudioSeconds, 86_400);
-    this.userDailyChars = budget(options.userDailyChars, 120_000);
-    this.userDailyAudioSeconds = budget(options.userDailyAudioSeconds, 43_200);
-    this.requests = new Guard(this.now);
-    this.db = options.db;
-    this.billing = options.billing;
-  }
-
-  available(): boolean { return this.key !== ""; }
-
-  /** Optional diarization, billed only while a signed-in listener requests it.
-   * Rolling audio is bounded to 15 seconds, including overlap. Every second
-   * submitted (also repeated context) consumes the persistent provider budget. */
-  async hear(bytes: Uint8Array, by: string, signal?: AbortSignal, meter = this.billing, resource = ""): Promise<SpeakerTranscript> {
-    if (!this.available()) throw new SpeechError("speaker voices are unavailable", 503);
-    await meter?.require(by, resource);
-    this.checkProvider();
-    const wav = decodeWav(bytes);
-    const seconds = wav.samples.length / wav.rate;
-    if (wav.rate !== 16000 || wav.channels !== 1 || seconds < 0.2 || seconds > 15.1) throw new SpeechError("send up to 15 seconds of mono 16 kHz WAV", 400);
-    if (wav.samples.some(sample => !Number.isFinite(sample))) throw new SpeechError("invalid audio samples", 400);
-    if (!this.requests.check(`hear:${by}`, { allowed: 36, windowMs: 60_000 }).ok) throw new SpeechError("too many speaker transcription requests", 429);
-    if (quietSamples(wav.samples)) return { language: "", seconds, turns: [] };
-    if (this.hearing.has(by) || this.hearing.size >= 4) throw new SpeechError("speaker transcription is busy", 429);
-    this.hearing.add(by);
-    let reservation: string | undefined;
-    let accepted = false;
-    try {
-      const billed = Math.ceil(seconds);
-      await this.reserve(`scribe:user:${by}`, billed, 300, 60_000);
-      await this.reserve("scribe:server", billed, 600, 60_000);
-      await this.reserve(`scribe:user:${by}`, billed, this.userDailyAudioSeconds, 86_400_000);
-      await this.reserve("scribe:server", billed, this.dailyAudioSeconds, 86_400_000);
-      signal?.throwIfAborted();
-      this.checkProvider();
-      const form = new FormData();
-      // Canonical PCM prevents a crafted container from billing more audio
-      // than the duration we validated, and removes uploaded metadata.
-      form.set("file", new Blob([new Uint8Array(encodeWav(wav.samples))], { type: "audio/wav" }), "listening.wav");
-      form.set("model_id", "scribe_v2");
-      form.set("diarize", "true");
-      form.set("tag_audio_events", "false");
-      form.set("timestamps_granularity", "word");
-      // No language_code: preserve the source language, including Spanish.
-      reservation = await meter?.reserve(by, "transcription", wav.samples.length, resource);
-      const answer = await this.fetcher("https://api.elevenlabs.io/v1/speech-to-text", {
-        method: "POST", headers: { "xi-api-key": this.key }, body: form,
-        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
-      });
-      if (!answer.ok) await this.providerFailed(answer, "transcription");
-      accepted = true;
-      console.info(JSON.stringify({ event: "voice_provider_usage", provider: "elevenlabs", operation: "transcription", account: createHash("sha256").update(by).digest("hex").slice(0, 16), audioSeconds: seconds }));
-      if (reservation) await meter!.commit(reservation);
-      return speakerTurns(await answer.json() as ScribeResult, wav);
-    } catch (error) {
-      if (reservation && !accepted) await meter!.refund(reservation);
-      throw error;
-    } finally { this.hearing.delete(by); }
-  }
-
-  async voices(): Promise<LiveVoiceChoice[]> {
-    if (!this.available()) throw new SpeechError("translated audio needs ELEVENLABS_API_KEY on the account server", 503);
-    this.checkProvider();
-    if (!this.catalog || this.now() >= this.catalogUntil) {
-      this.catalogUntil = this.now() + 3600_000;
-      this.catalog = this.fetcher("https://api.elevenlabs.io/v2/voices?page_size=100&voice_type=default", {
-        headers: { "xi-api-key": this.key }, signal: AbortSignal.timeout(8000),
-      }).then(async response => {
-        if (!response.ok) await this.providerFailed(response, "voices");
-        const body = await response.json() as { voices: { voice_id: string; name: string; labels?: Record<string, string> }[] };
-        return body.voices.filter(voice => /^[a-zA-Z0-9_-]+$/.test(voice.voice_id)).map(voice => ({
-          id: voice.voice_id, name: voice.name, gender: voice.labels?.["gender"] ?? "neutral", language: voice.labels?.["language"] ?? "",
-        }));
-      }).catch(error => { this.catalog = null; throw error; });
-    }
-    return this.catalog;
-  }
-
-  /** A 90-second capability for one channel, never the viewer's account credential. */
-  async grant(by: string, channel: string): Promise<{ token: string; expires: number }> {
-    if (!/^[\w-]{1,80}$/.test(channel)) throw new SpeechError("choose a playback session or live channel", 400);
-    if (!this.requests.check(`grant:${by}`, { allowed: 10, windowMs: 60_000 }).ok) throw new SpeechError("too many audio authorization requests", 429);
-    await this.billing?.require(by, channel);
-    for (const [token, grant] of this.grants) if (grant.expires <= this.now()) this.grants.delete(token);
-    if (this.grants.size >= 5000) throw new SpeechError("audio authorization is busy", 503);
-    const token = `nxd_${randomBytes(32).toString("base64url")}`;
-    const expires = this.now() + 90_000;
-    if (this.db) {
-      await this.ensure();
-      await this.db.query("INSERT INTO live_voice_grants (token_hash, by_account, channel, expires_at, remaining) VALUES ($1, $2, $3, $4, 2000)", [createHash("sha256").update(token).digest("hex"), by, channel, new Date(expires)]);
-    } else this.grants.set(token, { by, channel, expires, remaining: 2000 });
-    return { token, expires };
-  }
-
-  async authorize(token: string, channel: string, chars: number): Promise<string> {
-    if (!/^nxd_[A-Za-z0-9_-]{43}$/.test(token)) throw new SpeechError("sign in to enable translated audio", 401);
-    if (!Number.isFinite(chars) || chars < 1 || chars > 600) throw new SpeechError("invalid caption length", 400);
-    if (this.db) {
-      await this.ensure();
-      const result = await this.db.query(`UPDATE live_voice_grants SET remaining = remaining - $3
-        WHERE token_hash = $1 AND channel = $2 AND expires_at > $4 AND remaining >= $3 RETURNING by_account`, [createHash("sha256").update(token).digest("hex"), channel, chars, new Date(this.now())]);
-      if (!result.rows.length) throw new SpeechError("audio authorization expired or reached its limit; enable translated audio again", 401);
-      return String(result.rows[0]?.["by_account"]);
-    }
-    const grant = this.grants.get(token);
-    if (!grant || grant.expires <= this.now() || grant.channel !== channel) throw new SpeechError("sign in to renew translated audio", 401);
-    if (grant.remaining < chars) throw new SpeechError("this audio authorization reached its character limit", 429);
-    grant.remaining -= chars;
-    return grant.by;
-  }
-
-  private async ensure(): Promise<void> {
-    if (!this.db) return;
-    this.schema ??= (async () => {
-      await this.db!.query("CREATE TABLE IF NOT EXISTS live_voice_usage (bucket TEXT PRIMARY KEY, chars BIGINT NOT NULL, expires_at TIMESTAMPTZ NOT NULL)");
-      await this.db!.query("CREATE TABLE IF NOT EXISTS live_voice_grants (token_hash TEXT PRIMARY KEY, by_account TEXT NOT NULL, channel TEXT NOT NULL, expires_at TIMESTAMPTZ NOT NULL, remaining INTEGER NOT NULL)");
-    })().catch(error => { this.schema = null; throw error; });
-    await this.schema;
-    if (this.now() >= this.cleanupAt) {
-      this.cleanupAt = this.now() + 60_000;
-      // Keep only live windows; accounting survives restarts and is shared by replicas.
-      await this.db.query("DELETE FROM live_voice_usage WHERE expires_at <= $1", [new Date(this.now())]);
-      await this.db.query("DELETE FROM live_voice_grants WHERE expires_at <= $1", [new Date(this.now())]);
-    }
-  }
-
-  private async reserve(bucket: string, chars: number, limit: number, windowMs: number): Promise<void> {
-    if (chars > limit) throw new SpeechError("translated audio reached its character budget; try again later", 429);
-    const window = Math.floor(this.now() / windowMs);
-    const key = `${bucket}:${windowMs}:${window}`;
-    if (this.db) {
-      await this.ensure();
-      const result = await this.db.query(`INSERT INTO live_voice_usage (bucket, chars, expires_at) VALUES ($1, $2, $4)
-        ON CONFLICT (bucket) DO UPDATE SET chars = live_voice_usage.chars + EXCLUDED.chars
-        WHERE live_voice_usage.chars + EXCLUDED.chars <= $3 RETURNING chars`, [key, chars, limit, new Date((window + 1) * windowMs)]);
-      if (!result.rows.length) throw new SpeechError("translated audio reached its character budget; try again later", 429);
-      return;
-    }
-    // Local/single-process installations without a database. Account servers pass their pool.
-    const record = this.usage.get(key) ?? { minute: (window + 1) * windowMs, chars: 0 };
-    if (record.chars + chars > limit) throw new SpeechError("translated audio reached its character budget; try again later", 429);
-    record.chars += chars; this.usage.set(key, record);
-  }
-
-  private async charge(by: string, channel: string, chars: number): Promise<void> {
-    for (const [key, record] of this.usage) if (record.minute <= this.now()) this.usage.delete(key);
-    await this.reserve(`user:${by}`, chars, this.charsPerMinute, 60_000);
-    await this.reserve(`channel:${channel}`, chars, 6000, 60_000);
-    await this.reserve("server", chars, 12_000, 60_000);
-    await this.reserve(`user:${by}`, chars, this.userDailyChars, 86400_000);
-    await this.reserve("server", chars, this.dailyChars, 86400_000);
-  }
-
-  private checkRequest(by: string): void {
-    if (!this.requests.check(`audio:${by}`, { allowed: 60, windowMs: 60_000 }).ok) throw new SpeechError("too many translated audio requests", 429);
-  }
-
-  /** Stream the first request immediately; concurrent listeners share its cached result. */
-  async stream(ask: VoiceRequest, by: string, signal?: AbortSignal, meter = this.billing): Promise<Response> {
-    this.checkRequest(by);
-    await meter?.require(by, ask.channel);
-    const text = typeof ask.text === "string" ? ask.text.trim() : "";
-    if (!text || text.length > 600) throw new SpeechError("translated audio needs a caption of 1–600 characters", 400);
-    if (!LIVE_VOICE_LANGUAGES.has(ask.language)) throw new SpeechError("this language is not supported by Flash voices", 400);
-    const voices = await this.voices();
-    signal?.throwIfAborted();
-    // The browser chooses unique voices for speakers. Legacy callers get a
-    // stable stock voice; pitch is not used to infer gender.
-    const seed = createHash("sha256").update(`${ask.channel ?? ""}|${ask.speaker ?? ""}`).digest().readUInt32BE(0);
-    const voice = ask.voice && ask.voice !== "auto"
-      ? voices.find(voice => voice.id === ask.voice)
-      : voices[seed % voices.length];
-    if (!voice) throw new SpeechError("choose an available voice", 400);
-    const id = createHash("sha256").update(JSON.stringify([LIVE_VOICE_MODEL, voice.id, ask.language, text])).digest("hex");
-    for (const [key, item] of this.cache) if (item.until < this.now()) this.cache.delete(key);
-    const cached = this.cache.get(id);
-    const pending = this.pending.get(id);
-    if (cached || pending) {
-      const bytes = cached?.bytes ?? await pending!;
-      signal?.throwIfAborted();
-      const paid = await meter?.reserve(by, "voice", text.length, ask.channel);
-      if (paid) await meter!.commit(paid);
-      return new Response(new Uint8Array(bytes), { headers: HEADERS });
-    }
-    if (this.pending.size >= 4) throw new SpeechError("translated audio is busy; waiting for the next caption", 429);
-    if ((this.activeBy.get(by) ?? 0) >= 2) throw new SpeechError("two voice requests are already active for this account", 429);
-    // Register before the first provider await, so identical requests cannot both bill.
-    let done!: (bytes: Uint8Array) => void;
-    let fail!: (error: unknown) => void;
-    const finished = new Promise<Uint8Array>((resolve, reject) => { done = resolve; fail = reject; });
-    this.pending.set(id, finished);
-    this.activeBy.set(by, (this.activeBy.get(by) ?? 0) + 1);
-    const release = (): void => { this.pending.delete(id); this.activeBy.set(by, Math.max(0, (this.activeBy.get(by) ?? 1) - 1)); if (!this.activeBy.get(by)) this.activeBy.delete(by); };
-    void finished.catch(() => undefined);
-    let reservation: string | undefined;
-    let accepted = false;
-    try {
-      await this.charge(by, ask.channel ?? "direct", text.length);
-      this.checkProvider();
-      signal?.throwIfAborted();
-      reservation = await meter?.reserve(by, "voice", text.length, ask.channel);
-      const response = await this.fetcher(`https://api.elevenlabs.io/v1/text-to-speech/${voice.id}/stream?output_format=pcm_16000`, {
-        method: "POST",
-        headers: { "xi-api-key": this.key, "content-type": "application/json" },
-        body: JSON.stringify({ text, model_id: LIVE_VOICE_MODEL, language_code: ask.language }),
-        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
-      });
-      if (!response.ok) await this.providerFailed(response, "synthesis");
-      if (!response.body) throw new SpeechError("ElevenLabs returned no audio", 502);
-      // Once the provider accepts, aborting playback cannot refund heard audio.
-      accepted = true;
-      console.info(JSON.stringify({ event: "voice_provider_usage", provider: "elevenlabs", operation: "synthesis", account: createHash("sha256").update(by).digest("hex").slice(0, 16), characters: text.length }));
-      if (reservation) await meter!.commit(reservation);
-      const [play, keep] = response.body.tee();
-      void (async () => {
-        const reader = keep.getReader();
-        const chunks: Uint8Array[] = [];
-        let size = 0;
-        try {
-          while (true) {
-            const { done: ended, value } = await reader.read();
-            if (ended) break;
-            size += value.length;
-            if (size > 2 * 1024 * 1024) { await reader.cancel(); throw new SpeechError("voice response was too long", 502); }
-            chunks.push(value);
-          }
-          if (!size || size % 2) throw new SpeechError("voice response contained incomplete audio", 502);
-          const bytes = new Uint8Array(size);
-          let at = 0;
-          for (const chunk of chunks) { bytes.set(chunk, at); at += chunk.length; }
-          this.cache.set(id, { until: this.now() + 60_000, bytes });
-          // At most a few MB for recent lines, never a recording archive.
-          while (this.cache.size > 32) this.cache.delete(this.cache.keys().next().value as string);
-          done(bytes);
-        } catch (error) { fail(error); }
-        finally { reader.releaseLock(); release(); }
-      })();
-      return new Response(play, { headers: HEADERS });
-    } catch (error) {
-      fail(error); release();
-      if (reservation && !accepted) await meter!.refund(reservation);
-      throw error;
-    }
-  }
+export class LiveVoice extends Base {
+  constructor(options: ConstructorParameters<typeof Base>[0] = {}) { super({ tokenPrefix: "nxd_", ...options }); }
 }

package/src/owner.ts

@@ -130,6 +130,9 @@ export function needsAdmin(path: string, method = "GET"): boolean {
   // Going live with a file on this server is the same act as going live
   // with a catalog entry, and the same question.
   if (/^\/api\/tracks\/\d+\/live$/.test(path)) return true;
+  // And so is a folder: without this the gate never ran for it, and a
+  // listen link alone could put any folder on the air, uncapped.
+  if (path === "/api/folders/live") return true;
   return false;
 }
 

package/src/pcm-wav.ts

@@ -1,26 +1 @@
-/** 16-bit mono PCM WAV bytes from samples in [-1, 1]. */
-export function encodeWav(samples: Float32Array, rate = 16000): Uint8Array {
-  const bytes = new Uint8Array(44 + samples.length * 2);
-  const view = new DataView(bytes.buffer);
-  const ascii = (at: number, text: string): void => {
-    for (let i = 0; i < text.length; i++) bytes[at + i] = text.charCodeAt(i);
-  };
-  ascii(0, "RIFF");
-  view.setUint32(4, 36 + samples.length * 2, true);
-  ascii(8, "WAVE");
-  ascii(12, "fmt ");
-  view.setUint32(16, 16, true);
-  view.setUint16(20, 1, true);
-  view.setUint16(22, 1, true);
-  view.setUint32(24, rate, true);
-  view.setUint32(28, rate * 2, true);
-  view.setUint16(32, 2, true);
-  view.setUint16(34, 16, true);
-  ascii(36, "data");
-  view.setUint32(40, samples.length * 2, true);
-  for (let i = 0; i < samples.length; i++) {
-    const clipped = Math.max(-1, Math.min(1, samples[i] as number));
-    view.setInt16(44 + i * 2, clipped < 0 ? clipped * 32768 : clipped * 32767, true);
-  }
-  return bytes;
-}
+export { encodeWav } from "@profullstack/live-translate/core";

package/src/playlist-input.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { protocolArgs } from "./decoder-policy.ts";
 import type { Readable } from "node:stream";
 import { codecsOf } from "./audio.ts";
 
@@ -11,24 +12,72 @@ export interface PlaylistInput {
   video: boolean;
   width?: number;
   height?: number;
+  /**
+   * Back to the top when the end is reached, instead of finishing: a
+   * station, which plays until somebody stops it.
+   */
+  repeat?: boolean;
+  /**
+   * The order to play a list of this length in, asked at the top of every
+   * pass: a station-wide shuffle is one order for everybody listening, drawn
+   * again each time round. Unset is the list's own order.
+   */
+  order?: (length: number) => number[];
+  /** Read at every entry boundary, so an edit to the list lands on the next track. */
+  current?: () => string[];
+  /** Entries already known not to play, passed over without being tried. */
+  excluded?: (file: string) => boolean;
+  /**
+   * Pass over an entry that will not play, instead of failing the stream.
+   * For a station, where the next track is what a listener should hear. A
+   * folder live leaves it unset: there a missing entry is usually a file
+   * still arriving, and the channel redials and waits for it.
+   */
+  passOver?: boolean;
+  /** Told when an entry is passed over because it would not play. */
+  onFailure?: (event: { at: number; file: string; reason: string }) => void;
 }
 
+/**
+ * How many entries in a row may fail before the list is given up on. A
+ * corrupt file is skipped; a list where nothing plays is an error, said once,
+ * not a loop.
+ */
+export const MAX_FAILURES_IN_A_ROW = 5;
+
 /** Decode each file independently; feed one persistent muxer a fixed stream
  * profile and continuous timestamps. A concat demuxer cannot decode a list
  * whose input codecs differ. Only one entry is encoded at a time, with pipe
  * backpressure bounding read-ahead independently of the directory's size. */
 export class PlaylistInputStream {
-  private entries: { at: number; start: number; position: number }[] = [];
+  private entries: { at: number; file: string; start: number; position: number }[] = [];
   error: Error | null = null;
   complete = false;
   constructor(private readonly options: PlaylistInput) {}
 
+  /** Every entry that has started, in the order it started, with where it sits in the stream. */
+  get history(): ReadonlyArray<{ at: number; file: string; start: number; position: number }> {
+    return this.entries;
+  }
+
   place(seconds: number): { at: number; position: number } {
     const entry = this.entries.findLast(one => seconds >= one.start) ?? this.entries[0];
     return entry ? { at: entry.at, position: Math.max(0, seconds - entry.start + entry.position) }
       : { at: this.options.at, position: this.options.position };
   }
 
+  /** The decoder for the entry that is on, so skip() can end it early. */
+  private stopCurrent: (() => void) | null = null;
+  private skipping = false;
+
+  /** End the entry that is on and go to the next. False when nothing is on. */
+  skip(): boolean {
+    if (!this.stopCurrent) return false;
+    this.skipping = true;
+    this.stopCurrent();
+    return true;
+  }
+
   async *open(signal: AbortSignal): AsyncGenerator<Buffer> {
     const o = this.options;
     const [command, ...prefix] = o.ffmpeg as [string, ...string[]];
@@ -36,59 +85,132 @@ export class PlaylistInputStream {
     const width = Math.max(2, Math.floor((o.width || 1280) * ratio / 2) * 2);
     const height = Math.max(2, Math.floor((o.height || 720) * ratio / 2) * 2);
     let offset = 0;
+    let failuresInARow = 0;
+    let first = true;
     try {
-      for (let at = o.at; at < o.files.length && !signal.aborted; at++) {
-        const file = o.files[at]!;
-        const codecs = await codecsOf({ ffmpeg: o.ffmpeg, ffprobe: o.ffprobe, play: null }, file, [], AbortSignal.any([signal, AbortSignal.timeout(10_000)]));
-        if (signal.aborted) return;
-        if (!codecs.audio && !codecs.video) throw new Error(`Cannot decode playlist entry ${at + 1}`);
-        const position = at === o.at ? o.position : 0;
-        const duration = (codecs.duration ?? 0) - position;
-        if (duration <= 0) throw new Error(`No playable duration for playlist entry ${at + 1}`);
-        this.entries.push({ at, start: offset, position });
-        const hasVideo = Boolean(codecs.video);
-        const extra = o.video && !hasVideo
-          ? ["-f", "lavfi", "-i", `color=c=black:s=${width}x${height}:r=30`]
-          : o.video && !codecs.audio ? ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"] : [];
-        const args = [
-          ...prefix, "-hide_banner", "-loglevel", "error", "-nostdin", "-filter_threads", "2",
-          "-threads", "2", ...(position > 0 ? ["-ss", String(position)] : []), "-i", file,
-          ...extra, "-t", String(duration),
-          ...(o.video ? [
-            "-map", hasVideo ? "0:v:0" : "1:v:0", "-map", codecs.audio ? "0:a:0" : "1:a:0",
-            "-vf", `fps=30,scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1,setpts=PTS-STARTPTS`,
-            "-c:v", "libx264", "-threads", "2", "-preset", "veryfast", "-tune", "zerolatency",
-            "-crf", "23", "-pix_fmt", "yuv420p", "-g", "60", "-keyint_min", "60", "-sc_threshold", "0",
-          ] : ["-map", "0:a:0", "-vn"]),
-          "-af", "aresample=48000,asetpts=PTS-STARTPTS", "-c:a", "aac", "-b:a", "160k", "-ac", "2",
-          "-mpegts_flags", "+initial_discontinuity", "-output_ts_offset", String(offset), "-mpegts_copyts", "1", "-muxdelay", "0", "-muxpreload", "0",
-          "-f", "mpegts", "pipe:1",
-        ];
-        const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
-        let tail = "";
-        child.stderr.on("data", chunk => { tail = (tail + chunk.toString()).slice(-1500); });
-        const closed = new Promise<number | null>((resolve) => {
-          child.once("error", error => { tail = error.message; resolve(-1); });
-          child.once("close", code => resolve(code));
-        });
-        const abort = (): void => { child.kill("SIGKILL"); };
-        signal.addEventListener("abort", abort, { once: true });
-        try {
-          for await (const chunk of child.stdout as Readable) {
+      const orderFor = (list: string[]): number[] =>
+        o.order ? o.order(list.length).filter((one) => one >= 0 && one < list.length) : list.map((_, index) => index);
+      let files = o.current?.() ?? o.files;
+      if (files.length === 0) throw new Error("The playlist is empty");
+      let order = orderFor(files);
+      let step = Math.min(o.at, order.length);
+      let played = 0;
+      let last = "";
+      for (;;) {
+        if (signal.aborted) break;
+        // Asked at every boundary, so an edit lands on the next track. The
+        // list goes on after the file that just played, where the new list
+        // has it; a shuffled list draws a new order.
+        if (o.current) {
+          const fresh = o.current();
+          if (fresh.length !== files.length || fresh.some((one, index) => one !== files[index])) {
+            if (fresh.length === 0) throw new Error("The playlist is empty");
+            files = fresh;
+            order = orderFor(files);
+            const where = last ? files.indexOf(last) : -1;
+            step = o.order ? 0 : where >= 0 ? where + 1 : Math.min(step, files.length);
+          }
+        }
+        if (step >= order.length) {
+          if (!o.repeat) break;
+          // A pass where everything was passed over is a list with nothing
+          // to play, and repeating it would be the loop this exists to avoid.
+          if (played === 0) throw new Error("Nothing in this playlist would play");
+          played = 0;
+          order = orderFor(files);
+          step = 0;
+          continue;
+        }
+        {
+          const at = order[step]!;
+          step += 1;
+          const file = files[at]!;
+          last = file;
+          if (o.excluded?.(file)) continue;
+          const position = first && step - 1 === o.at ? o.position : 0;
+          first = false;
+          let reached = 0;
+          try {
+            const codecs = await codecsOf({ ffmpeg: o.ffmpeg, ffprobe: o.ffprobe, play: null }, file, [], AbortSignal.any([signal, AbortSignal.timeout(10_000)]));
             if (signal.aborted) return;
-            yield chunk as Buffer;
+            if (!codecs.audio && !codecs.video) throw new Error(`Cannot decode playlist entry ${at + 1}`);
+            const duration = (codecs.duration ?? 0) - position;
+            if (duration <= 0) throw new Error(`No playable duration for playlist entry ${at + 1}`);
+            this.entries.push({ at, file, start: offset, position });
+            const hasVideo = Boolean(codecs.video);
+            const extra = o.video && !hasVideo
+              ? ["-f", "lavfi", "-i", `color=c=black:s=${width}x${height}:r=30`]
+              : o.video && !codecs.audio ? ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"] : [];
+            const args = [
+              ...prefix, "-hide_banner", "-loglevel", "error", "-nostdin", "-filter_threads", "2",
+              // How far this entry got, so an entry cut short -- skipped, or
+              // broken halfway -- moves the clock by what was played and the
+              // next one starts where this one stopped, not after a gap.
+              "-progress", "pipe:3", "-stats_period", "0.5",
+              "-threads", "2", ...(position > 0 ? ["-ss", String(position)] : []), ...protocolArgs(file), "-i", file,
+              ...extra, "-t", String(duration),
+              ...(o.video ? [
+                "-map", hasVideo ? "0:v:0" : "1:v:0", "-map", codecs.audio ? "0:a:0" : "1:a:0",
+                "-vf", `fps=30,scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1,setpts=PTS-STARTPTS`,
+                "-c:v", "libx264", "-threads", "2", "-preset", "veryfast", "-tune", "zerolatency",
+                "-crf", "23", "-pix_fmt", "yuv420p", "-g", "60", "-keyint_min", "60", "-sc_threshold", "0",
+              ] : ["-map", "0:a:0", "-vn"]),
+              "-af", "aresample=48000,asetpts=PTS-STARTPTS", "-c:a", "aac", "-b:a", "160k", "-ac", "2",
+              "-mpegts_flags", "+initial_discontinuity", "-output_ts_offset", String(offset), "-mpegts_copyts", "1", "-muxdelay", "0", "-muxpreload", "0",
+              "-f", "mpegts", "pipe:1",
+            ];
+            const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe", "pipe"] });
+            let tail = "";
+            child.stderr!.on("data", chunk => { tail = (tail + chunk.toString()).slice(-1500); });
+            (child.stdio[3] as Readable | null)?.on("data", (chunk: Buffer) => {
+              const found = /out_time_us=(\d+)/g;
+              let match: RegExpExecArray | null;
+              while ((match = found.exec(chunk.toString())) !== null) reached = Math.max(reached, Number(match[1]) / 1e6);
+            });
+            const closed = new Promise<number | null>((resolve) => {
+              child.once("error", error => { tail = error.message; resolve(-1); });
+              child.once("close", code => resolve(code));
+            });
+            const abort = (): void => { child.kill("SIGKILL"); };
+            signal.addEventListener("abort", abort, { once: true });
+            this.stopCurrent = abort;
+            let skipped = false;
+            try {
+              for await (const chunk of child.stdout as Readable) {
+                if (signal.aborted) return;
+                yield chunk as Buffer;
+              }
+              const code = await closed;
+              if (signal.aborted) return;
+              skipped = this.skipping;
+              if (code !== 0 && !skipped) throw new Error(`Playlist entry ${at + 1} failed: ${tail.trim()}`);
+            } finally {
+              this.stopCurrent = null;
+              this.skipping = false;
+              signal.removeEventListener("abort", abort);
+              abort();
+              await closed;
+            }
+            failuresInARow = 0;
+            played += 1;
+            // Match the frame grid used above so rounding cannot accumulate a
+            // backwards timestamp over hundreds of short files.
+            const length = skipped ? Math.min(duration, reached) : duration;
+            offset += o.video ? Math.ceil(length * 30) / 30 : length;
+          } catch (error) {
+            if (signal.aborted || !o.passOver) throw error;
+            // Passed over, not dialled again: the next entry is what a
+            // listener should hear, and a file that will not decode now will
+            // not decode in two seconds either.
+            const reason = error instanceof Error ? error.message : String(error);
+            o.onFailure?.({ at, file, reason });
+            if (reached > 0) offset += o.video ? Math.ceil(reached * 30) / 30 : reached;
+            failuresInARow += 1;
+            if (failuresInARow >= Math.min(MAX_FAILURES_IN_A_ROW, Math.max(1, files.length))) {
+              throw new Error(`Nothing in this playlist would play: ${reason}`);
+            }
           }
-          const code = await closed;
-          if (signal.aborted) return;
-          if (code !== 0) throw new Error(`Playlist entry ${at + 1} failed: ${tail.trim()}`);
-        } finally {
-          signal.removeEventListener("abort", abort);
-          abort();
-          await closed;
         }
-        // Match the frame grid used above so rounding cannot accumulate a
-        // backwards timestamp over hundreds of short files.
-        offset += o.video ? Math.ceil(duration * 30) / 30 : duration;
       }
       this.complete = !signal.aborted;
     } catch (error) {