@cliangdev/conductor 0.22.0 → 0.24.0

package/assets/claude/skills/conductor-creative/SKILL.md

@@ -121,6 +121,63 @@ worst. A logo lockup and CTA claim land on the last beat only by default; `cta:
 beat overrides that. A carousel renders every card at one shared aspect ratio (`carouselRatio`),
 since the destination platforms require that.
 
+## Video you already have
+
+Not every video needs the brand layout above — a finished clip (a demo recording, an existing edit,
+something a person or another tool already produced) can go up as-is. That's a CLIP Creative: no
+photo, headline or layout, just the video.
+
+1. `upload_creative_media` (local path or URL) — same provenance fields as a photo (`source`,
+   `licence`, `aiGenerated`). It detects video vs. audio vs. photo automatically and, for a video,
+   extracts a poster frame. Use the returned media's id below.
+2. `create_creative` with `kind: "CLIP"` and `clipMedia`. One file for every placement:
+   `{"default": mediaId}`. A different cut per placement (e.g. a square edit for feed, a vertical one
+   for Reels): `{"9x16": mediaId, "4x5": mediaId}` — `default` still covers any placement without its
+   own entry. A reel takes exactly one video, so don't split a reel-eligible placement across two.
+3. `render_creative` — instant for a CLIP (the backend assembles the frames; nothing renders locally
+   here the way a STILL creative's browser-driven render does).
+4. `preview_creative` — returns a small poster sheet across placements instead of the STILL contact
+   sheet, plus each placement's duration. Still worth a look: a poster is one frame, not the whole
+   cut, so open the actual video before calling a rough or misframed clip done.
+5. `attach_creative_to_post`, same as any other Creative.
+
+Mind each destination's own duration limit (per docs/publishing.md) — a clip that's fine on one
+platform may get rejected or trimmed on another; check before attaching to a Post that fans out
+broadly.
+
+## Short videos from a photo or clip
+
+A MOTION Creative animates the same brand layout from steps 1-5 above into a short video, instead
+of a static frame — no separate video tool needed. Use it when a still doesn't hold attention, or a
+destination rewards video over an image.
+
+1. Pick a photo (step 5) or, for a moving background, `upload_creative_media` a video first and
+   note its media id.
+2. `create_creative`/`update_creative` with `kind: "MOTION"` plus:
+   - `motion.preset` — how the copy enters: `fade-up` (default), `word-by-word`, `accent-pop`, or
+     `none` (everything visible from the first frame).
+   - `motion.durationSec` — 3 to 60, default 8.
+   - `motion.background` — `source: "photo"` (default; `motion: "zoom-in"` (default), `zoom-out`,
+     `pan-left`, `pan-right`, or `none`) or `source: "clip"` with `clipMediaId` (from step 1) and
+     `clipStartSec`.
+   - `motion.endCard` — default true: the last 2 seconds hold the finished composition, CTA
+     included, regardless of how short the preset's own entrance would otherwise leave it.
+   - `audio` — `source: "clip"` (the background clip's own recorded sound — the default when there
+     is one), `"track"` (a separate library track: `trackId` from `upload_creative_media`, plus
+     `volume` and `fadeOutSec`), or `"none"`.
+3. `render_creative` runs a local, ffmpeg-driven encode — roughly 20 seconds per placement for an
+   8-second video. No ffmpeg on this machine fails with a clear message naming how to get one rather
+   than silently producing nothing.
+4. `preview_creative` renders three key moments across the timeline into one sheet image (not the
+   finished video). Judge it the same honest way as step 7 above — does the copy's entrance finish
+   before the next beat, does the end card actually hold long enough to read — before spending a
+   full render on it.
+5. `attach_creative_to_post`, same as any Creative — one MP4 per placement.
+
+A library music track's `licence` has to be recorded on upload (same as a photo's provenance) — the
+readiness checklist blocks a MOTION Creative on it whenever `audio.source` is `"track"`. A reel or
+other vertical placement takes exactly one video, same as a CLIP.
+
 ## Failures that are silent (carried over from this skill's predecessor)
 
 Automated checks are real but incomplete. These are the ones worth remembering to look for by eye:

package/assets/cli-manifest.json

@@ -752,9 +752,14 @@
         "version"
       ]
     },
+    {
+      "name": "upload_creative_media",
+      "description": "Upload a photo, video or audio file into the project's media library from a local file or a public URL, recording its provenance for the readiness checklist. Kind, dimensions, duration and audio are detected automatically; a video also gets a poster frame.",
+      "category": "marketing"
+    },
     {
       "name": "upload_creative_photo",
-      "description": "Upload a photo into the project's photo library from a local file or a public URL, recording its provenance for the readiness checklist. Width/height are read from the file.",
+      "description": "Deprecated alias for upload_creative_media — same behavior, including for video/audio.",
       "category": "marketing"
     },
     {

package/dist/commands/creative.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"creative.d.ts","sourceRoot":"","sources":["../../src/commands/creative.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAKnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiEvD"}
+{"version":3,"file":"creative.d.ts","sourceRoot":"","sources":["../../src/commands/creative.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAKnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqEvD"}

package/dist/commands/creative.js

@@ -43,7 +43,12 @@ Examples:
             for (const frame of result.frames) {
                 const label = frame.sequenceIndex != null ? `${frame.placementKey}[${frame.sequenceIndex}]` : frame.placementKey;
                 const size = frame.width && frame.height ? `${frame.width}x${frame.height}` : '';
-                console.log(`  ${label}  ${size}  ${frame.url ?? ''}`.trimEnd());
+                // CLIP/MOTION frames are videos, not JPEGs — durationSeconds/hasAudio/posterUrl are only ever set on those.
+                const duration = frame.durationSeconds != null ? `${frame.durationSeconds}s${frame.hasAudio ? ' audio' : ''}` : '';
+                const parts = [label, size, duration, frame.url ?? ''].filter(Boolean);
+                console.log(`  ${parts.join('  ')}`);
+                if (frame.posterUrl)
+                    console.log(`    poster: ${frame.posterUrl}`);
             }
             if (result.error)
                 console.error(result.error);

package/dist/commands/creative.js.map

@@ -1 +1 @@
-{"version":3,"file":"creative.js","sourceRoot":"","sources":["../../src/commands/creative.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"creative.js","sourceRoot":"","sources":["../../src/commands/creative.ts"],"names":[],"mappings":"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"}

package/dist/creative/assertions.js

@@ -118,7 +118,7 @@ function sameRgb(a, b) {
  * registry entry (pixel size, safe zone); `brand` is the same object handed
  * to renderBoard. An empty `errors` array means the frame is safe to ship;
  * `warnings` are non-fatal (e.g. a soft, upscaled photo). */
-export async function runAssertions(board, placement, brand) {
+export async function runAssertions(board, placement, brand, { outputScale = 2 } = {}) {
   const errors = [];
   const warnings = [];
   const br = rectOf(board);
@@ -162,10 +162,10 @@ export async function runAssertions(board, placement, brand) {
     });
     if (!probe.ok) {
       errors.push(`background photo failed to load: ${bgUrlMatch[1]}`);
-    } else if (placement && probe.w < placement.w * 2 && probe.h < placement.h * 2) {
-      // Soft photography check: a source smaller than the 2x frame is
+    } else if (placement && probe.w < placement.w * outputScale && probe.h < placement.h * outputScale) {
+      // Soft photography check: a source smaller than the output frame (2x for images, 1x for video) is
       // upscaled, so the photo goes soft while the text stays crisp.
-      warnings.push(`photo is ${probe.w}x${probe.h}, upscaled to fit ${placement.w * 2}x${placement.h * 2}`);
+      warnings.push(`photo is ${probe.w}x${probe.h}, upscaled to fit ${placement.w * outputScale}x${placement.h * outputScale}`);
     }
   }
 

package/dist/creative/frame.css

@@ -115,6 +115,27 @@
 .cc-cta__note { font-weight: 600; font-size: var(--cc-note-size); color: var(--cc-note-color); }
 .cc-board--light .cc-cta__note { color: var(--cc-ink-2); }
 
+/* ── Background video (a MOTION clip background) ──────────────────────────── */
+/* One generic rule for every layout: a band/card layout's photo container is
+   already `position:relative; overflow:hidden`, sized to the band/card; a
+   bleed layout has no such container, but `.cc-board` itself is
+   `position:relative; overflow:hidden` (see above), so the video simply
+   covers the whole artboard there instead. render.js always appends this
+   AFTER the still photo (a same-frame fallback while the video loads) and
+   BEFORE the panel/scrim, so plain DOM order — no z-index anywhere in this
+   file — keeps it under the copy and over the photo. `--cc-bg-transform` is
+   motion.js's Ken Burns pan/zoom; unset (a STILL board, which never calls
+   applyMotion) falls back to no transform at all. */
+.cc-bg-video {
+  position: absolute; inset: 0;
+  width: 100%; height: 100%;
+  object-fit: cover;
+  object-position: var(--cc-focal, 50% 50%);
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
+  display: block;
+}
+
 /* ── Safe zones (review guide only, never exported) ───────────────────────── */
 .cc-safe { position: absolute; inset: 0; pointer-events: none; }
 .cc-safe__top    { position: absolute; top: 0; left: 0; right: 0; height: var(--cc-safe-top);

package/dist/creative/frame.js

@@ -9,18 +9,37 @@
  *     placementKey: '9x16' | ...,  // required, a key from the placements registry
  *     sequenceIndex?: number,      // required when creative.sequenceKind is set
  *     placements?, layouts?,       // registry overrides (default: the shipped ones)
+ *     motion?,                     // a MOTION creative's `creative.motion` (see motion.js)
+ *     time?: number,               // applied once at load when `motion` is set (default 0)
+ *     clipStartSec?: number,       // creative.clipStartSec, for a clip background's own seek
  *   }
  *
  * Result contract:
  *   window.__RENDER_RESULT = { ok, errors?, warnings?, width, height } | { ok: false, error }
  *   window.__ready = true   // set exactly once, success or failure, when the
  *                           // job's page.waitForFunction should stop waiting
+ *
+ * MOTION mode (`spec.motion` set): the job needs many frames off of ONE page
+ * load (a fresh navigation per frame would be far too slow — 8s at 30fps is
+ * 240 frames), so after applying `spec.time`/`spec.motion` once at load, this
+ * page also exposes a small driver API for the job to call directly via
+ * repeated `page.evaluate()`s against the SAME already-open page:
+ *   window.__seekMotion(t) -> Promise<true>     // applies motion + seeks the
+ *                                                // clip background (if any) to t
+ *   window.__assertBoard() -> Promise<{errors, warnings, width, height}>
+ *                                                // runs the normal assertions once,
+ *                                                // on demand (never per seek — see
+ *                                                // job/render.mjs, which calls this
+ *                                                // only on the final end-card frame)
+ * __RENDER_RESULT in this mode reports whether the board itself built (not
+ * whether it passes assertions, which __assertBoard reports separately).
  */
 import { resolveAd, resolveSequence, renderBoard, fitBoard } from './render.js';
 import { placements as DEFAULT_PLACEMENTS } from './placements.js';
 import { layouts as DEFAULT_LAYOUTS } from './layouts/index.js';
 import { ensureBrandFont } from './font.js';
 import { runAssertions } from './assertions.js';
+import { applyMotion, seekBackgroundVideo } from './motion.js';
 
 function finish(result) {
   window.__RENDER_RESULT = result;
@@ -66,6 +85,26 @@ async function main() {
     await Promise.all([...document.images].map((img) => (img.decode ? img.decode().catch(() => {}) : null)));
     fitBoard(board, placementsReg);
 
+    if (spec.motion) {
+      const durationSec = spec.motion.durationSec || 8;
+      const t0 = spec.time || 0;
+      applyMotion(board, spec.motion, t0, { durationSec });
+      await seekBackgroundVideo(board, t0, spec.clipStartSec);
+
+      // The job's frame-stepped capture driver (see the header comment above): one page load, many
+      // in-page seeks. Assertions are NOT run here — only once, on demand, via __assertBoard.
+      window.__seekMotion = async (t) => {
+        applyMotion(board, spec.motion, t, { durationSec });
+        await seekBackgroundVideo(board, t, spec.clipStartSec);
+        return true;
+      };
+      // A motion frame is captured at 1x (video), so the photo only needs to cover the placement itself.
+      window.__assertBoard = async () => runAssertions(board, placement, spec.brand || {}, { outputScale: 1 });
+
+      finish({ ok: true, width: placement.w, height: placement.h });
+      return;
+    }
+
     const { errors, warnings, width, height } = await runAssertions(board, placement, spec.brand || {});
     finish({ ok: errors.length === 0, errors, warnings, width, height });
   } catch (err) {

package/dist/creative/job/render.mjs

@@ -19,8 +19,12 @@
  */
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { startServer } from './server.mjs';
 import { createApiTransport } from './transport.mjs';
+import { motionKeyTimes, normalizeMotionCreative } from '../motion.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = join(HERE, '..'); // conductor-creative/, the static root
@@ -42,6 +46,15 @@ const SHEET_CONTENT_TYPE = 'image/jpeg';
 const FRAME_SCALE = 2;
 const SHEET_SCALE = 1;
 
+/* MOTION frames are captured at deviceScaleFactor 1 (the placement's true pixel size) — video, unlike
+ * a placement JPEG, is never worth doubling: it would roughly quadruple every per-frame screenshot
+ * and the ffmpeg encode, for no visible gain on any surface that plays this file back. Quality 90 (a
+ * hair below the placement JPEG's 92) keeps each frame small; H.264's own compression dominates the
+ * final file size regardless. */
+const MOTION_FRAME_SCREENSHOT = { type: 'jpeg', quality: 90 };
+const MOTION_DEVICE_SCALE_FACTOR = 1;
+const DEFAULT_FPS = 30;
+
 async function defaultBrowserFactory() {
   const { chromium } = await import('playwright');
   return chromium.launch();
@@ -84,21 +97,226 @@ export function framesFor(spec) {
   return (placements || []).map((placementKey) => ({ page: 'frame.html', placementKey }));
 }
 
-/** Renders every frame a spec calls for, uploads each PNG, and reports
- * complete/fail. Options:
+/* ── MOTION: frame-stepped video capture ──────────────────────────────────── */
+
+/* Writes `chunk` to `stream` and resolves once Node has flushed it, which
+ * naturally serializes the capture-then-write pipeline (screenshot, write,
+ * await, screenshot, write, ...) without any separate backpressure/'drain'
+ * handling — the write for frame i+1 never starts until frame i's bytes have
+ * actually left the process. */
+function writeAsync(stream, chunk) {
+  return new Promise((resolve, reject) => {
+    stream.write(chunk, (err) => (err ? reject(err) : resolve()));
+  });
+}
+
+/* The URL ffmpeg should read audio from, per spec.creative.audio.source (see
+ * README's Creative fields / motion.js's header comment): 'clip' reuses the
+ * SAME clip already playing as the video background (its own recorded
+ * sound); 'track' is a separate library audio file with its own signed URL.
+ * `null` for 'none' or a spec with no audio at all. */
+function audioSourceUrl(creative) {
+  const audio = creative.audio;
+  if (!audio || audio.source === 'none') return null;
+  if (audio.source === 'clip') return creative.backgroundVideoUrl || null;
+  if (audio.source === 'track') return audio.trackUrl || null;
+  return null;
+}
+
+async function downloadToTemp(url, dir, name) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`failed to download audio (${url}): ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  const path = join(dir, name);
+  await writeFile(path, buf);
+  return path;
+}
+
+/* ffmpeg argv for one MOTION placement: JPEGs piped in via stdin (image2pipe,
+ * one concatenated JPEG stream — ffmpeg's own SOI/EOI framing needs no extra
+ * delimiting), an optional audio input trimmed to durationSec, H.264/AAC,
+ * faststart. `-movflags +faststart` needs a seekable output (it rewrites the
+ * moov atom after the first encode pass), so `outPath` is a real temp file,
+ * never stdout. */
+function buildFfmpegArgs({ fps, durationSec, audioPath, audioSource, clipStartSec, volume, fadeOutSec, outPath }) {
+  const args = ['-f', 'image2pipe', '-framerate', String(fps), '-i', '-'];
+  if (audioPath) {
+    if (audioSource === 'clip') {
+      args.push('-ss', String(clipStartSec || 0), '-t', String(durationSec), '-i', audioPath);
+    } else {
+      args.push('-t', String(durationSec), '-i', audioPath);
+    }
+  }
+  // The piped JPEGs are full-range (yuvj420p); platforms expect limited-range yuv420p, so convert the range
+  // explicitly — `-pix_fmt yuv420p` alone keeps the full-range flag and ffprobe still reports yuvj420p.
+  // Map streams explicitly. A clip used for its sound is an MP4 with its own video stream, and ffmpeg's
+  // default picks the highest-resolution video among the inputs — for a 4:5 or 1:1 frame that is the
+  // clip's 9:16 picture, so the output was the raw clip, not the rendered creative.
+  args.push('-map', '0:v:0');
+  if (audioPath) args.push('-map', '1:a:0?');
+  args.push('-vf', 'scale=in_range=pc:out_range=tv,format=yuv420p', '-color_range', 'tv');
+  args.push('-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '20', '-preset', 'veryfast', '-r', String(fps));
+  if (audioPath) {
+    // A clip's own sound plays as recorded — untouched. A library track is a music bed layered under
+    // the creative, so only IT gets volume control and a fade-out (README/the contract: "volume,
+    // afade=t=out..." is listed for 'track', not for 'clip').
+    if (audioSource === 'track') {
+      const v = volume != null ? volume : 0.8;
+      const fadeOut = fadeOutSec != null ? fadeOutSec : 1;
+      const filters = [`volume=${v}`];
+      if (fadeOut > 0) filters.push(`afade=t=out:st=${Math.max(0, durationSec - fadeOut)}:d=${fadeOut}`);
+      args.push('-af', filters.join(','));
+    }
+    // Bound the output by the video's own length, not `-shortest`: the audio file reads instantly while
+    // frames trickle in through the pipe, and `-shortest` could end the file as soon as audio hit EOF
+    // (it raced — one placement would finish, the next would be cut off mid-render).
+    args.push('-c:a', 'aac', '-b:a', '128k', '-t', String(durationSec));
+  }
+  args.push('-movflags', '+faststart', '-y', outPath);
+  return args;
+}
+
+/* Renders ONE placement's MOTION video: one frame.html page load, then N
+ * in-page seeks (frame.js's window.__seekMotion — see its header comment for
+ * why this is not N page loads), streaming each screenshot into an ffmpeg
+ * child process. Runs the layout assertions exactly once, on the final
+ * (end-card) frame; a failure throws before any upload happens. Resolves
+ * `{ bytes, posterBytes, width, height, durationSeconds, hasAudio, warnings }`. */
+async function renderMotionPlacement({ browser, origin, spec, placementKey, ffmpegPath, fps, log }) {
+  const motion = spec.creative.motion || {};
+  const durationSec = motion.durationSec || 8;
+  const frameCount = Math.max(1, Math.round(durationSec * fps));
+  const warnings = [];
+
+  const tmpDir = await mkdtemp(join(tmpdir(), 'cc-motion-'));
+  const page = await browser.newPage({ deviceScaleFactor: MOTION_DEVICE_SCALE_FACTOR });
+  let ffmpeg;
+  try {
+    await page.addInitScript((s) => {
+      window.__RENDER_SPEC__ = s;
+    }, {
+      creative: spec.creative,
+      brand: spec.brand,
+      placementKey,
+      motion: spec.creative.motion,
+      time: 0,
+      clipStartSec: spec.creative.clipStartSec,
+    });
+    await page.goto(`${origin}/frame.html`, { waitUntil: 'load', timeout: PAGE_TIMEOUT_MS });
+    await page.waitForFunction(() => window.__ready === true, null, { timeout: PAGE_TIMEOUT_MS });
+    const boot = await page.evaluate(() => window.__RENDER_RESULT);
+    if (!boot || !boot.ok) {
+      throw new Error(`${placementKey}: ${(boot && boot.error) || 'failed to build the MOTION board'}`);
+    }
+    const box = await page.locator('.cc-board').first().boundingBox();
+    const width = Math.round((box && box.width) || 0);
+    const height = Math.round((box && box.height) || 0);
+
+    const srcUrl = audioSourceUrl(spec.creative);
+    const audioPath = srcUrl ? await downloadToTemp(srcUrl, tmpDir, 'audio-src') : null;
+    const audio = spec.creative.audio;
+
+    const outPath = join(tmpDir, `${placementKey}.mp4`);
+    const args = buildFfmpegArgs({
+      fps,
+      durationSec,
+      audioPath,
+      audioSource: audio && audio.source,
+      clipStartSec: spec.creative.clipStartSec,
+      volume: audio && audio.volume,
+      fadeOutSec: audio && audio.fadeOutSec,
+      outPath,
+    });
+    ffmpeg = spawn(ffmpegPath, args, { stdio: ['pipe', 'ignore', 'pipe'] });
+    // If ffmpeg exits early, the next frame write fails with EPIPE; without a listener that 'error' event
+    // is unhandled and kills the whole process (no failure is reported and the render stays RUNNING).
+    // The write's own callback rejects too, and the loop below turns that into ffmpeg's real message.
+    ffmpeg.stdin.on('error', () => {});
+    let ffmpegErr = '';
+    ffmpeg.stderr.on('data', (chunk) => {
+      ffmpegErr += chunk.toString();
+    });
+    const ffmpegExit = new Promise((resolve, reject) => {
+      ffmpeg.on('error', reject);
+      ffmpeg.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`ffmpeg exited ${code}: ${ffmpegErr.slice(-2000)}`))));
+    });
+    // An end-card assertion failure (below) throws before `await ffmpegExit` is ever reached, and the
+    // `finally` block then kills ffmpeg — which rejects this same promise with nothing left awaiting
+    // it. Without this, that becomes an unhandled rejection; this does not change what the success
+    // path below still awaits and reports.
+    ffmpegExit.catch(() => {});
+
+    let posterBytes = null;
+    let lastLoggedPct = -25;
+    for (let i = 0; i < frameCount; i += 1) {
+      const t = i / fps;
+      const seeked = await page.evaluate((tt) => window.__seekMotion(tt), t);
+      if (!seeked) throw new Error(`${placementKey}: motion seek failed at t=${t.toFixed(2)}s`);
+
+      if (i === frameCount - 1) {
+        const assertion = await page.evaluate(() => window.__assertBoard());
+        if (!assertion || (assertion.errors && assertion.errors.length)) {
+          const detail = (assertion && assertion.errors && assertion.errors.join('; ')) || 'end-card assertions failed';
+          throw new Error(`${placementKey}: ${detail}`);
+        }
+        (assertion.warnings || []).forEach((message) => warnings.push(message));
+      }
+
+      const bytes = await page.locator('.cc-board').first().screenshot(MOTION_FRAME_SCREENSHOT);
+      if (i === frameCount - 1) posterBytes = bytes;
+      try {
+        await writeAsync(ffmpeg.stdin, bytes);
+      } catch (err) {
+        // ffmpeg stopped reading: report why it stopped (its exit message), not the pipe error. Give it a
+        // moment to finish exiting so its stderr is complete.
+        const exitErr = await Promise.race([
+          ffmpegExit.then(() => null, (e) => e),
+          new Promise((resolve) => setTimeout(() => resolve(null), 5000)),
+        ]);
+        throw new Error(`${placementKey}: ${exitErr ? exitErr.message : `ffmpeg stopped reading frames (${err.code || err.message}): ${ffmpegErr.slice(-1500)}`}`);
+      }
+
+      const pct = Math.floor(((i + 1) / frameCount) * 100);
+      if (pct >= lastLoggedPct + 25 || i === frameCount - 1) {
+        log(`${placementKey}: ${pct}% (${i + 1}/${frameCount} frames)`);
+        lastLoggedPct = pct;
+      }
+    }
+    ffmpeg.stdin.end();
+    await ffmpegExit;
+    ffmpeg = null;
+
+    const bytes = await readFile(outPath);
+    return { bytes, posterBytes, width, height, durationSeconds: durationSec, hasAudio: Boolean(audioPath), warnings };
+  } finally {
+    if (ffmpeg && ffmpeg.exitCode === null) {
+      try { ffmpeg.kill('SIGKILL'); } catch { /* already gone */ }
+    }
+    await page.close().catch(() => {});
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/** Renders every frame a spec calls for, uploads each PNG (or, for a MOTION
+ * creative that is not `previewOnly`, one MP4 + poster per placement — see
+ * renderMotionPlacement above), and reports complete/fail. Options:
  *   transport        required. See transport.mjs.
  *   packageRoot       static root to serve (default: this package's own root).
  *   browserFactory    () => Promise<Browser> (default: launches real Playwright chromium).
+ *   ffmpegPath        a local ffmpeg binary's path. Required for a MOTION
+ *                     render (not previewOnly) — ignored otherwise.
+ *   fps               frames per second for a MOTION render (default 30).
  *   log               (...args) => void (default: console.log).
  * Resolves `true` on success, `false` on a reported failure (never throws —
  * a thrown error from a truly unexpected place still gets caught and turned
  * into a `transport.fail()` call before resolving `false`, so a caller never
  * has to guess whether `transport.fail` was already called). */
-export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactory = defaultBrowserFactory, log = console.log }) {
+export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactory = defaultBrowserFactory, ffmpegPath, fps = DEFAULT_FPS, log = console.log }) {
   let spec;
   try {
     log('fetching spec');
     spec = await transport.getSpec();
+    if (spec && spec.creative) spec = { ...spec, creative: normalizeMotionCreative(spec.creative) };
   } catch (err) {
     log(`FAIL ${err.message}`);
     await reportFailure(transport, err.message, log);
@@ -110,6 +328,40 @@ export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactor
   const warnings = [];
   try {
     browser = await browserFactory();
+    const isMotionRender = spec.creative && spec.creative.kind === 'MOTION' && !spec.previewOnly;
+
+    if (isMotionRender) {
+      if (!ffmpegPath) {
+        throw new Error(
+          'a MOTION render needs a local ffmpeg binary — pass `ffmpegPath` to run() (e.g. a system '
+          + '`ffmpeg` found via `which ffmpeg`, or a bundled ffmpeg-static build; conductor-tools '
+          + 'resolves this the same way it resolves Chromium).'
+        );
+      }
+      const placements = spec.placements || [];
+      if (!placements.length) {
+        throw new Error('the render spec names no placements to render (check the Brand Kit\'s enabled placements)');
+      }
+      log(`rendering ${placements.length} MOTION placement(s) at ${fps}fps`);
+      for (const placementKey of placements) {
+        const result = await renderMotionPlacement({ browser, origin, spec, placementKey, ffmpegPath, fps, log });
+        for (const message of result.warnings) warnings.push({ placementKey, message });
+        await transport.putFrame(placementKey, {
+          bytes: result.bytes,
+          contentType: 'video/mp4',
+          width: result.width,
+          height: result.height,
+          durationSeconds: result.durationSeconds,
+          hasAudio: result.hasAudio,
+        });
+        await transport.putPoster(placementKey, result.posterBytes);
+        log(`ok   ${placementKey}  video/mp4  ${result.width}x${result.height}  ${result.durationSeconds}s  audio=${result.hasAudio}`);
+      }
+      await transport.complete(warnings);
+      log(`complete (${warnings.length} warning(s))`);
+      return true;
+    }
+
     const frames = framesFor(spec);
     log(`rendering ${frames.length} frame(s)`);
 
@@ -119,6 +371,7 @@ export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactor
       const scale = isSheet ? SHEET_SCALE : FRAME_SCALE;
       const page = await browser.newPage({ deviceScaleFactor: scale });
       try {
+        const isMotionSheet = isSheet && spec.creative && spec.creative.kind === 'MOTION' && spec.creative.motion;
         await page.addInitScript((s) => {
           window.__RENDER_SPEC__ = s;
         }, {
@@ -127,6 +380,7 @@ export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactor
           placementKey: frame.placementKey,
           sequenceIndex: frame.index,
           placementKeys: spec.placements,
+          ...(isMotionSheet ? { times: motionKeyTimes(spec.creative.motion) } : {}),
         });
         await page.goto(`${origin}/${frame.page}`, { waitUntil: 'load', timeout: PAGE_TIMEOUT_MS });
         await page.waitForFunction(() => window.__ready === true, null, { timeout: PAGE_TIMEOUT_MS });
@@ -191,6 +445,9 @@ if (isMain()) {
   const previewOnly = /^(1|true)$/i.test(process.env.PREVIEW_ONLY || '');
   const renderer = process.env.RENDERER || 'cli';
   const workflowRunId = process.env.WORKFLOW_RUN_ID || undefined;
+  // MOTION only; a STILL/CLIP render, or a previewOnly one, never touches ffmpeg.
+  const ffmpegPath = process.env.FFMPEG_PATH || undefined;
+  const fps = process.env.FPS ? Number(process.env.FPS) : undefined;
   const missing = ['CONDUCTOR_API_URL', 'CONDUCTOR_API_KEY', 'CONDUCTOR_PROJECT_ID', 'CREATIVE_ID'].filter((k) => !process.env[k]);
   if (missing.length) {
     console.error(`missing required env var(s): ${missing.join(', ')}`);
@@ -199,5 +456,5 @@ if (isMain()) {
 
   const transport = createApiTransport({ apiUrl, apiKey, projectId, creativeId, previewOnly, renderer, workflowRunId });
   const log = (...args) => console.log(`[render ${creativeId}]`, ...args);
-  run({ transport, log }).then((ok) => process.exit(ok ? 0 : 1));
+  run({ transport, log, ffmpegPath, ...(fps ? { fps } : {}) }).then((ok) => process.exit(ok ? 0 : 1));
 }