belt-trailer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed9f2883e65374fed7efa5bddb143815548b666eeef890a4131c8a9fd2cdb0d7
-  data.tar.gz: db1be41d567472e59d903753807bef4931343bfacd16bb5d86759f19cbb21faf
+  metadata.gz: 6305cc863de1b96aa6052687e9bfb058d37173d8c87a9e1bd2e2e80f2c686782
+  data.tar.gz: 29d6ad1a84d46e9e70b8118e86499c3310b7a0750d49fb0a5a8a22923c230366
 SHA512:
-  metadata.gz: cbcbcb3fca347996debac439fea243eaf69046f91194f3c63468f3066dfd5a27277a0f5007230dbfbd02a1888e3f40b3a5ae253b0b8ad51adf977c541f21c064
-  data.tar.gz: 8e950ded3ad819261b365ea9b2e2baa0db8e2187bf65e67325429c50d0090ae3a365c2f0530716516e509cd9e2c3126def5090dd27f71b8b2f852703c61ce3e9
+  metadata.gz: b48f3596c962441ceebb65c7e2567e0d2982f05564e714d31a695e4fb23115a9138a4ecc253ee54d991569dc87d795854a660c8ca8115d265a10eb9ea51cfd21
+  data.tar.gz: fb5d0a83e35c95e3be7f8504becb333ef606c0bb2a20843ab5f5b5fde0982dc82f1cfa62434144879cdff34b21b2cff5f7e9ae3ebf8e787b8b7afd83083b2a30

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.0
+
+- Transitions between beats (Fizzy #1967): `transition: { type, ms }` in the
+  config, or per beat for the change into it. `dissolve`, `dip`, `dip-white`,
+  `slide`, `slide-right` and `wipe` overlap the two beats with ffmpeg `xfade`;
+  `cut` (the default) joins them end to end as before, without re-encoding.
+  Beat starts in `trailer-<format>.json`, effects and music follow the overlap.
+  Titles leave before the transition out of their beat, so no words show
+  through a dissolve. FeatureParity's trailer jumped between unrelated
+  framings at every change of page; hard cuts were all the engine could do.
+
 ## 0.1.0
 
 - The engine, split out of Posh Nosh's launch trailer (Fizzy #1818) and made

data/README.md

@@ -90,7 +90,7 @@ All take `--frontend NAME` (from `config/frontends.yml`; default `frontend/`), `
 
 `--clean` deletes those beats' old clips, leftover frame directories and the cached live sounds first. `--sounds bundled` plays the app's bundled files rather than the live site's replacements.
 
-**cut** joins the beats in config order, lays every effect where the app played it (ringing on past its own beat) and the music by the plan, and levels the whole thing. Writes `trailer-<format>.mp4` and `trailer-<format>.json` (where each beat starts, and every audio file in the cut). `--music PLAN` cuts with a named plan from `music.plans` into `trailer-<format>-<PLAN>.mp4`.
+**cut** joins the beats in config order (with a hard cut or a transition between each pair, see `transition` below), lays every effect where the app played it (ringing on past its own beat) and the music by the plan, and levels the whole thing. Writes `trailer-<format>.mp4` and `trailer-<format>.json` (where each beat starts, and every audio file in the cut). `--music PLAN` cuts with a named plan from `music.plans` into `trailer-<format>-<PLAN>.mp4`.
 
 **check** passes or fails a cut, exiting 1 on a fail:
 
@@ -147,6 +147,11 @@ export default {
   fps: 30,
   settle: 1500,                           // ms the page runs before a beat starts
   check: { maxSeconds: 30 },
+  // How the cut goes from one beat into the next: 'cut' (the default),
+  // 'dissolve', 'dip' (through black), 'dip-white', 'slide', 'slide-right'
+  // or 'wipe', over `ms`. A beat can set its own, for the change into it:
+  // transition: 'dip' or { type: 'dissolve', ms: 400 }.
+  transition: { type: 'dissolve', ms: 500 },
 
   beats: [
     { name: 'hook', view: 'battle-start', query: 'chat=on', css: '…', settle: 500,
@@ -192,6 +197,8 @@ Behind query flags, so the showcase stays quiet for screenshots:
 
 **Sound is captured, not placed.** An init script tags each `Response.arrayBuffer` with its URL, carries the tag through `decodeAudioData` to the `AudioBuffer`, and records `AudioBufferSourceNode.start(when)` with its scheduled delay. Each frame the recorder drains the list and notes the frame. Chromium runs with `--autoplay-policy=no-user-gesture-required`, and a key press unlocks the app's audio as a first tap would.
 
+**Transitions overlap.** A dissolve, dip, slide or wipe of 0.5 s blends the last 0.5 s of one beat with the first 0.5 s of the next (ffmpeg `xfade`), so the cut is shorter than the beats added up, by every transition's length. Lengths are snapped to whole frames. Effects and music are laid where each beat starts in the cut, so they stay with their pictures. Titles leave `titles.leaveBefore` before the transition out of their beat starts, not before the cut, so no words are left showing through a dissolve. With only cuts, the clips are joined without being encoded again.
+
 **The cut.** `amix` takes its timeline from its first input, so that's `anullsrc` for the whole length; every input is delayed and resampled from 0. The mix is rendered to 32-bit float WAV and then muxed. Each music track is brought to −16 LUFS with one measured gain; the trailer is brought to −14 LUFS with one measured gain and limited at 0.63 (about 4 dB of headroom for the AAC encode). `loudnorm`'s dynamic mode ducked the music after every hit and isn't used.
 
 ## Rules learned the hard way

data/engine/lib/config.mjs

@@ -24,9 +24,49 @@ export const DEFAULTS = {
   sounds: { bundled: 'public', live: null, ignore: [], cache: 'tmp/trailer-sounds' },
   music: { level: 0.7, fade: 1.5, loudness: -16, plan: {}, plans: {}, tracks: {} },
   mix: { loudness: -14, limit: 0.63 },
+  // How the cut goes from one beat into the next, unless a beat says
+  // otherwise with its own `transition`. 'cut' joins them end to end.
+  transition: { type: 'cut', ms: 600 },
   check: { maxSeconds: 30, loudness: -14, tolerance: 1, truePeak: -1 },
 };
 
+// The transitions a beat can come in on, and the ffmpeg xfade each one is.
+// 'cut' is none: the beats are joined end to end.
+export const TRANSITIONS = {
+  cut: null,
+  dissolve: 'fade',
+  dip: 'fadeblack',
+  'dip-white': 'fadewhite',
+  slide: 'slideleft',
+  'slide-right': 'slideright',
+  wipe: 'wipeleft',
+};
+
+// A transition as written in the config: a name, or { type, ms }.
+export function transitionOf(value) {
+  if (value == null) return {};
+  return typeof value === 'string' ? { type: value } : value;
+}
+
+// How long the transition out of `name` into the next beat is, in seconds
+// before it's snapped to frames (0 for a cut, or the last beat). The cut
+// overlaps that much of this beat's end with the next one.
+export function transitionOut(config, name) {
+  const i = config.beats.findIndex(b => b.name === name);
+  const next = config.beats[i + 1];
+  if (i < 0 || !next) return 0;
+  const own = transitionOf(next.transition);
+  const type = own.type ?? config.transition.type;
+  return type === 'cut' ? 0 : (own.ms ?? config.transition.ms) / 1000;
+}
+
+function checkTransition({ type, ms }, where) {
+  if (type != null && !(type in TRANSITIONS)) {
+    throw new Error(`${where} is ${type}; use one of ${Object.keys(TRANSITIONS).join(', ')}`);
+  }
+  if (ms != null && !(ms > 0)) throw new Error(`${where} needs ms above 0`);
+}
+
 // Loads `file` (relative to `appDir`) and fills in the defaults.
 export async function loadConfig(appDir, file = 'trailer.config.mjs') {
   const full = path.resolve(appDir, file);
@@ -46,16 +86,19 @@ export function normalize(raw, appDir) {
     sounds: { ...DEFAULTS.sounds, ...raw.sounds },
     music: { ...DEFAULTS.music, ...raw.music },
     mix: { ...DEFAULTS.mix, ...raw.mix },
+    transition: { ...DEFAULTS.transition, ...transitionOf(raw.transition) },
     check: { ...DEFAULTS.check, ...raw.check },
   };
   if (!config.showcase || !(config.showcase.build || config.showcase.url)) {
     throw new Error('trailer.config.mjs needs showcase: { build } (a module that builds the showcase) or showcase: { url }');
   }
+  checkTransition(config.transition, 'transition');
   if (!Array.isArray(config.beats) || !config.beats.length) throw new Error('trailer.config.mjs has no beats');
   const names = new Set();
   for (const beat of config.beats) {
     if (!beat.name || typeof beat.play !== 'function') throw new Error('every beat needs a name and a play function');
     if (names.has(beat.name)) throw new Error(`two beats are called ${beat.name}`);
+    checkTransition(transitionOf(beat.transition), `${beat.name}'s transition`);
     names.add(beat.name);
   }
   return config;

