frameyard 0.8.0 → 0.10.0

package/examples/intro/timelines/intro.timeline.json

@@ -0,0 +1,60 @@
+{
+  "version": 1,
+  "name": "Frameyard / intro film",
+  "durationInFrames": 1200,
+  "background": "#06080b",
+  "tracks": [
+    { "id": "scenes", "kind": "video", "name": "Scenes" },
+    { "id": "hud", "kind": "video", "name": "HUD overlay" },
+    { "id": "score", "kind": "audio", "name": "Original score" }
+  ],
+  "clips": [
+    {
+      "id": "opening",
+      "track": "scenes",
+      "source": { "kind": "composition", "id": "opening" },
+      "start": 0,
+      "duration": 300
+    },
+    {
+      "id": "studio",
+      "track": "scenes",
+      "source": { "kind": "composition", "id": "studio" },
+      "start": 270,
+      "duration": 330
+    },
+    {
+      "id": "lattice",
+      "track": "scenes",
+      "source": { "kind": "composition", "id": "lattice" },
+      "start": 570,
+      "duration": 330
+    },
+    {
+      "id": "brand",
+      "track": "scenes",
+      "source": { "kind": "composition", "id": "brand" },
+      "start": 870,
+      "duration": 330
+    },
+    {
+      "id": "chrome",
+      "track": "hud",
+      "source": { "kind": "composition", "id": "chrome" },
+      "start": 0,
+      "duration": 1200
+    },
+    {
+      "id": "score",
+      "track": "score",
+      "source": { "kind": "audio", "src": "assets/score.ogg" },
+      "start": 0,
+      "duration": 1200
+    }
+  ],
+  "transitions": [
+    { "from": "opening", "to": "studio", "kind": "dissolve", "easing": "ease-in-out" },
+    { "from": "studio", "to": "lattice", "kind": "dissolve", "easing": "ease-in-out" },
+    { "from": "lattice", "to": "brand", "kind": "dissolve", "easing": "ease-in-out" }
+  ]
+}

package/examples/keyframes/README.md

@@ -0,0 +1,76 @@
+# Timeline keyframes example
+
+A 6-second, 1280×720, 30 fps timeline that animates one clip through every
+supported presentation channel:
+
+- `v1` **backdrop** — a static HTML composition with a gradient, a perspective
+  grid, and a soft glow. It declares no time metadata, so it is captured once
+  as an opaque image layer.
+- `v2` **card** — a static transparent HTML composition captured once as well.
+  Its timeline clip uses `blend: "screen"` and keyframes on `x`, `y`, `scale`,
+  `rotation`, and `opacity`.
+
+The card enters from the left, settles in the center, holds, and leaves toward
+the right while it fades. Position, scale, and rotation use `ease-out` into the
+hold and `ease-in` out of it. The clip uses `ease-out` and `ease-in` rather than
+animating inside the card, because this animation belongs to the edit, not to
+the reusable composition.
+
+## Keyframe contract
+
+`keyframes` is a per-clip object keyed by channel. Each channel is an array of
+`{ "frame", "value", "easing" }` entries:
+
+- `frame` is clip-local. `0` is the clip start; `duration` is the end boundary.
+- Keys must be integers in `0..duration`, strictly increasing, with at least two
+  entries per channel.
+- A channel holds its first value before the first key and its last value after
+  the last key.
+- `easing` applies to the interval after that key and defaults to `linear`. The
+  supported vocabulary is `linear`, `ease`, `ease-in`, `ease-out`,
+  `ease-in-out`, `step-start`, `step-end`, `hold`, `cubic-bezier(...)`, and
+  `steps(...)`. The final key’s easing has no effect.
+- A channel cannot also be an explicit scalar in `transform`; keyed channels
+  and static channels are separate. Defaults do not conflict.
+- `opacity` is `0..1`, `scale` is `>= 0`, and interpolated opacity and scale are
+  clamped after easing. Position and rotation may overshoot.
+- `keyframes.scale` cannot be combined with a `transform.width`/`height` box.
+
+Preview evaluates the CSS timing functions exactly and seeks the clip styles on
+every frame. Production generates FFmpeg expressions from the same evaluator,
+using an alpha mask for animated opacity. Floating-point easing in the filter
+graph is an approximation of the CSS curve; parity is guaranteed at clip capture,
+not at the final encoded pixel. Fractional positions can differ by a subpixel.
+
+## Files
+
+```text
+examples/keyframes/
+  compositions/backdrop.html   opaque static backdrop
+  compositions/card.html       transparent static card
+  timelines/keyframes.timeline.json
+  fy.config.js
+```
+
+The timeline lives in `timelines/keyframes.timeline.json`. Both compositions are
+static: they declare neither `duration-in-frames` nor `fps`, and the timeline
+supplies their durations and `sourceIn: 0`. The card is still animated on the
+timeline because keyframes are a clip property, not a composition property.
+
+## Commands
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check keyframes --project examples/keyframes
+node dist/cli.js still keyframes --frame 12,90,170 --project examples/keyframes --out keyframes-stills
+node dist/cli.js still keyframes --frame 90 --project examples/keyframes --out keyframes-center.png
+FRAMEYARD_POLICY=full node dist/cli.js render keyframes --project examples/keyframes
+node dist/cli.js dev --project examples/keyframes
+```
+
+`render` writes `out/keyframes.mp4` inside the project by default. The batch
+still captures the entrance, the hold, and the exit through the same clip
+capture and composite path as the render. `dev` lists the timeline and shows
+the keyframe markers on the clip bar; clicking a marker seeks to that frame.

package/examples/keyframes/compositions/backdrop.html

@@ -0,0 +1,60 @@
+<style>
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: #080b10;
+  }
+  .backdrop {
+    position: absolute;
+    inset: 0;
+    background:
+      radial-gradient(circle at 24% 18%, rgba(95, 214, 255, 0.22), transparent 34%),
+      radial-gradient(circle at 78% 76%, rgba(184, 243, 107, 0.16), transparent 32%),
+      linear-gradient(145deg, #0a1018 0%, #0b1119 52%, #070a0f 100%);
+  }
+  .grid {
+    position: absolute;
+    inset: -20%;
+    background-image:
+      linear-gradient(rgba(120, 150, 180, 0.08) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(120, 150, 180, 0.08) 1px, transparent 1px);
+    background-size: 48px 48px;
+    transform: perspective(900px) rotateX(62deg) translateY(18%);
+    transform-origin: center bottom;
+  }
+  .glow {
+    position: absolute;
+    width: 520px;
+    height: 520px;
+    left: 50%;
+    top: 50%;
+    transform: translate(-50%, -50%);
+    border-radius: 50%;
+    background: radial-gradient(circle, rgba(184, 243, 107, 0.14), transparent 64%);
+  }
+  .title {
+    position: absolute;
+    left: 56px;
+    bottom: 48px;
+    color: #dce8f5;
+    font:
+      620 22px/1.2 Inter,
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      sans-serif;
+    letter-spacing: 0.16em;
+    text-transform: uppercase;
+    opacity: 0.82;
+  }
+</style>
+<fy-composition width="1280" height="720">
+  <div class="backdrop"></div>
+  <div class="grid"></div>
+  <div class="glow"></div>
+  <div class="title">Timeline keyframes</div>
+</fy-composition>

package/examples/keyframes/compositions/card.html

@@ -0,0 +1,99 @@
+<style>
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: transparent;
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    border: 1px solid rgba(184, 243, 107, 0.5);
+    border-radius: 28px;
+    background:
+      linear-gradient(135deg, rgba(184, 243, 107, 0.18), rgba(95, 214, 255, 0.06) 54%, rgba(8, 11, 16, 0.9)),
+      rgba(10, 16, 24, 0.82);
+    box-shadow:
+      0 0 0 1px rgba(184, 243, 107, 0.08) inset,
+      0 42px 120px rgba(0, 0, 0, 0.55);
+    overflow: hidden;
+  }
+  .card::before {
+    content: "";
+    position: absolute;
+    inset: -40% -10%;
+    background: radial-gradient(circle at 22% 26%, rgba(184, 243, 107, 0.32), transparent 36%);
+  }
+  .eyebrow {
+    position: absolute;
+    left: 48px;
+    top: 44px;
+    color: #b8f36b;
+    font:
+      600 15px/1 Inter,
+      ui-sans-serif,
+      system-ui,
+      sans-serif;
+    letter-spacing: 0.2em;
+    text-transform: uppercase;
+  }
+  .heading {
+    position: absolute;
+    left: 48px;
+    right: 48px;
+    top: 92px;
+    color: #f2f7fb;
+    font:
+      680 64px/1.02 Inter,
+      ui-sans-serif,
+      system-ui,
+      sans-serif;
+    letter-spacing: -0.035em;
+  }
+  .rule {
+    position: absolute;
+    left: 48px;
+    right: 48px;
+    bottom: 96px;
+    height: 1px;
+    background: linear-gradient(90deg, rgba(184, 243, 107, 0.6), rgba(95, 214, 255, 0.18), transparent);
+  }
+  .meta {
+    position: absolute;
+    left: 48px;
+    bottom: 52px;
+    color: rgba(220, 232, 245, 0.72);
+    font:
+      500 18px/1.4 Inter,
+      ui-sans-serif,
+      system-ui,
+      sans-serif;
+  }
+  .badge {
+    position: absolute;
+    right: 48px;
+    bottom: 48px;
+    padding: 10px 16px;
+    border: 1px solid rgba(184, 243, 107, 0.44);
+    border-radius: 999px;
+    color: #b8f36b;
+    font:
+      600 14px/1 Inter,
+      ui-sans-serif,
+      system-ui,
+      sans-serif;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+  }
+</style>
+<fy-composition width="640" height="360">
+  <div class="card">
+    <div class="eyebrow">Frameyard</div>
+    <div class="heading">Animate the edit,<br />not the composition.</div>
+    <div class="rule"></div>
+    <div class="meta">One clip. Five channels. Four keys.</div>
+    <div class="badge">Keyframes</div>
+  </div>
+</fy-composition>

package/examples/keyframes/fy.config.js

@@ -0,0 +1,10 @@
+export default {
+  format: { width: 1280, height: 720, fps: 30 },
+  compositions: {
+    backdrop: "./compositions/backdrop.html",
+    card: "./compositions/card.html",
+  },
+  timelines: {
+    keyframes: "./timelines/keyframes.timeline.json",
+  },
+};

package/examples/keyframes/timelines/keyframes.timeline.json

@@ -0,0 +1,60 @@
+{
+  "version": 1,
+  "name": "Keyframes",
+  "background": "#080b10",
+  "tracks": [
+    { "id": "v1", "kind": "video" },
+    { "id": "v2", "kind": "video" }
+  ],
+  "clips": [
+    {
+      "id": "backdrop",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "backdrop" },
+      "start": 0,
+      "duration": 180,
+      "sourceIn": 0
+    },
+    {
+      "id": "card",
+      "track": "v2",
+      "source": { "kind": "composition", "id": "card" },
+      "start": 0,
+      "duration": 180,
+      "sourceIn": 0,
+      "blend": "screen",
+      "keyframes": {
+        "opacity": [
+          { "frame": 0, "value": 0 },
+          { "frame": 24, "value": 1, "easing": "ease-out" },
+          { "frame": 150, "value": 1 },
+          { "frame": 180, "value": 0, "easing": "ease-in" }
+        ],
+        "x": [
+          { "frame": 0, "value": -120, "easing": "ease-out" },
+          { "frame": 24, "value": 0 },
+          { "frame": 150, "value": 0 },
+          { "frame": 180, "value": 120, "easing": "ease-in" }
+        ],
+        "y": [
+          { "frame": 0, "value": 48, "easing": "ease-out" },
+          { "frame": 24, "value": 0 },
+          { "frame": 150, "value": 0 },
+          { "frame": 180, "value": -32, "easing": "ease-in" }
+        ],
+        "scale": [
+          { "frame": 0, "value": 0.42, "easing": "ease-out" },
+          { "frame": 24, "value": 0.5 },
+          { "frame": 150, "value": 0.5 },
+          { "frame": 180, "value": 0.46, "easing": "ease-in" }
+        ],
+        "rotation": [
+          { "frame": 0, "value": -8, "easing": "ease-out" },
+          { "frame": 24, "value": 0 },
+          { "frame": 150, "value": 0 },
+          { "frame": 180, "value": 8, "easing": "ease-in" }
+        ]
+      }
+    }
+  ]
+}

package/examples/nested/README.md

@@ -0,0 +1,112 @@
+# Frameyard nested timelines example
+
+A 12-second, 1280×720, 30 fps outer timeline that places two reusable inner
+timelines on its tracks:
+
+| Frames | Placement | What plays |
+| --- | --- | --- |
+| 0–119 | `chapter-a` · full frame | Chapter A on track `v1` |
+| 120–239 | `chapter-b` · full frame | Chapter B on track `v2` |
+| 240–359 | `chapter-a` · 480×270 group | Chapter A again on track `v3`, muted |
+
+`chapter-a` and `chapter-b` are complete timelines in their own right. Each
+contains a static backdrop, an animated card composition with its own props, and
+a local audio clip. The outer timeline references them with
+`"source": { "kind": "timeline", "id": "chapter-a" }` instead of referencing
+their compositions directly.
+
+The third placement repeats `chapter-a` with a group transform:
+
+```json
+{
+  "source": { "kind": "timeline", "id": "chapter-a" },
+  "start": 240,
+  "duration": 120,
+  "transform": {
+    "fit": "cover",
+    "width": 480,
+    "height": 270,
+    "x": 360,
+    "y": 180
+  },
+  "audio": { "muted": true }
+}
+```
+
+The transform applies to the whole nested result. Every layer inside the chapter
+moves, scales, and clips together; the parent clip does not reach into the child
+timeline. The same rule applies to opacity and blend mode. Nested audio is mixed
+with the outer timeline automatically, so the final placement sets
+`audio.muted` to avoid replaying the pulse.
+
+## Layers inside the chapters
+
+- `backdrop` is a static opaque composition. It declares no dimensions, no
+  `fps`, and no `duration-in-frames`, so it inherits the project format. The
+  renderer captures it once and reuses that PNG across segments and both chapter
+  timelines.
+- `card` is a 120-frame animated composition. The chapter timeline places it
+  with props for the chapter number, copy, and accent color. The card paints on
+  transparent alpha above the backdrop; its progress bar reads
+  `--fy-progress` and the dial runs on the local frame clock.
+- `pulse` is a 1.8-second WAV on the chapter's audio track. In the outer
+  timeline the first two chapter clips contribute it; `check` reports two mixed
+  audio clips.
+
+`overlay` is a top-level composition on track `v4`. It draws the project chrome,
+the frame counter, and the global progress bar for the full 12 seconds. Its PiP
+border and left-hand caption are scheduled with
+`data-fy-anim-start="240"`/`"246"` and an `animation` with `both` fill, so they
+stay invisible until the grouped replay begins.
+
+## Files
+
+```text
+examples/nested/
+  compositions/backdrop.html       static inherited-format backdrop
+  compositions/card.html           animated transparent card
+  compositions/overlay.html        project chrome, PiP border, and outro caption
+  timelines/chapter-a.timeline.json
+  timelines/chapter-b.timeline.json
+  timelines/nested-reel.timeline.json
+  assets/pulse.wav                 local chapter audio
+  scripts/make-pulse.sh            regenerate assets/pulse.wav
+  fy.config.js
+```
+
+`chapter-a` and `chapter-b` are listed in `fy.config.js`, so each can be
+checked, previewed, stilled, or rendered on its own. Timeline `--props` is keyed
+by top-level composition clip ID; a nested timeline clip does not forward prop
+overrides to the compositions inside it. Fix chapter props in the chapter's own
+timeline document.
+
+## Commands
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check chapter-a --project examples/nested
+node dist/cli.js check nested-reel --project examples/nested
+node dist/cli.js still nested-reel --frame 60,180,300 --project examples/nested --out nested-stills
+FRAMEYARD_POLICY=full node dist/cli.js render chapter-a --project examples/nested
+FRAMEYARD_POLICY=full node dist/cli.js render nested-reel --project examples/nested
+node dist/cli.js dev --project examples/nested
+```
+
+The batch still captures chapter A full frame, chapter B full frame, and the
+grouped replay with its overlay. `render` writes `out/chapter-a.mp4` and
+`out/nested-reel.mp4` inside the project by default; pass `--out` for another
+path. The outer render uses the segmented lossless pipeline and captures the
+nested ranges through the same clip path as the stills. Use `--workers` and
+`--scratch` to tune timeline rendering.
+
+Regenerate the pulse with FFmpeg:
+
+```sh
+bash examples/nested/scripts/make-pulse.sh
+```
+
+Pass an output path as the first argument to write elsewhere. The source is a
+pair of faded sine tones; replace `assets/pulse.wav` with any local WAV, MP3,
+M4A, AAC, or video file if you want different audio.

