video: point explanations at the diagram, extend scenes for readable dwell

Explanations become Callout chips (kit.tsx): a leader line draws from the
target element, the chip fades in only after the line completes, timed to
the scene beat. The fixed bottom bullet row in SceneChrome is deleted.
Leaders stop at element outer edges; chips sit fully outside each visual
group (Pipeline push callout narrowed clear of the group box).

Timeline 62s -> 81s (2425 frames): every callout holds >=150 frames after
it appears; scene beats unchanged, hold time added at each scene end.
.vtt cue times, EN+VI chapter times, README take minimums (24s/17s) and
spec-v7 scene table, no-overlap and dwell rules follow the new boundaries.
Re-rendered public/media/how-it-works.mp4.
This commit is contained in:
dong.nguyen committed 2026-10-29 00:38:07 +07:00
1 parent aad36e38fc
commit e02fe19bbe
13 files changed
+221 -112

No files matched your search

+8 -6
View File
@@ -22,8 +22,8 @@ screen recorder:
| File (drop into `video/inputs/`) | Beat | Minimum length |
|---|---|---|
| `take-edit.mp4` | open the live site → append `?edit` → Basic-auth sign-in → edit one heading inline → Save | 18 s |
| `take-pipeline.mp4` | GitHub Actions run: build → generate-resume → deploy, then the updated live page | 12 s |
| `take-edit.mp4` | open the live site → append `?edit` → Basic-auth sign-in → edit one heading inline → Save | 24 s |
| `take-pipeline.mp4` | GitHub Actions run: build → generate-resume → deploy, then the updated live page | 17 s |
Record at 1920×1080, browser zoom 100%, dark theme. Trim so each take starts
clean (no cursor scrubbing). Then:
@@ -34,8 +34,10 @@ pnpm --dir video render-captured
Raw takes are gitignored — the rendered MP4 is the committed artifact.
## Timeline (source of truth: `src/Explainer.tsx`)
## Timeline (source of truth: `src/timeline.ts`)
30 fps · 1860 frames · 62 s. Scene boundaries drive the chapter list and the
`.vtt` caption tracks in `public/media/` — if the timeline changes, those and
the `howItWorks` UI group's chapters must change with it.
30 fps · 2425 frames · 81 s. Scene durations include ≥5 s of hold time after
the last callout so every on-screen explanation is readable before the cut.
Scene boundaries drive the chapter list and the `.vtt` caption tracks in
`public/media/` — if the timeline changes, those and the `howItWorks` UI
group's chapters (EN + VI) must change with it.
+66 -29
View File
@@ -1,6 +1,6 @@
import React from 'react';
import { useCurrentFrame } from 'remotion';
import { appear } from './motion';
import { appear, drawIn } from './motion';
import { theme } from './theme';
export const Fade: React.FC<{ start: number; y?: number; children: React.ReactNode }> = ({
@@ -15,36 +15,73 @@ export const Fade: React.FC<{ start: number; y?: number; children: React.ReactNo
);
};
export const SceneChrome: React.FC<{
index: string;
title: string;
bullets: string[];
bulletStart?: number;
}> = ({ index, title, bullets, bulletStart = 60 }) => (
<>
<div style={{ position: 'absolute', top: 80, left: 120 }}>
<Fade start={4}>
<div style={{ fontSize: 20, letterSpacing: '0.22em', color: theme.accent }}>{index}</div>
</Fade>
<Fade start={14} y={20}>
<div style={{ fontSize: 44, fontWeight: 650, color: theme.textPrimary, marginTop: 10 }}>
{title}
</div>
</Fade>
</div>
<div style={{ position: 'absolute', left: 120, bottom: 90, maxWidth: 700 }}>
{bullets.map((b, i) => (
<Fade key={i} start={bulletStart + i * 40}>
<div style={{ display: 'flex', gap: 14, marginBottom: 16 }}>
<span style={{ color: theme.accent, fontSize: 22, lineHeight: 1.45 }}>▸</span>
<span style={{ fontSize: 23, color: theme.textSecondary, lineHeight: 1.45 }}>{b}</span>
</div>
</Fade>
))}
</div>
</>
export const SceneChrome: React.FC<{ index: string; title: string }> = ({ index, title }) => (
<div style={{ position: 'absolute', top: 80, left: 120 }}>
<Fade start={4}>
<div style={{ fontSize: 20, letterSpacing: '0.22em', color: theme.accent }}>{index}</div>
</Fade>
<Fade start={14} y={20}>
<div style={{ fontSize: 44, fontWeight: 650, color: theme.textPrimary, marginTop: 10 }}>
{title}
</div>
</Fade>
</div>
);
// A callout that points at a diagram element: the leader line draws only after
// the target has appeared, and the chip only after the line completes — the
// scene's explanations therefore follow the diagram beat by beat instead of
// sitting in a fixed text row. `target` is the anchor on the element, `anchor`
// the chip-side end of the line.
export const Callout: React.FC<{
target: [number, number];
anchor: [number, number];
chip: { x: number; y: number; width: number };
start: number;
accent?: boolean;
children: string;
}> = ({ target, anchor, chip, start, accent, children }) => {
const frame = useCurrentFrame();
const line = drawIn(frame, start, 12);
const chipOn = appear(frame, start + 12);
return (
<>
<svg width={1920} height={1080} style={{ position: 'absolute', inset: 0, pointerEvents: 'none' }}>
<line
x1={target[0]}
y1={target[1]}
x2={anchor[0]}
y2={anchor[1]}
stroke={accent ? theme.accent : theme.borderStrong}
strokeWidth={1.5}
pathLength={1}
strokeDasharray={1}
strokeDashoffset={line}
/>
</svg>
<div
style={{
position: 'absolute',
left: chip.x,
top: chip.y,
width: chip.width,
opacity: chipOn,
transform: `translateY(${(1 - chipOn) * 10}px)`,
background: theme.surface,
border: `1px solid ${accent ? theme.accent : theme.borderStrong}`,
borderRadius: 8,
padding: '8px 12px',
fontSize: 15,
color: theme.textSecondary,
lineHeight: 1.45,
}}
>
{children}
</div>
</>
);
};
export const Panel: React.FC<{
width: number;
accent?: boolean;
+21 -11
View File
@@ -1,6 +1,6 @@
import React from 'react';
import { AbsoluteFill, interpolate, useCurrentFrame } from 'remotion';
import { ArrowDefs, BrowserFrame, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit';
import { ArrowDefs, BrowserFrame, Callout, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit';
import { appear, drawIn } from '../motion';
import { theme } from '../theme';
@@ -22,16 +22,7 @@ export const DataLayer: React.FC = () => {
return (
<AbsoluteFill style={{ background: theme.bg, fontFamily: theme.sans }}>
<SceneBackground />
<SceneChrome
index="01 · CONTENT AS DOCUMENTS"
title="Everything the site shows is a JSON document"
bullets={[
'Structure documents — language-neutral ids and order',
'Per-language dictionaries — EN and VI text, joined at build time',
'Field manifests — a missing key fails the build, never the page',
]}
bulletStart={70}
/>
<SceneChrome index="01 · CONTENT AS DOCUMENTS" title="Everything the site shows is a JSON document" />
{DOCS.map((d, i) => (
<Fade key={d.path} start={30 + i * 28} y={22}>
@@ -112,6 +103,25 @@ export const DataLayer: React.FC = () => {
<div style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: 3, background: theme.accent, opacity: pageOn }} />
</BrowserFrame>
</Fade>
<Callout
target={[600, 672]}
anchor={[600, 693]}
chip={{ x: 420, y: 695, width: 380 }}
start={110}
>
Field manifests claim every field a page renders — a missing key fails the build, never a silent half-render.
</Callout>
<Callout
target={[1502, 350]}
anchor={[1537, 340]}
chip={{ x: 1540, y: 315, width: 340 }}
start={200}
accent
>
EN and VI render through the same components — the join happened once, at build time.
</Callout>
</AbsoluteFill>
);
};
+30 -11
View File
@@ -1,6 +1,6 @@
import React from 'react';
import { AbsoluteFill, interpolate, useCurrentFrame } from 'remotion';
import { ArrowDefs, Fade, Label, Mono, Panel, SceneBackground, SceneChrome } from '../kit';
import { ArrowDefs, Callout, Fade, Label, Mono, Panel, SceneBackground, SceneChrome } from '../kit';
import { appear, drawIn } from '../motion';
import { theme } from '../theme';
@@ -25,16 +25,7 @@ export const GitStorage: React.FC = () => {
return (
<AbsoluteFill style={{ background: theme.bg, fontFamily: theme.sans }}>
<SceneBackground />
<SceneChrome
index="03 · GIT AS THE STORAGE"
title="A content edit is a file edit"
bullets={[
'Drafts live on a branch; master stays the published site',
'A branch preview is a URL: ?edit=preview',
'History, review and rollback come from git, free of charge',
]}
bulletStart={70}
/>
<SceneChrome index="03 · GIT AS THE STORAGE" title="A content edit is a file edit" />
<Panel width={470} style={{ left: 480, top: 200 }}>
<div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline' }}>
@@ -129,6 +120,34 @@ export const GitStorage: React.FC = () => {
</span>
</div>
</Fade>
<Callout
target={[478, 300]}
anchor={[455, 262]}
chip={{ x: 130, y: 230, width: 320 }}
start={40}
>
Content is plain JSON documents in the repository — no database, no admin panel.
</Callout>
<Callout
target={[1253, 460]}
anchor={[1447, 435]}
chip={{ x: 1450, y: 400, width: 340 }}
start={110}
accent
>
Drafts live on a branch — ?edit=preview opens the same site on that branch.
</Callout>
<Callout
target={[700, 655]}
anchor={[700, 685]}
chip={{ x: 480, y: 690, width: 380 }}
start={125}
>
History, review and rollback come from git, free of charge.
</Callout>
</AbsoluteFill>
);
};
+40 -12
View File
@@ -1,6 +1,6 @@
import React from 'react';
import { AbsoluteFill, OffthreadVideo, staticFile, useCurrentFrame } from 'remotion';
import { BrowserFrame, Fade, Label, Mono, PageSkeleton, SceneBackground, SceneChrome } from '../kit';
import { BrowserFrame, Callout, Fade, Label, Mono, PageSkeleton, SceneBackground, SceneChrome } from '../kit';
import { appear, typed } from '../motion';
import { theme } from '../theme';
@@ -46,17 +46,7 @@ export const LiveEdit: React.FC<{ captured: boolean }> = ({ captured }) => {
return (
<AbsoluteFill style={{ background: theme.bg, fontFamily: theme.sans }}>
<SceneBackground />
<SceneChrome
index="02 · LIVE EDITING"
title="?edit turns the live site into the editor"
bullets={[
'The page you are looking at becomes the editor — same components visitors see',
'HTTP Basic at the nginx proxy is the only gate',
'Text, tags, records and settings edit inline on the preview',
'Every save is a commit through the GitHub Contents API',
]}
bulletStart={70}
/>
<SceneChrome index="02 · LIVE EDITING" title="?edit turns the live site into the editor" />
<BrowserFrame
width={760}
@@ -168,6 +158,44 @@ export const LiveEdit: React.FC<{ captured: boolean }> = ({ captured }) => {
</>
)}
</BrowserFrame>
<Callout
target={[1342, 232]}
anchor={[1367, 228]}
chip={{ x: 1370, y: 205, width: 330 }}
start={150}
accent
>
?edit attaches edit mode — the very page being viewed becomes the editor.
</Callout>
<Callout
target={[578, 450]}
anchor={[505, 450]}
chip={{ x: 140, y: 420, width: 360 }}
start={215}
>
HTTP Basic at the nginx proxy is the only gate — the site itself carries no accounts system.
</Callout>
<Callout
target={[578, 242]}
anchor={[505, 252]}
chip={{ x: 140, y: 235, width: 360 }}
start={325}
>
Text, tags, records and settings edit inline — pencil-triggered, commit on blur, Vietnamese-IME safe.
</Callout>
<Callout
target={[700, 762]}
anchor={[700, 795]}
chip={{ x: 600, y: 800, width: 420 }}
start={465}
accent
>
Every save is a commit through the GitHub Contents API; a 409 conflict three-way rebases and keeps your edit.
</Callout>
</AbsoluteFill>
);
};
+21 -11
View File
@@ -1,6 +1,6 @@
import React from 'react';
import { AbsoluteFill, OffthreadVideo, staticFile, useCurrentFrame } from 'remotion';
import { ArrowDefs, BrowserFrame, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit';
import { ArrowDefs, BrowserFrame, Callout, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit';
import { appear, drawIn } from '../motion';
import { theme } from '../theme';
@@ -29,16 +29,7 @@ export const Pipeline: React.FC<{ captured: boolean }> = ({ captured }) => {
return (
<AbsoluteFill style={{ background: theme.bg, fontFamily: theme.sans }}>
<SceneBackground />
<SceneChrome
index="04 · AUTO DEPLOYMENT"
title="Merge to master — the pipeline ships it"
bullets={[
'GitHub Actions runs deploy.yml: build · resume PDFs · deploy',
'nginx.conf / compose.yaml changes redeploy the stack itself',
'No CMS, no manual upload: push to master is the publish button',
]}
bulletStart={70}
/>
<SceneChrome index="04 · AUTO DEPLOYMENT" title="Merge to master — the pipeline ships it" />
<Fade start={10}>
<Panel width={210} style={{ left: 449, top: 210 }}>
@@ -129,6 +120,25 @@ export const Pipeline: React.FC<{ captured: boolean }> = ({ captured }) => {
)}
</BrowserFrame>
</Fade>
<Callout
target={[555, 322]}
anchor={[555, 347]}
chip={{ x: 449, y: 350, width: 230 }}
start={30}
accent
>
No CMS, no manual upload — the push to master is the publish button.
</Callout>
<Callout
target={[1457, 560]}
anchor={[1467, 545]}
chip={{ x: 1470, y: 500, width: 330 }}
start={245}
>
From commit to live in minutes — the updated page is the receipt.
</Callout>
</AbsoluteFill>
);
};
+9 -6
View File
@@ -8,13 +8,16 @@ export type ExplainerProps = z.infer<typeof explainerProps>;
// Scene timeline (30 fps). These boundaries are the source of truth for the
// chapter list and the .vtt caption tracks on the site page.
// Dwell rule: every callout chip stays on screen at least 150 frames (5 s)
// before its scene switches — a ~25-word chip needs a calm read, not a glance.
// Scene beats are unchanged; the added frames are hold time at the end.
export const SCENES = [
{ id: 'title', from: 0, duration: 165 },
{ id: 'data', from: 165, duration: 255 },
{ id: 'edit', from: 420, duration: 540 },
{ id: 'git', from: 960, duration: 330 },
{ id: 'pipeline', from: 1290, duration: 360 },
{ id: 'outro', from: 1650, duration: 210 },
{ id: 'data', from: 165, duration: 420 },
{ id: 'edit', from: 585, duration: 700 },
{ id: 'git', from: 1285, duration: 420 },
{ id: 'pipeline', from: 1705, duration: 510 },
{ id: 'outro', from: 2215, duration: 210 },
] as const;
export const TOTAL_FRAMES = 1860;
export const TOTAL_FRAMES = 2425;