From 11926b1348da48ea863ba32abdd74d99c39d8c65 Mon Sep 17 00:00:00 2001 From: Slava Yultyyev Date: Sun, 15 Nov 2026 14:08:47 -0800 Subject: [PATCH] fix(timeline): refuse colors that are not colors before they reach FFmpeg MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/backlog/timeline-color-validation.md | 3 - src/cli-timeline.ts | 10 +- src/timeline/color.ts | 58 ++++++ src/timeline/compile.ts | 16 +- src/timeline/verbs.ts | 5 +- tests/integration/timeline-color.test.ts | 117 ++++++++++++ tests/timeline-color.test.ts | 211 ++++++++++++++++++++++ 7 files changed, 409 insertions(+), 11 deletions(-) delete mode 100644 docs/backlog/timeline-color-validation.md create mode 100644 src/timeline/color.ts create mode 100644 tests/integration/timeline-color.test.ts create mode 100644 tests/timeline-color.test.ts diff --git a/docs/backlog/timeline-color-validation.md b/docs/backlog/timeline-color-validation.md deleted file mode 100644 index 643dac7..0000000 --- a/docs/backlog/timeline-color-validation.md +++ /dev/null @@ -1,3 +0,0 @@ -# Timeline color validation - -Timeline `color` / `background` fields are bare `z.string()` (src/timeline/composition.ts, ops.ts) and `quoteColor` in src/timeline/compile.ts passes non-`#` values into the filtergraph unescaped, so a value like `red,drawtext=...` adds a filter; validate them as hex or a named-color allowlist in the schema. diff --git a/src/cli-timeline.ts b/src/cli-timeline.ts index e623c1e..1141d94 100644 --- a/src/cli-timeline.ts +++ b/src/cli-timeline.ts @@ -1,5 +1,6 @@ import { appendOp } from './session/store.js'; import { CaptionError, DEFAULT_CAPTION_WORDS, planCaptions } from './timeline/captions.js'; +import { invalidColorMessage, isColor } from './timeline/color.js'; import { buildFrameAtPlan, checkExportable, @@ -134,6 +135,11 @@ function optionalNum(name: string, value: string | undefined): number | undefine return n; } +function colorFlag(name: string, value: string | undefined): string | undefined { + if (value === undefined || isColor(value)) return value; + throw new Error(`--${name} ${invalidColorMessage(value)}`); +} + function fitFlag(value: string | undefined): Fit | undefined { if (value === undefined) return undefined; const parsed = FitSchema.safeParse(value); @@ -177,7 +183,7 @@ export async function runTimeline(args: string[]): Promise { width: flags.width ? num(flags.width, 1920) : undefined, height: flags.height ? num(flags.height, 1080) : undefined, fps: flags.fps ? num(flags.fps, 30) : undefined, - background: flags.background, + background: colorFlag('background', flags.background), fit: fitFlag(flags.fit), }), ); @@ -244,7 +250,7 @@ export async function runTimeline(args: string[]): Promise { const start = flags.start !== undefined ? num(flags.start, 0) : trackEnd(comp, trackId); const clip = colorClip({ id: makeClipId(), - color: flags.color, + color: colorFlag('color', flags.color), durationSec: num(duration, 2), startSec: start, }); diff --git a/src/timeline/color.ts b/src/timeline/color.ts new file mode 100644 index 0000000..9e9c214 --- /dev/null +++ b/src/timeline/color.ts @@ -0,0 +1,58 @@ +import { z } from 'zod'; + +/** + * Timeline colors reach FFmpeg as bare option values (`color=c=…`, + * `pad=…:color=…`), where a comma, semicolon or bracket starts a new filter. So a + * color must be one FFmpeg reads as a color and nothing more: anything else + * could add filters such as `movie=`, which reads any file on disk. + */ + +/** FFmpeg's color names (`ffmpeg -colors`), which it matches in any case. */ +const COLOR_NAMES = new Set( + `aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue + blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk + crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkkhaki darkmagenta + darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue + darkslategray darkturquoise darkviolet deeppink deepskyblue dimgray dodgerblue firebrick + floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green greenyellow + honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon + lightblue lightcoral lightcyan lightgoldenrodyellow lightgreen lightgrey lightpink + lightsalmon lightseagreen lightskyblue lightslategray lightsteelblue lightyellow lime + limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple + mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred + midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab orange + orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff + peru pink plum powderblue purple red rosybrown royalblue saddlebrown salmon sandybrown + seagreen seashell sienna silver skyblue slateblue slategray snow springgreen steelblue tan + teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen`.split(/\s+/), +); + +const HEX = /^(?:#|0x)?[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$/; +const HEX_ALPHA = /^0x[0-9a-fA-F]{1,2}$/; +const DECIMAL_ALPHA = /^(?:\d+(?:\.\d*)?|\.\d+)$/; + +/** Whether `value` is a color FFmpeg reads: a color name or hex (`#rrggbb`, + * `0xrrggbbaa`), with an optional `@alpha` from 0 to 1 (or 0x00 to 0xff). */ +export function isColor(value: string): boolean { + const [base = '', alpha, ...rest] = value.split('@'); + if (rest.length > 0) return false; + if (!HEX.test(base) && !COLOR_NAMES.has(base.toLowerCase())) return false; + return ( + alpha === undefined || + HEX_ALPHA.test(alpha) || + (DECIMAL_ALPHA.test(alpha) && Number(alpha) <= 1) + ); +} + +/** Why `value` was refused, with the forms that work. */ +export function invalidColorMessage(value: string): string { + return ( + `${JSON.stringify(value)} is not a color. Use a color name like black or white, ` + + 'or hex like #ffcc00, optionally with @0.5 for opacity.' + ); +} + +/** A color from an MCP client, the UI or the CLI (see `isColor`). */ +export const ColorSchema = z + .string() + .refine(isColor, { error: (issue) => invalidColorMessage(String(issue.input)) }); diff --git a/src/timeline/compile.ts b/src/timeline/compile.ts index 45dc785..869aa1c 100644 --- a/src/timeline/compile.ts +++ b/src/timeline/compile.ts @@ -3,6 +3,7 @@ import { buildPreviewFrameArgs } from '../ffmpeg/args/preview.js'; import { buildTransitionArgs } from '../ffmpeg/args/transition.js'; import { quoteFilterArg } from '../ffmpeg/escape.js'; import { fontFileFor, MissingFontError } from '../ffmpeg/font.js'; +import { invalidColorMessage, isColor } from './color.js'; import { type Clip, type Composition, @@ -449,7 +450,7 @@ function buildSegmentStep( '-f', 'lavfi', '-i', - `color=c=${quoteColor(clip.color)}:s=${width}x${height}:r=${fps}`, + `color=c=${quoteColor(clip.color, `Color clip "${clip.id}" color`)}:s=${width}x${height}:r=${fps}`, ); inputArgs.push( '-f', @@ -465,7 +466,7 @@ function buildSegmentStep( '-f', 'lavfi', '-i', - `color=c=${quoteColor(background)}:s=${width}x${height}:r=${fps}`, + `color=c=${quoteColor(background, CANVAS_BACKGROUND)}:s=${width}x${height}:r=${fps}`, ); inputArgs.push( '-f', @@ -555,7 +556,7 @@ function framingFilters( height: number, background: string, ): string[] { - const pad = `color=${quoteColor(background)}`; + const pad = `color=${quoteColor(background, CANVAS_BACKGROUND)}`; if (isDefaultFraming(framing)) { return [ `scale=${width}:${height}:force_original_aspect_ratio=decrease`, @@ -635,8 +636,13 @@ const ANCHOR_EXPR: Record = { 'bottom-right': { x: `w-text_w-${EDGE}`, y: `h-text_h-${EDGE}` }, }; -/** color filter `c=` rejects '#rrggbb'; normalize to 0x form, pass names through. */ -function quoteColor(color: string): string { +const CANVAS_BACKGROUND = 'Canvas background'; + +/** color filter `c=` rejects '#rrggbb'; normalize to 0x form, pass names through. + * The value lands unquoted in the graph, so anything but a color is refused: a + * stored document is only as safe as whatever wrote it. */ +function quoteColor(color: string, what: string): string { + if (!isColor(color)) throw new CompileError(`${what} ${invalidColorMessage(color)}`); return color.startsWith('#') ? `0x${color.slice(1)}` : color; } diff --git a/src/timeline/verbs.ts b/src/timeline/verbs.ts index b72e9ec..8558382 100644 --- a/src/timeline/verbs.ts +++ b/src/timeline/verbs.ts @@ -1,5 +1,6 @@ import { z } from 'zod'; import { DEFAULT_CAPTION_TRACK, DEFAULT_CAPTION_WORDS, planCaptions } from './captions.js'; +import { ColorSchema } from './color.js'; import type { MediaInfo } from './compile.js'; import { AnchorSchema, @@ -109,7 +110,9 @@ const EDITABLE_VERB_SCHEMAS = [ 'Optional clip id — supply one to reference this clip in a later verb of the SAME batch.', ), durationSec: z.number().positive(), - color: z.string().optional().describe('Card color (default black).'), + color: ColorSchema.optional().describe( + 'Card color: a name like black or white, or hex like #ffcc00 (default black).', + ), track: z.string().optional(), startSec: z.number().nonnegative().optional(), }), diff --git a/tests/integration/timeline-color.test.ts b/tests/integration/timeline-color.test.ts new file mode 100644 index 0000000..946f302 --- /dev/null +++ b/tests/integration/timeline-color.test.ts @@ -0,0 +1,117 @@ +import { access, mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'; +import { execa } from 'execa'; +import ffmpegStatic from 'ffmpeg-static'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { runFfmpeg } from '../../src/ffmpeg/run.js'; +import { buildMcpServer } from '../../src/mcp/server.js'; +import { mutateComposition } from '../../src/timeline/document-store.js'; + +const ffmpegPath = (): string => process.env.MAKEMYCLIP_FFMPEG_PATH ?? ffmpegStatic ?? 'ffmpeg'; + +// Unit tests assert the compiler refuses a color that is filter syntax; this +// checks that such a value is live in real FFmpeg (it writes a file outside the +// workspace) and that the MCP edit and export paths never hand it over. +const IS_CI = process.env.CI === 'true'; + +let workspace: string; +let outside: string; +let saved: string | undefined; + +beforeEach(async () => { + workspace = await mkdtemp(join(tmpdir(), 'mmc-color-')); + outside = await mkdtemp(join(tmpdir(), 'mmc-outside-')); + saved = process.env.MAKEMYCLIP_WORKSPACE; + process.env.MAKEMYCLIP_WORKSPACE = workspace; +}); + +afterEach(async () => { + if (saved === undefined) delete process.env.MAKEMYCLIP_WORKSPACE; + else process.env.MAKEMYCLIP_WORKSPACE = saved; + await rm(workspace, { recursive: true, force: true }); + await rm(outside, { recursive: true, force: true }); +}); + +const exists = (path: string): Promise => + access(path).then( + () => true, + () => false, + ); + +/** The average RGB of a video's first frame. */ +async function firstFrameRgb(video: string): Promise { + const { stdout } = await execa( + ffmpegPath(), + [ + ...['-hide_banner', '-loglevel', 'error', '-i', video, '-frames:v', '1'], + ...['-vf', 'scale=1:1:flags=area', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-'], + ], + { encoding: 'buffer' }, + ); + return [...stdout]; +} + +function payload(result: unknown): Record { + const content = (result as { content: { type: string; text?: string }[] }).content; + return JSON.parse(content.find((c) => c.type === 'text')?.text ?? '{}'); +} + +describe.skipIf(!IS_CI)('timeline colors against real FFmpeg', () => { + it('refuses a color that adds a filter, which FFmpeg would otherwise run', async () => { + const written = join(outside, 'written.txt'); + const hostile = `black,metadata=mode=print:file=${written}`; + + // Control: placed in pad= as the old compiler placed a background, it creates a file. + await runFfmpeg([ + ...['-hide_banner', '-loglevel', 'error', '-f', 'lavfi', '-i', 'color=c=red:s=16x16'], + ...['-vf', `pad=16:16:0:0:color=${hostile},setsar=1`, '-frames:v', '1', '-f', 'null', '-'], + ]); + expect(await exists(written)).toBe(true); + await rm(written); + + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + const server = buildMcpServer(); + await server.connect(serverTransport); + const client = new Client({ name: 'test', version: '1.0.0' }); + await client.connect(clientTransport); + try { + const refused = await client.callTool({ + name: 'timeline_edit', + arguments: { verbs: [{ verb: 'add_color', durationSec: 1, color: hostile }] }, + }); + expect((refused as { isError?: boolean }).isError).toBe(true); + + await client.callTool({ + name: 'timeline_edit', + arguments: { verbs: [{ verb: 'add_color', durationSec: 1, color: '#12ab34' }] }, + }); + // A stored document can still carry one (a hand edit, an older version). + await mutateComposition([{ op: 'setCanvas', width: 320, height: 240, background: hostile }]); + + const out = join(workspace, 'out.mp4'); + const blocked = payload( + await client.callTool({ name: 'timeline_export', arguments: { output: out } }), + ); + expect(String(blocked.error)).toMatch(/^Canvas background ".*" is not a color\./); + expect(await exists(out)).toBe(false); + expect(await exists(written)).toBe(false); + + // The valid colors still render: '#12ab34' reaches FFmpeg as 0x12ab34. + await mutateComposition([{ op: 'setCanvas', background: 'black' }]); + const exported = payload( + await client.callTool({ name: 'timeline_export', arguments: { output: out } }), + ); + expect(exported.error).toBeUndefined(); + const [r = 0, g = 0, b = 0] = await firstFrameRgb(out); + expect(Math.abs(r - 0x12)).toBeLessThan(12); + expect(Math.abs(g - 0xab)).toBeLessThan(12); + expect(Math.abs(b - 0x34)).toBeLessThan(12); + } finally { + await client.close(); + await server.close(); + } + }, 60_000); +}); diff --git a/tests/timeline-color.test.ts b/tests/timeline-color.test.ts new file mode 100644 index 0000000..785b410 --- /dev/null +++ b/tests/timeline-color.test.ts @@ -0,0 +1,211 @@ +import { mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { runTimeline } from '../src/cli-timeline.js'; +import { ColorSchema, isColor } from '../src/timeline/color.js'; +import { + type CompileContext, + CompileError, + checkExportable, + compileTimeline, +} from '../src/timeline/compile.js'; +import { type Composition, emptyComposition } from '../src/timeline/composition.js'; +import { readComposition } from '../src/timeline/document-store.js'; +import { applyOps, colorClip, mediaClip, videoTrack } from '../src/timeline/ops.js'; +import type { MediaId } from '../src/timeline/schema.js'; +import { CompositionVerbSchema, EditableVerbSchema } from '../src/timeline/verbs.js'; + +const M1 = 'm_aaaaaaaaaaaa' as MediaId; + +/** Values that would add filters to the graph if they reached FFmpeg unquoted. */ +const INJECTIONS = [ + 'red,drawtext=text=x', + 'black[p];movie=/etc/passwd[m];[p][m]overlay', + "black,metadata=mode=print:file=/tmp/x.txt:key='", + 'red:s=2x2', + 'red@0.5,null', +]; + +function ctx(): CompileContext { + return { + media: new Map([[M1, { path: '/ws/a.mp4', hasAudio: true }]]), + dir: '/ws', + output: '/ws/out.mp4', + }; +} + +/** A stored document holding one clip, as a hand edit or an older version could write it. */ +function docWith( + clip: ReturnType | ReturnType, + background = 'black', +): Composition { + return applyOps(emptyComposition({ background }), [ + { op: 'addTrack', track: videoTrack({ id: 'v0' }) }, + { op: 'addClip', trackId: 'v0', clip }, + ]); +} + +const card = (color: string) => colorClip({ id: 'c1', color, durationSec: 2, startSec: 0 }); +const media = () => + mediaClip({ id: 'm1', mediaId: M1, sourceInSec: 0, sourceOutSec: 2, startSec: 0 }); + +function stepArgs(comp: Composition): string[] { + return compileTimeline(comp, ctx()).steps[0]?.args ?? []; +} + +describe('isColor', () => { + it('accepts FFmpeg color names in any case, hex, and an @alpha', () => { + for (const value of [ + 'black', + 'Red', + 'AliceBlue', + '#ffcc00', + '#FFCC0080', + '0xffcc00', + 'ffcc00', + 'black@0.6', + 'white@1', + 'red@.5', + '#ffcc00@0x80', + ]) { + expect(isColor(value), value).toBe(true); + } + }); + + it('refuses filter syntax, unknown names and malformed hex or alpha', () => { + for (const value of [ + ...INJECTIONS, + '', + ' red', + 'grey', // FFmpeg knows gray and lightgrey, not grey + 'notacolor', + '#fff', + '0XFFCC00', + 'red@1.5', + 'red@0x100', + 'red@', + 'red@@0.5', + 'rgb(255,0,0)', + ]) { + expect(isColor(value), value).toBe(false); + } + }); + + it('refuses a long malformed alpha in linear time', () => { + const start = performance.now(); + expect(isColor(`red@${'1'.repeat(100_000)}x`)).toBe(false); + expect(performance.now() - start).toBeLessThan(500); + }); + + it('gives the schema a message naming the value and the forms that work', () => { + const result = ColorSchema.safeParse('red,drawtext=text=x'); + expect(result.success).toBe(false); + expect(result.error?.issues[0]?.message).toBe( + '"red,drawtext=text=x" is not a color. Use a color name like black or white, or hex like #ffcc00, optionally with @0.5 for opacity.', + ); + }); +}); + +describe('add_color verb', () => { + it('refuses a color that is not a color, for MCP clients and the UI alike', () => { + for (const schema of [EditableVerbSchema, CompositionVerbSchema]) { + for (const color of INJECTIONS) { + const result = schema.safeParse({ verb: 'add_color', durationSec: 1, color }); + expect(result.success, color).toBe(false); + expect(result.error?.issues[0]?.path).toEqual(['color']); + } + } + }); + + it('keeps hex, names and the default', () => { + expect( + EditableVerbSchema.parse({ verb: 'add_color', durationSec: 1, color: '#12ab34' }), + ).toEqual({ verb: 'add_color', durationSec: 1, color: '#12ab34' }); + expect( + EditableVerbSchema.parse({ verb: 'add_color', durationSec: 1, color: 'navy@0.5' }), + ).toEqual({ verb: 'add_color', durationSec: 1, color: 'navy@0.5' }); + expect(EditableVerbSchema.parse({ verb: 'add_color', durationSec: 1 })).toEqual({ + verb: 'add_color', + durationSec: 1, + }); + }); +}); + +describe('compileTimeline colors', () => { + it('passes a valid card color and canvas background into the args, # as 0x', () => { + const args = stepArgs(docWith(card('#12ab34'), 'Navy@0.5')); + expect(args.slice(0, 5)).toEqual([ + '-y', + '-f', + 'lavfi', + '-i', + 'color=c=0x12ab34:s=1920x1080:r=30', + ]); + const graph = args[args.indexOf('-filter_complex') + 1] ?? ''; + expect(graph).toContain('pad=1920:1080:(ow-iw)/2:(oh-ih)/2:color=Navy@0.5,setsar=1'); + }); + + it('refuses a stored card color that is not a color', () => { + for (const color of INJECTIONS) { + expect(() => stepArgs(docWith(card(color))), color).toThrow(CompileError); + } + expect(() => stepArgs(docWith(card('red,drawtext=text=x')))).toThrow( + 'Color clip "c1" color "red,drawtext=text=x" is not a color.', + ); + }); + + it('refuses a stored canvas background that is not a color', () => { + for (const background of INJECTIONS) { + expect(() => stepArgs(docWith(media(), background)), background).toThrow(CompileError); + } + expect(() => stepArgs(docWith(media(), 'red,drawtext=text=x'))).toThrow( + 'Canvas background "red,drawtext=text=x" is not a color.', + ); + }); + + it('reports the bad color as an export blocker', () => { + const report = checkExportable(docWith(card('red,null')), ctx().media, '/ws'); + expect(report.exportable).toBe(false); + expect(report.blockers[0]).toMatch(/^Color clip "c1" color "red,null" is not a color\./); + }); +}); + +describe('clip timeline color flags', () => { + let workspace: string; + let saved: string | undefined; + + beforeEach(async () => { + workspace = await mkdtemp(join(tmpdir(), 'mmc-color-')); + saved = process.env.MAKEMYCLIP_WORKSPACE; + process.env.MAKEMYCLIP_WORKSPACE = workspace; + vi.spyOn(process.stdout, 'write').mockImplementation(() => true); + }); + + afterEach(async () => { + vi.restoreAllMocks(); + if (saved === undefined) delete process.env.MAKEMYCLIP_WORKSPACE; + else process.env.MAKEMYCLIP_WORKSPACE = saved; + await rm(workspace, { recursive: true, force: true }); + }); + + it('new --background takes a color and refuses anything else before replacing the doc', async () => { + await runTimeline(['new', '--background', '#102030']); + expect((await readComposition()).background).toBe('#102030'); + + await expect( + runTimeline(['new', '--background', 'black[p];movie=/etc/passwd[m];[p][m]overlay']), + ).rejects.toThrow('--background "black[p];movie=/etc/passwd[m];[p][m]overlay" is not a color.'); + expect((await readComposition()).background).toBe('#102030'); + }); + + it('add-color --color takes a color and refuses anything else without adding a clip', async () => { + await runTimeline(['new']); + await runTimeline(['add-color', '1', '--color', 'papayawhip']); + await expect(runTimeline(['add-color', '1', '--color', 'red,drawtext=text=x'])).rejects.toThrow( + '--color "red,drawtext=text=x" is not a color.', + ); + const clips = (await readComposition()).tracks.flatMap((t) => t.clips); + expect(clips.map((c) => (c.kind === 'color' ? c.color : c.kind))).toEqual(['papayawhip']); + }); +});