@yoonion/mimi-seed-mcp 0.11.0 → 0.12.0

package/dist/video/providers.js

@@ -0,0 +1,321 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, createWriteStream, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { once } from 'node:events';
+import path from 'node:path';
+import { writeJsonAtomic } from './files.js';
+import { loadProject, registerAsset } from './project.js';
+function requireEnv(name) {
+    const value = process.env[name]?.trim();
+    if (!value)
+        throw new Error(`❌ ${name} 환경변수가 필요합니다.`);
+    return value;
+}
+async function fetchJson(url, init) {
+    const response = await fetch(url, init);
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    if (!response.ok) {
+        const message = typeof body === 'object' && body !== null && 'error' in body
+            ? JSON.stringify(body.error)
+            : String(body).slice(0, 500);
+        throw new Error(`외부 API 요청 실패 (${response.status}): ${message}`);
+    }
+    return body;
+}
+function sanitizeExternalText(value, maxLength) {
+    return (value ?? '').replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '').slice(0, maxLength);
+}
+export async function researchYouTube(input) {
+    const project = loadProject(input.projectDir);
+    const key = requireEnv('YOUTUBE_API_KEY');
+    const queries = (input.queries?.length ? input.queries : project.scenes.map((scene) => scene.searchQuery))
+        .filter(Boolean)
+        .slice(0, 5);
+    if (queries.length === 0)
+        throw new Error('검색어가 없습니다. queries를 전달하거나 프로젝트 장면에 searchQuery를 추가하세요.');
+    const references = [];
+    for (const query of queries) {
+        const params = new URLSearchParams({
+            key,
+            part: 'snippet',
+            type: 'video',
+            q: query,
+            maxResults: String(Math.min(Math.max(input.maxResultsPerQuery ?? 5, 1), 10)),
+            order: input.order ?? 'relevance',
+            videoDuration: 'short',
+            safeSearch: 'moderate',
+        });
+        if (input.regionCode)
+            params.set('regionCode', input.regionCode);
+        if (input.publishedAfter)
+            params.set('publishedAfter', input.publishedAfter);
+        if (input.creativeCommonsOnly)
+            params.set('videoLicense', 'creativeCommon');
+        const search = await fetchJson(`https://www.googleapis.com/youtube/v3/search?${params}`);
+        const ids = (search.items ?? []).map((item) => item.id?.videoId).filter((id) => !!id);
+        if (ids.length === 0)
+            continue;
+        const detailParams = new URLSearchParams({
+            key,
+            part: 'contentDetails,statistics,status',
+            id: ids.join(','),
+        });
+        const details = await fetchJson(`https://www.googleapis.com/youtube/v3/videos?${detailParams}`);
+        const detailById = new Map((details.items ?? []).map((item) => [item.id, item]));
+        for (const item of search.items ?? []) {
+            const videoId = item.id?.videoId;
+            if (!videoId)
+                continue;
+            const detail = detailById.get(videoId);
+            references.push({
+                videoId,
+                title: sanitizeExternalText(item.snippet?.title, 300),
+                description: sanitizeExternalText(item.snippet?.description, 1_000),
+                channelTitle: sanitizeExternalText(item.snippet?.channelTitle, 200),
+                publishedAt: item.snippet?.publishedAt ?? '',
+                thumbnailUrl: item.snippet?.thumbnails?.high?.url ?? item.snippet?.thumbnails?.medium?.url,
+                url: `https://www.youtube.com/watch?v=${videoId}`,
+                duration: detail?.contentDetails?.duration,
+                viewCount: detail?.statistics?.viewCount,
+                likeCount: detail?.statistics?.likeCount,
+                license: detail?.status?.license,
+                sourceType: 'reference-only',
+                allowedForRendering: false,
+                untrustedExternalText: true,
+                query,
+            });
+        }
+    }
+    const outputPath = path.join(path.resolve(input.projectDir), 'research', 'youtube.json');
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    writeJsonAtomic(outputPath, { generatedAt: new Date().toISOString(), references });
+    return references;
+}
+function bestPexelsFile(files = []) {
+    const mp4s = files.filter((file) => file.link && file.file_type === 'video/mp4');
+    return mp4s.sort((a, b) => ((b.width ?? 0) * (b.height ?? 0)) - ((a.width ?? 0) * (a.height ?? 0)))[0];
+}
+export async function searchStock(input) {
+    const project = loadProject(input.projectDir);
+    const key = requireEnv('PEXELS_API_KEY');
+    const queries = (input.queries?.length ? input.queries : project.scenes.map((scene) => scene.searchQuery))
+        .filter(Boolean)
+        .slice(0, 10);
+    if (queries.length === 0)
+        throw new Error('검색어가 없습니다.');
+    const results = [];
+    for (const query of queries) {
+        const params = new URLSearchParams({
+            query,
+            per_page: String(Math.min(Math.max(input.perQuery ?? 5, 1), 15)),
+        });
+        if (input.orientation)
+            params.set('orientation', input.orientation);
+        const data = await fetchJson(`https://api.pexels.com/v1/videos/search?${params}`, {
+            headers: { Authorization: key },
+        });
+        for (const video of data.videos ?? []) {
+            const selected = bestPexelsFile(video.video_files);
+            results.push({
+                id: video.id,
+                width: video.width,
+                height: video.height,
+                duration: video.duration,
+                pageUrl: video.url,
+                author: sanitizeExternalText(video.user?.name, 200),
+                authorUrl: video.user?.url,
+                previewImage: video.image,
+                downloadUrl: selected?.link,
+                downloadWidth: selected?.width,
+                downloadHeight: selected?.height,
+                license: 'Pexels License',
+                attribution: `Video by ${video.user?.name ?? 'Pexels creator'} on Pexels`,
+                query,
+            });
+        }
+    }
+    const outputPath = path.join(path.resolve(input.projectDir), 'research', 'pexels.json');
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    writeJsonAtomic(outputPath, { generatedAt: new Date().toISOString(), results });
+    return results;
+}
+const PEXELS_MEDIA_HOSTS = new Set([
+    'videos.pexels.com',
+    'images.pexels.com',
+    'static-videos.pexels.com',
+]);
+function validatePexelsUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || !PEXELS_MEDIA_HOSTS.has(url.hostname)) {
+        throw new Error(`허용되지 않은 Pexels 미디어 URL입니다: ${url.hostname}`);
+    }
+    return url;
+}
+async function fetchPexelsMedia(value) {
+    let current = validatePexelsUrl(value);
+    for (let redirects = 0; redirects <= 3; redirects += 1) {
+        const response = await fetch(current, { redirect: 'manual' });
+        if (![301, 302, 303, 307, 308].includes(response.status))
+            return response;
+        const location = response.headers.get('location');
+        if (!location)
+            throw new Error('Pexels 리디렉션 응답에 Location 헤더가 없습니다.');
+        await response.body?.cancel();
+        current = validatePexelsUrl(new URL(location, current).toString());
+    }
+    throw new Error('Pexels 자산 리디렉션이 3회를 초과했습니다.');
+}
+async function downloadLimited(response, destination, maxBytes) {
+    if (!response.body)
+        throw new Error('다운로드 응답에 본문이 없습니다.');
+    const tempPath = `${destination}.${randomUUID()}.tmp`;
+    const writer = createWriteStream(tempPath, { flags: 'wx' });
+    const reader = response.body.getReader();
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                throw new Error(`자산이 ${Math.round(maxBytes / 1024 / 1024)}MB 제한을 초과합니다.`);
+            }
+            if (!writer.write(Buffer.from(value)))
+                await once(writer, 'drain');
+        }
+        writer.end();
+        await once(writer, 'finish');
+        renameSync(tempPath, destination);
+    }
+    catch (error) {
+        writer.destroy();
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // The partial file may already be gone.
+        }
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function hasMp4Signature(filePath) {
+    const fd = openSync(filePath, 'r');
+    const header = Buffer.alloc(12);
+    try {
+        const read = readSync(fd, header, 0, header.length, 0);
+        return read >= 12 && header.subarray(4, 8).toString('ascii') === 'ftyp';
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export async function downloadStockAssets(projectDir, selections) {
+    loadProject(projectDir);
+    if (selections.length === 0 || selections.length > 5)
+        throw new Error('한 번에 1~5개 자산을 선택하세요.');
+    const assets = [];
+    for (const selection of selections) {
+        const url = validatePexelsUrl(selection.downloadUrl);
+        const response = await fetchPexelsMedia(url.toString());
+        if (!response.ok)
+            throw new Error(`Pexels 자산 다운로드 실패 (${response.status}): ${selection.id}`);
+        const contentType = response.headers.get('content-type')?.split(';')[0].trim().toLowerCase();
+        if (contentType !== 'video/mp4' && contentType !== 'application/octet-stream') {
+            throw new Error(`Pexels 자산이 MP4 응답이 아닙니다: ${contentType ?? 'unknown'}`);
+        }
+        const length = Number(response.headers.get('content-length') ?? 0);
+        if (length > 100 * 1024 * 1024)
+            throw new Error(`자산이 100MB 제한을 초과합니다: ${selection.id}`);
+        const id = `pexels-${selection.id}-${randomUUID().slice(0, 8)}`;
+        const destination = path.join(path.resolve(projectDir), 'assets', 'stock', `${id}.mp4`);
+        mkdirSync(path.dirname(destination), { recursive: true });
+        await downloadLimited(response, destination, 100 * 1024 * 1024);
+        if (!hasMp4Signature(destination)) {
+            unlinkSync(destination);
+            throw new Error(`Pexels 자산이 유효한 MP4 시그니처를 갖지 않습니다: ${selection.id}`);
+        }
+        assets.push(registerAsset(projectDir, {
+            id,
+            kind: 'video',
+            sourceType: 'stock',
+            path: destination,
+            sourceUrl: selection.pageUrl,
+            license: 'Pexels License',
+            author: selection.author,
+            attribution: selection.attribution ?? `Video by ${selection.author ?? 'Pexels creator'} on Pexels`,
+            allowedForRendering: true,
+            provider: 'pexels',
+        }));
+    }
+    return assets;
+}
+export async function generateImage(input) {
+    const project = loadProject(input.projectDir);
+    const key = requireEnv('OPENAI_API_KEY');
+    const size = input.size ?? (project.settings.aspectRatio === '9:16'
+        ? '1024x1536'
+        : project.settings.aspectRatio === '16:9' ? '1536x1024' : '1024x1024');
+    const data = await fetchJson('https://api.openai.com/v1/images/generations', {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            model: input.model ?? 'gpt-image-2',
+            prompt: input.prompt,
+            n: 1,
+            size,
+            quality: input.quality ?? 'medium',
+            output_format: 'png',
+        }),
+    });
+    const base64 = data.data?.[0]?.b64_json;
+    if (!base64)
+        throw new Error('이미지 생성 응답에 이미지 데이터가 없습니다.');
+    const bytes = Buffer.from(base64, 'base64');
+    const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    if (bytes.length === 0 || bytes.length > 50 * 1024 * 1024 || !bytes.subarray(0, 8).equals(pngSignature)) {
+        throw new Error('이미지 생성 응답이 유효한 50MB 이하 PNG가 아닙니다.');
+    }
+    const id = `openai-${randomUUID()}`;
+    const safeName = (input.name ?? id).replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || id;
+    const destination = path.join(path.resolve(input.projectDir), 'assets', 'generated', `${safeName}-${id.slice(-8)}.png`);
+    mkdirSync(path.dirname(destination), { recursive: true });
+    const tempPath = `${destination}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tempPath, bytes, { flag: 'wx' });
+        renameSync(tempPath, destination);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // The temp file may not have been created.
+        }
+        throw error;
+    }
+    return registerAsset(input.projectDir, {
+        id,
+        kind: 'image',
+        sourceType: 'generated',
+        path: destination,
+        license: 'OpenAI generated output; use subject to OpenAI terms and applicable law',
+        allowedForRendering: true,
+        provider: input.model ?? 'gpt-image-2',
+        prompt: input.prompt,
+    });
+}
+export const __testing = { bestPexelsFile, validatePexelsUrl, hasMp4Signature, sanitizeExternalText };

package/dist/video/render.d.ts

@@ -0,0 +1,39 @@
+import type { VideoRenderJob, VideoTimeline } from './types.js';
+declare function processAlive(pid: number | undefined): boolean;
+declare function readTail(filePath: string, maxBytes?: number): string;
+declare function sanitizeSubtitleText(value: string): string;
+declare function srtTime(seconds: number): string;
+export declare function formatSrt(timeline: VideoTimeline): string;
+export interface FfmpegPlan {
+    args: string[];
+    outputPath: string;
+    subtitlePath?: string;
+}
+export declare function buildFfmpegPlan(projectDir: string, outputPath: string, jobId: string): FfmpegPlan;
+export interface StartRenderInput {
+    projectDir: string;
+    outputFileName?: string;
+    ffmpegPath?: string;
+    overwriteOutput?: boolean;
+}
+declare function acquireOutputLock(lockPath: string, projectDir: string, jobId: string): void;
+export declare function startRender(input: StartRenderInput): Promise<VideoRenderJob>;
+export declare function getRenderJob(projectDir: string, jobId: string): VideoRenderJob & {
+    logTail?: string;
+};
+declare function ffprobeFor(ffmpegPath?: string): string;
+export declare function validateVideo(filePath: string, ffmpegPath?: string): Promise<{
+    valid: boolean;
+    format: unknown;
+    streams: unknown[];
+    issues: string[];
+}>;
+export declare const __testing: {
+    srtTime: typeof srtTime;
+    ffprobeFor: typeof ffprobeFor;
+    sanitizeSubtitleText: typeof sanitizeSubtitleText;
+    processAlive: typeof processAlive;
+    acquireOutputLock: typeof acquireOutputLock;
+    readTail: typeof readTail;
+};
+export {};

package/dist/video/render.js

@@ -0,0 +1,320 @@
+import { spawn, execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { closeSync, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { readJson, writeJsonAtomic } from './files.js';
+import { loadAssets, loadProject, loadTimeline } from './project.js';
+import { parseFile, renderJobSchema } from './schemas.js';
+const execFileAsync = promisify(execFile);
+function jobPath(projectDir, jobId) {
+    return path.join(path.resolve(projectDir), '.jobs', `${jobId}.json`);
+}
+function updateJob(projectDir, jobId, patch) {
+    const filePath = jobPath(projectDir, jobId);
+    const current = parseFile(renderJobSchema, readJson(filePath), filePath);
+    const next = { ...current, ...patch, updatedAt: new Date().toISOString() };
+    writeJsonAtomic(filePath, next);
+    return next;
+}
+function processAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function readTail(filePath, maxBytes = 64 * 1024) {
+    const size = statSync(filePath).size;
+    const length = Math.min(size, maxBytes);
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(filePath, 'r');
+    try {
+        readSync(fd, buffer, 0, length, Math.max(0, size - length));
+    }
+    finally {
+        closeSync(fd);
+    }
+    return buffer.toString('utf8');
+}
+function sanitizeSubtitleText(value) {
+    return value
+        .replace(/\r/g, '')
+        .replace(/\n{2,}/g, '\n')
+        .replace(/-->/g, '→')
+        .replace(/</g, '＜')
+        .replace(/>/g, '＞')
+        .replace(/{/g, '｛')
+        .replace(/}/g, '｝')
+        .trim();
+}
+function srtTime(seconds) {
+    const ms = Math.max(0, Math.round(seconds * 1000));
+    const hours = Math.floor(ms / 3_600_000);
+    const minutes = Math.floor((ms % 3_600_000) / 60_000);
+    const secs = Math.floor((ms % 60_000) / 1000);
+    const millis = ms % 1000;
+    return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(secs).padStart(2, '0')},${String(millis).padStart(3, '0')}`;
+}
+export function formatSrt(timeline) {
+    let cursor = 0;
+    const blocks = [];
+    for (const scene of timeline.scenes) {
+        const text = sanitizeSubtitleText(scene.onScreenText ?? '');
+        const start = cursor;
+        cursor += scene.durationSec;
+        if (!text)
+            continue;
+        blocks.push(`${blocks.length + 1}\n${srtTime(start)} --> ${srtTime(cursor)}\n${text}\n`);
+    }
+    return blocks.join('\n');
+}
+function isImage(asset) {
+    return asset.kind === 'image';
+}
+export function buildFfmpegPlan(projectDir, outputPath, jobId) {
+    const dir = path.resolve(projectDir);
+    const project = loadProject(dir);
+    const timeline = loadTimeline(dir);
+    const manifest = loadAssets(dir);
+    const byId = new Map(manifest.assets.map((asset) => [asset.id, asset]));
+    const assets = timeline.scenes.map((scene) => {
+        const asset = byId.get(scene.assetId);
+        if (!asset || !asset.allowedForRendering || !existsSync(asset.path)) {
+            throw new Error(`렌더링할 수 없는 장면 자산입니다: ${scene.assetId}`);
+        }
+        return asset;
+    });
+    const args = ['-nostdin', '-y'];
+    timeline.scenes.forEach((scene, index) => {
+        const asset = assets[index];
+        if (isImage(asset))
+            args.push('-loop', '1');
+        else
+            args.push('-stream_loop', '-1');
+        args.push('-t', String(scene.durationSec), '-i', asset.path);
+    });
+    let audioIndex;
+    if (timeline.audioAssetId) {
+        const audio = byId.get(timeline.audioAssetId);
+        if (!audio || audio.kind !== 'audio' || !audio.allowedForRendering || !existsSync(audio.path)) {
+            throw new Error(`렌더링할 수 없는 오디오 자산입니다: ${timeline.audioAssetId}`);
+        }
+        audioIndex = assets.length;
+        args.push('-stream_loop', '-1', '-i', audio.path);
+    }
+    const filters = timeline.scenes.map((scene, index) => (`[${index}:v]scale=${project.settings.width}:${project.settings.height}:force_original_aspect_ratio=increase,` +
+        `crop=${project.settings.width}:${project.settings.height},fps=${project.settings.fps},` +
+        `trim=duration=${scene.durationSec},setpts=PTS-STARTPTS,format=yuv420p[v${index}]`));
+    filters.push(`${timeline.scenes.map((_, index) => `[v${index}]`).join('')}concat=n=${timeline.scenes.length}:v=1:a=0[base]`);
+    const srt = formatSrt(timeline);
+    let videoLabel = '[base]';
+    let subtitlePath;
+    if (srt) {
+        const relativeSubtitlePath = `render/captions-${jobId}.srt`;
+        subtitlePath = path.join(dir, relativeSubtitlePath);
+        writeFileSync(subtitlePath, srt, 'utf8');
+        filters.push(`[base]subtitles=${relativeSubtitlePath}:force_style='FontName=Arial,FontSize=18,PrimaryColour=&H00FFFFFF,OutlineColour=&H80000000,BorderStyle=3,Outline=1,Shadow=0,Alignment=2,MarginV=48'[vout]`);
+        videoLabel = '[vout]';
+    }
+    args.push('-filter_complex', filters.join(';'), '-map', videoLabel);
+    if (audioIndex !== undefined) {
+        args.push('-map', `${audioIndex}:a:0`, '-c:a', 'aac', '-b:a', '192k', '-shortest');
+    }
+    args.push('-t', String(timeline.totalDurationSec), '-c:v', 'libx264', '-preset', 'medium', '-crf', '20', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', outputPath);
+    return { args, outputPath, subtitlePath };
+}
+async function verifyExecutable(command) {
+    try {
+        await execFileAsync(command, ['-version'], { timeout: 10_000, windowsHide: true });
+    }
+    catch (error) {
+        throw new Error(`FFmpeg를 실행할 수 없습니다: ${command}\nFFmpeg를 설치하거나 ffmpegPath를 지정하세요.`, { cause: error });
+    }
+}
+function acquireOutputLock(lockPath, projectDir, jobId) {
+    const tryCreate = () => {
+        const fd = openSync(lockPath, 'wx');
+        try {
+            writeFileSync(fd, jobId, 'utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    try {
+        tryCreate();
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    let active = false;
+    try {
+        const existingId = readFileSync(lockPath, 'utf8').trim();
+        const existingPath = jobPath(projectDir, existingId);
+        if (existsSync(existingPath)) {
+            const existing = parseFile(renderJobSchema, readJson(existingPath), existingPath);
+            const queuedRecently = existing.status === 'queued' && Date.now() - Date.parse(existing.updatedAt) < 60_000;
+            active = queuedRecently || (existing.status === 'running' && processAlive(existing.pid));
+        }
+    }
+    catch {
+        active = false;
+    }
+    if (active)
+        throw new Error(`같은 출력 파일의 렌더 작업이 이미 실행 중입니다: ${lockPath}`);
+    unlinkSync(lockPath);
+    tryCreate();
+}
+export async function startRender(input) {
+    const projectDir = path.resolve(input.projectDir);
+    loadProject(projectDir);
+    loadTimeline(projectDir);
+    const ffmpeg = input.ffmpegPath ?? process.env.MIMI_SEED_FFMPEG_PATH ?? 'ffmpeg';
+    await verifyExecutable(ffmpeg);
+    const safeOutputName = (input.outputFileName ?? 'output.mp4')
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'output.mp4';
+    const finalName = safeOutputName.toLowerCase().endsWith('.mp4') ? safeOutputName : `${safeOutputName}.mp4`;
+    const outputPath = path.join(projectDir, 'render', finalName);
+    if (existsSync(outputPath) && !input.overwriteOutput) {
+        throw new Error(`출력 파일이 이미 존재합니다: ${outputPath}\noverwriteOutput=true로 명시해야 덮어씁니다.`);
+    }
+    const id = randomUUID();
+    const logPath = path.join(projectDir, '.jobs', `${id}.log`);
+    const lockPath = `${outputPath}.render.lock`;
+    mkdirSync(path.dirname(logPath), { recursive: true });
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    const plan = buildFfmpegPlan(projectDir, outputPath, id);
+    const now = new Date().toISOString();
+    const job = {
+        id,
+        status: 'queued',
+        createdAt: now,
+        updatedAt: now,
+        projectDir,
+        outputPath,
+        logPath,
+    };
+    writeJsonAtomic(jobPath(projectDir, id), job);
+    try {
+        acquireOutputLock(lockPath, projectDir, id);
+    }
+    catch (error) {
+        updateJob(projectDir, id, { status: 'failed', error: error.message });
+        throw error;
+    }
+    const logStream = createWriteStream(logPath, { flags: 'a' });
+    let child;
+    try {
+        child = spawn(ffmpeg, plan.args, {
+            cwd: projectDir,
+            windowsHide: true,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+    }
+    catch (error) {
+        logStream.end();
+        unlinkSync(lockPath);
+        updateJob(projectDir, id, { status: 'failed', error: error.message });
+        throw error;
+    }
+    child.stderr?.pipe(logStream);
+    updateJob(projectDir, id, { status: 'running', pid: child.pid });
+    let settled = false;
+    const finalize = (patch) => {
+        if (settled)
+            return;
+        settled = true;
+        logStream.end();
+        try {
+            if (existsSync(lockPath))
+                unlinkSync(lockPath);
+        }
+        finally {
+            updateJob(projectDir, id, patch);
+        }
+    };
+    child.on('error', (error) => {
+        finalize({ status: 'failed', error: error.message });
+    });
+    child.on('close', (code) => {
+        finalize({
+            status: code === 0 ? 'completed' : 'failed',
+            exitCode: code,
+            error: code === 0 ? undefined : `FFmpeg가 종료 코드 ${code}로 실패했습니다.`,
+        });
+    });
+    return JSON.parse(readFileSync(jobPath(projectDir, id), 'utf8'));
+}
+export function getRenderJob(projectDir, jobId) {
+    const filePath = jobPath(projectDir, jobId);
+    if (!existsSync(filePath))
+        throw new Error(`렌더 작업을 찾을 수 없습니다: ${jobId}`);
+    let job = parseFile(renderJobSchema, readJson(filePath), filePath);
+    const queuedStale = job.status === 'queued' && Date.now() - Date.parse(job.updatedAt) >= 60_000;
+    const runningDead = job.status === 'running' &&
+        Date.now() - Date.parse(job.updatedAt) >= 5_000 &&
+        !processAlive(job.pid);
+    if (queuedStale || runningDead) {
+        job = updateJob(projectDir, jobId, {
+            status: 'failed',
+            error: queuedStale
+                ? '렌더 작업이 시작 대기 상태에서 중단되었습니다. 다시 렌더하세요.'
+                : '렌더 프로세스가 더 이상 실행 중이지 않습니다. 호스트 또는 MCP가 중단되었을 수 있습니다.',
+        });
+        const lockPath = `${job.outputPath}.render.lock`;
+        try {
+            if (existsSync(lockPath) && readFileSync(lockPath, 'utf8').trim() === jobId)
+                unlinkSync(lockPath);
+        }
+        catch {
+            // A concurrent render may have already replaced or removed the stale lock.
+        }
+    }
+    let logTail;
+    if (job.status === 'failed' && existsSync(job.logPath)) {
+        logTail = readTail(job.logPath).split(/\r?\n/).slice(-30).join('\n');
+    }
+    return { ...job, logTail };
+}
+function ffprobeFor(ffmpegPath) {
+    const configured = process.env.MIMI_SEED_FFPROBE_PATH;
+    if (configured)
+        return configured;
+    if (ffmpegPath && path.isAbsolute(ffmpegPath)) {
+        const ext = path.extname(ffmpegPath);
+        return path.join(path.dirname(ffmpegPath), `ffprobe${ext}`);
+    }
+    return 'ffprobe';
+}
+export async function validateVideo(filePath, ffmpegPath) {
+    if (!path.isAbsolute(filePath) || !existsSync(filePath)) {
+        throw new Error('filePath는 존재하는 절대경로여야 합니다.');
+    }
+    const ffprobe = ffprobeFor(ffmpegPath);
+    const { stdout } = await execFileAsync(ffprobe, [
+        '-v', 'error',
+        '-show_entries', 'format=duration,size,bit_rate,format_name:stream=index,codec_name,codec_type,width,height,r_frame_rate,pix_fmt',
+        '-of', 'json',
+        filePath,
+    ], { timeout: 30_000, windowsHide: true, maxBuffer: 2 * 1024 * 1024 });
+    const data = JSON.parse(stdout);
+    const streams = data.streams ?? [];
+    const video = streams.find((stream) => stream.codec_type === 'video');
+    const issues = [];
+    if (!video)
+        issues.push('비디오 스트림이 없습니다.');
+    if (video && video.codec_name !== 'h264')
+        issues.push(`권장 코덱 H.264가 아닙니다: ${String(video.codec_name)}`);
+    if (video && video.pix_fmt !== 'yuv420p')
+        issues.push(`권장 픽셀 포맷 yuv420p가 아닙니다: ${String(video.pix_fmt)}`);
+    return { valid: issues.length === 0, format: data.format ?? {}, streams, issues };
+}
+export const __testing = { srtTime, ffprobeFor, sanitizeSubtitleText, processAlive, acquireOutputLock, readTail };