SceneFromSpec
Compiles a YAML-shaped scene spec into a Remotion scene for either orientation, with timed blocks, explicit layouts, orientation overrides, and configurable safe areas.
Loading preview…
Install
npx shadcn@latest add @jbm/scene-specNeeds the @jbm entry in components.json; see Install once.
Also installs @jbm/tokens, @jbm/label, @jbm/big, @jbm/chip, @jbm/stat-card, @jbm/callout, @jbm/bullet-list, @jbm/scene, @jbm/pop, @jbm/code-card, @jbm/brand, @jbm/rebuild-screens, @jbm/catalog, @jbm/propagate, @jbm/shelf.
Needs Remotion: render inside a Remotion <Composition> or <Player>, not a plain React tree. Timing values are in seconds.
- Docs
- Schema
Usage
import { SceneFromSpec } from "@/jbm/motion/compile"import type { ScenesFile } from "@/jbm/motion/spec"// Placeholders: a parsed, schema-validated scenes file, and seconds from scene start per phrase.declare const scenes: ScenesFiledeclare const timings: Record<string, number>export const FirstScene = () => ( <SceneFromSpec spec={scenes.scenes[0]} orientation="landscape" host={{ resolve: (phrase) => timings[phrase] }} />)// Every block and field: https://jbm-ui.bns.studio/docs/scene-spec.mdimport type { SceneSpec } from "@/jbm/motion/spec"const spec: SceneSpec = { id: "library", anchors: { build: "una biblioteca" }, composition: { safeArea: "full", layout: "headline-illustration", subjectScale: 1.3 }, variants: { vertical: { headlineRatio: 0.23, gap: 48 } }, blocks: [ { type: "big", at: 0, text: "Una biblioteca.\nMuchas posibilidades.", align: "center", size: 90 }, { type: "screens", pieces: [{ kind: "card", at: "build" }, { kind: "button", at: "build+0.6" }], phoneScale: 1.5 }, ],}import { load } from "js-yaml"import Ajv2020 from "ajv/dist/2020"import { SceneFromSpec } from "@/jbm/motion/compile"import type { ScenesFile } from "@/jbm/motion/spec"import schema from "./scene-spec.schema.json" // curl -o scene-spec.schema.json https://jbm-ui.bns.studio/schemas/scene-spec.json// Placeholders: the YAML source, seconds from scene start per phrase, and a translator.declare const yamlText: stringdeclare const timings: Record<string, number>declare const translate: (text: string) => stringconst validate = new Ajv2020({ allErrors: true }).compile(schema)const data: unknown = load(yamlText)if (!validate(data)) throw new Error(JSON.stringify(validate.errors, null, 2))const { scenes } = data as ScenesFileexport const FirstScene = () => ( <SceneFromSpec spec={scenes[0]} orientation="vertical" host={{ resolve: (phrase) => timings[phrase], t: translate }} />)import { Composition, Series } from "remotion"import { loadFont as loadGeist } from "@remotion/google-fonts/Geist"import { loadFont as loadGeistMono } from "@remotion/google-fonts/GeistMono"import { load } from "js-yaml"import Ajv2020 from "ajv/dist/2020"import { SceneFromSpec } from "@/jbm/motion/compile"import type { ScenesFile } from "@/jbm/motion/spec"import schema from "./scene-spec.schema.json" // curl -o scene-spec.schema.json https://jbm-ui.bns.studio/schemas/scene-spec.json// npm install remotion @remotion/google-fonts js-yaml ajv (and @types/js-yaml).// Token font stacks fall back to the family names "Geist" and "Geist Mono" these load.loadGeist("normal", { weights: ["400", "500", "600", "700"], subsets: ["latin"] })loadGeistMono("normal", { weights: ["400", "500"], subsets: ["latin"] })const FPS = 30const yamlText = `scenes: - id: hook anchors: { reveal: "hecha de piezas" } blocks: - { type: big, at: 0, text: "Una biblioteca." } - { type: note, at: reveal, text: "Hecha de piezas." } - id: pieces composition: { safeArea: full, layout: illustration } anchors: { build: "una pieza" } blocks: - type: screens pieces: - { kind: card, at: build } - { kind: button, at: build+0.6 }`// No narration yet: a literal phrase → seconds (from its scene's start) table, and scene lengths.const timings: Record<string, number> = { "hecha de piezas": 1.2, "una pieza": 0.8 }const seconds: Record<string, number> = { hook: 4, pieces: 5 }const resolve = (phrase: string) => { const at = timings[phrase] if (at === undefined) throw new Error(`No timing for "${phrase}"`) return at}const validate = new Ajv2020({ allErrors: true }).compile(schema)const data: unknown = load(yamlText)if (!validate(data)) throw new Error(JSON.stringify(validate.errors, null, 2))const { scenes } = data as ScenesFileconst frames = (id: string) => Math.round(seconds[id] * FPS)// One Series.Sequence per scene: each scene's times start at 0 inside its own sequence.export const Explainer = () => ( <Series> {scenes.map((spec) => ( <Series.Sequence key={spec.id} durationInFrames={frames(spec.id)}> <SceneFromSpec spec={spec} orientation="vertical" host={{ resolve }} /> </Series.Sequence> ))} </Series>)// Register in your Remotion root (registerRoot). Use 1920×1080 with orientation="landscape".export const RemotionRoot = () => ( <Composition id="explainer-vertical" component={Explainer} width={1080} height={1920} fps={FPS} durationInFrames={scenes.reduce((total, spec) => total + frames(spec.id), 0)} />)API
- Stage px
- Declared at the documented defaults
- Landscape
1920 by 1080- Vertical
1080 by 1920- Basis
SceneFromSpec renders a Scene that fills its parent (position absolute, inset 0); use a 1920 × 1080 composition for landscape and 1080 × 1920 for vertical. Blocks lay out inside sceneGeometry(orientation, safeArea).
SceneFromSpeccomponent
Renders one SceneSpec as a full-canvas Scene for one orientation. Blocks (big, stat-row, note, callout, bullets, chips, code, spacer, screens, catalog, propagate, shelf, twice, brand, overlay) stack inside the safe area with gap between them; composition and variants[orientation] choose the layout (flow, hero, headline-illustration, illustration), safe area, headline ratio, subject scale, and optional block overrides. Anchors resolve through host.resolve, text through host.t. It does not fit, shrink, or paginate content, and throws on invalid layouts, anchors, gaps, or insets. It does not validate the spec's shape (an unknown block type renders nothing): validate parsed YAML against the JSON Schema in schemas first. Every block, field, default, unit, and error is listed in the scene spec guide in docs.
| Prop | Type | Default | Description |
|---|---|---|---|
spec | SceneSpec | required | One parsed scene (SceneSpec): required id and blocks; optional anchors (needed only when a block time names an anchor), title, starts, composition, variants, gap, and valign. The compiler takes plain objects; parse YAML in the host (the guide uses js-yaml 4 load) and validate against #/$defs/SceneSpec of the JSON Schema. |
showSafeArea | boolean | false | Draws a dashed vermilion outline of the safe area for debugging; leave off for final renders. |
orientation | Orientation | required | landscape (for a 1920 × 1080 composition) or vertical (1080 × 1920); picks stage geometry, block sizes, and variants. |
host | Host | required | Injected services: resolve(phrase) returns seconds from scene start for an anchor's narration phrase; optional t(string) translates on-screen text. |
resolveAtfunction
Resolves a block time: a number of seconds, an anchor name, or an anchor with a signed offset such as "explain+0.2".
| Param | Type | Default | Description |
|---|---|---|---|
at | At | required | Seconds from scene start, or an anchor name with an optional +/- offset in seconds. |
spec | SceneSpec | required | The scene whose anchors map names to narration phrases; its id appears in errors. |
host | Host | required | Supplies resolve(phrase) in seconds. |
Returns Seconds from scene start. Throws on malformed, unknown, or non-finite anchors.
sceneGeometryfunction
Safe-area rectangle in canvas pixels for an orientation and safe-area preset or custom insets.
| Param | Type | Default | Description |
|---|---|---|---|
orientation | Orientation | required | landscape or vertical; selects stage[orientation]. |
safeArea | SafeArea | "legacy" | legacy (default; portrait bottom 480), full (portrait 100/72/100/72, landscape 90/120/90/120), social (portrait 160/160/320/72), or explicit { top, right, bottom, left } insets. |
Returns { left, top, width, height } in canvas pixels. Throws when insets are negative, non-finite, or leave no content area.
Hosttype
Timing and translation services injected by the video project: resolve(phrase) and optional t(s).
SceneSpectype
One scene: required id and blocks; optional anchors, title, starts, composition, variants, gap, valign.
ScenesFiletype
The parsed YAML file: { scenes: SceneSpec[] }.
Blocktype
Any block body plus an optional until exit cue.
CompositionOptionstype
safeArea, layout, headlineRatio, subjectScale, gap, valign, and an optional full blocks override.
SafeAreatype
"legacy" | "full" | "social" | explicit pixel insets { top, right, bottom, left }. Social applies to vertical only; in landscape it falls back to full (90/120/90/120).
PerOrientationtype
{ landscape, vertical } pixel values, accepted wherever a size may differ per orientation (gap, spacer h, screens and propagate h).
StatItemtype
One stat-row card: at, label, value, optional sub and valueColor.
Exittype
The optional until cue every block accepts: fade out and drift up over 0.4 s.
BlockBodytype
The block union without until, discriminated by type.
SceneLayouttype
"flow" | "hero" | "headline-illustration" | "illustration".
Attype
A time: anchor name (optionally with an offset) or seconds.
QA checks
- Switch the preview through hero, headline-illustration, and illustration layouts and full/social safe areas; inspect beginning, middle, and end frames in both landscape and portrait.
- Turn guides on to see the safe area, then confirm showSafeArea is off in final renders.
- Nothing auto-fits: check tall content (code, stat rows, long headlines) for overflow or clipping at the safe-area edges, especially in portrait.
- Exercise error paths: unknown anchors, headline-illustration with other than two blocks or with a title, and invalid gap or insets must throw with the scene id or a clear message.