frameyard 0.4.0 → 0.6.0

package/examples/video/README.md

@@ -0,0 +1,105 @@
+# Frameyard video example
+
+A 12-second, 1920×1080 project that treats a local clip as source footage. The
+project includes the same layout for two source codecs:
+
+- `video` reads `assets/clip.webm` (VP9 + Opus)
+- `video-mp4` reads `assets/clip.mp4` (H.264 + AAC)
+
+Both compositions include:
+
+- a full-bleed hero pass whose unmuted soundtrack joins the composition audio timeline
+- a persistent detail pass with its own `data-fy-start`, `data-fy-trim`, and `data-fy-duration`
+- `data-fy-audio="off"` on the detail pass so only the hero contributes audio
+- a frame counter derived from `--fy-frame` in CSS, with static source-range labels
+- frame-scheduled CSS typography and a frame-state progress bar
+- a one-second fade to black over the final second of the composition
+
+The hero pass uses the full 12-second source at volume `0.85`. The detail window
+is visible for the whole composition: it holds the source at 5.8 seconds until
+composition frame 120, then plays 5 seconds of the same file, and holds the final
+source frame after frame 270. The result shows two source moments side by side.
+The example is entirely declarative: the runtime owns loading, pausing, and
+frame seeking, and CSS derives the frame counter from the frame state. No
+controller is needed. The header, copy, and footer fade individually rather
+than the whole scene; a full-scene opacity animation above a video can leave
+the load frame on screen in interactive preview after a large seek.
+
+## Timeline with the video on a track
+
+`video-timeline` and `video-timeline-mp4` move the footage out of the
+composition and onto timeline tracks. The HTML is now a transparent overlay
+above it:
+
+- `v1` holds the hero clip: the whole 12-second source, audio at `0.85`
+- `v2` holds the detail pass from source frame 174 (5.8 s) for 150 frames,
+  muted, placed in a 440×248 transform box in the bottom right
+- `v3` holds `video-overlay`, an HTML-only composition with no `<video>`
+  elements and a transparent document background
+
+`video-timeline` reads `assets/clip.webm` (VP9 + Opus) and
+`video-timeline-mp4` reads `assets/clip.mp4` (H.264 + AAC). Both share the same
+overlay composition and props file; the overlay clip sets its own `format` prop
+so the header reports the codec of each timeline.
+
+The detail clip uses `transform.width` and `transform.height` instead of
+`scale`, with `fit: "cover"` filling that box. The box matches the overlay's
+detail window exactly, so the video and its chrome stay aligned in production
+and preview.
+
+The overlay draws the scrim, typography, frame border, detail-window chrome,
+progress bar, and outro fade. `video-overlay` declares its own frame animations,
+so the title and footer still animate on the timeline clock. Production captures
+the overlay with alpha and composites it over the video layers with FFmpeg; the
+interactive timeline preview composites the same layers in Chromium.
+
+Both timelines accept `props/video-timeline.json`, which overrides the overlay
+composition's props. Timeline `--props` is keyed by composition clip id, so the
+file targets the `overlay` clip.
+
+Open the preview with `node dist/cli.js dev --project examples/video`; the
+compositions and both timelines are listed.
+
+The compositions live in `compositions/video.html` and
+`compositions/video-mp4.html`; the overlay lives in
+`compositions/video-overlay.html`, and the timelines in
+`timelines/video-timeline.timeline.json` and
+`timelines/video-timeline-mp4.timeline.json`. Both clips are 12-second 1280×720
+files generated procedurally for this example; the MP4 is transcoded from the
+WebM source. Replace either asset with a local, seekable video file that is at
+least 12 seconds long; remote URLs and live streams are not supported.
+
+Regenerate both clips from scratch with the bundled FFmpeg script:
+
+```sh
+bash examples/video/scripts/make-clip.sh
+```
+
+The script writes both files into `assets/`; pass `--out-dir <directory>` to
+write elsewhere. It requires FFmpeg with `libvpx-vp9`, `libx264`, Opus, and AAC
+encoders, and fixed noise seeds keep the generated grain stable across runs on
+the same FFmpeg build.
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check video --project examples/video
+node dist/cli.js check video-mp4 --project examples/video
+node dist/cli.js check video-timeline --project examples/video
+node dist/cli.js check video-timeline-mp4 --project examples/video
+node dist/cli.js still video --frame 210 --project examples/video --out video-still.png
+node dist/cli.js still video-mp4 --frame 210 --project examples/video --out video-mp4-still.png
+node dist/cli.js still video-timeline --frame 210 --project examples/video --out video-timeline-still.png
+node dist/cli.js still video-timeline-mp4 --frame 210 --project examples/video --out video-timeline-mp4-still.png
+node dist/cli.js render video --project examples/video --props examples/video/props/video.json
+node dist/cli.js render video-mp4 --project examples/video --props examples/video/props/video.json
+node dist/cli.js render video-timeline --project examples/video --props examples/video/props/video-timeline.json
+node dist/cli.js render video-timeline-mp4 --project examples/video --props examples/video/props/video-timeline.json
+```
+
+Start the interactive preview with:
+
+```sh
+node dist/cli.js dev --project examples/video
+```

package/examples/video/compositions/video-mp4.html

@@ -0,0 +1,362 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <script type="application/json" data-fy="props">
+      {
+        "kicker": "Frameyard / Clip Study 001",
+        "title": "Moving",
+        "titleAccent": "Image",
+        "subtitle": "A local clip, loaded once and seeked twice from the composition clock.",
+        "detail": "Detail / second pass",
+        "accent": "#ffc37a"
+      }
+    </script>
+    <style>
+      @keyframes fade-in {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+      @keyframes rise {
+        from {
+          opacity: 0;
+          transform: translateY(42px);
+        }
+        to {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+      @keyframes draw {
+        from {
+          opacity: 0;
+          transform: scaleX(0);
+        }
+        to {
+          opacity: 1;
+          transform: scaleX(1);
+        }
+      }
+      @keyframes outro-fade {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+      html,
+      body,
+      fy-composition {
+        background: #04080b;
+      }
+      #scene {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+        isolation: isolate;
+        background: #04080b;
+        color: #eef4f1;
+        font-family: Inter, "Helvetica Neue", ui-sans-serif, system-ui, sans-serif;
+      }
+      #hero {
+        position: absolute;
+        inset: 0;
+        display: block;
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        transform: scale(calc(1 + var(--fy-progress) * 0.035));
+        transform-origin: center;
+      }
+      #scrim {
+        position: absolute;
+        inset: 0;
+        background:
+          linear-gradient(
+            90deg,
+            rgba(4, 8, 11, 0.94) 0%,
+            rgba(4, 8, 11, 0.8) 24%,
+            rgba(4, 8, 11, 0.24) 52%,
+            rgba(4, 8, 11, 0) 74%
+          ),
+          linear-gradient(0deg, rgba(4, 8, 11, 0.9) 0%, rgba(4, 8, 11, 0) 34%);
+      }
+      #vignette {
+        position: absolute;
+        inset: 0;
+        background: radial-gradient(ellipse at 62% 44%, transparent 42%, rgba(0, 0, 0, 0.3) 100%);
+        pointer-events: none;
+      }
+      #frame-border {
+        position: absolute;
+        inset: 36px;
+        border: 1px solid rgba(238, 244, 241, 0.16);
+        pointer-events: none;
+      }
+      #header {
+        position: absolute;
+        top: 80px;
+        left: 148px;
+        right: 148px;
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        gap: 32px;
+        animation: fade-in 1s linear both;
+      }
+      #kicker {
+        display: flex;
+        align-items: center;
+        gap: 15px;
+        font:
+          600 14px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.24em;
+        text-transform: uppercase;
+        color: var(--fy-prop-accent);
+      }
+      #kicker::before {
+        content: "";
+        width: 8px;
+        height: 8px;
+        background: var(--fy-prop-accent);
+        box-shadow: 0 0 16px var(--fy-prop-accent);
+      }
+      #format {
+        font:
+          500 12px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.16em;
+        text-transform: uppercase;
+        color: #8b999c;
+      }
+      #copy {
+        position: absolute;
+        top: 278px;
+        left: 148px;
+        width: 860px;
+      }
+      #title {
+        margin: 0;
+        font-size: 174px;
+        line-height: 0.84;
+        letter-spacing: -0.064em;
+        font-weight: 660;
+      }
+      #title span,
+      #title em {
+        display: block;
+        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #title em {
+        margin-top: 0.06em;
+        font-family: "Iowan Old Style", "Palatino Linotype", Georgia, ui-serif, serif;
+        font-style: italic;
+        font-weight: 400;
+        letter-spacing: -0.035em;
+        color: var(--fy-prop-accent);
+      }
+      #subtitle {
+        width: 720px;
+        margin: 38px 0 0;
+        font-size: 29px;
+        line-height: 1.5;
+        font-weight: 420;
+        color: #a6b3b6;
+        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #footer {
+        position: absolute;
+        left: 148px;
+        right: 148px;
+        bottom: 70px;
+        contain: layout paint style;
+        animation: fade-in 1s linear both;
+      }
+      #rule {
+        position: relative;
+        height: 1px;
+        background: rgba(238, 244, 241, 0.16);
+        transform-origin: left center;
+        animation: draw 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #progress {
+        position: absolute;
+        inset: 0 auto 0 0;
+        width: calc(var(--fy-progress) * 100%);
+        background: var(--fy-prop-accent);
+        box-shadow: 0 0 14px var(--fy-prop-accent);
+      }
+      #footer-row {
+        display: flex;
+        justify-content: space-between;
+        align-items: baseline;
+        gap: 24px;
+        margin-top: 18px;
+        font:
+          500 12px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.14em;
+        color: #879598;
+        text-transform: uppercase;
+      }
+      #footer-row strong {
+        color: #edf5f2;
+        font-weight: 600;
+      }
+      #footer-row .accent {
+        color: var(--fy-prop-accent);
+      }
+      #frame-counter {
+        display: inline-block;
+        min-width: 3ch;
+        text-align: right;
+      }
+      #frame-counter::after {
+        counter-reset: fy-frame var(--fy-frame);
+        content: counter(fy-frame);
+      }
+      #detail {
+        position: absolute;
+        right: 148px;
+        bottom: 154px;
+        width: 440px;
+      }
+      #detail-bar {
+        display: flex;
+        justify-content: space-between;
+        align-items: baseline;
+        gap: 24px;
+        margin-bottom: 10px;
+        contain: layout paint style;
+        font:
+          600 11px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.18em;
+        text-transform: uppercase;
+      }
+      #detail-bar > span:first-child {
+        color: var(--fy-prop-accent);
+      }
+      #detail-time {
+        color: #98a5a6;
+        font-weight: 500;
+      }
+      #detail-window {
+        position: relative;
+        width: 440px;
+        height: 248px;
+        overflow: hidden;
+        border: 1px solid rgba(255, 195, 122, 0.65);
+        background: #000;
+        box-shadow: 0 24px 90px rgba(0, 0, 0, 0.55);
+      }
+      #detail-clip {
+        display: block;
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        object-position: 68% 50%;
+        transform: scale(1.3);
+      }
+      #detail-tint {
+        position: absolute;
+        inset: 0;
+        background: linear-gradient(0deg, rgba(4, 8, 11, 0.28) 0%, rgba(4, 8, 11, 0) 45%);
+        pointer-events: none;
+      }
+      #outro-fade {
+        position: absolute;
+        inset: 0;
+        background: #04080b;
+        pointer-events: none;
+        opacity: 0;
+        animation: outro-fade 1s linear both;
+      }
+    </style>
+  </head>
+  <body>
+    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="360">
+      <div id="scene">
+        <video
+          id="hero"
+          src="assets/clip.mp4"
+          data-fy-start="0"
+          data-fy-trim="0"
+          data-fy-duration="12"
+          data-fy-volume="0.85"
+        ></video>
+        <div id="scrim"></div>
+        <div id="vignette"></div>
+        <div id="frame-border"></div>
+
+        <header id="header" data-fy-anim-start="8" data-fy-anim-duration="28">
+          <div id="kicker" data-fy-text="kicker"></div>
+          <div id="format">Embedded video / H.264 + AAC / 30 FPS</div>
+        </header>
+
+        <div id="copy">
+          <h1 id="title">
+            <span
+              data-fy-text="title"
+              data-fy-anim-start="14"
+              data-fy-anim-duration="44"
+              data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+            ></span>
+            <em
+              data-fy-text="titleAccent"
+              data-fy-anim-start="26"
+              data-fy-anim-duration="44"
+              data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+            ></em>
+          </h1>
+          <p
+            id="subtitle"
+            data-fy-text="subtitle"
+            data-fy-anim-start="40"
+            data-fy-anim-duration="40"
+            data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+          ></p>
+        </div>
+
+        <div id="detail">
+          <div id="detail-bar">
+            <span data-fy-text="detail"></span>
+            <span id="detail-time">SRC 5.8–10.8 S</span>
+          </div>
+          <div id="detail-window">
+            <video
+              id="detail-clip"
+              src="assets/clip.mp4"
+              data-fy-start="120"
+              data-fy-trim="5.8"
+              data-fy-duration="5"
+              data-fy-audio="off"
+            ></video>
+            <div id="detail-tint"></div>
+          </div>
+        </div>
+
+        <div id="footer" data-fy-anim-start="46" data-fy-anim-duration="30">
+          <div id="rule" data-fy-anim-start="52" data-fy-anim-duration="50">
+            <div id="progress"></div>
+          </div>
+          <div id="footer-row">
+            <span>Hero / SRC <strong>0.0–12.0 S</strong></span>
+            <span>Frame <strong id="frame-counter"></strong> / 359</span>
+            <span class="accent">Frame-seeked</span>
+            <span>12.00 S · 30 FPS</span>
+          </div>
+        </div>
+
+        <div id="outro-fade" data-fy-anim-start="329" data-fy-anim-duration="30"></div>
+      </div>
+    </fy-composition>
+  </body>
+</html>