npm - voxflow - Versions diffs - 1.14.0 → 1.15.1 - Mend

voxflow 1.14.0 → 1.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (454) hide show

package/lib/commands/slice-preview.js ADDED Viewed

@@ -0,0 +1,266 @@
+'use strict';
+/**
+ * `voxflow slice preview <deck.json>` — open a localhost HTML page that
+ * shows a midpoint-frame still of every card in the deck so users can
+ * see the cards before paying the full render cost (~30s for 20s video).
+ *
+ * Renders N PNG stills via @remotion/renderer.renderStill() at the
+ * midpoint frame of each card, caches them under /tmp/, then serves a
+ * minimal HTML page with the grid + auto-opens the browser. The server
+ * stays alive until Ctrl+C.
+ *
+ * Shares buildInputProps / resolveServeUrl / chromeBinaryExists with
+ * slice-render so behavior is consistent between preview and render.
+ *
+ * No `meta` export — reached via `slice.js` dispatch (`voxflow slice
+ * preview <path>`), so it stays out of the registry parity test.
+ */
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const os = require('node:os');
+const open = require('open').default;
+const { validatePaperSlideDeck, isV2LayoutTreeDeck } = require('../internal/deck-validator');
+const {
+    buildInputProps,
+    resolveServeUrl,
+    chromeBinaryExists,
+    THEME_TO_DECK_ID,
+    DEFAULT_THEME,
+} = require('./slice-render');
+const FPS = 30;
+const DEFAULT_PORT = 5555;
+const PREVIEW_WIDTH = 540; // half of 1080 — stills don't need full-res for thumbnails
+function deckHash(deck) {
+    // 8-char hash so the cache dir is short but unique per deck content.
+    // If the deck changes, we want fresh stills; if it doesn't, reuse cache.
+    return crypto.createHash('sha1').update(JSON.stringify(deck)).digest('hex').slice(0, 8);
+}
+function cardMidpointFrame(deck, cardIndex) {
+    // Composition plays cards sequentially. To get card K's midpoint
+    // frame we sum previous durations then add half of this one.
+    let acc = 0;
+    for (let i = 0; i < cardIndex; i++) {
+        acc += deck.cards[i].durationSec || 4;
+    }
+    const here = deck.cards[cardIndex].durationSec || 4;
+    return Math.floor((acc + here / 2) * FPS);
+}
+async function findFreePort(start) {
+    return new Promise((resolve) => {
+        const probe = http.createServer();
+        probe.unref();
+        probe.on('error', () => resolve(findFreePort(start + 1)));
+        probe.listen(start, () => {
+            const port = probe.address().port;
+            probe.close(() => resolve(port));
+        });
+    });
+}
+function escapeHtml(s) {
+    return String(s ?? '').replace(/[&<>"']/g, (c) => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+}
+function renderHtml(deck, port) {
+    const title = escapeHtml(deck.seriesTitle || deck.header || 'Preview');
+    const meta = `${deck.cards.length} cards · theme: ${escapeHtml(deck.theme)} · 1080×1920`;
+    const cards = deck.cards.map((c, i) => {
+        const label = c.kind === 'title'
+            ? (Array.isArray(c.title) ? c.title.join(' / ') : '')
+            : (c.caption || '');
+        return `<figure class="card">
+            <img src="/still/${i}.png" alt="Card ${i + 1}" loading="lazy">
+            <figcaption><span class="idx">${i + 1}</span> <span class="kind">${escapeHtml(c.kind)}</span> ${escapeHtml(label)}</figcaption>
+        </figure>`;
+    }).join('\n        ');
+    return `<!DOCTYPE html>
+<html lang="zh">
+<head>
+    <meta charset="utf-8">
+    <title>VoxFlow Slice · ${title}</title>
+    <style>
+        :root { color-scheme: light; }
+        body { font-family: ui-sans-serif, system-ui, -apple-system, "PingFang SC", sans-serif; margin: 0; padding: 40px 48px 64px; background: #faf6ee; color: #1b1815; }
+        h1 { font-size: 28px; font-weight: 500; letter-spacing: -0.01em; margin: 0 0 6px; }
+        .meta { color: #7a6f5f; font-size: 13px; margin-bottom: 28px; }
+        .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(216px, 1fr)); gap: 20px 16px; }
+        .card { margin: 0; display: flex; flex-direction: column; gap: 8px; }
+        .card img { width: 100%; aspect-ratio: 9/16; background: #000; border-radius: 6px; box-shadow: 0 1px 2px rgba(0,0,0,0.08), 0 4px 14px rgba(60,40,20,0.07); display: block; }
+        .card figcaption { font-size: 12px; line-height: 1.45; color: #4d4339; display: flex; flex-wrap: wrap; align-items: baseline; gap: 6px; }
+        .idx { font-variant-numeric: tabular-nums; color: #b8a994; font-weight: 600; }
+        .kind { display: inline-block; padding: 1px 6px; border-radius: 3px; background: #efe7d6; color: #6e5f49; font-size: 10px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; }
+        .cmd { font-family: ui-monospace, "SF Mono", monospace; background: #2b2520; color: #faf6ee; padding: 14px 18px; border-radius: 6px; font-size: 13px; margin-top: 32px; user-select: all; }
+        .cmd .hint { color: #9c8e75; font-size: 11px; display: block; margin-bottom: 6px; }
+    </style>
+</head>
+<body>
+    <h1>${title}</h1>
+    <div class="meta">${meta}</div>
+    <div class="grid">
+        ${cards}
+    </div>
+    <div class="cmd">
+        <span class="hint">Satisfied? Render to mp4:</span>
+        voxflow slice render &lt;your-deck.json&gt; --output out.mp4
+    </div>
+</body>
+</html>`;
+}
+async function preview(opts) {
+    const deckPath = path.resolve(opts.deckPath);
+    if (!fs.existsSync(deckPath)) {
+        throw new Error(`Deck file not found: ${deckPath}`);
+    }
+    const raw = fs.readFileSync(deckPath, 'utf8');
+    let deck;
+    try {
+        deck = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`Could not parse deck JSON: ${err.message}`);
+    }
+    if (isV2LayoutTreeDeck(deck)) {
+        throw new Error(
+            'V2 LayoutTree decks are not yet supported by offline preview. ' +
+            'Use voxflow.studio/apps/slice for V2 decks or downgrade to V1 shape.'
+        );
+    }
+    validatePaperSlideDeck(deck);
+    const theme = deck.theme || DEFAULT_THEME;
+    const compId = THEME_TO_DECK_ID[theme];
+    if (!compId) {
+        throw new Error(
+            `Unknown theme "${theme}". Valid: ${Object.keys(THEME_TO_DECK_ID).join(', ')}`
+        );
+    }
+    const serveUrl = resolveServeUrl();
+    const inputProps = buildInputProps(deck);
+    const cacheDir = path.join(os.tmpdir(), `voxflow-preview-${deckHash(deck)}`);
+    fs.mkdirSync(cacheDir, { recursive: true });
+    // Lazy require — mirrors slice-render.js — keeps `voxflow login` etc. fast
+    // for users who never trigger Remotion.
+    const { selectComposition, renderStill } = require('@remotion/renderer');
+    const coldStart = !chromeBinaryExists();
+    if (coldStart) {
+        console.log('  First-run: Remotion will download chrome-headless-shell (~90 MB).');
+    }
+    console.log(`[slice preview] theme: ${theme}`);
+    console.log(`[slice preview] composition: ${compId}`);
+    console.log(`[slice preview] cards: ${deck.cards.length}`);
+    const composition = await selectComposition({
+        serveUrl,
+        id: compId,
+        inputProps,
+    });
+    const t0 = Date.now();
+    const cachedCount = deck.cards.filter((_, i) =>
+        fs.existsSync(path.join(cacheDir, `card-${i}.png`))
+    ).length;
+    if (cachedCount === deck.cards.length) {
+        console.log(`[slice preview] all ${cachedCount} stills cached — skipping render`);
+    } else {
+        for (let i = 0; i < deck.cards.length; i++) {
+            const outPath = path.join(cacheDir, `card-${i}.png`);
+            if (fs.existsSync(outPath)) continue;
+            const frame = cardMidpointFrame(deck, i);
+            process.stdout.write(`\r[slice preview] rendering still ${i + 1}/${deck.cards.length}...`);
+            await renderStill({
+                composition,
+                serveUrl,
+                inputProps,
+                frame,
+                output: outPath,
+                imageFormat: 'png',
+                scale: PREVIEW_WIDTH / 1080, // halve the resolution for snappier renders
+            });
+        }
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+        process.stdout.write(`\r[slice preview] ${deck.cards.length} stills rendered in ${elapsed}s\n`);
+    }
+    const port = await findFreePort(DEFAULT_PORT);
+    const html = renderHtml(deck, port);
+    const server = http.createServer((req, res) => {
+        const urlPath = (req.url || '/').split('?')[0];
+        if (urlPath === '/' || urlPath === '/index.html') {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(html);
+            return;
+        }
+        const m = /^\/still\/(\d+)\.png$/.exec(urlPath);
+        if (m) {
+            const idx = Number(m[1]);
+            const file = path.join(cacheDir, `card-${idx}.png`);
+            if (!fs.existsSync(file)) {
+                res.writeHead(404);
+                res.end('still not found');
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'image/png', 'Cache-Control': 'public, max-age=600' });
+            fs.createReadStream(file).pipe(res);
+            return;
+        }
+        res.writeHead(404);
+        res.end('Not found');
+    });
+    await new Promise((resolve) => server.listen(port, '127.0.0.1', resolve));
+    const url = `http://localhost:${port}`;
+    console.log(`[slice preview] http://localhost:${port}  (Ctrl+C to stop)`);
+    try {
+        await open(url);
+    } catch {
+        // open failed — user can paste the URL manually
+    }
+    process.stdin.resume();
+    process.on('SIGINT', () => {
+        console.log('\n[slice preview] stopped');
+        server.close(() => process.exit(0));
+    });
+}
+async function handle(args) {
+    const { parseFlag } = require('../core/args');
+    const positional = args.find((a) => !a.startsWith('-'));
+    parseFlag(args, '--output', '-o'); // parsed-but-ignored for symmetry with `slice render`
+    if (!positional) {
+        console.error('Usage: voxflow slice preview <deck.json>');
+        process.exit(1);
+    }
+    try {
+        await preview({ deckPath: positional });
+    } catch (err) {
+        console.error(`\nslice preview failed: ${err.message}`);
+        if (process.env.VOXFLOW_DEBUG) console.error(err.stack);
+        process.exit(1);
+    }
+}
+module.exports = {
+    preview,
+    handle,
+};

package/lib/commands/slice-render.js ADDED Viewed

@@ -0,0 +1,282 @@
+'use strict';
+/**
+ * `voxflow slice render <deck.json>` — offline local Remotion render.
+ *
+ * Reads a validator-shaped deck.json, transforms it into PaperSlideDeck
+ * composition input props, and renders directly to MP4 via the pre-bundled
+ * Remotion serveUrl at `cli/dist/remotion-bundle/`. No VoxFlow API call,
+ * no TTS, no quota — Phase 0 is silent video; Phase 1 will add local TTS.
+ *
+ * No `meta` export — reached only via `slice.js` dispatch (`voxflow slice
+ * render <path>`), so it stays out of the registry parity test (the same
+ * pattern slice-stage.js uses).
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { validatePaperSlideDeck, isV2LayoutTreeDeck } = require('../internal/deck-validator');
+const SLICE_THEME_REGISTRY = require('../internal/slice-themes.json');
+const THEME_TO_DECK_ID = Object.fromEntries(
+    SLICE_THEME_REGISTRY.themes.map((t) => [t.id, t.remotion.deck])
+);
+const DEFAULT_THEME = SLICE_THEME_REGISTRY.default;
+// Composition FPS is fixed at 30 across every theme's <Composition> in
+// video-present/src/Root.tsx. Captured here as documentation; the actual
+// frames-per-second comes back from selectComposition() at runtime.
+const DEFAULT_CARD_SEC = 4;
+/**
+ * Transform a validator-shaped deck (cards[].kind/title/caption/...) into
+ * PaperSlideDeckProps (cards[].slide + cards[].durationSec) so the same
+ * deck schema users author in Claude maps cleanly onto every Remotion deck
+ * composition without going through the cloud render-worker pipeline.
+ *
+ * Phase 0 is silent — every card gets DEFAULT_CARD_SEC. Phase 1 will
+ * splice per-card TTS in and replace this with audio-driven durations.
+ */
+function buildInputProps(deck) {
+    const numberBadge = null;
+    const cards = deck.cards.map((card) => {
+        const slide = {
+            kind: card.kind,
+            header: deck.header,
+            title: card.kind === 'title' ? card.title || [] : [],
+            caption: card.caption ?? null,
+            figureKeyword: card.figureKeyword ?? null,
+            seriesTitle: deck.seriesTitle,
+            seriesTagline: deck.seriesTagline,
+            voiceoverSrc: null,
+            numberBadge,
+            imageUrl: card.imageUrl,
+        };
+        if (deck.variantId) slide.variantId = deck.variantId;
+        return { slide, durationSec: card.durationSec || DEFAULT_CARD_SEC };
+    });
+    return { cards };
+}
+function humanSize(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+function fmtSec(ms) {
+    const s = ms / 1000;
+    if (s < 60) return `${s.toFixed(1)}s`;
+    const m = Math.floor(s / 60);
+    const rem = (s - m * 60).toFixed(0);
+    return `${m}m${rem.padStart(2, '0')}s`;
+}
+function resolveServeUrl() {
+    // dist/remotion-bundle is generated by `npm run build:bundle` at CLI
+    // prepublish. Local dev: rebuild after a Remotion edit (`cd cli && npm
+    // run build:bundle`). Path is intentionally relative to this file so
+    // both the unbundled source layout and the ncc-bundled dist/ resolve
+    // to the same on-disk artifact (dist/remotion-bundle is shipped flat
+    // in the npm tarball).
+    // Two layouts to support:
+    //  - Source/dev (`node bin/voxflow.js`): __dirname = cli/lib/commands/
+    //    → `../../dist/remotion-bundle` = cli/dist/remotion-bundle
+    //  - ncc-published (`voxflow ...` from npm tarball): __dirname = <pkg>/dist/
+    //    → `remotion-bundle` (sibling of bundled index.js)
+    const candidates = [
+        path.resolve(__dirname, '../../dist/remotion-bundle'),
+        path.resolve(__dirname, 'remotion-bundle'),
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(path.join(c, 'index.html'))) return c;
+    }
+    throw new Error(
+        `Pre-bundled Remotion serveUrl not found at ${candidates.join(' or ')}.\n` +
+        '  Run `cd cli && npm run build:bundle` from the monorepo first.'
+    );
+}
+/**
+ * Heuristic: Remotion downloads chrome-headless-shell into node_modules/.remotion
+ * the FIRST time the renderer is invoked. After that it's cached.
+ *
+ * We probe for the binary so we can give the user a clear "first-run wait"
+ * message instead of leaving them staring at a silent terminal for a minute.
+ */
+function chromeBinaryExists() {
+    // Remotion stores the downloaded chrome-headless-shell next to whatever
+    // node_modules/ contains @remotion/renderer at runtime. In a flat
+    // consumer install that's `<pkg>/node_modules/.remotion/`; in a hoisted
+    // monorepo it's the hoist root. We probe both CWD-based and renderer-
+    // resolved ancestors so a warm install is detected regardless of layout.
+    const candidates = new Set();
+    const addAncestors = (start) => {
+        let dir = start;
+        for (let i = 0; i < 12; i++) {
+            candidates.add(path.join(dir, 'node_modules', '.remotion', 'chrome-headless-shell'));
+            candidates.add(path.join(dir, '.remotion', 'chrome-headless-shell'));
+            const parent = path.dirname(dir);
+            if (parent === dir) break;
+            dir = parent;
+        }
+    };
+    addAncestors(process.cwd());
+    addAncestors(__dirname);
+    try {
+        const rendererPkgPath = require.resolve('@remotion/renderer/package.json');
+        addAncestors(path.dirname(rendererPkgPath));
+    } catch {
+        // renderer not installed — definitely cold
+    }
+    for (const cand of candidates) {
+        if (fs.existsSync(cand)) return true;
+    }
+    return false;
+}
+async function render(opts) {
+    const deckPath = path.resolve(opts.deckPath);
+    if (!fs.existsSync(deckPath)) {
+        throw new Error(`Deck file not found: ${deckPath}`);
+    }
+    const raw = fs.readFileSync(deckPath, 'utf8');
+    let deck;
+    try {
+        deck = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`Could not parse deck JSON: ${err.message}`);
+    }
+    // V2 LayoutTree decks have `cards[].children[]` — different shape than
+    // the V1 PaperSlide deck this renderer expects. V1 validator doesn't
+    // catch V2 input (V2 cards happen to satisfy V1's kind/narration checks)
+    // so without an explicit guard, render() would silently produce a deck
+    // with undefined caption/figureKeyword on every card and Remotion would
+    // happily render blank slides. Fail loud instead.
+    if (isV2LayoutTreeDeck(deck)) {
+        throw new Error(
+            'V2 LayoutTree decks are not yet supported by offline render. ' +
+            'Use voxflow.studio/apps/slice for V2 decks or downgrade to V1 shape.'
+        );
+    }
+    // Run the same validator the production cloud route uses — so an offline
+    // render fails fast on the same shape errors the backend would reject.
+    validatePaperSlideDeck(deck);
+    const theme = deck.theme || DEFAULT_THEME;
+    const deckId = THEME_TO_DECK_ID[theme];
+    if (!deckId) {
+        throw new Error(
+            `Unknown theme "${theme}". Valid: ${Object.keys(THEME_TO_DECK_ID).join(', ')}`
+        );
+    }
+    const outputPath = path.resolve(
+        opts.output || path.join(process.cwd(), 'out.mp4')
+    );
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+    const serveUrl = resolveServeUrl();
+    const inputProps = buildInputProps(deck);
+    // Lazy require so users who never run `slice render` don't pay the
+    // remotion install cost at CLI startup (renderer pulls in puppeteer-
+    // core + chromium glue, ~30 MB on disk).
+    const { selectComposition, renderMedia } = require('@remotion/renderer');
+    const coldStart = !chromeBinaryExists();
+    if (coldStart) {
+        console.log('  First-run: Remotion will download chrome-headless-shell (~90 MB).');
+        console.log('  Allow ~30-60 s for the one-time download, then ~30 s for the render itself.');
+    }
+    console.log(`[slice render] theme: ${theme}`);
+    console.log(`[slice render] composition: ${deckId}`);
+    console.log(`[slice render] cards: ${deck.cards.length}`);
+    console.log(`[slice render] output: ${outputPath}`);
+    const t0 = Date.now();
+    const composition = await selectComposition({
+        serveUrl,
+        id: deckId,
+        inputProps,
+    });
+    const totalFrames = composition.durationInFrames;
+    const videoSec = totalFrames / composition.fps;
+    console.log(
+        `[slice render] duration: ${videoSec.toFixed(1)}s ` +
+        `(${totalFrames} frames @ ${composition.fps} fps, ` +
+        `${composition.width}x${composition.height})`
+    );
+    let lastFrame = 0;
+    let lastLog = 0;
+    await renderMedia({
+        composition,
+        serveUrl,
+        codec: 'h264',
+        outputLocation: outputPath,
+        inputProps,
+        imageFormat: 'jpeg',
+        jpegQuality: 85,
+        concurrency: 4,
+        x264Preset: 'ultrafast',
+        chromiumOptions: { gl: 'swiftshader' },
+        offthreadVideoCacheSizeInBytes: 512 * 1024 * 1024,
+        onProgress: ({ progress, renderedFrames }) => {
+            lastFrame = renderedFrames;
+            const now = Date.now();
+            // Throttle to ~2 lines/sec so the terminal stays scrollable in
+            // dev and so AI agents reading stdout aren't flooded.
+            if (now - lastLog < 500 && progress < 1) return;
+            lastLog = now;
+            const elapsed = now - t0;
+            const pct = Math.round(progress * 100);
+            process.stdout.write(
+                `\r[slice render] frame ${renderedFrames}/${totalFrames} ` +
+                `(${pct}%) — elapsed ${fmtSec(elapsed)}    `
+            );
+        },
+    });
+    const totalMs = Date.now() - t0;
+    process.stdout.write('\n');
+    const stat = fs.statSync(outputPath);
+    console.log(`[slice render] done in ${fmtSec(totalMs)} — ${humanSize(stat.size)}`);
+    console.log(`[slice render] saved to ${outputPath}`);
+    return { outputPath, totalMs, frames: lastFrame, size: stat.size };
+}
+async function handle(args) {
+    const { parseFlag } = require('../core/args');
+    const output = parseFlag(args, '--output', '-o');
+    const positional = args.find(
+        (a) => !a.startsWith('-') && !a.startsWith('--')
+    );
+    if (!positional) {
+        console.error('Usage: voxflow slice render <deck.json> [--output out.mp4]');
+        process.exit(1);
+    }
+    try {
+        await render({ deckPath: positional, output });
+    } catch (err) {
+        console.error(`\nslice render failed: ${err.message}`);
+        if (process.env.VOXFLOW_DEBUG) console.error(err.stack);
+        process.exit(1);
+    }
+}
+module.exports = {
+    render,
+    handle,
+    buildInputProps,
+    resolveServeUrl,
+    chromeBinaryExists,
+    THEME_TO_DECK_ID,
+    DEFAULT_THEME,
+};