storyshot 0.5.0 → 0.7.0

package/src/qwen-tts.mjs

@@ -0,0 +1,155 @@
+// Narration with Qwen3-TTS 0.6B CustomVoice (Apache-2.0): nine preset voices, five of them Chinese
+// (serena, vivian, uncle_fu, dylan with a Beijing accent, eric with a Sichuan one), free and local.
+// It runs through mlx-audio, so on Apple Silicon only; elsewhere config.mjs falls back to kokoro.
+// Python (qwen_tts.py) runs in storyshot's own venv, once per render for all uncached lines.
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findPython } from './kokoro-zh.mjs';
+
+export const QWEN_VOICES = ['serena', 'vivian', 'uncle_fu', 'dylan', 'eric', 'ryan', 'aiden', 'ono_anna', 'sohee'];
+export const qwenSupported = () => process.platform === 'darwin' && process.arch === 'arm64';
+// `Uncle Fu`, `Serena` → uncle_fu, serena (null when it isn't one of the nine)
+export const qwenVoice = (name) => {
+  const v = String(name ?? '').trim().toLowerCase().replace(/[\s-]+/g, '_');
+  return QWEN_VOICES.includes(v) ? v : null;
+};
+
+const REPO = 'mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-bf16';
+const REVISION = '6415d95f88be018ff9e46813119dc3bc12261328';
+// 0.9 (the model's default) now and then runs on into made-up words; 0.7 keeps the same voice steadier
+const TEMPERATURE = 0.7;
+// Each take is checked by ear: Qwen3-ASR (Apache-2.0, ~1 GB) transcribes it, and a line it hears
+// differently is sampled again (pypinyin compares Chinese by sound, so homophones don't count)
+const ASR_REPO = 'mlx-community/Qwen3-ASR-0.6B-8bit';
+const ASR_REVISION = '89e96d92ba34aca20b3e29fb10cc284097d1219f';
+const REQUIREMENTS = ['mlx-audio==0.6.3', 'mlx==0.32.4', 'mlx-metal==0.32.4', 'transformers==5.22.0', 'huggingface-hub==2.4.0',
+  'tokenizers==0.23.3', 'safetensors==0.8.0', 'numpy==2.5.4', 'pypinyin==0.55.0'];
+// Part of every cached line's hash: change it when the model, the packages or qwen_tts.py's sampling change.
+export const QWEN_TTS_ID = `${REPO}@${REVISION.slice(0, 7)}|${REQUIREMENTS[0]}|t${TEMPERATURE}|guard-2|${ASR_REPO}@${ASR_REVISION.slice(0, 7)}`;
+const CACHE = path.join(os.homedir(), '.cache', 'storyshot');
+export const QWEN_VENV = path.join(CACHE, 'qwen-venv');
+const HELPER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'qwen_tts.py');
+const HUB = process.env.HF_HUB_CACHE ?? path.join(process.env.HF_HOME ?? path.join(os.homedir(), '.cache', 'huggingface'), 'hub');
+const MODEL_FILE = path.join(HUB, `models--${REPO.replace('/', '--')}`, 'snapshots', REVISION, 'model.safetensors');
+const ASR_FILE = path.join(HUB, `models--${ASR_REPO.replace('/', '--')}`, 'snapshots', ASR_REVISION, 'model.safetensors');
+
+// --- text (TTS only: subtitles keep the original) --------------------------------------------------
+// The model reads = + 2个 第2行 x² itself; a minus sign before a number it drops, and a number like
+// 2e-105 sets it babbling, so those are spelled out in Chinese lines.
+export function qwenSpeakText(text, lang = qwenLang(text)) {
+  let t = String(text).replace(/\s*\n+\s*/g, ' ');
+  if (lang === 'chinese') {
+    t = t.replace(/(\d(?:\.\d+)?)[eE]\s*([-−+]?)\s*(\d+)/g, (_, m, s, e) => `${m}乘10的${s && s !== '+' ? '负' : ''}${e}次方`)
+      .replace(/(?<![\w)²³]\s*)−\s*(?=\d)/g, '负');
+  }
+  return t;
+}
+
+// The language the model is told: the script decides; Latin text is left to the model.
+export function qwenLang(text) {
+  const s = String(text).replace(/\d+(?:\.\d+)?(?:[eE][-−+]?\d+)?/g, ' '); // the e in 2e-105 is no English word
+  if (/[぀-ヿ]/.test(s)) return 'japanese';
+  if (/[가-힯]/.test(s)) return 'korean';
+  const han = (s.match(/[㐀-鿿]/g) ?? []).length, latin = (s.match(/[A-Za-z]+/g) ?? []).length;
+  return han > latin ? 'chinese' : 'auto';
+}
+
+// --- the venv ---------------------------------------------------------------------------------------
+const venvPython = (dir) => path.join(dir, 'bin', 'python');
+const STAMP = 'storyshot-requirements.txt';
+const venvReady = () => {
+  try { return fs.readFileSync(path.join(QWEN_VENV, STAMP), 'utf8') === REQUIREMENTS.join('\n') && fs.existsSync(venvPython(QWEN_VENV)); } catch { return false; }
+};
+
+const NO_PYTHON = () => 'the Qwen3-TTS voice needs Python 3.10–3.12 to run (brew install python@3.12, or uv python install 3.12, ' +
+  `or set STORYSHOT_PYTHON); storyshot then keeps its packages in its own venv (${QWEN_VENV}), nothing is installed globally`;
+
+// For doctor and check: can this machine use it, and what's still to come on first use?
+export function qwenStatus() {
+  if (!qwenSupported()) return { supported: false };
+  const model = fs.existsSync(MODEL_FILE) && fs.existsSync(ASR_FILE);
+  if (venvReady()) return { supported: true, ready: true, venv: QWEN_VENV, model };
+  const python = findPython();
+  return { supported: true, ready: false, venv: QWEN_VENV, model, python, problem: python ? null : NO_PYTHON() };
+}
+
+function ensureVenv(log) {
+  if (venvReady()) return venvPython(QWEN_VENV);
+  const run = (cmd, args, what) => {
+    const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status !== 0) throw new Error(`${what} failed: ${(r.stderr || r.stdout || r.error?.message || '').trim().split('\n').slice(-6).join('\n')}`);
+  };
+  if (fs.existsSync(venvPython(QWEN_VENV))) {
+    // a venv from an older storyshot: bring its packages up to date in place, rebuild it only if that fails
+    log(`updating the Qwen3-TTS venv in ${QWEN_VENV}…`);
+    try {
+      run(venvPython(QWEN_VENV), ['-m', 'pip', 'install', '--disable-pip-version-check', '--no-input', '-q', ...REQUIREMENTS], 'updating the venv');
+      fs.writeFileSync(path.join(QWEN_VENV, STAMP), REQUIREMENTS.join('\n'));
+      return venvPython(QWEN_VENV);
+    } catch (e) { log(`  ${e.message.split('\n')[0]} — rebuilding it`); }
+  }
+  const py = findPython();
+  if (!py) throw new Error(NO_PYTHON());
+  log(`setting up the Qwen3-TTS voice (one time): a Python ${py.version} venv in ${QWEN_VENV} with mlx-audio (~400 MB, 1–2 min)…`);
+  fs.rmSync(QWEN_VENV, { recursive: true, force: true });
+  fs.mkdirSync(CACHE, { recursive: true });
+  run(py.exe, ['-m', 'venv', QWEN_VENV], `creating the venv with ${py.exe} -m venv`);
+  run(venvPython(QWEN_VENV), ['-m', 'pip', 'install', '--disable-pip-version-check', '--no-input', '-q', ...REQUIREMENTS], 'installing mlx-audio into the venv');
+  fs.writeFileSync(path.join(QWEN_VENV, STAMP), REQUIREMENTS.join('\n')); // written last: a half-built venv is rebuilt next time
+  return venvPython(QWEN_VENV);
+}
+
+// --- synthesis --------------------------------------------------------------------------------------
+// entries: [{ text, file }] (text already through qwenSpeakText) → a WAV at each `file`.
+export async function synthQwen(v, entries, { log = console.log } = {}) {
+  if (!entries.length) return;
+  if (!qwenSupported()) throw new Error('the Qwen3-TTS voice runs on Apple Silicon Macs only (it uses MLX)');
+  const py = ensureVenv(log);
+  if (!fs.existsSync(MODEL_FILE)) log(`downloading the Qwen3-TTS model (one time, ~2.3 GB) into ${HUB}…`);
+  if (!fs.existsSync(ASR_FILE)) log(`downloading the Qwen3-ASR model that listens to each take (one time, ~1 GB) into ${HUB}…`);
+  const lines = entries.map((e) => ({
+    text: e.text, file: `${e.file}.raw.wav`, voice: v.voice, lang: qwenLang(e.text),
+    // the same line gets the same take: a seed from the text
+    seed: parseInt(crypto.createHash('sha1').update(e.text).digest('hex').slice(0, 7), 16),
+  }));
+  const job = JSON.stringify({ repo: REPO, revision: REVISION, temperature: TEMPERATURE, asr: { repo: ASR_REPO, revision: ASR_REVISION }, lines });
+  const { code, stdout, tail } = await new Promise((resolve, reject) => {
+    const p = spawn(py, ['-I', HELPER], { env: { ...process.env, HF_HUB_DISABLE_TELEMETRY: '1', TRANSFORMERS_VERBOSITY: 'error' } });
+    let out = '', err = '', buf = '';
+    p.stdout.on('data', (d) => { out += d; });
+    p.stderr.on('data', (d) => {
+      err = (err + d).slice(-4000);
+      buf += d;
+      let nl;
+      while ((nl = buf.search(/[\r\n]/)) >= 0) {
+        const m = buf.slice(0, nl).match(/^line (\d+)\/\d+ (\S+)( \d+ tries)?/);
+        buf = buf.slice(nl + 1);
+        if (m) log(`  tts (qwen/${v.voice}, ${m[2]}${m[3] ? `,${m[3]}` : ''}): "${entries[m[1] - 1].text}"`);
+      }
+    });
+    p.on('error', reject);
+    p.on('close', (c) => resolve({ code: c, stdout: out, tail: err }));
+    p.stdin.end(job);
+  });
+  if (code !== 0) throw new Error(`Qwen3-TTS failed (${py} ${HELPER}): ${tail.trim().split('\n').slice(-8).join('\n')}`);
+  const { results, asr } = JSON.parse(stdout);
+  if (asr) log(`  ⚠ qwen: the speech check couldn't load (${asr}), so these takes were checked by length only`);
+  for (const [i, e] of entries.entries()) {
+    const r = results[i];
+    if (r?.suspect) {
+      log(r.heard != null && r.mismatch > 0
+        ? `  ⚠ qwen: "${e.text}" still doesn't come out right after ${r.tries} tries — it sounds like "${r.heard}". Listen to it; rephrase the line or add a pronounce entry`
+        : `  ⚠ qwen: "${e.text}" still sounds off after ${r.tries} tries (${r.seconds.toFixed(1)}s) — listen to it, or rephrase the line / add a pronounce entry`);
+    }
+    const raw = lines[i].file, tmp = `${e.file}.tmp.wav`;
+    // the model has no speed control: ffmpeg's pitch-preserving atempo does it
+    if ((v.speed ?? 1) !== 1) execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', raw, '-af', `atempo=${v.speed}`, tmp]);
+    else fs.renameSync(raw, tmp);
+    fs.rmSync(raw, { force: true });
+    fs.renameSync(tmp, e.file);
+  }
+}

package/src/qwen_tts.py

@@ -0,0 +1,186 @@
+# Qwen3-TTS CustomVoice through mlx-audio (Apple Silicon), for `voice: { provider: qwen }`. Runs in
+# storyshot's own venv (qwen-tts.mjs), one process per render: the model loads once for all lines.
+#
+# stdin:  {"repo", "revision", "temperature", "asr": {"repo", "revision"} | null,
+#          "lines": [{"text", "file", "voice", "lang", "seed"}]}
+# stderr: "line i/n <seconds>s [<tries> tries]" per line, plus whatever the libraries log
+# stdout: {"results": [{"seconds", "tries", "suspect", "heard", "mismatch"}], "asr": null | "why it didn't load"}
+#
+# The model samples its speech tokens, so now and then a take garbles a few words, drops one, runs on
+# into made-up words (a scientific number like 2e-105 does it) or stops early. Each take is checked:
+# its length against the text, and what a speech recognizer (Qwen3-ASR) hears in it against the text.
+# A take that fails is sampled again with another seed, and the best one is kept.
+import contextlib
+import json
+import os
+import re
+import sys
+
+os.environ.setdefault('HF_HUB_DISABLE_TELEMETRY', '1')
+os.environ.setdefault('TRANSFORMERS_VERBOSITY', 'error')
+
+TRIES = 4
+# a take is sampled again when the recognizer hears this share of the line differently, or this long a run
+# of mistakes in a row (a garble: 负 2 x → 负二长方荡 is 2.5); a warning if every take is still off
+RETRY_AT, RETRY_RUN = 0.10, 2
+WARN_AT, WARN_RUN = 0.15, 2
+
+
+def expected(text):
+    """Rough speaking time in seconds: ~3.6 Chinese characters a second, Latin words and numbers."""
+    han = len(re.findall(r'[㐀-鿿]', text))
+    words = len(re.findall(r'[A-Za-z]+', text))
+    nums = len(re.findall(r'\d+(?:\.\d+)?', text))
+    return han / 3.6 + words * 0.4 + nums * 0.5 + 0.3
+
+
+def plausible(seconds, est):
+    return 0.35 * est - 0.5 <= seconds <= 2.0 * est + 2.0
+
+
+# --- what was said vs. what was meant ---------------------------------------------------------------
+# Chinese is compared by sound (toneless pinyin), so a homophone the recognizer picks (交点/焦点) is no
+# mistake; numbers are read out first (0.5 → 零点五, 2 → 二), since the recognizer writes either form.
+DIGITS = '零一二三四五六七八九'
+
+
+def cn_int(n):
+    if n >= 10 ** 8:
+        return ''.join(DIGITS[int(c)] for c in str(n))
+
+    def four(x):
+        out, zero = '', False
+        for i, c in enumerate(f'{x:04d}'):
+            d = int(c)
+            if d == 0:
+                zero = bool(out)
+            else:
+                out += ('零' if zero else '') + DIGITS[d] + ['千', '百', '十', ''][i]
+                zero = False
+        return out
+
+    if n < 10:
+        return DIGITS[n]
+    hi, lo = divmod(n, 10000)
+    out = (four(hi) + '万' if hi else '') + (('零' if hi and lo < 1000 else '') + four(lo) if lo else '')
+    return re.sub('^一十', '十', out)
+
+
+def cn_number(m):
+    whole, _, frac = m.group().partition('.')
+    return cn_int(int(whole)) + ('点' + ''.join(DIGITS[int(c)] for c in frac) if frac else '')
+
+
+def units(text, chinese, pinyin):
+    """The line as a list of sounds: pinyin syllables, digits, and Latin words as '#word' (m x and mx as '#m', '#x')."""
+    t = text.lower().replace('−', '-')
+    if chinese:
+        t = re.sub(r'\d+(?:\.\d+)?', cn_number, t)
+    out = []
+    for tok in re.findall(r'[㐀-鿿]|[a-z]+|\d+', t):
+        if chinese and re.match(r'[㐀-鿿]', tok):
+            out += [{'liang': 'er'}.get(p, p) for p in pinyin(tok)]
+        elif tok.isdigit():
+            out += list(tok)  # digit by digit: a wrong number (260 → 45) is several mistakes in a row, not one
+        else:
+            out += ['#' + c for c in tok] if len(tok) <= 2 else ['#' + tok]
+    return out
+
+
+def mismatch(text, heard, chinese, pinyin):
+    """(share of the line heard differently, the longest run of mistakes in a row), both in units of the
+    text. A garbled take has a run of several; a homophone or a misheard letter is one on its own."""
+    a, b = units(text, chinese, pinyin), units(heard, chinese, pinyin)
+    letter = lambda u: len(u) == 2 and u[0] == '#'
+    d = {(0, 0): (0, None)}
+    for i in range(len(a) + 1):
+        for j in range(len(b) + 1):
+            if i == j == 0:
+                continue
+            ways = []
+            if i:
+                ways.append((d[i - 1, j][0] + 1, (i - 1, j, 1)))
+            if j:
+                ways.append((d[i, j - 1][0] + 1, (i, j - 1, 1)))
+            if i and j:
+                x, y = a[i - 1], b[j - 1]
+                # a variable (m, b, x) the recognizer wrote as a character is half a mistake
+                cost = 0 if x == y else 0.5 if letter(x) or letter(y) else 1
+                ways.append((d[i - 1, j - 1][0] + cost, (i - 1, j - 1, cost)))
+                # a name in Latin letters in a Chinese line (Desmos) can come back as a few syllables: one mistake
+                if chinese and len(x) > 3 and x[0] == '#':
+                    ways += [(d[i - 1, j - k][0] + 1, (i - 1, j - k, 1)) for k in range(2, min(5, j) + 1)]
+            d[i, j] = min(ways, key=lambda w: w[0])
+    i, j, run, worst = len(a), len(b), 0, 0
+    while (i, j) != (0, 0):
+        i, j, cost = d[i, j][1]
+        run = run + cost if cost else 0
+        worst = max(worst, run)
+    return d[len(a), len(b)][0] / max(1, len(a)), worst
+
+
+def main():
+    job = json.load(sys.stdin)
+    out = sys.stdout
+    # the libraries print their own notes on stdout: keep it for the JSON answer
+    with contextlib.redirect_stdout(sys.stderr):
+        import math
+        import mlx.core as mx
+        import numpy as np
+        from huggingface_hub import snapshot_download
+        from mlx_audio.audio_io import write
+        from mlx_audio.tts.utils import load_model
+
+        model = load_model(snapshot_download(job['repo'], revision=job['revision']))
+        asr, asr_error, pinyin = None, None, None
+        if job.get('asr'):
+            try:
+                from mlx_audio.stt.utils import load_model as load_stt
+                from pypinyin import lazy_pinyin as pinyin
+                asr = load_stt(snapshot_download(job['asr']['repo'], revision=job['asr']['revision']))
+            except Exception as e:  # offline before the first download, say: check by length only
+                asr_error = f'{type(e).__name__}: {e}'.splitlines()[0][:300]
+
+        def hear(audio, line):
+            """(what the recognizer heard, mismatch), or (None, None) for a line it can't check."""
+            chinese = line['lang'] == 'chinese'
+            if asr is None or not (chinese or (line['lang'] == 'auto' and not re.search(r'[㐀-鿿]', line['text']))):
+                return None, None
+            tmp = line['file'] + '.check.wav'
+            write(tmp, audio, model.sample_rate)
+            try:
+                heard = asr.generate(tmp, language='Chinese' if chinese else 'English').text.strip()
+            finally:
+                os.remove(tmp)
+            return heard, mismatch(line['text'], heard, chinese, pinyin)
+
+        results, n = [], len(job['lines'])
+        for i, line in enumerate(job['lines']):
+            est = expected(line['text'])
+            best = None
+            for k in range(TRIES):
+                mx.random.seed(line['seed'] + k * 7919)
+                parts = model.generate(text=line['text'], voice=line['voice'], lang_code=line['lang'],
+                                       temperature=job['temperature'])
+                audio = np.concatenate([np.array(r.audio, dtype=np.float32) for r in parts])
+                seconds = len(audio) / model.sample_rate
+                fits = plausible(seconds, est)
+                heard, m = hear(audio, line) if fits else (None, None)
+                # how far off the recognizer heard it: up to 1 is fine (0 when it couldn't check)
+                worse = max(m[0] / RETRY_AT, m[1] / RETRY_RUN) if m else 0
+                # a take of the right length that says the line beats one that doesn't; then the closest length
+                rank = (not fits, worse if worse > 1 else 0, abs(math.log(max(seconds, 0.1) / est)))
+                if best is None or rank < best['rank']:
+                    best = {'rank': rank, 'audio': audio, 'seconds': seconds, 'fits': fits, 'heard': heard, 'm': m}
+                if fits and worse <= 1:
+                    break
+            write(line['file'], best['audio'], model.sample_rate)
+            m = best['m']
+            results.append({'seconds': best['seconds'], 'tries': k + 1, 'heard': best['heard'], 'mismatch': m and m[0],
+                            'suspect': not best['fits'] or bool(m and (m[0] > WARN_AT or m[1] > WARN_RUN))})
+            print(f'line {i + 1}/{n} {best["seconds"]:.1f}s' + (f' {k + 1} tries' if k else ''), file=sys.stderr, flush=True)
+    out.write(json.dumps({'results': results, 'asr': asr_error}))
+
+
+if __name__ == '__main__':
+    main()

package/src/record.mjs

@@ -55,19 +55,60 @@ function pageScript({ scrollOffset }) {
     for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) if (scrollable(p)) return p;
     return docEl();
   };
+  // `behavior: 'instant'` on every frame: with `scroll-behavior: smooth` in the page's CSS (GitHub has it),
+  // plain scrollTop writes each start a smooth scroll of their own, so the page lags behind and is still
+  // moving after the step that scrolled it is over
   window.__demoScrollBy = (dy, ms = 1200, sc = mainScroller()) => new Promise((done) => {
     const start = sc.scrollTop, t0 = performance.now();
     const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
     const step = (now) => {
-      const k = Math.min(1, (now - t0) / ms);
-      sc.scrollTop = start + dy * ease(k);
+      const k = ms > 0 ? Math.min(1, Math.max(0, (now - t0) / ms)) : 1;
+      sc.scrollTo({ top: start + dy * ease(k), behavior: 'instant' });
       if (k < 1) requestAnimationFrame(step); else done();
     };
     requestAnimationFrame(step);
   });
+  // How far down a header will cover the window once `el` is scrolled to the top: bars fixed at the top,
+  // and sticky ones that stick inside a box holding `el` (GitHub's README bar sticks within the README).
+  const headerCover = (el) => {
+    let cover = 0;
+    for (const h of document.querySelectorAll('body *')) {
+      if (h.getAttribute('id')?.startsWith('__demo') || h.contains(el)) continue; // not h.id: a form with an <input name=id> has that input as its .id
+      const cs = getComputedStyle(h);
+      if (cs.position !== 'fixed' && cs.position !== 'sticky') continue;
+      const r = h.getBoundingClientRect();
+      if (!r.height || r.height > innerHeight * 0.3 || r.width < innerWidth * 0.3 || cs.visibility === 'hidden' || cs.opacity === '0') continue;
+      if (cs.position === 'fixed' && r.top <= 1) cover = Math.max(cover, r.bottom);
+      const stick = parseFloat(cs.top);
+      if (cs.position === 'sticky' && !Number.isNaN(stick) && stick < innerHeight * 0.3 && h.parentElement?.contains(el)) cover = Math.max(cover, stick + r.height);
+    }
+    return cover;
+  };
+  // the element's top lands `scrollOffset` px down, or just below a header that would cover it there
   window.__demoScrollTo = (el, ms) => {
-    const sc = scrollerFor(el), top = sc === docEl() ? 0 : sc.getBoundingClientRect().top;
-    return window.__demoScrollBy(el.getBoundingClientRect().top - top - scrollOffset, ms, sc);
+    const sc = scrollerFor(el), docs = sc === docEl(), top = docs ? 0 : sc.getBoundingClientRect().top;
+    const offset = docs ? Math.max(scrollOffset, headerCover(el) + 12) : scrollOffset;
+    return window.__demoScrollBy(el.getBoundingClientRect().top - top - offset, ms, sc);
+  };
+  // resolves once nothing has scrolled for a few frames (the page's own smooth scrolling included)
+  window.__demoScrollIdle = (max = 2000) => new Promise((done) => {
+    const sc = mainScroller(), pos = () => `${scrollX},${scrollY},${sc.scrollTop}`;
+    const end = performance.now() + max;
+    let last = pos(), still = 0;
+    const check = () => {
+      const now = pos();
+      still = now === last ? still + 1 : 0; last = now;
+      if (still >= 3 || performance.now() > end) done(); else requestAnimationFrame(check);
+    };
+    requestAnimationFrame(check);
+  });
+  // a slider's value and range: an <input type=range>, or an ARIA slider (Desmos: [role=slider] on its knob)
+  window.__demoSliderValue = (el) => {
+    const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
+    if (r) return { now: Number(r.value), lo: Number(r.min || 0), hi: Number(r.max || 100), native: r };
+    const aria = el.hasAttribute('aria-valuenow') ? el : el.querySelector?.('[aria-valuenow]');
+    const now = Number(aria?.getAttribute('aria-valuenow'));
+    return aria && Number.isFinite(now) ? { now, lo: Number(aria.getAttribute('aria-valuemin') ?? 0), hi: Number(aria.getAttribute('aria-valuemax') ?? 100) } : null;
   };
   // Tutorial callouts: spotlight a target, show a pressed key combo.
   window.__demoSpot = (r) => {
@@ -86,9 +127,10 @@ function pageScript({ scrollOffset }) {
     Object.assign(el.style, { left: `${r.x - pad}px`, top: `${r.y - pad}px`, width: `${r.width + 2 * pad}px`, height: `${r.height + 2 * pad}px` });
     requestAnimationFrame(() => { el.style.opacity = '1'; });
   };
-  window.__demoSpotOff = () => {
+  window.__demoSpotOff = (instant) => {
     const el = document.getElementById('__demo_spot');
-    if (el) { el.style.opacity = '0'; setTimeout(() => el.remove(), 300); }
+    if (el && instant) el.remove();
+    else if (el) { el.style.opacity = '0'; setTimeout(() => el.remove(), 300); }
   };
   window.__demoKeys = (label) => {
     const el = document.createElement('div');
@@ -424,7 +466,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     await sleep(280);
     return true;
   }
-  const spotOff = () => page.evaluate(() => window.__demoSpotOff()).catch(() => {});
+  const spotOff = (instant) => page.evaluate((i) => window.__demoSpotOff(i), !!instant).catch(() => {});
   const keyLabel = (k) => k.split('+').map((p) => ({ Meta: '⌘', ControlOrMeta: '⌘', Control: 'Ctrl', Shift: '⇧', Alt: '⌥', Enter: '↵ Enter', Escape: 'Esc', Backspace: '⌫', Tab: '⇥ Tab' })[p] ?? (p.length === 1 ? p.toUpperCase() : p)).join(' ');
 
   async function runAction(action) {
@@ -473,6 +515,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       case 'scrollTo': {
         const h = await locate(page, spec).elementHandle({ timeout: opt.timeout ?? 15000 });
         await page.evaluate(([el, ms]) => window.__demoScrollTo(el, ms), [h, opt.ms ?? 1200]);
+        // where it landed: a zoom on the same target frames it there, not where it was before the scroll
+        const b = await h.boundingBox().catch(() => null);
+        if (b) boxes.set(keyOf(spec), b);
         break;
       }
       case 'scroll': await page.evaluate(([dy, ms]) => window.__demoScrollBy(dy, ms), [value.y ?? value, value.ms ?? 1000]); break;
@@ -570,25 +615,28 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       }
       case 'slide': {
         // slide: { target: <slider>, to: 0.2 } — drag a slider to a position along its track (0 = start,
-        // 1 = end), found from the element instead of pixel positions that break when the layout moves
-        if (!value?.target || typeof value?.to !== 'number') throw new Error('slide needs { target: <slider>, to: 0..1 }');
+        // 1 = end), or { target, value: 3 } — to a value, for sliders that report their range; found from
+        // the element instead of pixel positions that break when the layout moves
+        if (!value?.target || (typeof value?.to !== 'number' && typeof value?.value !== 'number')) throw new Error('slide needs { target: <slider>, to: 0..1 } or { target: <slider>, value: <number> }');
         const p = await pointOf(value.target, value);
-        const b = p.box;
-        const from = await locate(page, value.target).evaluate((el) => {
-          const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
-          if (r) return (Number(r.value) - Number(r.min || 0)) / ((Number(r.max || 100) - Number(r.min || 0)) || 1);
-          const aria = el.hasAttribute('aria-valuenow') ? el : el.querySelector?.('[aria-valuenow]');
-          if (aria) {
-            const now = Number(aria.getAttribute('aria-valuenow')), lo = Number(aria.getAttribute('aria-valuemin') ?? 0), hi = Number(aria.getAttribute('aria-valuemax') ?? 100);
-            if (Number.isFinite(now)) return (now - lo) / ((hi - lo) || 1);
+        const s = await locate(page, value.target).evaluate((el) => {
+          // a knob (Desmos's [role=slider] is its 38 px thumb): slide along its track, the nearest wide parent
+          let track = el;
+          const w = el.getBoundingClientRect().width;
+          for (let a = el.parentElement, i = 0; w < 60 && a && i < 4; a = a.parentElement, i++) if (a.getBoundingClientRect().width >= 3 * w) { track = a; break; }
+          const t = track.getBoundingClientRect(), v = window.__demoSliderValue(el);
+          let from = v ? (v.now - v.lo) / ((v.hi - v.lo) || 1) : null;
+          if (from == null) {
+            // custom sliders: start where the knob is drawn, so the value doesn't jump first
+            const knob = [...track.querySelectorAll('[role=slider], [class*=thumb], [class*=handle], [class*=knob]')]
+              .map((k) => k.getBoundingClientRect()).find((k) => k.width > 0 && k.width < t.width * 0.5);
+            from = knob ? (knob.x + knob.width / 2 - t.x) / (t.width || 1) : 0.5;
           }
-          // custom sliders (e.g. Desmos): start where the knob is drawn, so the value doesn't jump first
-          const t = el.getBoundingClientRect();
-          const knob = [...el.querySelectorAll('[role=slider], [class*=thumb], [class*=handle], [class*=knob]')]
-            .map((k) => k.getBoundingClientRect()).find((k) => k.width > 0 && k.width < t.width * 0.5);
-          return knob ? (knob.x + knob.width / 2 - t.x) / (t.width || 1) : 0.5;
-        }).catch(() => 0.5);
-        const x0 = b.x + b.width * from, x1 = b.x + b.width * Math.max(0, Math.min(1, value.to)), y = b.y + b.height / 2;
+          return { box: { x: t.x, y: t.y, width: t.width, height: t.height }, from, range: v && { lo: v.lo, hi: v.hi } };
+        }).catch(() => ({ box: p.box, from: 0.5, range: null }));
+        if (typeof value.value === 'number' && !s.range) throw new Error('slide value: this slider doesn\'t report its range (no aria-valuemin/max, not an <input type=range>) — use to: 0..1');
+        const to = typeof value.value === 'number' ? (value.value - s.range.lo) / ((s.range.hi - s.range.lo) || 1) : value.to;
+        const b = s.box, x0 = b.x + b.width * s.from, x1 = b.x + b.width * Math.max(0, Math.min(1, to)), y = b.y + b.height / 2;
         await moveTo(x0, y, value.ms ?? cfg.pace.cursor);
         await sleep(120);
         clicks.push(now());
@@ -596,6 +644,19 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         await moveTo(x1, y, value.dragMs ?? 900);
         await sleep(120);
         await page.mouse.up();
+        if (typeof value.value === 'number') {
+          // a native range's thumb doesn't reach the ends of its box, so the drag can land a step off: set it
+          const got = await locate(page, value.target).evaluate((el, want) => {
+            const v = window.__demoSliderValue(el), r = v?.native;
+            if (r && v.now !== want) {
+              Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(r, String(want));
+              r.dispatchEvent(new Event('input', { bubbles: true })); r.dispatchEvent(new Event('change', { bubbles: true }));
+              return Number(r.value);
+            }
+            return v?.now;
+          }, value.value).catch(() => null);
+          if (got != null && Math.abs(got - value.value) > 1e-9) log(`  ⚠ ${acting}: slide stopped at ${got}, not ${value.value} — the slider snaps to its step`);
+        }
         await settle();
         await beat();
         break;
@@ -608,11 +669,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         let box = null;
         const phraseOnly = v.text && Object.keys(v).every((k) => ['text', 'exact'].includes(k));
         if (phraseOnly) {
+          await page.evaluate(() => window.__demoScrollIdle()).catch(() => {}); // judge "in view" where the page ends up
           const found = await page.evaluate((t) => window.__demoFind(t), v.text);
-          if (found && !found.inView) {
-            await page.evaluate((ms) => window.__demoScrollTo(window.__demoFound.startContainer.parentElement, ms), fast ? 0 : 900);
-            await sleep(fast ? 50 : 950);
-          }
+          if (found && !found.inView) await page.evaluate((ms) => window.__demoScrollTo(window.__demoFound.startContainer.parentElement, ms), fast ? 0 : 900);
           if (found) box = await page.evaluate(([ms, color, b]) => window.__demoMark('found', { ms, color, box: b }), [ms, color, opt.box ?? false]);
         }
         if (!box) {
@@ -659,7 +718,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
 
   // --- setup (not recorded) -----------------------------------------------------------
   // Run a list of actions; on failure, say exactly which one and save a screenshot.
+  let acting = '';
   async function runAll(actions, where) {
+    acting = where;
     for (const [j, a] of actions.entries()) {
       try {
         // watchdog: an action that hangs (a frozen page, a stalled browser) fails with a clear message
@@ -759,9 +820,10 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     const n = Math.min(inspectAfter, cfg.steps.length);
     for (const [i, s] of cfg.steps.slice(0, n).entries()) {
       stepHighlight = false;
-      // like the recording: marks and notes end with their step (the last step's stay in the screenshot)
-      if (i > 0) await page.evaluate(() => { window.__demoUnmark(); window.__demoUnnote(); }).catch(() => {});
+      // like the recording: marks, notes and spotlights end with their step (the last step's stay in the screenshot)
+      if (i > 0) await page.evaluate(() => { window.__demoUnmark(true); window.__demoUnnote(true); window.__demoSpotOff(true); }).catch(() => {});
       await runAll(s.actions, `step ${i + 1}`);
+      await page.evaluate(() => window.__demoScrollIdle()).catch(() => {});
     }
     await sleep(800);
     const shot = path.join(cfg.work, `inspect-after-${n}.jpg`);
@@ -804,10 +866,14 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     const zoomTarget = s.zoom?.target && !isPoint(s.zoom.target);
     const startBox = zoomTarget ? await boxNow() : null;
     await runAll(s.actions, `step ${i + 1}`);
+    // a scroll still running (the page's own smooth scrolling) ends in this step, not in the next one's first shot
+    await page.evaluate(() => window.__demoScrollIdle()).catch(() => {});
     const end = now(); // before clearing: a step that is held for its narration keeps its marks
-    await spotOff();
-    // docs clips start where the step starts: clear at once, so no fading callout leaks into the next clip
-    await page.evaluate((i) => { window.__demoUnmark(i); window.__demoUnnote(i); }, cfg.clips.length > 0).catch(() => {});
+    // docs clips start where the step starts, and a hidden step is cut: clear at once, so no fading
+    // callout leaks into the next shot
+    const instant = cfg.clips.length > 0 || !!s.hidden;
+    await spotOff(instant);
+    await page.evaluate((i) => { window.__demoUnmark(i); window.__demoUnnote(i); }, instant).catch(() => {});
     let zoomBox = null;
     if (s.zoom?.target) {
       if (isPoint(s.zoom.target)) {