frameyard 0.7.0 → 0.9.0

package/examples/blend/README.md

@@ -0,0 +1,106 @@
+# Frameyard blend example
+
+A 12-second, 1920×1080, 30 fps timeline that demonstrates every supported CSS
+blend mode on composition and video clips. Four video tracks build one frame:
+
+- `v1` **backdrop** — a static opaque HTML composition with a grid, concentric
+  rings, and a dark vignette. It omits the time metadata and all dimensions, so
+  it inherits the project format and is captured once at the timeline's size.
+- `v2` **aurora** — a static transparent HTML composition with three blurred
+  color blobs. It declares its dimensions but no time metadata, so it is also
+  captured once. Its clip uses `blend: "screen"` for the full 12 seconds.
+- `v3` **ink** — a local 1280×720 H.264 clip scaled to fill the project frame.
+  Twelve touching clips play one second each, cycling through all 12 supported
+  modes in timeline order.
+- `v4` **labels** — an animated transparent HTML composition in normal mode. It
+  lists the modes and their time ranges, and draws a progress bar from the
+  `--fy-progress` frame-state variable, so it is evaluated per frame.
+
+The mode sequence on `v3` is:
+
+| Time | Mode |
+| --- | --- |
+| 0–1 s | `normal` |
+| 1–2 s | `multiply` |
+| 2–3 s | `screen` |
+| 3–4 s | `overlay` |
+| 4–5 s | `darken` |
+| 5–6 s | `lighten` |
+| 6–7 s | `color-dodge` |
+| 7–8 s | `color-burn` |
+| 8–9 s | `hard-light` |
+| 9–10 s | `soft-light` |
+| 10–11 s | `difference` |
+| 11–12 s | `exclusion` |
+
+The aurora is transparent, so its `screen` blends only where its blobs have
+alpha. The video is opaque, so its whole scaled frame participates in the blend.
+The labels layer stays in `normal` mode so the copy remains readable.
+
+Blend modes are static per clip. The example uses consecutive clips on `v3` to
+show every mode in one timeline; it does not animate `blend` itself. `hue`,
+`saturation`, `color`, and `luminosity` are rejected because they need
+cross-channel math and are not part of the supported set.
+
+`backdrop` and `aurora` are static compositions: they declare no
+`duration-in-frames` or `fps`, are captured once, and the same image is reused
+for every timeline frame. `labels` remains animated because its progress bar
+reads `--fy-progress`; making it static would freeze the bar.
+
+Preview composites with Chromium `mix-blend-mode`; production uses FFmpeg's
+`blend` filter plus an alpha mask. The preview stage stacks by track order and
+is isolated from the preview chrome. Small scaling, alpha, and color differences
+between preview and the final encode are expected.
+
+## Files
+
+```text
+examples/blend/
+  compositions/backdrop.html   opaque base composition
+  compositions/aurora.html     transparent screen layer
+  compositions/labels.html     transparent mode list and progress layer
+  timelines/blend.timeline.json
+  assets/ink.mp4               procedural 12-second source clip
+  scripts/make-ink.sh          regenerate assets/ink.mp4
+  fy.config.js
+```
+
+The timeline lives in `timelines/blend.timeline.json`; the project format and
+entries are fixed in `fy.config.js`. `backdrop.html` is a static composition
+that omits all dimensions and time metadata, so it inherits the project's
+1920×1080 size. `aurora.html` is a static composition that declares its
+dimensions but no time metadata. `labels.html` is an animated composition and
+keeps its `fps` and `duration-in-frames`.
+
+## Commands
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check blend-timeline --project examples/blend
+node dist/cli.js still blend-timeline --frame 15,45,75,105,135,165,195,225,255,285,315,345 --project examples/blend --out blend-stills
+node dist/cli.js still blend-timeline --frame 285 --project examples/blend --out blend-soft-light.png
+FRAMEYARD_POLICY=full node dist/cli.js render blend-timeline --project examples/blend
+node dist/cli.js dev --project examples/blend
+```
+
+The batch still captures one representative frame per mode into `blend-stills/`
+using the same clip capture and composite path as the render. `render` writes
+`out/blend-timeline.mp4` inside the project by default; use `--out <file.mp4>`
+to choose another path. `dev` lists the compositions and the timeline in the
+preview.
+
+## Source clip
+
+`assets/ink.mp4` is a 12-second, 1280×720, 30 fps rotating gradient with a
+silent AAC track, generated by FFmpeg. Regenerate it with:
+
+```sh
+bash examples/blend/scripts/make-ink.sh
+```
+
+Pass an output path as the first argument to write elsewhere. Replace
+`assets/ink.mp4` with any local, seekable MP4 or WebM that is at least 12 seconds
+long; remote URLs and live streams are not supported. If you use a different
+length, update the clip durations and source in-points in the timeline.

package/examples/blend/compositions/aurora.html

@@ -0,0 +1,55 @@
+<style>
+  html,
+  body,
+  fy-composition {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: transparent;
+  }
+  fy-composition {
+    display: block;
+    overflow: hidden;
+  }
+  .scene {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    isolation: isolate;
+  }
+  .blob {
+    position: absolute;
+    border-radius: 50%;
+    filter: blur(78px);
+    opacity: 0.9;
+  }
+  .pink {
+    left: 6%;
+    top: -18%;
+    width: 980px;
+    height: 980px;
+    background: radial-gradient(circle, rgba(255, 64, 164, 0.92), rgba(255, 64, 164, 0) 68%);
+  }
+  .blue {
+    right: -12%;
+    top: 4%;
+    width: 1180px;
+    height: 1180px;
+    background: radial-gradient(circle, rgba(46, 146, 255, 0.88), rgba(46, 146, 255, 0) 68%);
+  }
+  .amber {
+    left: 30%;
+    bottom: -30%;
+    width: 900px;
+    height: 900px;
+    background: radial-gradient(circle, rgba(255, 186, 72, 0.7), rgba(255, 186, 72, 0) 70%);
+  }
+</style>
+<fy-composition width="1920" height="1080">
+  <div class="scene">
+    <div class="blob pink"></div>
+    <div class="blob blue"></div>
+    <div class="blob amber"></div>
+  </div>
+</fy-composition>

package/examples/blend/compositions/backdrop.html

@@ -0,0 +1,74 @@
+<style>
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #05070d;
+  }
+  fy-composition {
+    display: block;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+  }
+  .scene {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background:
+      radial-gradient(1200px 760px at 72% 34%, rgba(42, 104, 220, 0.5), transparent 62%),
+      radial-gradient(860px 620px at 18% 82%, rgba(255, 76, 140, 0.14), transparent 64%),
+      linear-gradient(145deg, #060a12 0%, #0b1424 52%, #05070d 100%);
+  }
+  .grid {
+    position: absolute;
+    inset: -1px;
+    background-image:
+      linear-gradient(rgba(150, 190, 255, 0.075) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(150, 190, 255, 0.075) 1px, transparent 1px);
+    background-size: 72px 72px;
+  }
+  .fade {
+    position: absolute;
+    inset: 0;
+    background:
+      radial-gradient(ellipse at 58% 38%, transparent 18%, rgba(5, 7, 13, 0.55) 62%, rgba(5, 7, 13, 0.92) 100%),
+      linear-gradient(90deg, rgba(5, 7, 13, 0.5), transparent 38%, transparent 74%, rgba(5, 7, 13, 0.55));
+  }
+  .ring {
+    position: absolute;
+    left: 58%;
+    top: 44%;
+    width: 1060px;
+    height: 1060px;
+    border: 1px solid rgba(160, 205, 255, 0.18);
+    border-radius: 50%;
+    box-shadow:
+      0 0 140px rgba(54, 118, 255, 0.16) inset,
+      0 0 90px rgba(54, 118, 255, 0.08);
+    transform: translate(-50%, -50%);
+  }
+  .ring::before,
+  .ring::after {
+    content: "";
+    position: absolute;
+    border: 1px solid rgba(255, 118, 190, 0.13);
+    border-radius: 50%;
+  }
+  .ring::before {
+    inset: 138px;
+  }
+  .ring::after {
+    inset: 286px;
+    border-color: rgba(255, 179, 71, 0.12);
+  }
+</style>
+<fy-composition>
+  <div class="scene">
+    <div class="grid"></div>
+    <div class="ring"></div>
+    <div class="fade"></div>
+  </div>
+</fy-composition>

package/examples/blend/compositions/labels.html

@@ -0,0 +1,149 @@
+<style>
+  html,
+  body,
+  fy-composition {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: transparent;
+  }
+  fy-composition {
+    display: block;
+    overflow: hidden;
+  }
+  .scene {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    color: #eef4ff;
+    font-family: Inter, "Helvetica Neue", ui-sans-serif, system-ui, sans-serif;
+  }
+  .panel {
+    position: absolute;
+    left: 92px;
+    top: 96px;
+    width: 920px;
+    padding: 44px 46px 40px;
+    border: 1px solid rgba(160, 205, 255, 0.24);
+    border-radius: 22px;
+    background: linear-gradient(135deg, rgba(6, 12, 24, 0.91), rgba(6, 12, 24, 0.64));
+    box-shadow: 0 38px 110px rgba(0, 0, 0, 0.38);
+  }
+  .kicker {
+    color: #7fd6ff;
+    font-family: ui-monospace, "SFMono-Regular", "Cascadia Code", monospace;
+    font-size: 13px;
+    font-weight: 650;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+  }
+  h1 {
+    margin: 18px 0 14px;
+    font-size: 78px;
+    font-weight: 680;
+    letter-spacing: -0.045em;
+    line-height: 0.95;
+  }
+  h1 span {
+    color: #ffb347;
+  }
+  .subtitle {
+    margin: 0;
+    max-width: 780px;
+    color: #a9b8d0;
+    font-size: 20px;
+    line-height: 1.4;
+  }
+  .modes {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    gap: 14px 18px;
+    margin-top: 28px;
+  }
+  .modes div {
+    padding-top: 9px;
+    border-top: 2px solid rgba(127, 214, 255, 0.5);
+  }
+  .modes div:nth-child(4n + 2) {
+    border-top-color: rgba(255, 179, 71, 0.5);
+  }
+  .modes div:nth-child(4n + 3) {
+    border-top-color: rgba(255, 100, 180, 0.5);
+  }
+  .modes div:nth-child(4n + 4) {
+    border-top-color: rgba(160, 190, 255, 0.5);
+  }
+  .modes b {
+    display: block;
+    margin-bottom: 5px;
+    color: #eef4ff;
+    font-family: ui-monospace, "SFMono-Regular", "Cascadia Code", monospace;
+    font-size: 15px;
+    font-weight: 600;
+    letter-spacing: -0.01em;
+  }
+  .modes span {
+    display: block;
+    color: #7f90a8;
+    font-family: ui-monospace, "SFMono-Regular", "Cascadia Code", monospace;
+    font-size: 11px;
+  }
+  .foot {
+    margin-top: 26px;
+    color: #73839a;
+    font-family: ui-monospace, "SFMono-Regular", "Cascadia Code", monospace;
+    font-size: 12px;
+    line-height: 1.55;
+    letter-spacing: 0.03em;
+  }
+  .progress {
+    position: absolute;
+    left: 142px;
+    bottom: 92px;
+    width: 820px;
+    height: 3px;
+    overflow: hidden;
+    border-radius: 99px;
+    background: rgba(220, 235, 255, 0.16);
+  }
+  .progress::after {
+    content: "";
+    display: block;
+    width: calc(var(--fy-progress) * 100%);
+    height: 100%;
+    border-radius: inherit;
+    background: linear-gradient(90deg, #7fd6ff, #ffb347);
+  }
+</style>
+<fy-composition width="1920" height="1080" fps="30" duration-in-frames="360">
+  <div class="scene">
+    <div class="panel">
+      <div class="kicker">Frameyard / Blend lab</div>
+      <h1>12 modes.<br /><span>One timeline.</span></h1>
+      <p class="subtitle">
+        A composition stays on screen while the video clip cycles through every supported CSS blend mode, one second
+        each.
+      </p>
+      <div class="modes">
+        <div><b>normal</b><span>0–1s</span></div>
+        <div><b>multiply</b><span>1–2s</span></div>
+        <div><b>screen</b><span>2–3s</span></div>
+        <div><b>overlay</b><span>3–4s</span></div>
+        <div><b>darken</b><span>4–5s</span></div>
+        <div><b>lighten</b><span>5–6s</span></div>
+        <div><b>color-dodge</b><span>6–7s</span></div>
+        <div><b>color-burn</b><span>7–8s</span></div>
+        <div><b>hard-light</b><span>8–9s</span></div>
+        <div><b>soft-light</b><span>9–10s</span></div>
+        <div><b>difference</b><span>10–11s</span></div>
+        <div><b>exclusion</b><span>11–12s</span></div>
+      </div>
+      <div class="foot">
+        v2 · composition · screen · 0–12s<br />
+        v3 · video · 12 modes · 1s each · Preview uses CSS; render uses FFmpeg + alpha mask
+      </div>
+    </div>
+    <div class="progress"></div>
+  </div>
+</fy-composition>

package/examples/blend/fy.config.js

@@ -0,0 +1,11 @@
+export default {
+  format: { width: 1920, height: 1080, fps: 30 },
+  compositions: {
+    backdrop: "./compositions/backdrop.html",
+    aurora: "./compositions/aurora.html",
+    labels: "./compositions/labels.html",
+  },
+  timelines: {
+    "blend-timeline": "./timelines/blend.timeline.json",
+  },
+};

package/examples/blend/scripts/make-ink.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+out="${1:-$root/assets/ink.mp4}"
+mkdir -p "$(dirname "$out")"
+
+ffmpeg -y -v error \
+  -f lavfi \
+  -i "gradients=size=1280x720:rate=30:c0=0x0b1020:c1=0x1b4dff:c2=0xff2d7a:c3=0xffb347:n=4:type=spiral:speed=0.08:duration=12" \
+  -f lavfi \
+  -i "anullsrc=channel_layout=stereo:sample_rate=48000" \
+  -t 12 \
+  -map 0:v:0 \
+  -map 1:a:0 \
+  -c:v libx264 \
+  -preset medium \
+  -crf 20 \
+  -pix_fmt yuv420p \
+  -g 30 \
+  -c:a aac \
+  -b:a 96k \
+  -shortest \
+  "$out"
+
+printf 'Wrote %s\n' "$out"

package/examples/blend/timelines/blend.timeline.json

@@ -0,0 +1,155 @@
+{
+  "version": 1,
+  "name": "Blend lab: every supported mode on a video clip",
+  "background": "#05070d",
+  "tracks": [
+    { "id": "v1", "kind": "video", "name": "Backdrop" },
+    { "id": "v2", "kind": "video", "name": "Aurora · screen" },
+    { "id": "v3", "kind": "video", "name": "Video · 12 modes, one per second" },
+    { "id": "v4", "kind": "video", "name": "Labels" }
+  ],
+  "clips": [
+    {
+      "id": "backdrop",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "backdrop" },
+      "start": 0,
+      "duration": 360
+    },
+    {
+      "id": "aurora",
+      "track": "v2",
+      "source": { "kind": "composition", "id": "aurora" },
+      "start": 0,
+      "duration": 360,
+      "blend": "screen"
+    },
+    {
+      "id": "ink-normal",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 0,
+      "duration": 30,
+      "sourceIn": 0,
+      "blend": "normal",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-multiply",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 30,
+      "duration": 30,
+      "sourceIn": 30,
+      "blend": "multiply",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-screen",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 60,
+      "duration": 30,
+      "sourceIn": 60,
+      "blend": "screen",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-overlay",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 90,
+      "duration": 30,
+      "sourceIn": 90,
+      "blend": "overlay",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-darken",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 120,
+      "duration": 30,
+      "sourceIn": 120,
+      "blend": "darken",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-lighten",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 150,
+      "duration": 30,
+      "sourceIn": 150,
+      "blend": "lighten",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-color-dodge",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 180,
+      "duration": 30,
+      "sourceIn": 180,
+      "blend": "color-dodge",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-color-burn",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 210,
+      "duration": 30,
+      "sourceIn": 210,
+      "blend": "color-burn",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-hard-light",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 240,
+      "duration": 30,
+      "sourceIn": 240,
+      "blend": "hard-light",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-soft-light",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 270,
+      "duration": 30,
+      "sourceIn": 270,
+      "blend": "soft-light",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-difference",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 300,
+      "duration": 30,
+      "sourceIn": 300,
+      "blend": "difference",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "ink-exclusion",
+      "track": "v3",
+      "source": { "kind": "video", "src": "assets/ink.mp4" },
+      "start": 330,
+      "duration": 30,
+      "sourceIn": 330,
+      "blend": "exclusion",
+      "audio": { "muted": true }
+    },
+    {
+      "id": "labels",
+      "track": "v4",
+      "source": { "kind": "composition", "id": "labels" },
+      "start": 0,
+      "duration": 360
+    }
+  ]
+}

package/examples/demo/README.md

@@ -19,13 +19,13 @@ From the repository root:
 pnpm build
 node dist/cli.js check demo-timeline --project examples/demo
 node dist/cli.js still demo-timeline --frame 240 --project examples/demo --out demo-still.png
-node dist/cli.js render demo-timeline --project examples/demo --props examples/demo/props/demo.json
+FRAMEYARD_POLICY=full node dist/cli.js render demo-timeline --project examples/demo --props examples/demo/props/demo.json
 ```
 
 The composition remains renderable on its own:
 
 ```sh
-node dist/cli.js render demo --project examples/demo --props examples/demo/props/demo.json
+FRAMEYARD_POLICY=full node dist/cli.js render demo --project examples/demo --props examples/demo/props/demo.json
 ```
 
 Start the interactive preview with: