Skip to content

joeseesun/qiaomu-cut-skill

qiaomu-cut

Verified

把一句话需求转成可复现、可验收视频工程的乔木智能剪辑导演。Use when the user asks to create, plan, edit, remix, explain, narrate, subtitle, animate, composite, or render a video—including one-line requests such as “制作一个科普视频:介绍 LLM 中的 RL”. Builds English-learning movie mixes, person profiles, explainers, code-drawn motion graphics (UI morph loops, showreels, kinetic-type promos, line-art/pixel/Three.js animation, lyric MVs), product launch videos, cinematic shorts, social clips, course/PPT videos, AI image/video/TTS/music-assisted stories, stock-footage stories, or multi-source montage. Routes across 33台词, ClipSeek/open media, local files, ListenHub, image generation, HTML/SVG/Canvas motion graphics with beat-grid storyboards and determinism probes, Manim, ffmpeg-full, captions, sound design, frame-0 video covers with YouTube thumbnails, and release checks.

FileKindSize
SKILL.mdskill md54.0 KB
agents/interface.yamlconfig17.2 KB
agents/openai.yamlconfig323 B
assets/explainer-social/base.cssother24.9 KB
assets/explainer-social/component-runtime.jsscript41.1 KB
assets/explainer-social/scene-shell.htmlother829 B
assets/motion-kit/qiaocut-motion.jsscript8.2 KB
assets/qiaomu-profile/qiaomu_avatar.jpegbinary5.6 MB
assets/qiaomu-profile/qiaomu_reward_qr.pngbinary515.9 KB
assets/qiaomu-profile/qiaomu_wechat_public_account_qr.jpgbinary8.3 KB
references/ad-concept-library.mdmarkdown6.5 KB
references/aesthetic-preferences.mdmarkdown3.0 KB
references/brand-card-templates.mdmarkdown1.6 KB
references/chinese-font-themes.mdmarkdown804 B
references/cinematic-techniques.mdmarkdown2.8 KB
references/code-motion-direction.mdmarkdown11.1 KB
references/cover-thumbnail-method.mdmarkdown6.4 KB
references/english-mix-fast-path.mdmarkdown6.0 KB
references/explainer-autopilot.mdmarkdown11.1 KB
references/feedback-evolution.mdmarkdown37.6 KB
references/ffmpeg-full.mdmarkdown1.7 KB
references/incremental-production.mdmarkdown4.4 KB
references/licensing.mdmarkdown1.9 KB
references/listenhub-provider.mdmarkdown12.6 KB
references/motion-prompt-patterns.mdmarkdown9.3 KB
references/movie-montage-fast-path.mdmarkdown4.4 KB
references/qiaocut-ir.mdmarkdown4.2 KB
references/renderer-engines.mdmarkdown3.3 KB
references/schemas/qiaocut.timeline.v1.schema.jsonconfig7.2 KB
references/social-safe-zones.mdmarkdown3.3 KB
references/source-adapters.mdmarkdown5.7 KB
references/source-selection-gate.mdmarkdown2.5 KB
references/styles/cinematic.mdmarkdown475 B
references/styles/explainer.mdmarkdown1.5 KB
references/styles/social-short.mdmarkdown383 B
references/timeline-schema.mdmarkdown12.2 KB
references/trust-boundary.mdmarkdown3.0 KB
references/workflows.mdmarkdown7.5 KB
scripts/adapters/33tc.jsscript2.1 KB
scripts/adapters/33tc_cli.jsscript4.8 KB
scripts/adapters/clipseek.jsexecutablescript5.4 KB
scripts/adapters/listenhub.jsscript35.7 KB
scripts/adapters/listenhub_cli.jsexecutablescript2.1 KB
scripts/adapters/local.jsscript2.4 KB
scripts/audio_beats.jsscript17.5 KB
scripts/bilingual_typography_smoke.jsscript1.4 KB
scripts/bootstrap_listenhub.shexecutablescript5.4 KB
scripts/bootstrap_macos.shexecutablescript2.5 KB
scripts/brand_templates.jsscript2.4 KB
scripts/brand_templates_smoke.jsscript869 B
scripts/complete_sentence.jsscript3.9 KB
scripts/component_motion_smoke.jsscript21.2 KB
scripts/concept_smoke.jsscript5.6 KB
scripts/cover.jsscript9.1 KB
scripts/cover_smoke.jsscript5.1 KB
scripts/english_mix.jsscript24.1 KB
scripts/english_mix_smoke.jsscript5.7 KB
scripts/explainer_beats.jsscript6.7 KB
scripts/explainer_beats_smoke.jsscript4.8 KB
scripts/explainer_cognitive_timing_smoke.jsscript5.8 KB
scripts/explainer_e2e_smoke.jsscript7.4 KB
scripts/explainer_pipeline.jsscript49.3 KB
scripts/explainer_pipeline_smoke.jsscript12.7 KB
scripts/explainer_spec.jsscript51.4 KB
scripts/explainer_timing.jsscript8.6 KB
scripts/fetch_generated.jsexecutablescript17.4 KB
scripts/ffmpeg_retry_shim_smoke.jsscript2.3 KB
scripts/file_narration_smoke.jsexecutablescript6.6 KB
scripts/ingest_asset.jsexecutablescript15.0 KB
scripts/kinetic_caption_smoke.jsscript1.4 KB
scripts/license_report.jsexecutablescript2.3 KB
scripts/listenhub_narration.jsexecutablescript11.0 KB
scripts/listenhub_smoke.jsexecutablescript26.7 KB
scripts/local_preferences.jsscript1.8 KB
scripts/motion_studio.jsscript55.9 KB
scripts/motion_studio_smoke.jsscript11.0 KB
scripts/movie_montage.jsscript24.7 KB
scripts/movie_montage_smoke.jsscript4.0 KB
scripts/qcut.jsexecutablescript40.8 KB
scripts/release_check.jsscript7.0 KB
scripts/render_project.jsscript85.1 KB
scripts/render_scene.jsscript26.4 KB
scripts/renderers/ass.jsexecutablescript2.7 KB
scripts/renderers/bilingual_ass.jsscript12.6 KB
scripts/renderers/html_scene.jsexecutablescript3.9 KB
scripts/renderers/procedural_music.jsscript7.6 KB
scripts/scene_content_cache.jsscript3.2 KB
scripts/scene_renderer_smoke.jsscript2.8 KB
scripts/security_smoke.jsscript10.2 KB
scripts/sentence_boundary_smoke.jsscript1.6 KB
scripts/setup_deps.jsscript8.4 KB
scripts/shims/ffmpegexecutablescript3.0 KB
scripts/source_review.jsexecutablescript5.1 KB
scripts/timeline_features_smoke.jsscript3.7 KB
scripts/trigger_eval.pyexecutablescript2.5 KB
scripts/validate_skill.pyexecutablescript3.1 KB
scripts/verify_marswave_vendor.jsexecutablescript3.5 KB
scripts/verify_video.jsexecutablescript3.4 KB

scripts/render_project.js

View on GitHub
#!/usr/bin/env node
'use strict';

const fs = require('fs');
const crypto = require('crypto');
const os = require('os');
const path = require('path');
const { spawnSync } = require('child_process');
const { generateBilingualAss, readCaptionDocument } = require('./renderers/bilingual_ass');
const { generateProceduralMusic } = require('./renderers/procedural_music');

class UsageError extends Error {}

const SEGMENT_CACHE_VERSION = 'qiaomu-cut-segment-v1';
const TTS_CACHE_VERSION = 'qiaomu-cut-macos-say-v1';
const PICTURE_CACHE_VERSION = 'qiaomu-cut-picture-v2';
const RENDER_PROFILES = Object.freeze({
  preview: Object.freeze({
    maxDimension: 960,
    maxFps: 24,
    intermediatePreset: 'ultrafast',
    intermediateCrf: 28,
    preset: 'ultrafast',
    crf: 25,
    normalization: 'single-pass',
    validation: 'basic',
    contactSheet: false
  }),
  standard: Object.freeze({
    maxDimension: 1280,
    maxFps: 30,
    intermediatePreset: 'veryfast',
    intermediateCrf: 24,
    preset: 'veryfast',
    crf: 21,
    normalization: 'single-pass',
    validation: 'standard',
    contactSheet: true
  }),
  final: Object.freeze({
    maxDimension: null,
    maxFps: null,
    normalization: 'two-pass',
    validation: 'full',
    contactSheet: true
  })
});
const VALIDATION_LEVELS = new Set(['basic', 'standard', 'full']);
const TRANSITION_TYPES = new Set([
  'cut', 'fade', 'dissolve', 'wipeleft', 'wiperight', 'wipeup', 'wipedown',
  'slideleft', 'slideright', 'slideup', 'slidedown', 'circleopen', 'circleclose',
  'pixelize', 'smoothleft', 'smoothright', 'smoothup', 'smoothdown'
]);

function displayPath(file) {
  if (!file || typeof file !== 'string') return file;
  const home = os.homedir();
  return file === home || file.startsWith(`${home}${path.sep}`)
    ? `<HOME>${file.slice(home.length)}`
    : file;
}

function displayText(value) {
  return String(value || '').split(os.homedir()).join('<HOME>');
}

function finite(value, fallback) {
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : fallback;
}

function clamp(value, min, max) {
  return Math.max(min, Math.min(max, value));
}

function stableValue(value) {
  if (Array.isArray(value)) return value.map(stableValue);
  if (!value || typeof value !== 'object') return value;
  return Object.keys(value).sort().reduce((result, key) => {
    result[key] = stableValue(value[key]);
    return result;
  }, {});
}

function stableStringify(value) {
  return JSON.stringify(stableValue(value));
}

function transitionSpec(shot) {
  if (!shot || shot.transition == null) return { type: 'cut', duration: 0 };
  const raw = typeof shot.transition === 'string' ? { type: shot.transition } : shot.transition;
  const type = String(raw.type || 'cut').toLowerCase();
  const duration = type === 'cut' ? 0 : finite(raw.duration, 0.25);
  return { type, duration };
}

function effectiveTimelineDuration(shots) {
  return (shots || []).reduce((total, shot, index) => {
    const overlap = index === 0 ? 0 : transitionSpec(shot).duration;
    return total + finite(shot.duration, 0) - overlap;
  }, 0);
}

function suffixedPath(file, suffix) {
  const extension = path.extname(file);
  const stem = extension ? file.slice(0, -extension.length) : file;
  return `${stem}.${suffix}${extension}`;
}

function scaledDimensions(width, height, maxDimension) {
  if (!maxDimension || Math.max(width, height) <= maxDimension) return { width, height };
  const ratio = maxDimension / Math.max(width, height);
  const even = (value) => Math.max(2, Math.round(value * ratio / 2) * 2);
  return { width: even(width), height: even(height) };
}

function applyRenderProfile(sourceTimeline, options = {}) {
  const name = options.profile || 'final';
  const profile = RENDER_PROFILES[name];
  if (!profile) throw new UsageError(`Unknown render profile: ${name}. Expected preview, standard, or final.`);
  const validation = options.validation || profile.validation;
  if (!VALIDATION_LEVELS.has(validation)) {
    throw new UsageError(`Unknown validation level: ${validation}. Expected basic, standard, or full.`);
  }

  const timeline = JSON.parse(JSON.stringify(sourceTimeline));
  timeline.output = { ...(timeline.output || {}) };
  timeline.reports = { ...(timeline.reports || {}) };
  timeline._renderProfile = name;
  timeline._validationLevel = validation;
  timeline._normalizationMode = profile.normalization;
  timeline._sourceOutputWidth = finite(timeline.output.width, 0);
  timeline._sourceOutputHeight = finite(timeline.output.height, 0);

  if (name !== 'final') {
    const dimensions = scaledDimensions(
      finite(timeline.output.width, 0),
      finite(timeline.output.height, 0),
      profile.maxDimension
    );
    timeline.output.width = dimensions.width;
    timeline.output.height = dimensions.height;
    timeline.output.fps = Math.min(finite(timeline.output.fps, profile.maxFps), profile.maxFps);
    timeline.output.intermediatePreset = profile.intermediatePreset;
    timeline.output.intermediateCrf = profile.intermediateCrf;
    timeline.output.preset = profile.preset;
    timeline.output.crf = profile.crf;
  }

  const originalOutput = timeline.output.file || 'renders/final.mp4';
  timeline.output.file = options.output || (name === 'final' ? originalOutput : suffixedPath(originalOutput, name));
  if (name !== 'final') {
    if (timeline.captionSource) {
      timeline.captions = suffixedPath(timeline.captions || 'captions/final.ass', name);
    }
    timeline.reports.renderReport = suffixedPath(
      timeline.reports.renderReport || 'reports/render-report.json',
      name
    );
    if (profile.contactSheet === false) {
      timeline.reports.contactSheet = false;
    } else if (timeline.reports.contactSheet !== false) {
      timeline.reports.contactSheet = suffixedPath(
        timeline.reports.contactSheet || 'reports/contact-sheet.jpg',
        name
      );
      timeline.reports.contactSheetFrames = Math.min(finite(timeline.reports.contactSheetFrames, 8), 8);
      timeline.reports.contactSheetThumbWidth = Math.min(finite(timeline.reports.contactSheetThumbWidth, 240), 240);
    }
  } else if (options.output) {
    timeline.output.file = options.output;
  }
  return { timeline, name, validation, profile };
}

