Skip to content

fix(timeline): refuse colors that are not colors before they reach FFmpeg - #72

Merged
yultyyev merged 1 commit into
feat/shortsfrom
fix/timeline-color-validation
Nov 15, 2026
Merged

yultyyev merged 1 commit into
feat/shortsfrom
fix/timeline-color-validation

Conversation

@yultyyev

@yultyyev yultyyev commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

What

  • New src/timeline/color.ts: isColor, invalidColorMessage and a Zod ColorSchema. It accepts FFmpeg's 140 color names (any case), hex #rrggbb[aa] / 0xrrggbb[aa] (bare rrggbb[aa] too, which FFmpeg also reads), and an optional @alpha from 0 to 1 or 0x00–0xff. Everything else is refused with: "<value>" is not a color. Use a color name like black or white, or hex like #ffcc00, optionally with @0.5 for opacity.
  • Entry points validate:
    • the add_color verb (EditableVerbSchema for MCP timeline_edit, CompositionVerbSchema for the clip ui verbs route)
    • clip timeline new --background and clip timeline add-color --color. Both throw before writing, so a bad --background no longer replaces the current document.
  • The compiler's quoteColor now throws a CompileError (Color clip "<id>" color … / Canvas background …) instead of emitting the value. It runs during plan building, so nothing reaches FFmpeg, and checkExportable reports it as a blocker in timeline show / timeline_check.
  • Removed docs/backlog/timeline-color-validation.md.

Not changed, on purpose:

  • CompositionSchema and CompositionOpSchema stay z.string(). A stored document or op log with a bad value still loads, and export refuses it.
  • Text styles (fontcolor, boxcolor) already go through quoteFilterArg. A bad text color fails inside drawtext; it can't add filters. I checked the single-file tools too: add_title_card uses a strict regex, and add_text / chroma_key quote their colors. No gap there.

Why

quoteColor passed any non-# string straight into the graph in two places:

  1. pad=…:color=<canvas background> in every clip's framing chain
  2. -f lavfi -i color=c=<color>:s=WxH:r=F for color clips (and the canvas background behind text clips)

The hypothesis holds. Checked with the bundled ffmpeg-static 6.0 (FFmpeg 7.1.1 has the same color table), using the exact arg arrays the compiler emitted before this change:

  • Reads files outside the workspace. A canvas background of black[p];movie=<file outside the workspace>[m];[p][m]overlay rendered that file into the export. The test image was solid #12ab34: the exported pixel read 0fa92f, against 000000 for a plain black background. The color-clip input works the same way. The trailing :s=…:r=… gets in the way, but an unterminated quote in a final metadata=…:value=' absorbs it, and the export showed the outside file again.
  • Creates or truncates files outside the workspace. black,metadata=mode=print:file=<path> created that file.

So any caller that can set a color could break non-negotiable #3: an MCP client (add_color), the browser UI (verbs route), the CLI flags, or any stored document (hand edit, older version, or the library API colorClip / setCanvas).

How to test

pnpm test -- tests/timeline-color.test.ts
CI=true pnpm exec vitest run tests/integration/timeline-color.test.ts
  • tests/timeline-color.test.ts (unit, no FFmpeg):
    • accepted and refused forms, including filter-syntax payloads
    • add_color refused through both verb schemas
    • compiler arg arrays for valid colors: color=c=0x12ab34:s=1920x1080:r=30 and pad=…:color=Navy@0.5
    • CompileError for stored bad card colors and backgrounds, and the checkExportable blocker
    • CLI flags refused without touching the document
    • a 100k-digit malformed alpha rejected in linear time
  • tests/integration/timeline-color.test.ts (real FFmpeg, CI only):
    • a control showing the hostile value really creates a file when placed in pad= the way the old compiler placed it
    • MCP timeline_edit refusing it
    • timeline_export refusing a stored hostile background with no output and no file written
    • after resetting the background, an export whose #12ab34 card renders as that color

Checks

  • pnpm lint: pass, 0 errors. The 7 warnings are already on main, in tests/speed.test.ts and tests/transition.test.ts.
  • pnpm type-check: pass.
  • pnpm test: 857 passed, 28 skipped.
  • pnpm build: pass.
  • Retargeted to feat/shorts to ship with the shorts release. This branch merged into feat/shorts (at a2b0895) with no conflicts, and the merged tree passes: lint 0 errors, type-check, test (902 passed, 29 skipped), build. The shorts code adds no new place a color reaches FFmpeg.
  • CI=true vitest run tests/integration, locally on macOS with real FFmpeg: 28 passed, 4 skipped. This ran before the Codex fix; the new integration test was rerun after it and passes.
  • Regression proof:
    • On the old compile.ts, the 3 compiler tests fail, and the integration test fails because the export runs.
    • On the old alpha regex, the linear-time test takes 4.9s and fails.
  • Codex review (codex review, gpt-6.1-sol, on the full change): gate PASS with 1 finding.
    • [P2] The decimal alpha regex \d+\.?\d* backtracked quadratically on a long malformed @alpha, so a large MCP/UI input could stall the event loop. Fixed with the non-overlapping \d+(?:\.\d*)? and the linear-time regression test above. Codex was not rerun after the fix.

…mpeg

A color clip's color and the canvas background went into the filter graph
unquoted (`color=c=…`, `pad=…:color=…`), so a value like
`black[p];movie=/path[m];[p][m]overlay` added filters: it read a file
outside the workspace into the export, and `metadata=…:file=` created one.

Validate colors where they enter (the add_color verb for MCP and the UI,
and `clip timeline new --background` / `add-color --color`), and have the
compiler refuse a stored value that is not a color with a CompileError.
Accepted: FFmpeg color names in any case, #rrggbb[aa], 0xrrggbb[aa], with
an optional @Alpha.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@yultyyev
yultyyev changed the base branch from main to feat/shorts November 15, 2026 23:52
@yultyyev
yultyyev merged commit 7b3a321 into feat/shorts Nov 15, 2026
1 check passed
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 0.5.2 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant