jbmui

SceneFromSpec

  • Layout
  • adjustable
  • replayable
  • landscape + vertical
  • video player

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-spec

Needs 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

Compile a parsed scene
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.md
Headline and illustration, tuned for portrait
import 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 },  ],}
Parse, validate, and compile a YAML scenes file
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 }} />)
Multi-scene vertical composition
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.

PropTypeDefaultDescription
specSceneSpecrequiredOne 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.
showSafeAreabooleanfalseDraws a dashed vermilion outline of the safe area for debugging; leave off for final renders.
orientationOrientationrequiredlandscape (for a 1920 × 1080 composition) or vertical (1080 × 1920); picks stage geometry, block sizes, and variants.
hostHostrequiredInjected 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".

ParamTypeDefaultDescription
atAtrequiredSeconds from scene start, or an anchor name with an optional +/- offset in seconds.
specSceneSpecrequiredThe scene whose anchors map names to narration phrases; its id appears in errors.
hostHostrequiredSupplies 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.

ParamTypeDefaultDescription
orientationOrientationrequiredlandscape or vertical; selects stage[orientation].
safeAreaSafeArea"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.