function readJson(file) {
  return JSON.parse(fs.readFileSync(file, 'utf8'));
}

function sha256File(file) {
  const hash = crypto.createHash('sha256');
  const descriptor = fs.openSync(file, 'r');
  const buffer = Buffer.allocUnsafe(1024 * 1024);
  try {
    let bytes;
    do {
      bytes = fs.readSync(descriptor, buffer, 0, buffer.length, null);
      if (bytes) hash.update(buffer.subarray(0, bytes));
    } while (bytes);
  } finally {
    fs.closeSync(descriptor);
  }
  return hash.digest('hex');
}

function temporarySibling(file) {
  const extension = path.extname(file);
  const stem = path.basename(file, extension);
  return path.join(
    path.dirname(file),
    `.${stem}.qiaocut-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}${extension}`
  );
}

function commitTemporary(temp, destination) {
  try {
    fs.renameSync(temp, destination);
  } catch (error) {
    try { fs.rmSync(temp, { force: true }); } catch (_) {}
    throw error;
  }
}

function atomicWriteFile(file, data, encoding = 'utf8') {
  fs.mkdirSync(path.dirname(file), { recursive: true });
  const temp = temporarySibling(file);
  try {
    fs.writeFileSync(temp, data, { encoding, mode: 0o600 });
    commitTemporary(temp, file);
  } catch (error) {
    try { fs.rmSync(temp, { force: true }); } catch (_) {}
    throw error;
  }
}

function writeJson(file, data) {
  atomicWriteFile(file, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
}

function isWithin(root, target) {
  const relative = path.relative(root, target);
  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
}

function entryExists(target) {
  try {
    fs.lstatSync(target);
    return true;
  } catch {
    return false;
  }
}

function nearestExisting(target) {
  let cursor = target;
  while (!entryExists(cursor)) {
    const parent = path.dirname(cursor);
    if (parent === cursor) return null;
    cursor = parent;
  }
  return cursor;
}

function assertPhysicalPathWithin(root, target, label) {
  const rootReal = fs.realpathSync(root);
  const anchor = nearestExisting(target);
  if (!anchor) throw new Error(`${label} has no resolvable parent path.`);
  let anchorReal;
  try {
    anchorReal = fs.realpathSync(anchor);
  } catch {
    throw new Error(`${label} contains a dangling or unreadable symbolic link.`);
  }
  if (!isWithin(rootReal, anchorReal)) {
    throw new Error(`${label} escapes the project directory through a symbolic link.`);
  }
}

function ensureInternalDirectory(root, target, label) {
  assertPhysicalPathWithin(root, target, label);
  fs.mkdirSync(target, { recursive: true });
  assertPhysicalPathWithin(root, target, label);
}

function projectPath(root, relativePath, label, options = {}) {
  if (typeof relativePath !== 'string' || !relativePath.trim()) {
    throw new Error(`${label} must be a non-empty project-relative path.`);
  }
  if (path.isAbsolute(relativePath)) {
    throw new Error(`${label} must be project-relative, not absolute: ${relativePath}`);
  }
  const absolute = path.resolve(root, relativePath);
  if (!isWithin(root, absolute)) {
    throw new Error(`${label} escapes the project directory: ${relativePath}`);
  }
  assertPhysicalPathWithin(root, absolute, label);
  if (options.exists && !fs.existsSync(absolute)) {
    throw new Error(`${label} not found: ${relativePath}`);
  }
  return absolute;
}

function samePath(left, right) {
  if (left === right) return true;
  try {
    const canonical = (target) => {
      const anchor = nearestExisting(target);
      if (!anchor) return path.resolve(target);
      return path.resolve(fs.realpathSync(anchor), path.relative(anchor, target));
    };
    return canonical(left) === canonical(right);
  } catch {
    return false;
  }
}

function commandPath(command) {
  const result = spawnSync('which', [command], { encoding: 'utf8' });
  return result.status === 0 ? result.stdout.trim() : null;
}

function executable(candidate) {
  if (!candidate) return null;
  if (!candidate.includes(path.sep)) return commandPath(candidate);
  try {
    fs.accessSync(candidate, fs.constants.X_OK);
    return candidate;
  } catch {
    return null;
  }
}

function preferredFfmpeg() {
  return [
    process.env.QIAOMU_FFMPEG,
    '/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg',
    '/usr/local/opt/ffmpeg-full/bin/ffmpeg',
    'ffmpeg'
  ].map(executable).find(Boolean) || null;
}

function preferredFfprobe(ffmpeg) {
  return [
    process.env.QIAOMU_FFPROBE,
    ffmpeg && path.join(path.dirname(ffmpeg), 'ffprobe'),
    '/opt/homebrew/opt/ffmpeg-full/bin/ffprobe',
    '/usr/local/opt/ffmpeg-full/bin/ffprobe',
    'ffprobe'
  ].map(executable).find(Boolean) || null;
}

function run(command, args, options = {}) {
  const result = spawnSync(command, args, {
    cwd: options.cwd,
    env: options.env ? { ...process.env, ...options.env } : process.env,
    encoding: 'utf8',
    stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'ignore', 'inherit'],
    maxBuffer: options.maxBuffer || 16 * 1024 * 1024
  });
  if (result.error) throw result.error;
  if (result.status !== 0) {
    const detail = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
    const suffix = detail ? `\n${detail.slice(-6000)}` : '';
    throw new Error(`${path.basename(command)} failed with exit code ${result.status}.${suffix}`);
  }
  return result;
}

function inspectDependencies() {
  const ffmpeg = preferredFfmpeg();
  if (!ffmpeg) {
    throw new Error('ffmpeg not found. Install ffmpeg-full or set QIAOMU_FFMPEG.');
  }
  const ffprobe = preferredFfprobe(ffmpeg);
  if (!ffprobe) {
    throw new Error('ffprobe not found. Install ffmpeg-full or set QIAOMU_FFPROBE.');
  }
  const version = run(ffmpeg, ['-hide_banner', '-version'], { capture: true });
  const filters = run(ffmpeg, ['-hide_banner', '-filters'], { capture: true });
  const encoders = run(ffmpeg, ['-hide_banner', '-encoders'], { capture: true });
  const filterText = `${filters.stdout}\n${filters.stderr}`;
  const encoderText = `${encoders.stdout}\n${encoders.stderr}`;
  const requiredFilters = ['ass', 'zoompan', 'gblur', 'sidechaincompress', 'loudnorm'];
  const missing = requiredFilters.filter((name) => !new RegExp(`\\b${name}\\b`).test(filterText));
  if (!/\blibx264\b/.test(encoderText)) missing.push('encoder:libx264');
  if (missing.length) {
    throw new Error(`The selected ffmpeg is missing required capabilities: ${missing.join(', ')}. Run: qcut setup --only ffmpeg`);
  }
  return {
    ffmpeg,
    ffprobe,
    version: `${version.stdout}\n${version.stderr}`.split(/\r?\n/).find(Boolean) || 'ffmpeg'
  };
}

