frameyard 0.7.0 → 0.9.0

package/examples/nested/timelines/nested-reel.timeline.json

@@ -0,0 +1,52 @@
+{
+  "version": 1,
+  "name": "Nested timelines: A full, B full, A as a group",
+  "durationInFrames": 360,
+  "background": "#05070d",
+  "tracks": [
+    { "id": "v1", "kind": "video", "name": "Chapter A · full frame" },
+    { "id": "v2", "kind": "video", "name": "Chapter B · full frame" },
+    { "id": "v3", "kind": "video", "name": "Chapter A · group transform" },
+    { "id": "v4", "kind": "video", "name": "Overlay" }
+  ],
+  "clips": [
+    {
+      "id": "chapter-a-full",
+      "track": "v1",
+      "source": { "kind": "timeline", "id": "chapter-a" },
+      "start": 0,
+      "duration": 120
+    },
+    {
+      "id": "chapter-b-full",
+      "track": "v2",
+      "source": { "kind": "timeline", "id": "chapter-b" },
+      "start": 120,
+      "duration": 120
+    },
+    {
+      "id": "chapter-a-group",
+      "track": "v3",
+      "source": { "kind": "timeline", "id": "chapter-a" },
+      "start": 240,
+      "duration": 120,
+      "transform": {
+        "fit": "cover",
+        "width": 480,
+        "height": 270,
+        "x": 360,
+        "y": 180,
+        "rotation": 0,
+        "opacity": 1
+      },
+      "audio": { "muted": true }
+    },
+    {
+      "id": "overlay",
+      "track": "v4",
+      "source": { "kind": "composition", "id": "overlay" },
+      "start": 0,
+      "duration": 360
+    }
+  ]
+}

package/examples/static/README.md

@@ -0,0 +1,17 @@
+# Static composition example
+
+`compositions/still.html` declares neither `duration-in-frames` nor `fps`, so
+Frameyard treats it as a static composition. The project `format` supplies the
+1280×720 dimensions. Rendering the composition writes a single PNG; the
+timeline uses the same composition as an image layer for 90 frames.
+
+```sh
+node dist/cli.js check still --project examples/static
+FRAMEYARD_POLICY=full node dist/cli.js render still --project examples/static --out examples/static/out/still.png
+node dist/cli.js check still-timeline --project examples/static
+FRAMEYARD_POLICY=full node dist/cli.js render still-timeline --project examples/static --out examples/static/out/still-timeline.mp4
+```
+
+`render still` defaults to `out/still.png`. Static compositions render to PNG;
+`--container`, `--codec`, `--encoder`, and `--concurrency` are not valid for
+them. Use the timeline when you need a video, audio, or a duration.

package/examples/static/compositions/still.html

@@ -0,0 +1,37 @@
+<style>
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: radial-gradient(circle at 50% 40%, #1b3b4a 0%, #08161d 70%);
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    color: #b8f36b;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    text-align: center;
+  }
+  .card h1 {
+    margin: 0;
+    font-size: 72px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+  .card p {
+    margin: 16px 0 0;
+    color: #e6f4ea;
+    font-size: 22px;
+  }
+</style>
+<fy-composition>
+  <div class="card">
+    <div>
+      <h1>Static</h1>
+      <p>No duration, no frame rate, one capture.</p>
+    </div>
+  </div>
+</fy-composition>

package/examples/static/fy.config.js

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

package/examples/static/timelines/still.timeline.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "tracks": [{ "id": "v1", "kind": "video" }],
+  "clips": [
+    {
+      "id": "still",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "still" },
+      "start": 0,
+      "duration": 90
+    }
+  ]
+}

package/examples/transitions/README.md

@@ -0,0 +1,128 @@
+# Timeline transitions example
+
+This project has two timelines:
+
+- `transitions` dissolves three timed composition cards on one video track and
+  lets their contributed audio crossfade.
+- `audio-crossfade` mutes the composition audio and places the sound directly on
+  an audio track, with a `crossfade` between two audio clips.
+
+## Visual dissolve with contributed audio
+
+`transitions` is a 4-second, 1280×720, 30 fps timeline:
+
+- **alpha** `0..60` — the A-major card and the outgoing clip. It keeps rendering
+  for the whole overlap, including after `beta` starts.
+- **beta** `45..105` — the C#-major card and the incoming clip. Its first 15
+  frames are the `alpha → beta` dissolve, then it runs alone, then it hands off
+  to `gamma`.
+- **gamma** `90..120` — the E-major card and the second incoming clip.
+
+Each composition is a timed HTML fragment (`duration-in-frames`) with one
+`<audio>` element. The audio belongs to the visual clip, so the dissolve
+crossfades it automatically.
+
+## Audio clips on the timeline
+
+`audio-crossfade` renders the same alpha and beta cards for 3.5 seconds, but
+mutes their composition audio with `audio.muted: true` and puts the sound on
+`a1` instead:
+
+- **chord-alpha** `0..60` — `assets/alpha.wav`, the outgoing chord.
+- **chord-beta** `45..105` — `assets/beta.wav`, the incoming chord.
+
+```json
+"transitions": [
+  { "from": "alpha", "to": "beta", "kind": "dissolve", "easing": "ease-in-out" },
+  { "from": "chord-alpha", "to": "chord-beta", "kind": "crossfade", "easing": "linear" }
+]
+```
+
+The visual dissolve and the audio crossfade share the same 15-frame overlap, so
+the picture and the sound hand off together. `crossfade` is the audio-track
+kind: it applies an equal-power gain ramp and changes no pixels.
+
+## Transition contract
+
+`transitions` is a timeline-level array of `{ "from", "to", "kind", "easing" }`:
+
+- `from` and `to` are clip IDs on the **same track**. A transition never spans
+  tracks.
+- `kind` is `dissolve` on a video track or `crossfade` on an audio track. A
+  dissolve fades the incoming picture in and also crossfades the audio the two
+  clips contribute; a crossfade only ramps audio gain. Using the wrong kind for
+  the track is an error.
+- `easing` defaults to `linear` and accepts the same CSS timing-function
+  vocabulary as clip keyframes.
+- The transition window is the overlap: `to.start .. from.end`. There is no
+  `duration` field; move the incoming clip earlier to make the transition
+  longer.
+- The geometry must be `from.start < to.start < from.end < to.end`. The incoming
+  clip must begin inside the outgoing clip and outlast it.
+- A clip may be the `to` of one transition and the `from` of the next, so
+  transitions chain. A clip cannot participate twice on the same side.
+- Overlap without a declared transition is still an error. Touching endpoints
+  are not a transition.
+
+During a dissolve the incoming clip composites above the outgoing clip with
+alpha `clipOpacity × eased progress`. Clip opacity may be static or keyframed
+and multiplies the transition.
+
+## Audio semantics
+
+Both kinds use an equal-power ramp over the window: the outgoing clip's gain is
+`sqrt(1 - t)` and the incoming clip's is `sqrt(t)`, after easing. For a
+dissolve, the ramp applies to the audio the two visual clips contribute. For a
+crossfade, it applies to the two audio-track clips themselves.
+
+`audio.muted` still zeroes a side, and `audio.gain` plus the track `gain`
+multiply the envelope. A crossfade on an audio track has no visual effect; a
+dissolve on an audio track is rejected.
+
+## What to look at
+
+The first dissolve uses `ease-in-out`, so it starts and ends gently around a
+faster middle. The second uses `linear`, so its progress tracks the frame clock
+exactly. The read-only preview draws a hatched band over each overlap, including
+the audio crossfade; the band is informational, not editable.
+
+Render or preview with sound. In `transitions` the chords hand off at frames 45
+and 90. In `audio-crossfade` the sound is on the timeline, and the A → C#
+crossfade happens at frames 45..60 while the picture dissolves over the same
+window.
+
+## Files
+
+```text
+examples/transitions/
+  assets/alpha.wav                 A-major chord, 2 s
+  assets/beta.wav                  C#-major chord, 2 s
+  assets/gamma.wav                 E-major chord, 1 s
+  compositions/alpha.html          outgoing timed card
+  compositions/beta.html           middle timed card
+  compositions/gamma.html          incoming timed card
+  timelines/transitions.timeline.json
+  timelines/audio-crossfade.timeline.json
+  fy.config.js
+```
+
+## Commands
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check transitions --project examples/transitions
+node dist/cli.js check audio-crossfade --project examples/transitions
+node dist/cli.js still transitions --frame 0,52,60,97 --project examples/transitions --out transitions-stills
+node dist/cli.js still audio-crossfade --frame 52 --project examples/transitions --out audio-crossfade-still.png
+FRAMEYARD_POLICY=full node dist/cli.js render transitions --project examples/transitions
+FRAMEYARD_POLICY=full node dist/cli.js render audio-crossfade --project examples/transitions
+node dist/cli.js dev --project examples/transitions
+```
+
+`render` writes `out/<timeline-id>.mp4` inside the project by default. Frame 52
+sits halfway into the first dissolve, frame 59 is the last frame of that overlap,
+and frame 97 is inside the second dissolve. In `audio-crossfade`, frame 52 is
+also inside the audio crossfade. `still` and `render` share the same composite
+path, so a still taken inside a transition matches the rendered frame.

package/examples/transitions/compositions/alpha.html

@@ -0,0 +1,56 @@
+<style>
+  :root {
+    color-scheme: dark;
+  }
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #0b1220;
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-content: center;
+    gap: 20px;
+    text-align: center;
+    color: #e9f1ff;
+    font-family:
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      sans-serif;
+    background:
+      radial-gradient(circle at 50% 42%, rgba(88, 140, 255, 0.55), transparent 58%),
+      linear-gradient(160deg, #0d1c3a, #0b1220 70%);
+  }
+  .eyebrow {
+    font-size: 20px;
+    letter-spacing: 0.42em;
+    text-transform: uppercase;
+    color: #8fb3ff;
+  }
+  h1 {
+    margin: 0;
+    font-size: 148px;
+    line-height: 0.92;
+    letter-spacing: -0.04em;
+    font-weight: 800;
+  }
+  p {
+    margin: 0;
+    font-size: 28px;
+    color: #9fb0c9;
+  }
+</style>
+<fy-composition duration-in-frames="60">
+  <div class="card">
+    <div class="eyebrow">scene one</div>
+    <h1>ALPHA</h1>
+    <p>the outgoing clip keeps rendering</p>
+  </div>
+  <audio src="assets/alpha.wav" data-fy-start="0" data-fy-duration="2"></audio>
+</fy-composition>

package/examples/transitions/compositions/beta.html

@@ -0,0 +1,56 @@
+<style>
+  :root {
+    color-scheme: dark;
+  }
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #1d1206;
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-content: center;
+    gap: 20px;
+    text-align: center;
+    color: #fff5e6;
+    font-family:
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      sans-serif;
+    background:
+      radial-gradient(circle at 50% 42%, rgba(255, 168, 66, 0.6), transparent 58%),
+      linear-gradient(160deg, #2a1708, #1d1206 70%);
+  }
+  .eyebrow {
+    font-size: 20px;
+    letter-spacing: 0.42em;
+    text-transform: uppercase;
+    color: #ffc078;
+  }
+  h1 {
+    margin: 0;
+    font-size: 148px;
+    line-height: 0.92;
+    letter-spacing: -0.04em;
+    font-weight: 800;
+  }
+  p {
+    margin: 0;
+    font-size: 28px;
+    color: #d8b892;
+  }
+</style>
+<fy-composition duration-in-frames="60">
+  <div class="card">
+    <div class="eyebrow">scene two</div>
+    <h1>BETA</h1>
+    <p>the incoming clip fades in above it</p>
+  </div>
+  <audio src="assets/beta.wav" data-fy-start="0" data-fy-duration="2"></audio>
+</fy-composition>

package/examples/transitions/compositions/gamma.html

@@ -0,0 +1,56 @@
+<style>
+  :root {
+    color-scheme: dark;
+  }
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #071a18;
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-content: center;
+    gap: 20px;
+    text-align: center;
+    color: #e6fffb;
+    font-family:
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      sans-serif;
+    background:
+      radial-gradient(circle at 50% 42%, rgba(64, 224, 190, 0.45), transparent 58%),
+      linear-gradient(160deg, #0a2823, #071a18 70%);
+  }
+  .eyebrow {
+    font-size: 20px;
+    letter-spacing: 0.42em;
+    text-transform: uppercase;
+    color: #7cf0d8;
+  }
+  h1 {
+    margin: 0;
+    font-size: 148px;
+    line-height: 0.92;
+    letter-spacing: -0.04em;
+    font-weight: 800;
+  }
+  p {
+    margin: 0;
+    font-size: 28px;
+    color: #9ec9c1;
+  }
+</style>
+<fy-composition duration-in-frames="30">
+  <div class="card">
+    <div class="eyebrow">scene three</div>
+    <h1>GAMMA</h1>
+    <p>one clip can dissolve in and out</p>
+  </div>
+  <audio src="assets/gamma.wav" data-fy-start="0" data-fy-duration="1"></audio>
+</fy-composition>

package/examples/transitions/fy.config.js

@@ -0,0 +1,12 @@
+export default {
+  format: { width: 1280, height: 720, fps: 30 },
+  compositions: {
+    alpha: "./compositions/alpha.html",
+    beta: "./compositions/beta.html",
+    gamma: "./compositions/gamma.html",
+  },
+  timelines: {
+    transitions: "./timelines/transitions.timeline.json",
+    "audio-crossfade": "./timelines/audio-crossfade.timeline.json",
+  },
+};

package/examples/transitions/timelines/audio-crossfade.timeline.json

@@ -0,0 +1,44 @@
+{
+  "version": 1,
+  "name": "Audio crossfade",
+  "tracks": [
+    { "id": "v1", "kind": "video" },
+    { "id": "a1", "kind": "audio", "gain": 1 }
+  ],
+  "clips": [
+    {
+      "id": "alpha",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "alpha" },
+      "start": 0,
+      "duration": 60,
+      "audio": { "muted": true }
+    },
+    {
+      "id": "beta",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "beta" },
+      "start": 45,
+      "duration": 60,
+      "audio": { "muted": true }
+    },
+    {
+      "id": "chord-alpha",
+      "track": "a1",
+      "source": { "kind": "audio", "src": "assets/alpha.wav" },
+      "start": 0,
+      "duration": 60
+    },
+    {
+      "id": "chord-beta",
+      "track": "a1",
+      "source": { "kind": "audio", "src": "assets/beta.wav" },
+      "start": 45,
+      "duration": 60
+    }
+  ],
+  "transitions": [
+    { "from": "alpha", "to": "beta", "kind": "dissolve", "easing": "ease-in-out" },
+    { "from": "chord-alpha", "to": "chord-beta", "kind": "crossfade", "easing": "linear" }
+  ]
+}

package/examples/transitions/timelines/transitions.timeline.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "tracks": [{ "id": "main", "kind": "video" }],
+  "clips": [
+    {
+      "id": "alpha",
+      "track": "main",
+      "source": { "kind": "composition", "id": "alpha" },
+      "start": 0,
+      "duration": 60
+    },
+    {
+      "id": "beta",
+      "track": "main",
+      "source": { "kind": "composition", "id": "beta" },
+      "start": 45,
+      "duration": 60
+    },
+    {
+      "id": "gamma",
+      "track": "main",
+      "source": { "kind": "composition", "id": "gamma" },
+      "start": 90,
+      "duration": 30
+    }
+  ],
+  "transitions": [
+    { "from": "alpha", "to": "beta", "kind": "dissolve", "easing": "ease-in-out" },
+    { "from": "beta", "to": "gamma", "kind": "dissolve", "easing": "linear" }
+  ]
+}

package/examples/video/README.md

@@ -92,10 +92,10 @@ node dist/cli.js still video --frame 210 --project examples/video --out video-st
 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
+FRAMEYARD_POLICY=full node dist/cli.js render video --project examples/video --props examples/video/props/video.json
+FRAMEYARD_POLICY=full node dist/cli.js render video-mp4 --project examples/video --props examples/video/props/video.json
+FRAMEYARD_POLICY=full node dist/cli.js render video-timeline --project examples/video --props examples/video/props/video-timeline.json
+FRAMEYARD_POLICY=full node dist/cli.js render video-timeline-mp4 --project examples/video --props examples/video/props/video-timeline.json
 ```
 
 Start the interactive preview with: