Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions docs/backlog/timeline-color-validation.md

This file was deleted.

10 changes: 8 additions & 2 deletions src/cli-timeline.ts
Original file line number Diff line number Diff line change
@@ -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,
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -177,7 +183,7 @@ export async function runTimeline(args: string[]): Promise<void> {
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),
}),
);
Expand Down Expand Up @@ -244,7 +250,7 @@ export async function runTimeline(args: string[]): Promise<void> {
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,
});
Expand Down
58 changes: 58 additions & 0 deletions src/timeline/color.ts
Original file line number Diff line number Diff line change
@@ -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)) });
16 changes: 11 additions & 5 deletions src/timeline/compile.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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',
Expand All @@ -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',
Expand Down Expand Up @@ -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`,
Expand Down Expand Up @@ -635,8 +636,13 @@ const ANCHOR_EXPR: Record<string, { x: string; y: string }> = {
'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;
}

Expand Down
5 changes: 4 additions & 1 deletion src/timeline/verbs.ts
Original file line number Diff line number Diff line change
@@ -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,
Expand Down Expand Up @@ -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(),
}),
Expand Down
117 changes: 117 additions & 0 deletions tests/integration/timeline-color.test.ts
Original file line number Diff line number Diff line change
@@ -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<boolean> =>
access(path).then(
() => true,
() => false,
);

/** The average RGB of a video's first frame. */
async function firstFrameRgb(video: string): Promise<number[]> {
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<string, unknown> {
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);
});
Loading
Loading