data/engine/lib/cut.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ffmpeg, loudness } from './ffmpeg.mjs';
-import { loadConfig, outDir, pickFormats } from './config.mjs';
+import { loadConfig, outDir, pickFormats, TRANSITIONS, transitionOf } from './config.mjs';
 import { liveSounds } from './sound.mjs';
 
 // Runs of beats under the same music track. A beat's 'hush' mark stops its
@@ -45,6 +45,54 @@ export function runEnvelope(runs, i, total, fade) {
   };
 }
 
+// How each beat comes in: its own `transition`, else the config's. The first
+// beat has nothing to come in from. A transition overlaps the end of one beat
+// with the start of the next, so its length is snapped to whole frames and
+// kept shorter than either beat.
+export function transitions(config, beats, fps) {
+  return beats.map((beat, i) => {
+    if (i === 0) return { type: 'cut', seconds: 0 };
+    const own = transitionOf(config.beats.find(b => b.name === beat.name)?.transition);
+    const type = own.type ?? config.transition.type;
+    if (type === 'cut') return { type, seconds: 0 };
+    const ms = own.ms ?? config.transition.ms;
+    const seconds = Math.round((ms / 1000) * fps) / fps;
+    const shortest = Math.min(beats[i - 1].seconds, beat.seconds);
+    if (seconds >= shortest) throw new Error(`the ${type} into ${beat.name} (${ms} ms) is as long as a beat it joins; make it shorter`);
+    return { type, seconds };
+  });
+}
+
+// Where each beat starts in the cut, and how long the cut is, once each
+// transition overlaps a beat with the one before it.
+export function layout(seconds, overlaps) {
+  let t = 0;
+  const starts = seconds.map((s, i) => {
+    t -= overlaps[i] || 0;
+    const start = t;
+    t += s;
+    return start;
+  });
+  return { starts, total: t };
+}
+
+// The ffmpeg filter that joins the beat clips (inputs 0…n-1) with their
+// transitions into [video].
+export function joinFilter(steps, starts, fps) {
+  const parts = steps.map((_, i) => `[${i}:v]settb=AVTB,fps=${fps},format=yuv420p,setpts=PTS-STARTPTS[b${i}]`);
+  let last = 'b0';
+  for (let i = 1; i < steps.length; i += 1) {
+    const out = i === steps.length - 1 ? 'video' : `j${i}`;
+    const { type, seconds } = steps[i];
+    parts.push(type === 'cut'
+      ? `[${last}][b${i}]concat=n=2:v=1:a=0[${out}]`
+      : `[${last}][b${i}]xfade=transition=${TRANSITIONS[type]}:duration=${seconds.toFixed(6)}:offset=${starts[i].toFixed(6)}[${out}]`);
+    last = out;
+  }
+  if (steps.length === 1) parts.push('[b0]null[video]');
+  return parts.join(';');
+}
+
 // The music plan to cut with: the default `music.plan`, or a named one from
 // `music.plans`.
 export function pickPlan(config, name) {
@@ -72,7 +120,6 @@ export async function cut(appDir, opts = {}) {
   const written = [];
 
   for (const format of pickFormats(config, opts.format)) {
-    let t = 0;
     const beats = config.beats.map(({ name }) => {
       const file = path.join(dir, `${name}-${format.name}.mp4`);
       const meta = path.join(dir, `${name}-${format.name}.json`);
@@ -80,11 +127,11 @@ export async function cut(appDir, opts = {}) {
         throw new Error(`${path.relative(process.cwd(), file)} is missing: film it first (belt trailer film --only ${name} --format ${format.name})`);
       }
       const { seconds, sounds, marks = {} } = JSON.parse(fs.readFileSync(meta, 'utf8'));
-      const beat = { name, track: plan[name] ?? null, file, start: t, seconds, sounds, hush: marks.hush };
-      t += seconds;
-      return beat;
+      return { name, track: plan[name] ?? null, file, seconds, sounds, hush: marks.hush };
     });
-    const total = t;
+    const steps = transitions(config, beats, config.fps);
+    const { starts, total } = layout(beats.map(b => b.seconds), steps.map(s => s.seconds));
+    beats.forEach((beat, i) => { beat.start = starts[i]; beat.transition = steps[i]; });
     const runs = planRuns(beats);
     if (!runs[0].track) console.warn(`  ! no music under ${beats[0].name}: a silent cold open reads as a broken video`);
 
@@ -124,10 +171,18 @@ export async function cut(appDir, opts = {}) {
 
     const work = fs.mkdtempSync(path.join(dir, '.cut-'));
     try {
-      const list = path.join(work, 'list.txt');
-      fs.writeFileSync(list, beats.map(b => `file '${b.file.replace(/'/g, "'\\''")}'`).join('\n'));
       const video = path.join(work, 'video.mp4');
-      ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, '-an', '-c', 'copy', video]);
+      if (steps.every(s => s.type === 'cut')) {
+        const list = path.join(work, 'list.txt');
+        fs.writeFileSync(list, beats.map(b => `file '${b.file.replace(/'/g, "'\\''")}'`).join('\n'));
+        ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, '-an', '-c', 'copy', video]);
+      } else {
+        // A transition blends two clips, so the picture is encoded again, at
+        // the same settings the beats were filmed with.
+        ffmpeg([...beats.flatMap(b => ['-i', b.file]), '-filter_complex', joinFilter(steps, starts, config.fps),
+          '-map', '[video]', '-an', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '14', '-r', String(config.fps),
+          '-t', total.toFixed(6), video]);
+      }
 
       // amix takes its timeline from its first input, so that is silence
       // from 0 for the whole trailer: with music first, everything before
@@ -156,7 +211,10 @@ export async function cut(appDir, opts = {}) {
       ffmpeg(['-i', video, '-i', wav, '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', '-t', total.toFixed(6), out]);
       fs.writeFileSync(out.replace(/\.mp4$/, '.json'), `${JSON.stringify({
         format: format.name, music: opts.music || 'default', seconds: Number(total.toFixed(3)),
-        beats: beats.map(b => ({ name: b.name, start: Number(b.start.toFixed(3)), seconds: b.seconds, track: b.track })),
+        beats: beats.map(b => ({
+          name: b.name, start: Number(b.start.toFixed(3)), seconds: b.seconds, track: b.track,
+          ...(b.transition.type === 'cut' ? {} : { transition: { type: b.transition.type, seconds: Number(b.transition.seconds.toFixed(3)) } }),
+        })),
         sources,
       }, null, 2)}\n`);
       console.log(`${path.relative(process.cwd(), out)}  ${total.toFixed(1)} s`);

data/engine/lib/film.mjs

@@ -122,7 +122,7 @@ export async function film(appDir, opts = {}) {
         await beat.play(stage(page, cam, format));
         await page.close();
         if (!cam.frames) throw new Error(`beat ${beat.name} filmed no frames: its play() never called cam.hold, move or shoot`);
-        await filmTitles(browser, { site, route, config, format, cues: cam.cues, frames: cam.frames, dir: titles });
+        await filmTitles(browser, { site, route, config, format, beat: beat.name, cues: cam.cues, frames: cam.frames, dir: titles });
 
         // The effects the beat played, for the cut to lay across the whole
         // trailer (a knockout rings on past its own beat), and mixed into the

data/engine/lib/titles.mjs

@@ -4,6 +4,7 @@
 import path from 'node:path';
 import { freeze, step } from './clock.mjs';
 import { TITLES_PATH } from './showcase.mjs';
+import { transitionOut } from './config.mjs';
 
 // The cues with a closing hide added: a title still up near the end leaves
 // `leaveBefore` seconds before the cut, so a shot never ends on words and the
@@ -15,7 +16,7 @@ export function closeTitles(cues, frames, fps, leaveBefore) {
   return [...cues, { frame: Math.max(last.frame + 1, frames - Math.round(leaveBefore * fps)), hide: true }];
 }
 
-export async function filmTitles(browser, { site, route, config, format, cues, frames, dir }) {
+export async function filmTitles(browser, { site, route, config, format, beat, cues, frames, dir }) {
   const [width, height] = format.out;
   const page = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: 1 });
   await page.route(`${site.origin}/**`, route);
@@ -27,7 +28,9 @@ export async function filmTitles(browser, { site, route, config, format, cues, f
   }, config.titles.endCard?.logo);
   await freeze(page);
   const frameMs = 1000 / config.fps;
-  const all = closeTitles(cues, frames, config.fps, config.titles.leaveBefore);
+  // Words leave before the next beat starts to come in, not just before the
+  // cut: a dissolve shows the end of this beat under the next one.
+  const all = closeTitles(cues, frames, config.fps, config.titles.leaveBefore + transitionOut(config, beat));
   let now = 0;
   for (let i = 0; i < frames; i += 1) {
     for (const cue of all.filter(c => c.frame === i)) {

data/engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "belt-trailer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "description": "Films a launch trailer of a web app from its own screens and sounds",
   "type": "module",

data/lib/belt/trailer/version.rb

@@ -2,6 +2,6 @@
 
 module Belt
   module Trailer
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

data/skills/belt-trailer/SKILL.md

@@ -13,7 +13,7 @@ description: >-
   editing of footage that wasn't filmed from the app, or vehicle trailers.
 metadata:
   author: stowzilla
-  version: "0.1.0"
+  version: "0.2.0"
 ---
 
 # belt-trailer

data/skills/belt-trailer/references/beats.md

@@ -110,6 +110,26 @@ await cam.hold(1300);
   } },
 ```
 
+## Between beats: transitions
+
+By default beats are joined with a hard cut. That works when the next beat
+opens on the framing the last one ended on. Between two different pages, or
+from a close-up to a wide shot, a hard cut reads as a glitch, so set a
+transition:
+
+```js
+transition: { type: 'dissolve', ms: 500 },          // every change of beat
+{ name: 'end', transition: 'dip', play: … },        // into this beat only
+{ name: 'level', transition: 'cut', play: … },      // a hard cut here
+```
+
+Types: `cut`, `dissolve`, `dip` (through black), `dip-white`, `slide`,
+`slide-right`, `wipe`. A transition overlaps the two beats, so the cut gets
+shorter by its length, and titles leave that much earlier. Add the same to
+the hold after a beat's last title so it is still read for ~2 s. Keep them
+short (0.4–0.6 s) and the same throughout; a different one is for a change
+of mood (into the end card, say).
+
 ## Wide and tall
 
 The same beat films both formats: wide from a 1280×720 page, tall from a

data/skills/belt-trailer/references/storyboard.md

@@ -58,6 +58,8 @@ The beat names are yours (`--only` takes them), lower-case, one word.
 - Every product shot is **the same session at a later moment**: the same
   records, people, names and numbers moving forward. Say so in the
   storyboard and name the fixture function that builds them.
+- **Between pages, transition**: when the next beat is a different screen,
+  write the transition (usually a 0.5 s dissolve) in the Camera column.
 - **Match framing across cuts**: end a shot on the framing the next one opens
   with. Write the end framing and the next opening framing in the Camera column.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt-trailer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stowzilla
@@ -96,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.24
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Film a launch trailer of a web app from its own screens and sounds
 test_files: []