package/examples/nested/compositions/backdrop.html

@@ -0,0 +1,84 @@
+<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(980px 680px at 76% 22%, rgba(43, 104, 210, 0.42), transparent 63%),
+      radial-gradient(760px 520px at 12% 88%, rgba(255, 158, 74, 0.13), transparent 66%),
+      linear-gradient(148deg, #07101d 0%, #0a1628 50%, #05070d 100%);
+  }
+  .grid {
+    position: absolute;
+    inset: -1px;
+    background-image:
+      linear-gradient(rgba(154, 192, 255, 0.07) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(154, 192, 255, 0.07) 1px, transparent 1px);
+    background-size: 64px 64px;
+    -webkit-mask-image: radial-gradient(ellipse at 50% 44%, #000 20%, transparent 78%);
+    mask-image: radial-gradient(ellipse at 50% 44%, #000 20%, transparent 78%);
+  }
+  .ring {
+    position: absolute;
+    right: -140px;
+    top: 50%;
+    width: 720px;
+    height: 720px;
+    border: 1px solid rgba(160, 205, 255, 0.12);
+    border-radius: 50%;
+    transform: translateY(-50%);
+  }
+  .ring::before,
+  .ring::after {
+    content: "";
+    position: absolute;
+    border: 1px solid rgba(255, 179, 71, 0.09);
+    border-radius: 50%;
+  }
+  .ring::before {
+    inset: 110px;
+  }
+  .ring::after {
+    inset: 230px;
+    border-color: rgba(127, 214, 255, 0.08);
+  }
+  .beam {
+    position: absolute;
+    left: 58%;
+    top: -20%;
+    width: 1px;
+    height: 140%;
+    background: linear-gradient(180deg, transparent, rgba(127, 214, 255, 0.16), transparent);
+    transform: rotate(18deg);
+  }
+  .vignette {
+    position: absolute;
+    inset: 0;
+    background:
+      radial-gradient(ellipse at 52% 44%, transparent 30%, rgba(5, 7, 13, 0.4) 72%, rgba(5, 7, 13, 0.85) 100%),
+      linear-gradient(90deg, rgba(5, 7, 13, 0.35), transparent 28%, transparent 72%, rgba(5, 7, 13, 0.4));
+    pointer-events: none;
+  }
+</style>
+<fy-composition>
+  <div class="scene">
+    <div class="grid"></div>
+    <div class="ring"></div>
+    <div class="beam"></div>
+    <div class="vignette"></div>
+  </div>
+</fy-composition>