function filterPath(file) {
  return path.resolve(file)
    .replace(/\\/g, '/')
    .replace(/:/g, '\\:')
    .replace(/'/g, "\\'");
}

function durationOf(file, ffprobe) {
  const result = run(ffprobe, [
    '-v', 'error',
    '-show_entries', 'format=duration',
    '-of', 'default=nw=1:nk=1',
    file
  ], { capture: true });
  return Number(result.stdout.trim());
}

function hasAudio(file, ffprobe) {
  const result = spawnSync(ffprobe, [
    '-v', 'error',
    '-select_streams', 'a:0',
    '-show_entries', 'stream=index',
    '-of', 'csv=p=0',
    file
  ], { encoding: 'utf8' });
  return result.status === 0 && Boolean(result.stdout.trim());
}

function validateTimeline(timeline, projectRoot, options = {}) {
  if (!timeline || typeof timeline !== 'object' || Array.isArray(timeline)) {
    throw new Error('timeline.json must contain an object.');
  }
  if (timeline.schema !== 'qiaocut.timeline.v1') {
    throw new Error(`Unsupported timeline schema: ${timeline.schema || '(missing)'}. Expected qiaocut.timeline.v1.`);
  }
  const output = timeline.output || {};
  const width = finite(output.width, NaN);
  const height = finite(output.height, NaN);
  const fps = finite(output.fps, NaN);
  const duration = finite(output.duration, NaN);
  if (![width, height, fps, duration].every((value) => Number.isFinite(value) && value > 0)) {
    throw new Error('output.width, output.height, output.fps, and output.duration must be positive numbers.');
  }
  if (!Number.isInteger(width) || !Number.isInteger(height) || width % 2 || height % 2) {
    throw new Error('output.width and output.height must be even integers for yuv420p video.');
  }
  if (!Array.isArray(timeline.shots) || timeline.shots.length === 0) {
    throw new Error('timeline.shots must contain at least one shot.');
  }
  if (!options.allowLarge) {
    if (width > 8192 || height > 8192 || width * height > 35400000) {
      throw new Error('Output resolution exceeds the default safety limit. Re-run with --allow-large after reviewing resource cost.');
    }
    if (fps > 120 || duration > 14400 || timeline.shots.length > 1000) {
      throw new Error('Timeline exceeds default FPS, duration, or shot-count safety limits. Re-run with --allow-large after reviewing resource cost.');
    }
  }
  const ids = new Set();
  const shotFiles = [];
  for (const [index, shot] of timeline.shots.entries()) {
    const label = `shots[${index}]`;
    if (!shot || typeof shot !== 'object') throw new Error(`${label} must be an object.`);
    if (!shot.id || typeof shot.id !== 'string') throw new Error(`${label}.id is required.`);
    if (ids.has(shot.id)) throw new Error(`Duplicate shot id: ${shot.id}`);
    ids.add(shot.id);
    if (!['image', 'video'].includes(shot.kind)) throw new Error(`${label}.kind must be image or video.`);
    const shotDuration = finite(shot.duration, NaN);
    if (!Number.isFinite(shotDuration) || shotDuration <= 0) throw new Error(`${label}.duration must be positive.`);
    if (finite(shot.in, 0) < 0) throw new Error(`${label}.in cannot be negative.`);
    const transition = transitionSpec(shot);
    if (!TRANSITION_TYPES.has(transition.type)) throw new Error(`${label}.transition type is unsupported: ${transition.type}.`);
    if (index === 0 && transition.duration > 0) throw new Error('The first shot cannot declare an incoming transition.');
    if (!Number.isFinite(transition.duration) || transition.duration < 0 || transition.duration > 3) {
      throw new Error(`${label}.transition duration must be between 0 and 3 seconds.`);
    }
    if (index > 0 && transition.duration >= Math.min(shotDuration, finite(timeline.shots[index - 1].duration, 0))) {
      throw new Error(`${label}.transition duration must be shorter than both adjacent shots.`);
    }
    shotFiles.push(projectPath(projectRoot, shot.path, `${label}.path`, { exists: true }));
  }
  const declared = effectiveTimelineDuration(timeline.shots);
  const tolerance = Math.max(0.01, 1 / fps);
  if (Math.abs(declared - duration) > tolerance) {
    throw new Error(`Effective shot duration ${declared.toFixed(3)} after transition overlaps does not match output.duration ${duration.toFixed(3)}.`);
  }
  const finalOutput = projectPath(projectRoot, output.file || 'renders/final.mp4', 'output.file');
  if (shotFiles.some((source) => samePath(source, finalOutput))) {
    throw new Error('output.file must not overwrite or alias a source shot asset.');
  }
  if (timeline.captionSource) projectPath(projectRoot, timeline.captionSource, 'captionSource', { exists: true });
  if (timeline.captions) projectPath(projectRoot, timeline.captions, 'captions');
  if (typeof timeline.narration === 'string') projectPath(projectRoot, timeline.narration, 'narration', { exists: true });
  const narration = narrationSpec(timeline, projectRoot);
  if (narration && !['file', 'macos-say', 'none'].includes(narration.engine)) {
    throw new Error(`Unsupported narration engine: ${narration.engine || '(missing)'}`);
  }
  if (narration && narration.engine === 'file') {
    if (!narration.path || typeof narration.path !== 'string') {
      throw new Error('narration.engine file requires a project-relative path.');
    }
    projectPath(projectRoot, narration.path, 'narration.path', { exists: true });
    for (const [field, minimum, exclusive, maximum] of [
      ['start', 0, false, duration],
      ['trim', 0, false, null],
      ['duration', 0, true, null],
      ['gain', 0, false, 4]
    ]) {
      if (narration[field] == null) continue;
      const value = Number(narration[field]);
      const below = !Number.isFinite(value) || (exclusive ? value <= minimum : value < minimum);
      const above = maximum != null && value > maximum;
      if (below || above || (field === 'start' && value >= duration)) {
        throw new Error(`narration.${field} is outside the supported timeline range.`);
      }
    }
  }
  if (narration && narration.engine === 'macos-say') {
    if (!Array.isArray(narration.cues) || narration.cues.length === 0) {
      throw new Error('narration.engine macos-say requires at least one cue.');
    }
  }
  if (typeof timeline.music === 'string') projectPath(projectRoot, timeline.music, 'music');
  if (timeline.music && typeof timeline.music === 'object' && timeline.music.path) {
    projectPath(projectRoot, timeline.music.path, 'music.path');
  }
  if (timeline.soundEffects != null && !Array.isArray(timeline.soundEffects)) {
    throw new Error('soundEffects must be an array.');
  }
  if (timeline.audio != null && (!timeline.audio || typeof timeline.audio !== 'object' || Array.isArray(timeline.audio))) {
    throw new Error('audio must be an object.');
  }
  if (timeline.audio && timeline.audio.masteringMode != null && !['default', 'montage'].includes(timeline.audio.masteringMode)) {
    throw new Error('audio.masteringMode must be default or montage.');
  }
  for (const [index, effect] of (timeline.soundEffects || []).entries()) {
    const label = `soundEffects[${index}]`;
    if (!effect || typeof effect !== 'object' || Array.isArray(effect)) throw new Error(`${label} must be an object.`);
    projectPath(projectRoot, effect.path, `${label}.path`, { exists: true });
    const start = finite(effect.start, NaN);
    if (!Number.isFinite(start) || start < 0 || start >= duration) throw new Error(`${label}.start is outside the timeline.`);
    for (const field of ['trim', 'duration', 'gain', 'fadeInMs', 'fadeOutMs']) {
      if (effect[field] != null && (!Number.isFinite(Number(effect[field])) || Number(effect[field]) < 0)) {
        throw new Error(`${label}.${field} must be a non-negative number.`);
      }
    }
    if (effect.duration != null && Number(effect.duration) <= 0) throw new Error(`${label}.duration must be greater than zero.`);
    if (effect.gain != null && Number(effect.gain) > 4) throw new Error(`${label}.gain cannot exceed 4.`);
  }
  if (timeline.fontsDir) projectPath(projectRoot, timeline.fontsDir, 'fontsDir', { exists: true });
  return { width, height, fps, duration };
}

function collectProjectIO(timeline, projectRoot, timelineFile) {
  const reads = [{ label: 'timeline', file: timelineFile }];
  const writes = [];
  for (const shot of timeline.shots) {
    reads.push({ label: `shot ${shot.id}`, file: projectPath(projectRoot, shot.path, `shot ${shot.id}`, { exists: true }) });
  }
  if (timeline.captionSource) {
    reads.push({ label: 'captionSource', file: projectPath(projectRoot, timeline.captionSource, 'captionSource', { exists: true }) });
    writes.push({ label: 'captions', file: projectPath(projectRoot, timeline.captions || 'captions/final.ass', 'captions') });
  } else if (timeline.captions) {
    reads.push({ label: 'captions', file: projectPath(projectRoot, timeline.captions, 'captions', { exists: true }) });
  }
  if (typeof timeline.narration === 'string') {
    reads.push({ label: 'narration', file: projectPath(projectRoot, timeline.narration, 'narration', { exists: true }) });
  }
  const narration = narrationSpec(timeline, projectRoot);
  if (narration && narration.engine === 'file') {
    reads.push({ label: 'narration.path', file: projectPath(projectRoot, narration.path, 'narration.path', { exists: true }) });
  }
  for (const [index, effect] of (timeline.soundEffects || []).entries()) {
    reads.push({
      label: `soundEffects[${index}].path`,
      file: projectPath(projectRoot, effect.path, `soundEffects[${index}].path`, { exists: true })
    });
  }
  if (typeof timeline.music === 'string') {
    reads.push({ label: 'music', file: projectPath(projectRoot, timeline.music, 'music', { exists: true }) });
  } else if (timeline.music && typeof timeline.music === 'object' && timeline.music.path) {
    const item = { label: 'music.path', file: projectPath(projectRoot, timeline.music.path, 'music.path') };
    if (timeline.music.mode === 'file') {
      if (!fs.existsSync(item.file)) throw new Error(`Music file not found: ${timeline.music.path}`);
      reads.push(item);
    } else if (timeline.music.mode === 'procedural') {
      writes.push(item);
    }
  }
  writes.push({ label: 'output.file', file: projectPath(projectRoot, timeline.output.file || 'renders/final.mp4', 'output.file') });
  const reports = timeline.reports || {};
  if (reports.contactSheet !== false) {
    writes.push({ label: 'reports.contactSheet', file: projectPath(projectRoot, reports.contactSheet || 'reports/contact-sheet.jpg', 'reports.contactSheet') });
  }
  writes.push({ label: 'reports.renderReport', file: projectPath(projectRoot, reports.renderReport || 'reports/render-report.json', 'reports.renderReport') });
  return { reads, writes };
}

function preflightProjectIO(io, options = {}) {
  for (let index = 0; index < io.writes.length; index += 1) {
    const current = io.writes[index];
    for (const source of io.reads) {
      if (samePath(current.file, source.file)) {
        throw new Error(`${current.label} must not overwrite or alias read input ${source.label}.`);
      }
    }
    for (let previous = 0; previous < index; previous += 1) {
      if (samePath(current.file, io.writes[previous].file)) {
        throw new Error(`${current.label} aliases write target ${io.writes[previous].label}.`);
      }
    }
    if (entryExists(current.file)) {
      const stat = fs.lstatSync(current.file);
      if (stat.isDirectory()) throw new Error(`${current.label} points to a directory.`);
      if (!options.force) {
        throw new Error(`${current.label} already exists: ${current.file}. Re-run with --force to replace generated outputs.`);
      }
    }
  }
}

function gradeFilter(timeline, shot) {
  const look = { ...(timeline.look || {}), ...(shot.look || {}) };
  const preview = timeline._renderProfile === 'preview';
  const contrast = clamp(finite(look.contrast, 1.035), 0.5, 2);
  const saturation = clamp(finite(look.saturation, 0.95), 0, 3);
  const brightness = clamp(finite(look.brightness, -0.008), -0.5, 0.5);
  const gamma = clamp(finite(look.gamma, 0.995), 0.2, 5);
  const filters = [`eq=contrast=${contrast}:saturation=${saturation}:brightness=${brightness}:gamma=${gamma}`];
  if (!preview && look.vignette !== false) filters.push(`vignette=${typeof look.vignette === 'string' ? look.vignette : 'PI/5'}`);
  const grain = preview ? 0 : clamp(finite(look.grain, 0.8), 0, 12);
  if (grain > 0) filters.push(`noise=alls=${grain}:allf=t+u`);
  filters.push('format=yuv420p');
  return filters.join(',');
}

function zoomExpression(motion, frames) {
  const last = Math.max(1, frames - 1);
  const centered = "x='iw/2-iw/zoom/2':y='ih/2-ih/zoom/2'";
  if (motion === 'pullBack') return `z='max(1,1.14-0.14*on/${last})':${centered}`;
  if (motion === 'panDown') return `z='1.12':x='iw/2-iw/zoom/2':y='(ih-ih/zoom)*on/${last}'`;
  if (motion === 'panUp') return `z='1.12':x='iw/2-iw/zoom/2':y='(ih-ih/zoom)*(1-on/${last})'`;
  if (motion === 'panLeft') return `z='1.12':x='(iw-iw/zoom)*(1-on/${last})':y='ih/2-ih/zoom/2'`;
  if (motion === 'panRight') return `z='1.12':x='(iw-iw/zoom)*on/${last}':y='ih/2-ih/zoom/2'`;
  if (motion === 'none') return `z='1':${centered}`;
  return `z='min(1.14,1+0.14*on/${last})':${centered}`;
}

function imageFilter(shot, timeline, frames) {
  const { width, height, fps } = timeline.output;
  const scaleFlags = timeline._renderProfile === 'preview' ? 'bilinear' : 'lanczos';
  const fit = shot.fit || 'cover';
  const zoom = zoomExpression(shot.motion || 'pushIn', frames);
  let composition;
  if (fit === 'containBlur') {
    const foregroundWidth = Math.max(2, width - Math.round(width * 0.067));
    const foregroundHeight = Math.max(2, height - Math.round(height * 0.156));
    composition = [
      '[0:v]split=2[bg][fg]',
      `[bg]scale=${width}:${height}:force_original_aspect_ratio=increase:flags=${scaleFlags},crop=${width}:${height},gblur=sigma=32,eq=brightness=-0.11:saturation=0.72[bgv]`,
      `[fg]scale=${foregroundWidth}:${foregroundHeight}:force_original_aspect_ratio=decrease:flags=${scaleFlags}[fgv]`,
      `[bgv][fgv]overlay=(W-w)/2:(H-h)/2:format=auto[composed]`
    ].join(';');
  } else if (fit === 'contain') {
    composition = `[0:v]scale=${width}:${height}:force_original_aspect_ratio=decrease:flags=${scaleFlags},pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=black[composed]`;
  } else {
    const workingWidth = Math.ceil(width * 1.2 / 2) * 2;
    const workingHeight = Math.ceil(height * 1.2 / 2) * 2;
    composition = `[0:v]scale=${workingWidth}:${workingHeight}:force_original_aspect_ratio=increase:flags=${scaleFlags},crop=${workingWidth}:${workingHeight}[composed]`;
  }
  return `${composition};[composed]zoompan=${zoom}:d=1:s=${width}x${height}:fps=${fps},settb=AVTB,setsar=1,${gradeFilter(timeline, shot)}[v]`;
}

function videoFilter(shot, timeline) {
  const { width, height, fps } = timeline.output;
  const scaleFlags = timeline._renderProfile === 'preview' ? 'bilinear' : 'lanczos';
  const duration = finite(shot.duration, 1);
  const commonTail = `setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=${duration},trim=duration=${duration},fps=${fps},settb=AVTB,setsar=1,${gradeFilter(timeline, shot)}[v]`;
  if (shot.fit === 'containBlur') {
    const foregroundWidth = Math.max(2, width - Math.round(width * 0.067));
    const foregroundHeight = Math.max(2, height - Math.round(height * 0.156));
    return [
      '[0:v]split=2[bg][fg]',
      `[bg]scale=${width}:${height}:force_original_aspect_ratio=increase:flags=${scaleFlags},crop=${width}:${height},gblur=sigma=32,eq=brightness=-0.11:saturation=0.72[bgv]`,
      `[fg]scale=${foregroundWidth}:${foregroundHeight}:force_original_aspect_ratio=decrease:flags=${scaleFlags}[fgv]`,
      `[bgv][fgv]overlay=(W-w)/2:(H-h)/2:format=auto,${commonTail}`
    ].join(';');
  }
  if (shot.fit === 'contain') {
    return `[0:v]scale=${width}:${height}:force_original_aspect_ratio=decrease:flags=${scaleFlags},pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=black,${commonTail}`;
  }
  return `[0:v]scale=${width}:${height}:force_original_aspect_ratio=increase:flags=${scaleFlags},crop=${width}:${height},${commonTail}`;
}

function segmentCacheKey(context, shot, input) {
  const { timeline, tools } = context;
  const stat = fs.statSync(input);
  const output = timeline.output || {};
  const payload = {
    version: SEGMENT_CACHE_VERSION,
    ffmpeg: tools.version,
    source: {
      realpath: fs.realpathSync(input),
      size: stat.size,
      mtimeMs: stat.mtimeMs,
      ctimeMs: stat.ctimeMs,
      ino: stat.ino
    },
    shot,
    look: timeline.look || null,
    profile: timeline._renderProfile,
    output: {
      width: output.width,
      height: output.height,
      fps: output.fps,
      level: output.level || '4.2',
      intermediatePreset: output.intermediatePreset || 'veryfast',
      intermediateCrf: finite(output.intermediateCrf, 18)
    }
  };
  return crypto.createHash('sha256').update(stableStringify(payload)).digest('hex');
}

function cacheFileAtomically(source, destination) {
  fs.mkdirSync(path.dirname(destination), { recursive: true });
  const temporary = temporarySibling(destination);
  try {
    fs.copyFileSync(source, temporary, fs.constants.COPYFILE_FICLONE);
    commitTemporary(temporary, destination);
  } catch (error) {
    try { fs.rmSync(temporary, { force: true }); } catch (_) {}
    throw error;
  }
}

function reusableCacheFile(file, minimumBytes = 1024) {
  try {
    const stat = fs.lstatSync(file);
    return stat.isFile() && stat.size > minimumBytes;
  } catch {
    return false;
  }
}

function renderShot(context, shot, index) {
  const { timeline, projectRoot, buildDir, tools, progress, cacheRoot, cacheStats } = context;
  const output = timeline.output;
  const duration = finite(shot.duration, 0);
  const frames = Math.round(duration * output.fps);
  const input = projectPath(projectRoot, shot.path, `shot ${shot.id} path`, { exists: true });
  const segment = path.join(buildDir, 'segments', `${String(index + 1).padStart(3, '0')}-${shot.id.replace(/[^a-zA-Z0-9._-]/g, '_')}.mkv`);
  const cacheFile = cacheRoot
    ? path.join(cacheRoot, `${segmentCacheKey(context, shot, input)}.mkv`)
    : null;
  if (cacheFile && reusableCacheFile(cacheFile)) {
    cacheStats.hits += 1;
    cacheStats.segments.hits += 1;
    progress(`shot ${index + 1}/${timeline.shots.length}: ${shot.id} (cache hit)`);
    return cacheFile;
  }
  if (cacheFile && cacheStats) {
    cacheStats.misses += 1;
    cacheStats.segments.misses += 1;
  }
  fs.mkdirSync(path.dirname(segment), { recursive: true });
  const args = ['-hide_banner', '-loglevel', 'warning', '-y'];
  if (shot.kind === 'image') {
    args.push('-loop', '1', '-framerate', String(output.fps), '-i', input);
  } else {
    if (finite(shot.in, 0) > 0) args.push('-ss', String(finite(shot.in, 0)));
    args.push('-i', input);
  }
  args.push('-f', 'lavfi', '-i', `anullsrc=channel_layout=stereo:sample_rate=48000:d=${duration}`);
  const sourceHasAudio = shot.kind === 'video' && shot.sourceAudio === true && hasAudio(input, tools.ffprobe);
  const gain = clamp(finite(shot.sourceGainDb, 0), -60, 24);
  const videoGraph = shot.kind === 'image' ? imageFilter(shot, timeline, frames) : videoFilter(shot, timeline);
  const audioGraph = sourceHasAudio
    ? `[0:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,volume=${gain}dB,apad,atrim=0:${duration}[a]`
    : `[1:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,atrim=0:${duration}[a]`;
  progress(`shot ${index + 1}/${timeline.shots.length}: ${shot.id}`);
  run(tools.ffmpeg, [
    ...args,
    '-filter_complex', `${videoGraph};${audioGraph}`,
    '-map', '[v]', '-map', '[a]',
    '-t', String(duration),
    '-c:v', 'libx264', '-preset', output.intermediatePreset || 'veryfast', '-crf', String(finite(output.intermediateCrf, 18)),
    '-profile:v', 'high', '-level', output.level || '4.2', '-pix_fmt', 'yuv420p',
    '-r', String(output.fps), '-g', String(Math.round(output.fps * 2)),
    '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
    '-color_primaries', 'bt709', '-color_trc', 'bt709', '-colorspace', 'bt709',
    segment
  ], { cwd: projectRoot });
  if (!cacheFile) return segment;
  cacheFileAtomically(segment, cacheFile);
  return cacheFile;
}

function concatSegments(context, segments) {
  const { buildDir, tools, projectRoot, progress, timeline } = context;
  const transitions = timeline.shots.slice(1).map(transitionSpec);
  const hasTransitions = transitions.some((transition) => transition.duration > 0);
  const assembled = path.join(buildDir, 'assembled.mkv');
  if (hasTransitions) {
    const args = ['-hide_banner', '-loglevel', 'warning', '-y'];
    for (const segment of segments) args.push('-i', segment);
    const graph = [];
    let video = '0:v';
    let audio = '0:a';
    let currentDuration = finite(timeline.shots[0].duration, 0);
    for (let index = 1; index < segments.length; index += 1) {
      const transition = transitionSpec(timeline.shots[index]);
      const nextVideo = `${index}:v`;
      const nextAudio = `${index}:a`;
      const outVideo = `v${index}`;
      const outAudio = `a${index}`;
      if (transition.duration > 0) {
        const offset = Math.max(0, currentDuration - transition.duration);
        graph.push(`[${video}][${nextVideo}]xfade=transition=${transition.type}:duration=${transition.duration}:offset=${offset}[${outVideo}]`);
        graph.push(`[${audio}][${nextAudio}]acrossfade=d=${transition.duration}:c1=tri:c2=tri[${outAudio}]`);
        currentDuration += finite(timeline.shots[index].duration, 0) - transition.duration;
      } else {
        graph.push(`[${video}][${nextVideo}]concat=n=2:v=1:a=0[${outVideo}]`);
        graph.push(`[${audio}][${nextAudio}]concat=n=2:v=0:a=1[${outAudio}]`);
        currentDuration += finite(timeline.shots[index].duration, 0);
      }
      video = outVideo;
      audio = outAudio;
    }
    graph.push(`[${video}]trim=duration=${timeline.output.duration},setpts=PTS-STARTPTS[vout]`);
    graph.push(`[${audio}]atrim=duration=${timeline.output.duration},asetpts=PTS-STARTPTS[aout]`);
    const graphFile = path.join(buildDir, 'transitions.ffscript');
    fs.writeFileSync(graphFile, `${graph.join(';\n')}\n`, 'utf8');
    progress(`assembling shots with ${transitions.filter((transition) => transition.duration > 0).length} transition(s)`);
    args.push(
      '-/filter_complex', graphFile,
      '-map', '[vout]', '-map', '[aout]',
      '-c:v', 'libx264', '-preset', timeline.output.intermediatePreset || 'veryfast',
      '-crf', String(finite(timeline.output.intermediateCrf, 18)),
      '-profile:v', 'high', '-level', timeline.output.level || '4.2', '-pix_fmt', 'yuv420p',
      '-r', String(timeline.output.fps), '-g', String(Math.round(timeline.output.fps * 2)),
      '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
      assembled
    );
    run(tools.ffmpeg, args, { cwd: projectRoot });
    return assembled;
  }
  const list = path.join(buildDir, 'segments.txt');
  const content = segments.map((file) => {
    if (/\r|\n/.test(file)) throw new Error('Segment paths cannot contain newlines.');
    return `file '${file.replace(/'/g, "'\\''")}'`;
  }).join('\n') + '\n';
  fs.writeFileSync(list, content, 'utf8');
  progress('assembling shots');
  run(tools.ffmpeg, [
    '-hide_banner', '-loglevel', 'warning', '-y',
    '-f', 'concat', '-safe', '0', '-i', list,
    '-c', 'copy',
    assembled
  ], { cwd: projectRoot });
  return assembled;
}

function resolveCaptionFont(context, document) {
  const { timeline, projectRoot, fontFilesRoot } = context;
  if (timeline.fontsDir) {
    return {
      family: timeline.font || document.font || 'Noto Sans CJK SC',
      directory: projectPath(projectRoot, timeline.fontsDir, 'fontsDir', { exists: true }),
      source: 'project'
    };
  }
  const candidates = [
    path.join(os.homedir(), 'Library', 'Fonts', 'NotoSansCJKsc-Regular.otf'),
    '/Library/Fonts/NotoSansCJKsc-Regular.otf',
    '/opt/homebrew/share/fonts/NotoSansCJKsc-Regular.otf',
    '/usr/local/share/fonts/NotoSansCJKsc-Regular.otf',
    '/usr/share/fonts/opentype/noto/NotoSansCJKsc-Regular.otf',
    '/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc'
  ];
  const source = candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
  if (!source) {
    return {
      family: timeline.font || document.font || 'Noto Sans CJK SC',
      directory: null,
      source: 'system-unverified'
    };
  }
  const stat = fs.statSync(source);
  const extension = path.extname(source) || '.otf';
  const fingerprint = crypto.createHash('sha256')
    .update(`${source}\0${stat.size}\0${stat.mtimeMs}\0${stat.ctimeMs}`)
    .digest('hex')
    .slice(0, 16);
  const directory = path.join(fontFilesRoot, fingerprint);
  const destination = path.join(directory, `NotoSansCJKsc-Regular${extension}`);
  ensureInternalDirectory(projectRoot, directory, 'caption font cache');
  if (!reusableCacheFile(destination, 0) || fs.lstatSync(destination).size !== stat.size) {
    cacheFileAtomically(source, destination);
  }
  return { family: 'Noto Sans CJK SC', directory, source: 'local-auto' };
}

function prepareCaptions(context) {
  const { timeline, projectRoot, progress } = context;
  if (!timeline.captionSource && !timeline.captions) return null;
  const output = projectPath(projectRoot, timeline.captions || 'captions/final.ass', 'captions');
  if (!timeline.captionSource) {
    if (!fs.existsSync(output)) throw new Error(`Caption ASS not found: ${path.relative(projectRoot, output)}`);
    context.resolvedCaptionFont = resolveCaptionFont(context, { font: timeline.font });
    return output;
  }
  const input = projectPath(projectRoot, timeline.captionSource, 'captionSource', { exists: true });
  const document = readCaptionDocument(input);
  const resolvedFont = resolveCaptionFont(context, document);
  context.resolvedCaptionFont = resolvedFont;
  const events = [...(document.events || []), ...(document.cues || [])];
  if (events.length > 20000) throw new Error('Caption event count exceeds the default safety limit of 20,000.');
  for (const [index, event] of events.entries()) {
    if (finite(event.end, 0) > finite(timeline.output.duration, 0) + 0.01) {
      throw new Error(`Caption ${index + 1} ends after output.duration.`);
    }
  }
  progress('generating bilingual ASS captions');
  const ass = generateBilingualAss(document, {
    width: timeline.output.width,
    height: timeline.output.height,
    coordinateWidth: timeline._sourceOutputWidth,
    coordinateHeight: timeline._sourceOutputHeight,
    font: resolvedFont.family
  });
  atomicWriteFile(output, ass, 'utf8');
  return output;
}

function atempoChain(tempo) {
  const filters = [];
  let remaining = tempo;
  while (remaining > 2.000001) {
    filters.push('atempo=2');
    remaining /= 2;
  }
  if (remaining > 1.001) filters.push(`atempo=${remaining.toFixed(6)}`);
  return filters;
}

function narrationSpec(timeline, projectRoot) {
  if (!timeline.narration) return null;
  if (typeof timeline.narration === 'string') {
    return readJson(projectPath(projectRoot, timeline.narration, 'narration', { exists: true }));
  }
  if (typeof timeline.narration === 'object' && !Array.isArray(timeline.narration)) return timeline.narration;
  throw new Error('narration must be a project-relative JSON path or an object.');
}

function narrationCacheKey(context, spec, cue, start) {
  const sayStat = fs.statSync('/usr/bin/say');
  const rate = Math.round(finite(cue.rate, finite(spec.rate, 174)));
  const remaining = context.timeline.output.duration - start;
  const declaredMaxDuration = Number.isFinite(Number(cue.maxDuration))
    ? clamp(Number(cue.maxDuration), 0.05, remaining)
    : null;
  const payload = {
    version: TTS_CACHE_VERSION,
    platform: process.platform,
    osRelease: os.release(),
    sayMtimeMs: sayStat.mtimeMs,
    ffmpeg: context.tools.version,
    text: cue.text,
    voice: cue.voice || spec.voice || null,
    rate,
    gain: clamp(finite(cue.gain, finite(spec.gain, 1.18)), 0, 4),
    declaredMaxDuration,
    remaining
  };
  return crypto.createHash('sha256').update(stableStringify(payload)).digest('hex');
}

function verifiedFileNarrationProvenance(projectRoot, spec, source) {
  const declaredProvenance = Boolean(
    spec.provider || spec.assetId || spec.speakerId || spec.speakerName || spec.narrationTextSha256
  );
  const manifestFile = projectPath(projectRoot, 'assets-manifest.json', 'asset manifest');
  if (!fs.existsSync(manifestFile)) {
    if (declaredProvenance) throw new Error('File narration provenance requires assets-manifest.json.');
    return null;
  }
  const manifest = readJson(manifestFile);
  if (!manifest || !Array.isArray(manifest.assets)) throw new Error('assets-manifest.json must contain { assets: [] }.');
  const asset = manifest.assets.find((candidate) => (
    spec.assetId ? candidate.id === spec.assetId : candidate.localPath === spec.path
  ));
  if (!asset) {
    if (declaredProvenance) throw new Error('File narration provenance does not match an asset manifest record.');
    return null;
  }
  if (asset.provider === 'listenhub') {
    for (const field of ['assetId', 'speakerId', 'speakerName', 'narrationTextSha256']) {
      if (!spec[field]) throw new Error(`ListenHub file narration requires ${field} provenance.`);
    }
  }
  if (spec.assetId && asset.id !== spec.assetId) throw new Error('File narration assetId does not match the asset manifest record.');
  if (asset.localPath !== spec.path) throw new Error('File narration assetId does not match narration.path.');
  if (asset.mediaType !== 'audio') throw new Error('File narration manifest record must be an audio asset.');
  if (spec.provider && asset.provider !== spec.provider) throw new Error('File narration provider does not match the asset manifest.');
  if (asset.provider === 'listenhub') {
    if (!/^[a-f0-9]{64}$/.test(String(asset.sha256 || ''))) {
      throw new Error('ListenHub file narration manifest record requires a valid SHA-256 digest.');
    }
    if (sha256File(source) !== asset.sha256) {
      throw new Error('ListenHub file narration content SHA-256 does not match the asset manifest.');
    }
  }
  const runs = Array.isArray(asset.provenanceRuns) && asset.provenanceRuns.length
    ? asset.provenanceRuns
    : asset.provenance
      ? [asset.provenance]
      : [];
  const matchingRun = runs.find((run) => {
    const identityMatches = (
      (!spec.speakerId || run.speakerId === spec.speakerId)
      && (!spec.speakerName || run.speakerName === spec.speakerName)
      && (!spec.narrationTextSha256 || run.narrationTextSha256 === spec.narrationTextSha256)
    );
    if (!identityMatches || asset.provider !== 'listenhub') return identityMatches;
    return /^[a-f0-9]{64}$/.test(String(run.speakerCatalogSha256 || ''))
      && /^[a-f0-9]{64}$/.test(String(run.captureSha256 || ''))
      && /^\.qiaocut\/jobs\/listenhub\/.+\.json$/.test(String(run.capturePath || ''));
  });
  if ((spec.speakerId || spec.speakerName || spec.narrationTextSha256) && !matchingRun) {
    throw new Error('File narration speaker/text/catalog/capture provenance does not match the asset manifest.');
  }
  return {
    provider: asset.provider,
    assetId: asset.id,
    speakerId: spec.speakerId || (matchingRun && matchingRun.speakerId) || null,
    speakerName: spec.speakerName || (matchingRun && matchingRun.speakerName) || null,
    narrationTextSha256: spec.narrationTextSha256 || (matchingRun && matchingRun.narrationTextSha256) || null,
    speakerCatalogSha256: (matchingRun && matchingRun.speakerCatalogSha256) || null,
    capturePath: (matchingRun && matchingRun.capturePath) || null,
    captureSha256: (matchingRun && matchingRun.captureSha256) || null
  };
}

function prepareNarration(context) {
  const { timeline, projectRoot, buildDir, tools, progress, ttsCacheRoot, cacheStats } = context;
  const spec = narrationSpec(timeline, projectRoot);
  if (!spec || spec.engine === 'none') return null;
  if (spec.engine === 'file') {
    if (!spec.path || typeof spec.path !== 'string') throw new Error('narration.engine file requires path.');
    const source = projectPath(projectRoot, spec.path, 'narration.path', { exists: true });
    const provenance = verifiedFileNarrationProvenance(projectRoot, spec, source);
    const sourceDuration = durationOf(source, tools.ffprobe);
    const trim = clamp(finite(spec.trim, 0), 0, Math.max(0, sourceDuration));
    const start = clamp(finite(spec.start, 0), 0, timeline.output.duration);
    if (!Number.isFinite(sourceDuration) || sourceDuration <= trim + 0.01) {
      throw new Error('File narration has no playable audio after trim.');
    }
    if (start >= timeline.output.duration) throw new Error('File narration start must be before output.duration.');
    const available = sourceDuration - trim;
    const duration = Math.min(
      clamp(finite(spec.duration, available), 0.01, available),
      timeline.output.duration - start
    );
    const output = path.join(buildDir, 'narration-file.wav');
    const delay = Math.round(start * 1000);
    progress('normalizing project file narration');
    run(tools.ffmpeg, [
      '-hide_banner', '-loglevel', 'error', '-y',
      '-i', source,
      '-af', [
        `atrim=start=${trim}:duration=${duration}`,
        'asetpts=PTS-STARTPTS',
        'aresample=48000',
        'aformat=sample_fmts=fltp:channel_layouts=stereo',
        `volume=${clamp(finite(spec.gain, 1), 0, 4)}`,
        `adelay=${delay}:all=1`,
        'apad',
        `atrim=0:${timeline.output.duration}`,
        'alimiter=limit=0.94'
      ].join(','),
      '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
      output
    ], { cwd: projectRoot });
    return {
      file: output,
      engine: 'file',
      cues: 1,
      voice: spec.speakerName || spec.voice || null,
      provenance
    };
  }
  if (spec.engine !== 'macos-say') throw new Error(`Unsupported narration engine: ${spec.engine}`);
  if (process.platform !== 'darwin' || !fs.existsSync('/usr/bin/say')) {
    throw new Error('narration.engine macos-say requires macOS /usr/bin/say. Supply recorded narration or disable narration on this platform.');
  }
  if (!Array.isArray(spec.cues) || spec.cues.length === 0) return null;
  if (spec.cues.length > 2000) throw new Error('Narration cue count exceeds the default safety limit of 2,000.');
  const ttsDir = path.join(buildDir, 'tts');
  fs.mkdirSync(ttsDir, { recursive: true });
  const normalized = [];
  const cueIds = new Set();
  progress(`synthesizing ${spec.cues.length} narration cues with macOS say`);
  for (const [index, cue] of spec.cues.entries()) {
    const id = String(cue.id || `cue-${index + 1}`).replace(/[^a-zA-Z0-9._-]/g, '_');
    if (cueIds.has(id)) throw new Error(`Duplicate narration cue id: ${id}`);
    cueIds.add(id);
    if (typeof cue.text !== 'string' || !cue.text.trim()) throw new Error(`Narration cue ${id} has no text.`);
    const start = finite(cue.start, NaN);
    if (!Number.isFinite(start) || start < 0 || start >= timeline.output.duration) {
      throw new Error(`Narration cue ${id} has invalid start time.`);
    }
    const raw = path.join(ttsDir, `${id}.aiff`);
    const wav = path.join(ttsDir, `${id}.wav`);
    const cacheFile = ttsCacheRoot
      ? path.join(ttsCacheRoot, `${narrationCacheKey(context, spec, cue, start)}.wav`)
      : null;
    if (cacheFile && reusableCacheFile(cacheFile)) {
      cacheStats.hits += 1;
      cacheStats.narration.hits += 1;
      normalized.push({ id, start, path: cacheFile });
      continue;
    }
    if (cacheFile && cacheStats) {
      cacheStats.misses += 1;
      cacheStats.narration.misses += 1;
    }
    const sayArgs = [];
    if (cue.voice || spec.voice) sayArgs.push('-v', String(cue.voice || spec.voice));
    sayArgs.push('-r', String(Math.round(finite(cue.rate, finite(spec.rate, 174)))), '-o', raw, cue.text);
    run('/usr/bin/say', sayArgs, { cwd: projectRoot });
    const rawDuration = durationOf(raw, tools.ffprobe);
    if (!Number.isFinite(rawDuration) || rawDuration <= 0.05) {
      throw new Error(`Narration cue ${id} produced no playable audio. Grant access to the local macOS speech service and retry.`);
    }
    const remaining = timeline.output.duration - start;
    const maxDuration = clamp(finite(cue.maxDuration, rawDuration), 0.05, remaining);
    const tempo = rawDuration > maxDuration ? rawDuration / maxDuration : 1;
    const filters = [
      'aresample=48000',
      'aformat=sample_fmts=fltp:channel_layouts=stereo',
      'highpass=f=75',
      'lowpass=f=11500',
      'acompressor=threshold=0.12:ratio=2.2:attack=12:release=140',
      `volume=${clamp(finite(cue.gain, finite(spec.gain, 1.18)), 0, 4)}`,
      ...atempoChain(tempo),
      `atrim=0:${maxDuration}`,
      'asetpts=PTS-STARTPTS'
    ];
    run(tools.ffmpeg, [
      '-hide_banner', '-loglevel', 'error', '-y',
      '-i', raw,
      '-af', filters.join(','),
      '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
      wav
    ], { cwd: projectRoot });
    if (cacheFile) {
      cacheFileAtomically(wav, cacheFile);
      normalized.push({ id, start, path: cacheFile });
    } else {
      normalized.push({ id, start, path: wav });
    }
  }
  const graphFile = path.join(buildDir, 'narration.ffscript');
  const graph = normalized.map((cue, index) => {
    const delay = Math.round(cue.start * 1000);
    return `[${index}:a]adelay=${delay}:all=1,apad,atrim=0:${timeline.output.duration}[n${index}]`;
  }).join(';\n') + ';\n' + normalized.map((_, index) => `[n${index}]`).join('') +
    `amix=inputs=${normalized.length}:duration=longest:dropout_transition=0:normalize=0,atrim=0:${timeline.output.duration},alimiter=limit=0.94[narration]\n`;
  fs.writeFileSync(graphFile, graph, 'utf8');
  const narration = path.join(buildDir, 'narration.wav');
  const args = ['-hide_banner', '-loglevel', 'warning', '-y'];
  for (const cue of normalized) args.push('-i', cue.path);
  args.push(
    '-/filter_complex', graphFile,
    '-map', '[narration]',
    '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
    narration
  );
  run(tools.ffmpeg, args, { cwd: projectRoot });
  return { file: narration, engine: spec.engine, cues: normalized.length, voice: spec.voice || null, provenance: null };
}

function prepareSoundEffects(context) {
  const { timeline, projectRoot, buildDir, tools, progress } = context;
  const effects = timeline.soundEffects || [];
  if (!effects.length) return null;
  const output = path.join(buildDir, 'sound-effects.wav');
  const args = ['-hide_banner', '-loglevel', 'warning', '-y'];
  const graph = [];
  const cues = [];
  for (const [index, effect] of effects.entries()) {
    const source = projectPath(projectRoot, effect.path, `soundEffects[${index}].path`, { exists: true });
    args.push('-i', source);
    let start = finite(effect.start, 0);
    let trim = finite(effect.trim, 0);
    let peakMs = null;
    if (effect.alignPeak) {
      // `start` is the visual hit; shift so the measured peak lands on it.
      peakMs = require('./audio_beats').peakOffset(source, { trim }).peakMs;
      start -= peakMs / 1000;
      if (start < 0) { trim += -start; start = 0; }
    }
    const available = Math.max(0.01, durationOf(source, tools.ffprobe) - trim);
    const duration = Math.min(
      effect.duration == null ? available : finite(effect.duration, available),
      timeline.output.duration - start
    );
    if (!(duration > 0)) throw new Error(`soundEffects[${index}] has no playable duration inside the timeline.`);
    const filters = [
      `atrim=start=${trim}:duration=${duration}`,
      'asetpts=PTS-STARTPTS',
      'aresample=48000',
      'aformat=sample_fmts=fltp:channel_layouts=stereo',
      `volume=${clamp(finite(effect.gain, 1), 0, 4)}`
    ];
    const fadeIn = Math.min(duration / 2, finite(effect.fadeInMs, 0) / 1000);
    const fadeOut = Math.min(duration / 2, finite(effect.fadeOutMs, 0) / 1000);
    if (fadeIn > 0) filters.push(`afade=t=in:st=0:d=${fadeIn}`);
    if (fadeOut > 0) filters.push(`afade=t=out:st=${Math.max(0, duration - fadeOut)}:d=${fadeOut}`);
    filters.push(`adelay=${Math.round(start * 1000)}:all=1`, `apad`, `atrim=0:${timeline.output.duration}`);
    graph.push(`[${index}:a]${filters.join(',')}[fx${index}]`);
    cues.push({ id: effect.id || `fx${index + 1}`, path: effect.path, start: Math.round(start * 1000) / 1000, duration, gain: clamp(finite(effect.gain, 1), 0, 4), ...(peakMs != null ? { hitAt: finite(effect.start, 0), peakMs } : {}) });
  }
  graph.push(`${effects.map((_, index) => `[fx${index}]`).join('')}amix=inputs=${effects.length}:duration=longest:dropout_transition=0:normalize=0,alimiter=limit=0.94,atrim=0:${timeline.output.duration}[sfx]`);
  const graphFile = path.join(buildDir, 'sound-effects.ffscript');
  fs.writeFileSync(graphFile, `${graph.join(';\n')}\n`, 'utf8');
  args.push(
    '-/filter_complex', graphFile,
    '-map', '[sfx]',
    '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
    output
  );
  progress(`mixing ${effects.length} sound effect cue(s)`);
  run(tools.ffmpeg, args, { cwd: projectRoot });
  return { file: output, cues };
}

function shotStarts(shots) {
  const starts = [];
  let cursor = 0;
  for (const [index, shot] of shots.entries()) {
    if (index > 0) cursor -= transitionSpec(shot).duration;
    starts.push(Math.round(cursor * 1000) / 1000);
    cursor += finite(shot.duration, 0);
  }
  return starts;
}

function prepareMusic(context) {
  const { timeline, projectRoot, buildDir, progress } = context;
  if (timeline.music === false) return null;
  const object = timeline.music && typeof timeline.music === 'object' && !Array.isArray(timeline.music)
    ? timeline.music
    : null;
  const relativePath = object && object.path
    ? object.path
    : typeof timeline.music === 'string'
      ? timeline.music
      : null;
  const output = relativePath
    ? projectPath(projectRoot, relativePath, 'music path')
    : path.join(buildDir, 'procedural-music.wav');
  const mode = object && object.mode
    ? object.mode
    : typeof timeline.music === 'string'
      ? 'file'
      : 'procedural';
  if (mode === 'none') return null;
  if (mode === 'file') {
    if (!fs.existsSync(output)) throw new Error(`Music file not found: ${relativePath}`);
    return { file: output, mode: 'file' };
  }
  if (mode !== 'procedural') throw new Error(`Unsupported music mode: ${mode}`);
  const options = { ...(timeline.musicOptions || {}), ...(object || {}) };
  progress('generating deterministic procedural score');
  const temp = temporarySibling(output);
  try {
    const report = generateProceduralMusic(temp, {
      ...options,
      duration: timeline.output.duration,
      transitions: options.transitions || shotStarts(timeline.shots)
    });
    commitTemporary(temp, output);
    return { ...report, file: output, mode: 'procedural' };
  } catch (error) {
    try { fs.rmSync(temp, { force: true }); } catch (_) {}
    throw error;
  }
}

function captionFontFingerprints(projectRoot, directory) {
  const extensions = new Set(['.otf', '.otc', '.ttf', '.ttc', '.woff', '.woff2']);
  const entries = fs.readdirSync(directory, { withFileTypes: true })
    .filter((entry) => entry.isFile() || entry.isSymbolicLink())
    .filter((entry) => extensions.has(path.extname(entry.name).toLowerCase()))
    .sort((left, right) => left.name.localeCompare(right.name));
  if (entries.length > 256) throw new Error('Caption font directory exceeds the 256-file safety limit.');
  let totalBytes = 0;
  return entries.map((entry) => {
    const file = path.join(directory, entry.name);
    assertPhysicalPathWithin(projectRoot, file, `caption font ${entry.name}`);
    const stat = fs.statSync(file);
    if (!stat.isFile()) throw new Error(`Caption font entry is not a regular file: ${entry.name}`);
    totalBytes += stat.size;
    if (stat.size > 128 * 1024 * 1024 || totalBytes > 512 * 1024 * 1024) {
      throw new Error('Caption font files exceed the default size safety limit.');
    }
    return {
      name: entry.name,
      size: stat.size,
      mtimeMs: stat.mtimeMs,
      ctimeMs: stat.ctimeMs,
      sha256: crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
    };
  });
}

function pictureCacheKey(context, segments, captions) {
  const { timeline, tools } = context;
  const captionHash = captions
    ? crypto.createHash('sha256').update(fs.readFileSync(captions)).digest('hex')
    : null;
  const segmentFingerprints = segments.map((file) => {
    const stat = fs.statSync(file);
    return {
      name: path.basename(file),
      size: stat.size,
      mtimeMs: stat.mtimeMs,
      ctimeMs: stat.ctimeMs
    };
  });
  const resolvedFont = context.resolvedCaptionFont || null;
  const fontDirectory = resolvedFont && resolvedFont.directory ? resolvedFont.directory : null;
  const fontFiles = captions && fontDirectory
    ? captionFontFingerprints(context.projectRoot, fontDirectory)
    : null;
  const payload = {
    version: PICTURE_CACHE_VERSION,
    ffmpeg: tools.version,
    profile: timeline._renderProfile,
    captions: captionHash,
    segments: segmentFingerprints,
    transitions: timeline.shots.slice(1).map(transitionSpec),
    fonts: captions
      ? fontDirectory
        ? { family: resolvedFont.family, files: fontFiles }
        : { system: os.release(), family: resolvedFont ? resolvedFont.family : (timeline.font || null) }
      : null,
    output: {
      width: timeline.output.width,
      height: timeline.output.height,
      fps: timeline.output.fps,
      duration: timeline.output.duration,
      preset: timeline.output.preset || 'slow',
      crf: finite(timeline.output.crf, 18),
      level: timeline.output.level || '4.2'
    }
  };
  return crypto.createHash('sha256').update(stableStringify(payload)).digest('hex');
}

function renderPicture(context, assembled, captions, segments) {
  const {
    timeline,
    projectRoot,
    buildDir,
    tools,
    progress,
    fontCacheRoot,
    pictureCacheRoot,
    cacheStats
  } = context;
  const deterministicFont = !captions ||
    (context.resolvedCaptionFont && context.resolvedCaptionFont.source !== 'system-unverified');
  const cacheFile = pictureCacheRoot && deterministicFont
    ? path.join(pictureCacheRoot, `${pictureCacheKey(context, segments, captions)}.mp4`)
    : null;
  if (cacheFile && reusableCacheFile(cacheFile)) {
    cacheStats.hits += 1;
    cacheStats.pictures.hits += 1;
    progress('mastered picture (cache hit)');
    return cacheFile;
  }
  if (cacheFile && cacheStats) {
    cacheStats.misses += 1;
    cacheStats.pictures.misses += 1;
  }
  const picture = path.join(buildDir, 'picture.mp4');
  let filter = 'format=yuv420p';
  if (captions) {
    const fonts = context.resolvedCaptionFont && context.resolvedCaptionFont.directory
      ? `:fontsdir='${filterPath(context.resolvedCaptionFont.directory)}'`
      : '';
    filter = `ass=filename='${filterPath(captions)}'${fonts},format=yuv420p`;
  }
  progress(captions ? 'burning captions and mastering picture' : 'mastering picture');
  const rendered = run(tools.ffmpeg, [
    '-hide_banner', '-loglevel', 'error', '-y',
    '-i', assembled,
    '-vf', filter,
    '-an', '-t', String(timeline.output.duration),
    '-c:v', 'libx264', '-preset', timeline.output.preset || 'slow', '-crf', String(finite(timeline.output.crf, 18)),
    '-profile:v', 'high', '-level', timeline.output.level || '4.2', '-pix_fmt', 'yuv420p',
    '-r', String(timeline.output.fps), '-g', String(Math.round(timeline.output.fps * 2)),
    '-color_primaries', 'bt709', '-color_trc', 'bt709', '-colorspace', 'bt709',
    '-movflags', '+faststart',
    picture
  ], {
    cwd: projectRoot,
    capture: true,
    maxBuffer: 4 * 1024 * 1024,
    env: { XDG_CACHE_HOME: fontCacheRoot }
  });
  if (/error opening font|failed to find any fallback with glyph|fontselect:.*failed/i.test(rendered.stderr)) {
    throw new Error(
      'Subtitle rendering could not resolve one or more glyphs. Add a CJK-capable font file under the project, set timeline.fontsDir to that project-relative directory, and set the caption font family.'
    );
  }
  if (!cacheFile) return picture;
  cacheFileAtomically(picture, cacheFile);
  return cacheFile;
}

function mixAudio(context, assembled, narration, music, soundEffects) {
  const { timeline, projectRoot, buildDir, tools, progress } = context;
  const mix = path.join(buildDir, 'mix.wav');
  const duration = finite(timeline.output.duration, 0);
  const audio = timeline.audio || {};
  const args = ['-hide_banner', '-loglevel', 'warning', '-y', '-i', assembled];
  let narrationIndex = null;
  let musicIndex = null;
  let soundEffectsIndex = null;
  if (narration) {
    narrationIndex = args.filter((value) => value === '-i').length;
    args.push('-i', narration.file);
  }
  if (music) {
    musicIndex = args.filter((value) => value === '-i').length;
    args.push('-i', music.file);
  }
  if (soundEffects) {
    soundEffectsIndex = args.filter((value) => value === '-i').length;
    args.push('-i', soundEffects.file);
  }
  const graph = [];
  graph.push(`[0:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,volume=${clamp(finite(audio.originalGain, 1), 0, 4)}[original]`);
  if (narrationIndex != null) {
    graph.push(`[${narrationIndex}:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,volume=${clamp(finite(audio.narrationGain, 1), 0, 4)}[narration]`);
    graph.push('[original][narration]amix=inputs=2:duration=longest:dropout_transition=0:normalize=0,alimiter=limit=0.93[speech]');
  } else {
    graph.push('[original]anull[speech]');
  }
  if (musicIndex != null) {
    graph.push('[speech]asplit=2[speechout][sidechain]');
    graph.push(`[${musicIndex}:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,volume=${clamp(finite(audio.musicGain, 0.62), 0, 4)},highpass=f=35,lowpass=f=12000[music]`);
    graph.push(`[music][sidechain]sidechaincompress=threshold=${clamp(finite(audio.duckThreshold, 0.022), 0.0001, 1)}:ratio=${clamp(finite(audio.duckRatio, 8), 1, 20)}:attack=${clamp(finite(audio.duckAttackMs, 12), 1, 500)}:release=${clamp(finite(audio.duckReleaseMs, 380), 10, 3000)}[ducked]`);
    graph.push(`[speechout][ducked]amix=inputs=2:duration=longest:dropout_transition=0:normalize=0,alimiter=limit=0.92,atrim=0:${duration}[bed]`);
  } else {
    graph.push(`[speech]alimiter=limit=0.92,atrim=0:${duration}[bed]`);
  }
  if (soundEffectsIndex != null) {
    graph.push(`[${soundEffectsIndex}:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,volume=${clamp(finite(audio.sfxGain, 1), 0, 4)}[sfx]`);
    graph.push(`[bed][sfx]amix=inputs=2:duration=longest:dropout_transition=0:normalize=0,alimiter=limit=0.92,atrim=0:${duration}[premaster]`);
  } else {
    graph.push('[bed]anull[premaster]');
  }
  if (audio.masteringMode === 'montage') {
    graph.push(`[premaster]acompressor=threshold=0.10:ratio=2.5:attack=12:release=180:makeup=1.5,alimiter=limit=0.92,atrim=0:${duration}[mix]`);
  } else {
    graph.push('[premaster]anull[mix]');
  }
  const graphFile = path.join(buildDir, 'mix.ffscript');
  fs.writeFileSync(graphFile, `${graph.join(';\n')}\n`, 'utf8');
  progress('mixing source audio, narration, music, and sound effects');
  args.push(
    '-/filter_complex', graphFile,
    '-map', '[mix]',
    '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
    mix
  );
  run(tools.ffmpeg, args, { cwd: projectRoot });
  return mix;
}

function parseLoudnormStats(stderr) {
  const matches = String(stderr || '').match(/\{\s*"input_i"[\s\S]*?\}/g);
  if (!matches || !matches.length) throw new Error('Could not parse ffmpeg loudnorm analysis.');
  return JSON.parse(matches[matches.length - 1]);
}

function usableLoudnormStats(stats) {
  return ['input_i', 'input_tp', 'input_lra', 'input_thresh', 'target_offset']
    .every((key) => Number.isFinite(Number(stats[key])));
}

function loudnorm(context, input) {
  const { timeline, projectRoot, buildDir, tools, progress } = context;
  const normalized = path.join(buildDir, 'normalized.wav');
  const target = clamp(finite(timeline.output.loudnessLufs, -14), -70, -5);
  const peak = clamp(finite(timeline.output.truePeakDb, -1.5), -9, -0.1);
  const mode = timeline._normalizationMode || 'two-pass';
  progress(`normalizing audio to ${target} LUFS / ${peak} dBTP (${mode})`);
  if (mode === 'single-pass') {
    run(tools.ffmpeg, [
      '-hide_banner', '-loglevel', 'warning', '-y', '-i', input,
      '-af', `loudnorm=I=${target}:LRA=7:TP=${peak},aresample=48000`,
      '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
      normalized
    ], { cwd: projectRoot });
    return {
      file: normalized,
      stats: null,
      passes: 1,
      mode,
      targetLufs: target,
      targetTruePeakDb: peak
    };
  }
  const first = run(tools.ffmpeg, [
    '-hide_banner', '-nostats', '-i', input,
    '-af', `loudnorm=I=${target}:LRA=7:TP=${peak}:print_format=json`,
    '-f', 'null', '-'
  ], { cwd: projectRoot, capture: true });
  const stats = parseLoudnormStats(first.stderr);
  const filter = usableLoudnormStats(stats)
    ? [
        `loudnorm=I=${target}`,
        'LRA=7',
        `TP=${peak}`,
        `measured_I=${stats.input_i}`,
        `measured_TP=${stats.input_tp}`,
        `measured_LRA=${stats.input_lra}`,
        `measured_thresh=${stats.input_thresh}`,
        `offset=${stats.target_offset}`,
        'linear=true',
        'print_format=summary'
      ].join(':') + ',aresample=48000'
    : `loudnorm=I=${target}:LRA=7:TP=${peak},aresample=48000`;
  run(tools.ffmpeg, [
    '-hide_banner', '-loglevel', 'warning', '-y', '-i', input,
    '-af', filter,
    '-c:a', 'pcm_s24le', '-ar', '48000', '-ac', '2',
    normalized
  ], { cwd: projectRoot });
  return {
    file: normalized,
    stats,
    passes: 2,
    mode,
    targetLufs: target,
    targetTruePeakDb: peak
  };
}

function muxFinal(context, picture, audio) {
  const { timeline, projectRoot, tools, progress } = context;
  const output = projectPath(projectRoot, timeline.output.file || 'renders/final.mp4', 'output.file');
  fs.mkdirSync(path.dirname(output), { recursive: true });
  const temporaryOutput = temporarySibling(output);
  const metadata = timeline.metadata || {};
  progress(`muxing final video: ${path.relative(projectRoot, output)}`);
  const args = [
    '-hide_banner', '-loglevel', 'warning', '-y',
    '-i', picture, '-i', audio,
    '-t', String(timeline.output.duration),
    '-map', '0:v:0', '-map', '1:a:0',
    '-c:v', 'copy',
    '-c:a', 'aac', '-b:a', timeline.output.audioBitrate || '192k', '-ar', '48000', '-ac', '2',
    '-movflags', '+faststart',
    '-metadata', `title=${metadata.title || timeline.title || 'QiaoCut video'}`,
    '-metadata', `comment=${metadata.comment || 'Created with qiaomu-cut.'}`
  ];
  if (metadata.artist) args.push('-metadata', `artist=${metadata.artist}`);
  if (metadata.copyright) args.push('-metadata', `copyright=${metadata.copyright}`);
  args.push(temporaryOutput);
  try {
    run(tools.ffmpeg, args, { cwd: projectRoot });
    commitTemporary(temporaryOutput, output);
  } catch (error) {
    try { fs.rmSync(temporaryOutput, { force: true }); } catch (_) {}
    throw error;
  }
  return output;
}

function contactSheet(context, finalVideo) {
  const { timeline, projectRoot, tools, progress } = context;
  if (timeline.reports && timeline.reports.contactSheet === false) return null;
  const spec = timeline.reports || {};
  const output = projectPath(projectRoot, spec.contactSheet || 'reports/contact-sheet.jpg', 'reports.contactSheet');
  const count = clamp(Math.round(finite(spec.contactSheetFrames, 12)), 4, 30);
  const columns = clamp(Math.round(finite(spec.contactSheetColumns, 4)), 2, 6);
  const rows = Math.ceil(count / columns);
  const thumbWidth = clamp(Math.round(finite(spec.contactSheetThumbWidth, 270)), 120, 640);
  fs.mkdirSync(path.dirname(output), { recursive: true });
  const temporaryOutput = temporarySibling(output);
  progress('creating visual contact sheet');
  try {
    run(tools.ffmpeg, [
      '-hide_banner', '-loglevel', 'error', '-y',
      '-i', finalVideo,
      '-vf', `fps=${count}/${timeline.output.duration},scale=${thumbWidth}:-2:flags=lanczos,tile=${columns}x${rows}:nb_frames=${count}:padding=8:margin=8:color=0x111111`,
      '-frames:v', '1',
      temporaryOutput
    ], { cwd: projectRoot });
    commitTemporary(temporaryOutput, output);
  } catch (error) {
    try { fs.rmSync(temporaryOutput, { force: true }); } catch (_) {}
    throw error;
  }
  return output;
}

function fraction(value) {
  if (typeof value !== 'string' || !value.includes('/')) return finite(value, 0);
  const [numerator, denominator] = value.split('/').map(Number);
  return denominator ? numerator / denominator : 0;
}

function lastNumber(text, pattern) {
  const matches = [...String(text || '').matchAll(pattern)];
  return matches.length ? Number(matches[matches.length - 1][1]) : null;
}

function inspectFinal(context, file) {
  const { timeline, tools, projectRoot } = context;
  const validation = context.validation || timeline._validationLevel || 'full';
  const checks = {
    streams: true,
    loudness: validation !== 'basic',
    blackFrames: validation === 'full',
    silence: validation !== 'basic'
  };
  const result = run(tools.ffprobe, [
    '-v', 'error', '-show_format', '-show_streams', '-of', 'json', file
  ], { capture: true });
  const data = JSON.parse(result.stdout);
  const video = (data.streams || []).find((stream) => stream.codec_type === 'video');
  const audio = (data.streams || []).find((stream) => stream.codec_type === 'audio');
  const duration = finite(data.format && data.format.duration, 0);
  const errors = [];
  const warnings = [];
  if (!video) errors.push('No video stream.');
  if (!audio) errors.push('No audio stream.');
  if (video && (video.width !== timeline.output.width || video.height !== timeline.output.height)) {
    errors.push(`Unexpected resolution ${video.width}x${video.height}.`);
  }
  if (video && video.pix_fmt !== 'yuv420p') errors.push(`Unexpected pixel format ${video.pix_fmt}.`);
  if (video && Math.abs(fraction(video.avg_frame_rate) - timeline.output.fps) > 0.01) {
    errors.push(`Unexpected frame rate ${video.avg_frame_rate}.`);
  }
  if (Math.abs(duration - timeline.output.duration) > Math.max(0.15, 2 / timeline.output.fps)) {
    errors.push(`Unexpected duration ${duration.toFixed(3)} seconds.`);
  }
  if (!data.format || finite(data.format.size, 0) <= 0) errors.push('Output file is empty.');

  let integratedLufs = null;
  let truePeakDbfs = null;
  const targetLufs = finite(timeline.output.loudnessLufs, -14);
  const targetPeak = finite(timeline.output.truePeakDb, -1.5);
  const allowSilent = Boolean(timeline.audio && timeline.audio.allowSilent);
  if (checks.loudness) {
    const loudnessRun = run(tools.ffmpeg, [
      '-hide_banner', '-nostats', '-i', file,
      '-vn', '-filter_complex', 'ebur128=peak=true',
      '-f', 'null', '-'
    ], { cwd: projectRoot, capture: true });
    const loudnessText = `${loudnessRun.stdout}\n${loudnessRun.stderr}`;
    integratedLufs = lastNumber(loudnessText, /I:\s+(-?\d+(?:\.\d+)?)\s+LUFS/g);
    truePeakDbfs = lastNumber(loudnessText, /Peak:\s+(-?\d+(?:\.\d+)?)\s+dBFS/g);
    if (integratedLufs === null || truePeakDbfs === null) {
      const message = 'Could not measure final integrated loudness and true peak.';
      if (allowSilent) warnings.push(message);
      else errors.push(message);
    } else {
      const tolerance = validation === 'full' ? 1 : 1.5;
      if (!allowSilent && Math.abs(integratedLufs - targetLufs) > tolerance) {
        errors.push(`Integrated loudness ${integratedLufs} LUFS misses target ${targetLufs} LUFS by more than ${tolerance} LU.`);
      }
    }
    if (truePeakDbfs !== null && truePeakDbfs > targetPeak + 0.6) {
      errors.push(`True peak ${truePeakDbfs} dBFS exceeds target tolerance ${targetPeak + 0.6} dBFS.`);
    }
  }

  let blackEvents = [];
  if (checks.blackFrames) {
    const blackRun = run(tools.ffmpeg, [
      '-hide_banner', '-nostats', '-i', file,
      '-vf', 'blackdetect=d=0.35:pix_th=0.10',
      '-an', '-f', 'null', '-'
    ], { cwd: projectRoot, capture: true });
    blackEvents = [...`${blackRun.stdout}\n${blackRun.stderr}`.matchAll(/black_start:([\d.]+) black_end:([\d.]+) black_duration:([\d.]+)/g)]
      .map((match) => ({ start: Number(match[1]), end: Number(match[2]), duration: Number(match[3]) }));
    if (blackEvents.length) warnings.push(`${blackEvents.length} black-frame interval(s) require visual review.`);
  }

  let silenceEvents = [];
  if (checks.silence) {
    const silenceRun = run(tools.ffmpeg, [
      '-hide_banner', '-nostats', '-i', file,
      '-af', 'silencedetect=noise=-45dB:d=1.5',
      '-vn', '-f', 'null', '-'
    ], { cwd: projectRoot, capture: true });
    silenceEvents = [...`${silenceRun.stdout}\n${silenceRun.stderr}`.matchAll(/silence_start:\s*([\d.]+)|silence_end:\s*([\d.]+)/g)]
      .map((match) => match[1]
        ? { type: 'start', time: Number(match[1]) }
        : { type: 'end', time: Number(match[2]) });
    if (silenceEvents.length && !allowSilent) warnings.push(`${silenceEvents.length} silence boundary event(s) require review.`);
  }

  return {
    ok: errors.length === 0,
    level: validation,
    checks,
    errors,
    warnings,
    duration,
    sizeBytes: data.format ? finite(data.format.size, 0) : 0,
    video: video ? {
      codec: video.codec_name,
      width: video.width,
      height: video.height,
      fps: fraction(video.avg_frame_rate),
      pixelFormat: video.pix_fmt,
      colorSpace: video.color_space || null
    } : null,
    audio: audio ? {
      codec: audio.codec_name,
      sampleRate: finite(audio.sample_rate, null),
      channels: audio.channels,
      integratedLufs,
      truePeakDbfs
    } : null,
    diagnostics: { blackEvents, silenceEvents }
  };
}

function makeProgress(options) {
  if (typeof options.onProgress === 'function') return options.onProgress;
  if (options.quiet) return () => {};
  return (message) => process.stderr.write(`[qiaomu-cut] ${message}\n`);
}

function timedStage(context, name, operation) {
  const started = process.hrtime.bigint();
  try {
    return operation();
  } finally {
    const seconds = Number(process.hrtime.bigint() - started) / 1e9;
    context.timings[name] = Math.round(seconds * 100) / 100;
  }
}

function renderProject(projectDir, options = {}) {
  const started = Date.now();
  const projectRoot = path.resolve(projectDir);
  if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
    throw new Error(`Project directory not found: ${projectRoot}`);
  }
  const timelineRelative = options.timeline || 'timeline.json';
  const timelineFile = projectPath(projectRoot, timelineRelative, 'timeline', { exists: true });
  const sourceTimeline = readJson(timelineFile);
  const renderProfile = applyRenderProfile(sourceTimeline, options);
  const timeline = renderProfile.timeline;
  validateTimeline(timeline, projectRoot, options);
  preflightProjectIO(collectProjectIO(timeline, projectRoot, timelineFile), options);
  const tools = inspectDependencies();
  const buildRoot = projectPath(projectRoot, '.qiaocut', 'internal build root');
  ensureInternalDirectory(projectRoot, buildRoot, 'internal build root');
  const cacheBase = options.cache === false ? null : path.join(buildRoot, 'cache');
  const cacheRoot = cacheBase ? path.join(cacheBase, 'segments') : null;
  const ttsCacheRoot = cacheBase ? path.join(cacheBase, 'tts') : null;
  const pictureCacheRoot = cacheBase ? path.join(cacheBase, 'pictures') : null;
  if (cacheBase) {
    for (const [directory, label] of [
      [cacheRoot, 'segment cache'],
      [ttsCacheRoot, 'narration cache'],
      [pictureCacheRoot, 'picture cache']
    ]) {
      ensureInternalDirectory(projectRoot, directory, label);
    }
  }
  const buildDir = fs.mkdtempSync(path.join(buildRoot, 'render-'));
  const fontCacheRoot = path.join(buildDir, 'fontconfig');
  const fontFilesRoot = cacheBase ? path.join(cacheBase, 'fonts') : path.join(buildDir, 'fonts');
  for (const [directory, label] of [
    [fontCacheRoot, 'Fontconfig runtime cache'],
    [fontFilesRoot, 'caption font cache root']
  ]) {
    ensureInternalDirectory(projectRoot, directory, label);
  }
  const progress = makeProgress(options);
  const cacheStats = {
    enabled: Boolean(cacheBase),
    hits: 0,
    misses: 0,
    segments: { hits: 0, misses: 0 },
    narration: { hits: 0, misses: 0 },
    pictures: { hits: 0, misses: 0 }
  };
  const timings = {};
  const context = {
    timeline,
    projectRoot,
    timelineFile,
    buildDir,
    tools,
    progress,
    cacheRoot,
    ttsCacheRoot,
    pictureCacheRoot,
    fontCacheRoot,
    fontFilesRoot,
    cacheStats,
    timings,
    profile: renderProfile.name,
    validation: renderProfile.validation
  };
  progress(`${tools.version}; profile=${renderProfile.name}; validation=${renderProfile.validation}`);
  try {
    const captions = timedStage(context, 'captions', () => prepareCaptions(context));
    const music = timedStage(context, 'music', () => prepareMusic(context));
    const narration = timedStage(context, 'narration', () => prepareNarration(context));
    const soundEffects = timedStage(context, 'soundEffects', () => prepareSoundEffects(context));
    const segments = timedStage(context, 'shots', () => timeline.shots.map((shot, index) => renderShot(context, shot, index)));
    const assembled = timedStage(context, 'assemble', () => concatSegments(context, segments));
    const picture = timedStage(context, 'picture', () => renderPicture(context, assembled, captions, segments));
    const mix = timedStage(context, 'audioMix', () => mixAudio(context, assembled, narration, music, soundEffects));
    const normalized = timedStage(context, 'normalization', () => loudnorm(context, mix));
    const finalVideo = timedStage(context, 'mux', () => muxFinal(context, picture, normalized.file));
    const sheet = timedStage(context, 'contactSheet', () => contactSheet(context, finalVideo));
    const verification = timedStage(context, 'verification', () => inspectFinal(context, finalVideo));
    const captionFontVerified = !captions ||
      (context.resolvedCaptionFont && context.resolvedCaptionFont.source !== 'system-unverified');
    if (!captionFontVerified) {
      verification.warnings.push('Caption font resolution is system-unverified; configure fontsDir before release.');
    }
    const reportPath = projectPath(
      projectRoot,
      (timeline.reports && timeline.reports.renderReport) || 'reports/render-report.json',
      'reports.renderReport'
    );
    const report = {
      ok: verification.ok,
      schema: timeline.schema,
      title: timeline.title || null,
      profile: renderProfile.name,
      releaseReady: renderProfile.name === 'final' && renderProfile.validation === 'full' &&
        verification.ok && captionFontVerified,
      project: '.',
      timeline: path.relative(projectRoot, timelineFile),
      finalVideo: path.relative(projectRoot, finalVideo),
      contactSheet: sheet ? path.relative(projectRoot, sheet) : null,
      renderReport: path.relative(projectRoot, reportPath),
      durationSeconds: timeline.output.duration,
      resolution: `${timeline.output.width}x${timeline.output.height}`,
      fps: timeline.output.fps,
      shots: timeline.shots.length,
      transitions: timeline.shots.slice(1).map((shot, index) => ({
        from: timeline.shots[index].id,
        to: shot.id,
        ...transitionSpec(shot)
      })).filter((transition) => transition.duration > 0),
      captions: captions ? path.relative(projectRoot, captions) : null,
      captionFont: captions && context.resolvedCaptionFont ? {
        family: context.resolvedCaptionFont.family,
        source: context.resolvedCaptionFont.source
      } : null,
      narration: narration ? {
        engine: narration.engine,
        cues: narration.cues,
        voice: narration.voice,
        provenance: narration.provenance
      } : null,
      music: music ? { mode: music.mode, file: path.relative(projectRoot, music.file), bpm: music.bpm || null, seed: music.seed || null } : null,
      soundEffects: soundEffects ? { count: soundEffects.cues.length, cues: soundEffects.cues } : null,
      audio: { masteringMode: timeline.audio && timeline.audio.masteringMode || 'default' },
      loudness: {
        targetLufs: normalized.targetLufs,
        targetTruePeakDb: normalized.targetTruePeakDb,
        mode: normalized.mode,
        passes: normalized.passes,
        firstPass: normalized.stats
      },
      cache: cacheStats,
      timings,
      ffmpeg: tools.version,
      verification,
      elapsedSeconds: Math.round((Date.now() - started) / 100) / 10,
      buildDir: options.keepBuild ? path.relative(projectRoot, buildDir) : null
    };
    writeJson(reportPath, report);
    if (!verification.ok) {
      throw new Error(`Final video verification failed: ${verification.errors.join(' ')}`);
    }
    if (!options.keepBuild) fs.rmSync(buildDir, { recursive: true, force: true });
    return {
      ...report,
      finalVideo: path.resolve(projectRoot, report.finalVideo),
      contactSheet: report.contactSheet ? path.resolve(projectRoot, report.contactSheet) : null,
      renderReport: reportPath
    };
  } catch (error) {
    error.buildDir = buildDir;
    throw error;
  }
}

