@crievo/omni 0.0.0-stage → 0.1.1

package/tools/voice-envelope.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Voice envelope for the VoiceAvatar component (templates/components/voiceavatar).
+
+     node tools/voice-envelope.mjs voice.wav [more.wav …] --out env.js
+     node tools/voice-envelope.mjs --scene videos/<slug> <sceneId> [--out env.js]
+
+   Writes { fps: 60, duration, low, mid, high, all }: four per-frame arrays, 0..1.
+   It emulates what the live orb reads from a browser AnalyserNode
+   (sampleRate 48 kHz, fftSize 256, Blackman window, smoothingTimeConstant 0.8,
+   -100…-30 dB mapped to a byte) and averages the same bands: low 0–200 Hz,
+   mid 200–2000 Hz, high 2–20 kHz, all = whole spectrum. Doing it here, once,
+   makes the render deterministic: the scene never decodes audio.
+
+   Several WAVs are laid end to end; in --scene mode each line of the scene
+   goes at its `start` (scenes.json), so the envelope is on the scene's clock.
+
+   --out file.json writes JSON; --out file.js writes `window.VOICE_ENVELOPE = …`
+   (what a scene loads with <script src>); no --out prints JSON to stdout.
+   Requires ffmpeg.
+   ============================================================================ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const SR = 48000;
+const FPS = 60;
+const FFT = 256;
+const BINS = FFT / 2;
+const SMOOTH = 0.8;
+const MIN_DB = -100;
+const MAX_DB = -30;
+const STEP = SR / FPS; /* 800 samples per frame */
+
+/* --- arguments ------------------------------------------------------------- */
+const argv = process.argv.slice(2);
+const flag = n => {
+  const i = argv.indexOf(`--${n}`);
+  return i < 0 ? null : argv[i + 1];
+};
+const sceneDir = flag("scene");
+const out = flag("out");
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i].startsWith("--")) {
+    i++;
+    continue;
+  }
+  positional.push(argv[i]);
+}
+
+const fail = msg => {
+  console.error(`erro: ${msg}`);
+  process.exit(1);
+};
+
+/* --- decode: any audio → mono float32 at 48 kHz ------------------------------ */
+function decode(file) {
+  const r = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-f", "f32le", "-ac", "1", "-ar", String(SR), "-"], {
+    maxBuffer: 1 << 30,
+  });
+  if (r.status !== 0) fail(`ffmpeg não leu ${file}: ${r.stderr}`);
+  const b = r.stdout;
+  return new Float32Array(b.buffer, b.byteOffset, Math.floor(b.byteLength / 4));
+}
+
+/* --- the signal: the files placed on one timeline --------------------------- */
+const parts = []; /* { start (s), samples } */
+if (sceneDir) {
+  const dir = resolve(sceneDir);
+  const video = JSON.parse(readFileSync(join(dir, "scenes.json"), "utf8"));
+  const scene = video.scenes.find(s => s.id === positional[0]);
+  if (!scene) fail(`cena "${positional[0]}" não existe em ${dir}/scenes.json`);
+  for (const l of scene.lines ?? []) {
+    if (!l.wav || l.start == null) continue;
+    parts.push({ start: l.start, samples: decode(join(dir, l.wav)) });
+  }
+  if (!parts.length) fail(`a cena ${scene.id} não tem fala com áudio e posição (rode a etapa de voz)`);
+} else {
+  if (!positional.length) {
+    console.error("uso: node voice-envelope.mjs <audio…> [--out env.js]");
+    console.error("     node voice-envelope.mjs --scene videos/<slug> <sceneId> [--out env.js]");
+    process.exit(1);
+  }
+  let at = 0;
+  for (const f of positional) {
+    const samples = decode(f);
+    parts.push({ start: at, samples });
+    at += samples.length / SR;
+  }
+}
+const total = Math.max(...parts.map(p => Math.round(p.start * SR) + p.samples.length));
+const signal = new Float32Array(total);
+for (const p of parts) {
+  const o = Math.round(p.start * SR);
+  for (let i = 0; i < p.samples.length; i++) signal[o + i] += p.samples[i];
+}
+
+/* --- analyser emulation ------------------------------------------------------ */
+const window_ = Float32Array.from({ length: FFT }, (_, n) => {
+  const a = 0.16;
+  return (1 - a) / 2 - 0.5 * Math.cos((2 * Math.PI * n) / FFT) + (a / 2) * Math.cos((4 * Math.PI * n) / FFT);
+});
+
+/* iterative radix-2 FFT, in place */
+function fft(re, im) {
+  const n = re.length;
+  for (let i = 1, j = 0; i < n; i++) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = (-2 * Math.PI) / len;
+    const wr = Math.cos(ang);
+    const wi = Math.sin(ang);
+    for (let i = 0; i < n; i += len) {
+      let cr = 1;
+      let ci = 0;
+      for (let k = 0; k < len / 2; k++) {
+        const a = i + k;
+        const b = a + len / 2;
+        const tr = re[b] * cr - im[b] * ci;
+        const ti = re[b] * ci + im[b] * cr;
+        re[b] = re[a] - tr;
+        im[b] = im[a] - ti;
+        re[a] += tr;
+        im[a] += ti;
+        const nr = cr * wr - ci * wi;
+        ci = cr * wi + ci * wr;
+        cr = nr;
+      }
+    }
+  }
+}
+
+/* the same index math as the orb: [round(f / (sr/2) * bins)] inclusive */
+const range = (lo, hi) => [Math.round((lo / (SR / 2)) * BINS), Math.round((hi / (SR / 2)) * BINS)];
+const BANDS = { low: range(0, 200), mid: range(200, 2000), high: range(2000, 20000), all: [0, BINS - 1] };
+
+const frames = Math.ceil(total / STEP);
+const result = { fps: FPS, duration: +(total / SR).toFixed(3), low: [], mid: [], high: [], all: [] };
+const smoothed = new Float32Array(BINS);
+const re = new Float32Array(FFT);
+const im = new Float32Array(FFT);
+const bytes = new Float32Array(BINS);
+
+for (let f = 0; f < frames; f++) {
+  const end = Math.min((f + 1) * STEP, total);
+  for (let i = 0; i < FFT; i++) {
+    const s = end - FFT + i;
+    re[i] = (s >= 0 ? signal[s] : 0) * window_[i];
+    im[i] = 0;
+  }
+  fft(re, im);
+  for (let k = 0; k < BINS; k++) {
+    const mag = Math.hypot(re[k], im[k]) / FFT;
+    smoothed[k] = SMOOTH * smoothed[k] + (1 - SMOOTH) * mag;
+    const db = 20 * Math.log10(Math.max(smoothed[k], 1e-12));
+    bytes[k] = Math.min(255, Math.max(0, Math.floor((255 / (MAX_DB - MIN_DB)) * (db - MIN_DB))));
+  }
+  for (const [name, [lo, hi]] of Object.entries(BANDS)) {
+    let sum = 0;
+    for (let k = lo; k <= hi; k++) sum += bytes[k];
+    result[name].push(+(sum / (hi - lo + 1) / 255).toFixed(3));
+  }
+}
+
+/* --- output ------------------------------------------------------------------ */
+const json = JSON.stringify(result);
+if (!out) {
+  process.stdout.write(`${json}\n`);
+} else {
+  mkdirSync(dirname(resolve(out)), { recursive: true });
+  writeFileSync(out, out.endsWith(".js") ? `window.VOICE_ENVELOPE = ${json};\n` : `${json}\n`);
+  const peak = k => Math.max(...result[k]).toFixed(2);
+  console.error(
+    `envelope: ${frames} frames (${result.duration}s) → ${out}  pico low ${peak("low")} mid ${peak("mid")} high ${peak("high")} all ${peak("all")}`,
+  );
+}

package/tools/voice.py

@@ -0,0 +1,448 @@
+"""omnivideo voice providers: Fish Audio, Cartesia, VoiceStudio and ElevenLabs.
+
+The order comes from `voice.order` in the config: the first is the default, the
+others are fallbacks, in that order. A video picks its own in `voice.provider`
+of scenes.json (the studio screen writes there); the rest of the order stays
+as fallback.
+
+Voice profile: `voice.profiles` in the config keeps, by name, the Fish voice_id,
+the Cartesia one and the ElevenLabs one, the VoiceStudio profile name and the
+`order` to try them in (the first is preferred, the others are fallbacks). The
+video picks its own in `voice.voice_profile` of scenes.json; without a choice,
+`voice.default_profile` applies; with no profile at all, each provider's
+`voice_id` and the global `voice.order`.
+
+Each provider can tell whether it is ready (key, voice, service up), generate a
+line as WAV and compute the line hash with its settings. The hash is what tells
+whether the line must be generated again.
+
+Keys: environment variable or `.env` at the omnivideo root (outside git), named
+in `voice.<provider>.key_env`.
+"""
+
+import hashlib
+import io
+import json
+import os
+import re
+import threading
+import wave
+
+from omni_paths import DATA_ROOT as ROOT
+
+CFG = json.loads((ROOT / "omnivideo.config.json").read_text())
+NAMES = {"fish": "Fish Audio", "cartesia": "Cartesia", "voicestudio": "VoiceStudio", "elevenlabs": "ElevenLabs"}
+
+
+class Failed(Exception):
+    """The provider did not generate this line. `disable` = no point trying the
+    next lines with it in this run (no key, no credit, service down)."""
+
+    def __init__(self, msg, disable=True, rate_limited=False):
+        super().__init__(msg)
+        self.disable = disable
+        # 429: the provider is up, just too many lines at once (the voice runs in
+        # parallel): wait and try the same provider again, don't drop it
+        self.rate_limited = rate_limited
+
+
+def _env():
+    vals = {}
+    path = ROOT / ".env"
+    if path.exists():
+        for row in path.read_text().splitlines():
+            row = row.strip()
+            if row and not row.startswith("#") and "=" in row:
+                k, v = row.split("=", 1)
+                vals[k.strip()] = v.strip().strip('"').strip("'")
+    vals.update({k: v for k, v in os.environ.items() if v})
+    return vals
+
+
+def spoken_text(line):
+    """The text sent to the voice provider. `text` is also the caption and does not
+    change; here the pronunciation map of `voice.pronunciation` in the config
+    applies (term → how it is said), for every provider and every video. A term
+    that does not occur leaves the text as is: old lines keep the same hash."""
+    text = line["text"]
+    for term, said_as in (CFG["voice"].get("pronunciation") or {}).items():
+        if term and not term.startswith("_"):
+            text = re.sub(rf"(?<![\w.]){re.escape(term)}(?!\w|\.\d)", said_as, text, flags=re.IGNORECASE)
+    return text
+
+
+def _digest(line, extra):
+    key = json.dumps([spoken_text(line), line.get("instruct", ""), extra], ensure_ascii=False, sort_keys=True)
+    return hashlib.sha1(key.encode()).hexdigest()[:12]
+
+
+def _speed(data, cfg):
+    return float({**cfg, **(data.get("voice") or {})}.get("speed", 1.0))
+
+
+def voice_profile(data):
+    """The video's voice profile (`voice.voice_profile` in scenes.json, the id of a
+    `voice.profiles` item) or, without a choice, the config's `voice.default_profile`.
+    Returns `(profile, reason)`: with no profile registered, each provider's
+    `voice_id` applies (`(None, None)`); a chosen profile that no longer exists
+    is a reason, not a silent voice swap."""
+    cfg = CFG["voice"]
+    profiles = cfg.get("profiles") or []
+    requested = (data.get("voice") or {}).get("voice_profile")
+    if requested:
+        found = next((p for p in profiles if p.get("id") == requested), None)
+        if found:
+            return found, None
+        return None, f"o perfil de voz “{requested}” não existe mais (voice.profiles na config)"
+    default = cfg.get("default_profile")
+    found = next((p for p in profiles if p.get("id") == default), None) if default else None
+    return found, None
+
+
+def _voice_id(cfg, data, provider):
+    """The provider's voice_id for this video: the profile's, or the config's without
+    a profile. A profile without this provider's id does not fall back to the
+    config's (it would be another voice): the provider is left out and the line
+    moves on to the next."""
+    profile, reason = voice_profile(data)
+    if reason:
+        return None, reason
+    if profile is None:
+        return cfg.get("voice_id"), None
+    voice = profile.get(provider)
+    if not voice:
+        return None, f"o perfil “{profile.get('name', profile.get('id'))}” não tem voz na {NAMES[provider]}"
+    return voice, None
+
+
+def _http_error(name, resp):
+    body = resp.text[:300].replace("\n", " ")
+    if resp.status_code == 429:
+        return Failed(f"{name} respondeu 429 (muitas falas ao mesmo tempo): {body}", disable=False, rate_limited=True)
+    # 401/402/403: key or credit; 5xx: service. Either way, the rest of the
+    # lines in this run go to the next provider: consistent voice
+    return Failed(f"{name} respondeu {resp.status_code}: {body}", disable=True)
+
+
+def is_free(model):
+    """`s2.1-pro-free` is the same model as `s2.1-pro`, without charging the API balance."""
+    return str(model or "").endswith("-free")
+
+
+class Fish:
+    """`voice.fish.model` is tried first (the free one, by default) and
+    `voice.fish.fallback_model` next (the paid one, charged to the API balance).
+    A model that fails on key, quota or service is dropped for the rest of the run."""
+
+    id = "fish"
+
+    def __init__(self, requests, data):
+        self.r = requests
+        self.cfg = CFG["voice"]["fish"]
+        self.speed = _speed(data, self.cfg)
+        self.key = _env().get(self.cfg["key_env"])
+        self.voice_id, self._no_voice = _voice_id(self.cfg, data, "fish")
+        # the model that generated the line, per thread (the lines run in parallel):
+        # the usage log only charges the paid one
+        self._local = threading.local()
+        self.disabled = set()
+
+    @property
+    def model(self):
+        return getattr(self._local, "model", None)
+
+    def ready(self):
+        if not self.key:
+            return f"sem chave ({self.cfg['key_env']} no ambiente ou no .env)"
+        if self._no_voice:
+            return self._no_voice
+        if not self.voice_id:
+            return "sem voice_id (o reference_id do modelo de voz clonado, em voice.fish.voice_id)"
+        return None
+
+    def config_hash(self):
+        # free and paid give the same voice: swapping one for the other does not redo the lines
+        model = self.cfg["model"].removesuffix("-free")
+        # hash-compat: do not translate
+        return {"provider": "fish", "voz": self.voice_id, "modelo": model, "speed": self.speed}
+
+    def generate(self, line):
+        models = [
+            m
+            for m in dict.fromkeys((self.cfg["model"], self.cfg.get("fallback_model")))
+            if m and m not in self.disabled
+        ]
+        if not models:
+            raise Failed("Fish Audio: nenhum modelo disponível nesta execução")
+        for i, model in enumerate(models):
+            try:
+                audio = self._tts(line, model)
+                self._local.model = model
+                return audio
+            except Failed as exc:
+                # too many at once is not a reason to go to the paid model: the caller waits and retries
+                if exc.rate_limited:
+                    raise
+                if exc.disable:
+                    self.disabled.add(model)
+                if i == len(models) - 1:
+                    raise
+                print(f"⚠ {line['id']}: {exc} → tentando o {models[i + 1]}")
+
+    def _tts(self, line, model):
+        body = {
+            "text": spoken_text(line),
+            "reference_id": self.voice_id,
+            "format": "wav",
+            "sample_rate": 44100,
+            "latency": "normal",
+            "prosody": {"speed": self.speed, "volume": 0},
+        }
+        try:
+            resp = self.r.post(
+                "https://api.fish.audio/v1/tts",
+                json=body,
+                timeout=self.cfg["timeout_s"],
+                headers={"Authorization": f"Bearer {self.key}", "model": model},
+            )
+        except self.r.RequestException as exc:
+            raise Failed(f"Fish Audio ({model}): {exc}")
+        if resp.status_code != 200:
+            raise _http_error(f"Fish Audio ({model})", resp)
+        return resp.content
+
+
+class Cartesia:
+    id = "cartesia"
+
+    def __init__(self, requests, data):
+        self.r = requests
+        self.cfg = CFG["voice"]["cartesia"]
+        # Cartesia accepts 0.6 to 1.5
+        self.speed = min(1.5, max(0.6, _speed(data, self.cfg)))
+        self.key = _env().get(self.cfg["key_env"])
+        self.voice_id, self._no_voice = _voice_id(self.cfg, data, "cartesia")
+
+    def ready(self):
+        if not self.key:
+            return f"sem chave ({self.cfg['key_env']} no ambiente ou no .env)"
+        if self._no_voice:
+            return self._no_voice
+        if not self.voice_id:
+            return "sem voice_id (o id da voz clonada, em voice.cartesia.voice_id)"
+        return None
+
+    def config_hash(self):
+        # hash-compat: do not translate
+        return {
+            "provider": "cartesia",
+            "voz": self.voice_id,
+            "modelo": self.cfg["model"],
+            "idioma": self.cfg["language"],
+            "speed": self.speed,
+        }
+
+    def generate(self, line):
+        body = {
+            "model_id": self.cfg["model"],
+            "transcript": spoken_text(line),
+            "voice": {"mode": "id", "id": self.voice_id},
+            "language": self.cfg["language"],
+            "generation_config": {"speed": self.speed},
+            "output_format": {"container": "wav", "encoding": "pcm_s16le", "sample_rate": 44100},
+        }
+        try:
+            resp = self.r.post(
+                "https://api.cartesia.ai/tts/bytes",
+                json=body,
+                timeout=self.cfg["timeout_s"],
+                headers={"Authorization": f"Bearer {self.key}", "Cartesia-Version": self.cfg["api_version"]},
+            )
+        except self.r.RequestException as exc:
+            raise Failed(f"Cartesia: {exc}")
+        if resp.status_code != 200:
+            raise _http_error("Cartesia", resp)
+        return resp.content
+
+
+class ElevenLabs:
+    """ElevenLabs TTS. The response is 16-bit PCM, mono, 44.1 kHz (no header): it
+    becomes WAV here, the same format as the other providers. No per-provider
+    line in `usage.py`: consumption stays in the ElevenLabs account."""
+
+    id = "elevenlabs"
+
+    def __init__(self, requests, data):
+        self.r = requests
+        self.cfg = CFG["voice"].get("elevenlabs") or {}
+        # ElevenLabs accepts 0.7 to 1.2
+        self.speed = min(1.2, max(0.7, _speed(data, self.cfg)))
+        self.key = _env().get(self.cfg.get("key_env", "ELEVENLABS_API_KEY"))
+        self.voice_id, self._no_voice = _voice_id(self.cfg, data, "elevenlabs")
+
+    def ready(self):
+        if not self.key:
+            return f"sem chave ({self.cfg.get('key_env', 'ELEVENLABS_API_KEY')} no ambiente ou no .env)"
+        if self._no_voice:
+            return self._no_voice
+        if not self.voice_id:
+            return "sem voice_id (o id da voz na ElevenLabs, em voice.elevenlabs.voice_id)"
+        return None
+
+    def config_hash(self):
+        # hash-compat: do not translate
+        return {
+            "provider": "elevenlabs",
+            "voz": self.voice_id,
+            "modelo": self.cfg.get("model"),
+            "idioma": self.cfg.get("language"),
+            "speed": self.speed,
+            "estabilidade": self.cfg.get("stability"),
+            "similaridade": self.cfg.get("similarity"),
+        }
+
+    def generate(self, line):
+        body = {
+            "text": spoken_text(line),
+            "model_id": self.cfg.get("model", "eleven_multilingual_v2"),
+            "voice_settings": {
+                "speed": self.speed,
+                "stability": self.cfg.get("stability", 0.5),
+                "similarity_boost": self.cfg.get("similarity", 0.75),
+            },
+        }
+        if self.cfg.get("language"):
+            body["language_code"] = self.cfg["language"]
+        try:
+            resp = self.r.post(
+                f"https://api.elevenlabs.io/v1/text-to-speech/{self.voice_id}",
+                params={"output_format": "pcm_44100"},
+                json=body,
+                timeout=self.cfg.get("timeout_s", 120),
+                headers={"xi-api-key": self.key},
+            )
+        except self.r.RequestException as exc:
+            raise Failed(f"ElevenLabs: {exc}")
+        if resp.status_code != 200:
+            raise _http_error("ElevenLabs", resp)
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as w:
+            w.setnchannels(1)
+            w.setsampwidth(2)
+            w.setframerate(44100)
+            w.writeframes(resp.content)
+        return buf.getvalue()
+
+
+class VoiceStudio:
+    """Local, profile picked by name: the user redoes the clone and the id changes.
+
+    A nonexistent profile_id is not an error in VoiceStudio: it generates with a
+    generic voice, without the clone. That is why the id never goes fixed in the config.
+    """
+
+    id = "voicestudio"
+
+    def __init__(self, requests, data):
+        self.r = requests
+        self.cfg = CFG["voicestudio"]
+        self.vs = {**self.cfg, **(data.get("voice") or {})}
+        # the video's voice profile may point to another VoiceStudio profile
+        profile, _ = voice_profile(data)
+        if profile and profile.get("voicestudio") and not (data.get("voice") or {}).get("profile"):
+            self.vs["profile"] = profile["voicestudio"]
+        self.url = self.cfg["url"]
+        self._settings = None
+        self._reason = None
+
+    def _resolve(self):
+        if self._settings or self._reason:
+            return
+        try:
+            self.r.get(f"{self.url}/health", timeout=5).raise_for_status()
+            profiles = self.r.get(f"{self.url}/profiles", timeout=10).json()
+        except self.r.RequestException:
+            self._reason = f"não responde em {self.url} (abra o app ou `bun run dev:api` no repo)"
+            return
+        name = self.vs["profile"]
+        hits = [p for p in profiles if p.get("name") == name]
+        if len(hits) != 1:
+            found = ", ".join(f"“{p.get('name')}”" for p in profiles) or "nenhum"
+            self._reason = f"preciso de exatamente um perfil chamado “{name}”; achei {len(hits)}. Perfis: {found}"
+            return
+        self._settings = {k: self.vs[k] for k in ("language", "num_step", "speed")}
+        self._settings["profile_id"] = hits[0]["id"]
+
+    def ready(self):
+        self._resolve()
+        return self._reason
+
+    def config_hash(self):
+        # same format as before the providers existed: lines already generated stay valid
+        self._resolve()
+        return self._settings
+
+    def generate(self, line):
+        if self.ready():
+            raise Failed(f"VoiceStudio {self._reason}")
+        form = {"text": spoken_text(line), **{k: str(v) for k, v in self._settings.items()}}
+        if line.get("instruct"):
+            form["instruct"] = line["instruct"]
+        try:
+            resp = self.r.post(f"{self.url}/generate", data=form, timeout=self.cfg["timeout_s"])
+        except self.r.RequestException as exc:
+            # a timeout does not take VoiceStudio down for the next lines
+            raise Failed(f"VoiceStudio: {exc}", disable=False)
+        if resp.status_code != 200 or not resp.headers.get("content-type", "").startswith("audio/"):
+            raise Failed(f"VoiceStudio respondeu {resp.status_code}: {resp.text[:300]}", disable=False)
+        return resp.content
+
+
+CLASSES = {"fish": Fish, "cartesia": Cartesia, "voicestudio": VoiceStudio, "elevenlabs": ElevenLabs}
+
+
+def video_order(data):
+    """This video's try order. With a voice profile, it is the profile's `order`
+    (only the providers it configured); without one, the config's `voice.order`.
+    `voice.provider` in scenes.json moves one provider to the front."""
+    profile, _ = voice_profile(data)
+    base = []
+    if profile:
+        base = [p for p in (profile.get("order") or []) if p in CLASSES and profile.get(p)]
+        # profile without `order` (or with an old one): the configured ones, in config order
+        base += [p for p in CFG["voice"]["order"] if p in CLASSES and profile.get(p) and p not in base]
+    if not base:
+        base = [p for p in CFG["voice"]["order"] if p in CLASSES]
+    first = (data.get("voice") or {}).get("provider")
+    if first in CLASSES:
+        return [first] + [p for p in base if p != first]
+    return base
+
+
+def preferred(data):
+    return video_order(data)[0]
+
+
+def chain(requests, data):
+    """The video's provider and then the fallbacks, in profile (or config) order."""
+    return [CLASSES[p](requests, data) for p in video_order(data)]
+
+
+def digest(provider, line):
+    extra = provider.config_hash()
+    return _digest(line, extra) if extra is not None else None
+
+
+def status(requests=None):
+    """For the studio and for checking: each provider ready, or why not."""
+    if requests is None:
+        import requests
+    return [
+        {"id": c.id, "name": NAMES[c.id], "reason": c(requests, {}).ready()}
+        for c in (CLASSES[p] for p in CFG["voice"]["order"])
+    ]
+
+
+if __name__ == "__main__":
+    for p in status():
+        print(f"{'✓' if not p['reason'] else '·'} {p['name']}{'' if not p['reason'] else ': ' + p['reason']}")