function parseArgs(argv) {
  const options = { keepBuild: false, json: false, force: false, allowLarge: false, cache: true };
  const positional = [];
  for (let index = 0; index < argv.length; index += 1) {
    const token = argv[index];
    if (token === '-h') {
      options.help = true;
      continue;
    }
    if (!token.startsWith('--')) {
      positional.push(token);
      continue;
    }
    if (token === '--json') options.json = true;
    else if (token === '--keep-build') options.keepBuild = true;
    else if (token === '--force') options.force = true;
    else if (token === '--allow-large') options.allowLarge = true;
    else if (token === '--no-cache') options.cache = false;
    else if (token === '--help') options.help = true;
    else if (token === '--timeline') {
      const value = argv[index + 1];
      if (!value || value.startsWith('--')) throw new UsageError('--timeline requires a project-relative path.');
      options.timeline = value;
      index += 1;
    } else if (token.startsWith('--timeline=')) {
      options.timeline = token.slice('--timeline='.length);
      if (!options.timeline) throw new UsageError('--timeline requires a project-relative path.');
    } else if (['--profile', '--validation', '--output'].includes(token)) {
      const value = argv[index + 1];
      if (!value || value.startsWith('--')) throw new UsageError(`${token} requires a value.`);
      options[token.slice(2)] = value;
      index += 1;
    } else if (token.startsWith('--profile=')) {
      options.profile = token.slice('--profile='.length);
      if (!options.profile) throw new UsageError('--profile requires a value.');
    } else if (token.startsWith('--validation=')) {
      options.validation = token.slice('--validation='.length);
      if (!options.validation) throw new UsageError('--validation requires a value.');
    } else if (token.startsWith('--output=')) {
      options.output = token.slice('--output='.length);
      if (!options.output) throw new UsageError('--output requires a project-relative path.');
    } else {
      throw new UsageError(`Unknown option: ${token}`);
    }
  }
  if (positional.length > 1) throw new UsageError('Only one project directory may be supplied.');
  return { projectDir: positional[0], options };
}

function usage() {
  return `Usage: render_project.js <project-dir> [--profile preview|standard|final] [--validation basic|standard|full]
       [--timeline timeline.json] [--output renders/file.mp4] [--no-cache]
       [--json] [--keep-build] [--force] [--allow-large]

Renders a qiaocut.timeline.v1 project with ffmpeg-full. All media and output paths
inside the timeline must be relative to <project-dir>. Existing generated outputs
are preserved unless --force is supplied. The default profile remains final for
backward compatibility; preview and standard use separate suffixed outputs.
`;
}

function cli(argv = process.argv.slice(2)) {
  let parsed;
  try {
    parsed = parseArgs(argv);
    if (parsed.options.help) {
      process.stdout.write(usage());
      return 0;
    }
    if (!parsed.projectDir) throw new UsageError('A project directory is required.');
    const report = renderProject(parsed.projectDir, parsed.options);
    const printable = {
      ...report,
      finalVideo: displayPath(report.finalVideo),
      contactSheet: displayPath(report.contactSheet),
      renderReport: displayPath(report.renderReport),
      buildDir: displayPath(report.buildDir)
    };
    if (parsed.options.json) process.stdout.write(`${JSON.stringify(printable, null, 2)}\n`);
    else process.stdout.write(`Rendered: ${printable.finalVideo}\nReport: ${printable.renderReport}\n`);
    return 0;
  } catch (error) {
    const isUsage = error instanceof UsageError;
    const json = parsed && parsed.options && parsed.options.json;
    if (json) {
      process.stdout.write(`${JSON.stringify({
        ok: false,
        error: displayText(error.message),
        buildDir: displayPath(error.buildDir || null)
      }, null, 2)}\n`);
    } else {
      process.stderr.write(`${displayText(error.message)}\n`);
      if (isUsage) process.stderr.write(usage());
      if (error.buildDir) process.stderr.write(`Intermediate files retained at: ${displayPath(error.buildDir)}\n`);
    }
    return isUsage ? 2 : 1;
  }
}

module.exports = {
  applyRenderProfile,
  ensureInternalDirectory,
  UsageError,
  inspectDependencies,
  parseArgs,
  preflightProjectIO,
  prepareSoundEffects,
  projectPath,
  renderProject,
  verifiedFileNarrationProvenance,
  validateTimeline
};

if (require.main === module) process.exitCode = cli();
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall