@hadialmarzooq/agent-media-ffmpeg 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hadi Almarzooq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { MediaMetadata, FfmpegCapabilities, MediaPlan, VerificationReport } from '@hadialmarzooq/agent-media-core';
+
+interface FfmpegOptions {
+    ffmpegPath?: string;
+    ffprobePath?: string;
+    timeoutMs?: number;
+}
+declare function inspectMedia(input: string, options?: FfmpegOptions): Promise<MediaMetadata>;
+
+declare function getCapabilities(options?: FfmpegOptions): Promise<FfmpegCapabilities>;
+
+interface CompiledOperation {
+    executable: string;
+    args: string[];
+}
+/** Compile semantic Media IR into a deterministic FFmpeg invocation. */
+declare function compilePlan(plan: MediaPlan, source: MediaMetadata, output: string): CompiledOperation;
+declare function extensionForPlan(plan: MediaPlan): string;
+
+type MediaProgressPhase = 'inspecting' | 'planning' | 'executing' | 'verifying' | 'completed';
+/** A monotonic progress event safe to surface through SDK, CLI, and MCP adapters. */
+interface MediaProgress {
+    phase: MediaProgressPhase;
+    percent: number;
+    message: string;
+    processedSeconds?: number;
+    totalSeconds?: number;
+    speed?: number;
+}
+type ProgressCallback = (progress: MediaProgress) => void;
+
+interface ExecuteOptions extends FfmpegOptions {
+    output: string;
+    sourceMetadata?: MediaMetadata;
+    overwrite?: boolean;
+    allowedOutputDirectory?: string;
+    signal?: AbortSignal;
+    onProgress?: ProgressCallback;
+}
+interface ExecutionResult {
+    output: string;
+    operation: CompiledOperation;
+}
+declare function executePlan(planInput: MediaPlan, options: ExecuteOptions): Promise<ExecutionResult>;
+
+interface WorkflowOptions extends FfmpegOptions {
+    input: string;
+    output: string;
+    overwrite?: boolean;
+    allowedOutputDirectory?: string;
+    signal?: AbortSignal;
+    onProgress?: ProgressCallback;
+}
+interface MakeVerticalOptions extends WorkflowOptions {
+    width?: number;
+    height?: number;
+    trimStartSeconds?: number;
+    durationSeconds?: number;
+    maxSizeMB?: number;
+    audio?: 'preserve' | 'remove';
+}
+interface OptimizeForWebOptions extends WorkflowOptions {
+    trimStartSeconds?: number;
+    durationSeconds?: number;
+    maxSizeMB?: number;
+    audio?: 'preserve' | 'remove';
+    quality?: 'high' | 'balanced' | 'small';
+}
+interface NormalizeOptions extends WorkflowOptions {
+    trimStartSeconds?: number;
+    durationSeconds?: number;
+    audio?: 'preserve' | 'remove';
+}
+interface ExtractAudioOptions extends WorkflowOptions {
+    format?: 'm4a' | 'mp3' | 'wav';
+    trimStartSeconds?: number;
+    durationSeconds?: number;
+}
+interface ExtractFrameOptions extends WorkflowOptions {
+    atSeconds?: number;
+    format?: 'jpg' | 'png';
+}
+interface WorkflowResult {
+    source: MediaMetadata;
+    plan: MediaPlan;
+    serializedPlan: string;
+    output: MediaMetadata;
+    verification: VerificationReport;
+}
+/**
+ * Inspect, plan, execute, and verify a high-compatibility 9:16 video in one semantic workflow.
+ * The returned Media IR remains portable and replayable; this convenience API does not bypass it.
+ */
+declare function makeVertical(options: MakeVerticalOptions): Promise<WorkflowResult>;
+/**
+ * Inspect, plan, execute, and verify a web-optimized video: balanced quality,
+ * H.264/yuv420p, faststart, and an optional maximum file size.
+ */
+declare function optimizeForWeb(options: OptimizeForWebOptions): Promise<WorkflowResult>;
+/**
+ * Inspect, plan, execute, and verify a normalized high-compatibility copy without
+ * changing dimensions or aspect ratio. Ensures H.264, yuv420p, and faststart.
+ */
+declare function normalize(options: NormalizeOptions): Promise<WorkflowResult>;
+/**
+ * Inspect, plan, execute, and verify audio extraction from any media source.
+ */
+declare function extractAudio(options: ExtractAudioOptions): Promise<WorkflowResult>;
+/**
+ * Inspect, plan, execute, and verify a still frame extraction from a video source.
+ */
+declare function extractFrame(options: ExtractFrameOptions): Promise<WorkflowResult>;
+
+export { type CompiledOperation, type ExecuteOptions, type ExecutionResult, type ExtractAudioOptions, type ExtractFrameOptions, type FfmpegOptions, type MakeVerticalOptions, type MediaProgress, type MediaProgressPhase, type NormalizeOptions, type OptimizeForWebOptions, type ProgressCallback, type WorkflowOptions, type WorkflowResult, compilePlan, executePlan, extensionForPlan, extractAudio, extractFrame, getCapabilities, inspectMedia, makeVertical, normalize, optimizeForWeb };

package/dist/index.js

@@ -0,0 +1,774 @@
+// src/capabilities.ts
+import { MediaError } from "@hadialmarzooq/agent-media-core";
+
+// src/process.ts
+import { spawn } from "child_process";
+async function runProcess(executable, args, options = 3e4) {
+  return new Promise((resolve3, reject) => {
+    const { timeoutMs, signal, onStdout } = typeof options === "number" ? { timeoutMs: options, onStdout: void 0 } : options;
+    if (signal?.aborted) {
+      resolve3({ stdout: "", stderr: "", exitCode: -1, timedOut: false, aborted: true });
+      return;
+    }
+    const child = spawn(executable, [...args], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let aborted = false;
+    const stopForAbort = () => {
+      aborted = true;
+      child.kill("SIGTERM");
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs ?? 3e4);
+    signal?.addEventListener("abort", stopForAbort, { once: true });
+    child.stdout.setEncoding("utf8").on("data", (chunk) => {
+      stdout += chunk;
+      onStdout?.(chunk);
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", stopForAbort);
+      reject(error);
+    });
+    child.once("close", (exitCode) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", stopForAbort);
+      resolve3({ stdout, stderr, exitCode: exitCode ?? -1, timedOut, aborted });
+    });
+  });
+}
+
+// src/capabilities.ts
+async function getCapabilities(options = {}) {
+  try {
+    const [version, encoders, filters, hardware] = await Promise.all([
+      runProcess(options.ffmpegPath ?? "ffmpeg", ["-version"], options.timeoutMs),
+      runProcess(options.ffmpegPath ?? "ffmpeg", ["-hide_banner", "-encoders"], options.timeoutMs),
+      runProcess(options.ffmpegPath ?? "ffmpeg", ["-hide_banner", "-filters"], options.timeoutMs),
+      runProcess(options.ffmpegPath ?? "ffmpeg", ["-hide_banner", "-hwaccels"], options.timeoutMs)
+    ]);
+    if ([version, encoders, filters, hardware].some((result) => result.exitCode !== 0)) {
+      throw new Error("FFmpeg returned a non-zero exit code.");
+    }
+    const versionLine = version.stdout.split("\n")[0] ?? "";
+    const match = /ffmpeg version\s+([^\s]+)/i.exec(versionLine);
+    return {
+      ffmpegVersion: match?.[1] ?? "unknown",
+      encoders: {
+        // The current compiler emits libx264, so advertise only the implementation it can use.
+        h264: hasCapability(encoders.stdout, /\blibx264\b/),
+        hevc: hasCapability(encoders.stdout, /\b(?:libx265|hevc_videotoolbox|hevc_nvenc)\b/),
+        av1: hasCapability(encoders.stdout, /\b(?:libaom-av1|libsvtav1|av1_nvenc)\b/),
+        aac: hasCapability(encoders.stdout, /\baac\b/)
+      },
+      hardwareAcceleration: hardware.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("Hardware acceleration")),
+      filters: {
+        scale: hasCapability(filters.stdout, /\bscale\b/),
+        crop: hasCapability(filters.stdout, /\bcrop\b/),
+        concat: hasCapability(filters.stdout, /\bconcat\b/),
+        subtitles: hasCapability(filters.stdout, /\bsubtitles\b/)
+      }
+    };
+  } catch (error) {
+    throw new MediaError({
+      code: "FFMPEG_NOT_FOUND",
+      message: "FFmpeg capabilities could not be detected.",
+      context: { executable: options.ffmpegPath ?? "ffmpeg" },
+      suggestedActions: ["Install FFmpeg and ensure ffmpeg is on PATH."],
+      debug: { backend: "ffmpeg", stderr: error instanceof Error ? error.message : String(error) }
+    });
+  }
+}
+function hasCapability(output, pattern) {
+  return pattern.test(output);
+}
+
+// src/compiler.ts
+import { extname } from "path";
+import { MediaError as MediaError2 } from "@hadialmarzooq/agent-media-core";
+function compilePlan(plan, source, output) {
+  const specialStep = plan.steps.find(
+    (step) => step.operation === "extract-audio" || step.operation === "extract-frame" || step.operation === "concatenate"
+  );
+  if (specialStep !== void 0) return compileSpecial(plan, specialStep, source, output);
+  if (plan.steps.length === 0) {
+    return {
+      executable: "ffmpeg",
+      args: [
+        "-hide_banner",
+        "-nostdin",
+        "-y",
+        "-i",
+        plan.source.path,
+        "-map",
+        "0",
+        "-c",
+        "copy",
+        output
+      ]
+    };
+  }
+  const args = ["-hide_banner", "-nostdin", "-y"];
+  const trim = plan.steps.find((step) => step.operation === "trim");
+  if (trim?.operation === "trim") {
+    args.push("-ss", String(trim.startSeconds));
+    if (trim.endSeconds !== void 0) args.push("-to", String(trim.endSeconds));
+  }
+  args.push("-i", plan.source.path);
+  const filters = plan.steps.flatMap((step) => filtersForStep(step, source));
+  if (filters.length > 0) args.push("-vf", filters.join(","));
+  const encode = plan.steps.find((step) => step.operation === "encode");
+  if (encode?.operation === "encode") {
+    args.push(...encodingArgs(encode, source, plan));
+  } else {
+    args.push("-c:v", "libx264", "-c:a", "aac");
+  }
+  if (plan.expectations.audio === "remove") args.push("-an");
+  args.push("-movflags", "+faststart", output);
+  return { executable: "ffmpeg", args };
+}
+function compileSpecial(plan, step, source, output) {
+  if (step.operation === "extract-audio") {
+    return {
+      executable: "ffmpeg",
+      args: [
+        "-hide_banner",
+        "-nostdin",
+        "-y",
+        "-i",
+        plan.source.path,
+        "-vn",
+        "-c:a",
+        audioCodec(step.format),
+        output
+      ]
+    };
+  }
+  if (step.operation === "extract-frame") {
+    return {
+      executable: "ffmpeg",
+      args: [
+        "-hide_banner",
+        "-nostdin",
+        "-y",
+        "-ss",
+        String(step.atSeconds),
+        "-i",
+        plan.source.path,
+        "-frames:v",
+        "1",
+        "-q:v",
+        "2",
+        output
+      ]
+    };
+  }
+  if (step.operation === "concatenate") {
+    const args = ["-hide_banner", "-nostdin", "-y"];
+    for (const input of step.inputs) args.push("-i", input);
+    const hasVideo = source.video !== void 0;
+    const hasAudio = source.audio.present;
+    const labels = step.inputs.map((_, index) => `${hasVideo ? `[${index}:v]` : ""}${hasAudio ? `[${index}:a]` : ""}`).join("");
+    const outputs = `${hasVideo ? "[v]" : ""}${hasAudio ? "[a]" : ""}`;
+    args.push(
+      "-filter_complex",
+      `${labels}concat=n=${step.inputs.length}:v=${hasVideo ? 1 : 0}:a=${hasAudio ? 1 : 0}${outputs}`
+    );
+    if (hasVideo) args.push("-map", "[v]", "-c:v", "libx264");
+    if (hasAudio) {
+      args.push("-map", "[a]", "-c:a", hasVideo ? "aac" : audioCodecForOutput(output));
+    }
+    args.push(output);
+    return { executable: "ffmpeg", args };
+  }
+  throw new MediaError2({
+    code: "INVALID_PLAN",
+    message: `Unsupported special operation: ${step.operation}.`
+  });
+}
+function filtersForStep(step, source) {
+  if (step.operation === "resize") return [`scale=${step.width}:${step.height}:flags=lanczos`];
+  if (step.operation !== "reframe") return [];
+  if (source.video === void 0)
+    throw new MediaError2({
+      code: "UNSUPPORTED_INPUT",
+      message: "Reframing requires a video stream."
+    });
+  const [ratioWidth, ratioHeight] = step.aspectRatio.split(":").map(Number);
+  if (ratioWidth === void 0 || ratioHeight === void 0)
+    throw new MediaError2({ code: "INVALID_PLAN", message: "Invalid aspect ratio in plan." });
+  const targetRatio = ratioWidth / ratioHeight;
+  const sourceRatio = source.video.width / source.video.height;
+  if (sourceRatio > targetRatio) {
+    const width = even(source.video.height * targetRatio);
+    return [`crop=${width}:${source.video.height}:(iw-${width})/2:0`];
+  }
+  const height = even(source.video.width / targetRatio);
+  return [`crop=${source.video.width}:${height}:0:(ih-${height})/2`];
+}
+function encodingArgs(step, source, plan) {
+  const args = ["-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac"];
+  const crf = step.profile === "high-quality" ? "18" : step.profile === "high-compatibility" ? "23" : "21";
+  args.push("-crf", crf, "-preset", "medium");
+  if (step.maxSizeMB !== void 0) {
+    const duration = plan.expectations.durationSeconds ?? source.durationSeconds;
+    if (duration !== void 0 && duration > 0) {
+      const totalKbps = Math.max(64, Math.floor(step.maxSizeMB * 8e3 * 0.94 / duration));
+      const videoKbps = Math.max(32, totalKbps - 128);
+      args.push(
+        "-b:v",
+        `${videoKbps}k`,
+        "-maxrate",
+        `${videoKbps}k`,
+        "-bufsize",
+        `${videoKbps * 2}k`
+      );
+    }
+  }
+  return args;
+}
+function audioCodec(format) {
+  return format === "mp3" ? "libmp3lame" : format === "wav" ? "pcm_s16le" : "aac";
+}
+function audioCodecForOutput(output) {
+  const extension = extname(output).slice(1).toLowerCase();
+  return extension === "mp3" || extension === "wav" ? audioCodec(extension) : audioCodec("m4a");
+}
+function even(value) {
+  return Math.max(2, Math.floor(value / 2) * 2);
+}
+function extensionForPlan(plan) {
+  const special = plan.steps.find(
+    (step) => step.operation === "extract-audio" || step.operation === "extract-frame"
+  );
+  if (special?.operation === "extract-audio") return `.${special.format}`;
+  if (special?.operation === "extract-frame") return `.${special.format}`;
+  return extname(plan.source.path) || ".mp4";
+}
+
+// src/executor.ts
+import { access, constants, rm } from "fs/promises";
+import { dirname, relative, resolve as resolve2 } from "path";
+import { MediaError as MediaError4, validatePlan } from "@hadialmarzooq/agent-media-core";
+
+// src/inspect.ts
+import { stat } from "fs/promises";
+import { basename, resolve } from "path";
+import { MediaError as MediaError3 } from "@hadialmarzooq/agent-media-core";
+async function inspectMedia(input, options = {}) {
+  const path = resolve(input);
+  let sourceStat;
+  try {
+    sourceStat = await stat(path);
+  } catch {
+    throw new MediaError3({
+      code: "UNSUPPORTED_INPUT",
+      message: `The input file does not exist: ${basename(input)}.`,
+      context: { input: path },
+      suggestedActions: ["Check the source path and permissions."]
+    });
+  }
+  let result;
+  try {
+    result = await runProcess(
+      options.ffprobePath ?? "ffprobe",
+      ["-v", "error", "-show_format", "-show_streams", "-of", "json", path],
+      options.timeoutMs
+    );
+  } catch (error) {
+    throw new MediaError3({
+      code: "FFMPEG_NOT_FOUND",
+      message: "ffprobe could not be started.",
+      context: { executable: options.ffprobePath ?? "ffprobe" },
+      suggestedActions: ["Install FFmpeg and ensure ffprobe is on PATH."],
+      debug: { backend: "ffmpeg", stderr: error instanceof Error ? error.message : String(error) }
+    });
+  }
+  if (result.exitCode !== 0) {
+    throw new MediaError3({
+      code: "PROBE_FAILED",
+      message: "ffprobe could not read the input media.",
+      context: { input: path },
+      suggestedActions: [
+        "Run inspect to confirm the file is readable.",
+        "Try a supported media container."
+      ],
+      debug: { backend: "ffmpeg", stderr: result.stderr }
+    });
+  }
+  const probe = JSON.parse(result.stdout);
+  const streams = probe.streams ?? [];
+  const videoStream = streams.find((stream) => stream.codec_type === "video");
+  const audioStream = streams.find((stream) => stream.codec_type === "audio");
+  const video = normalizeVideo(videoStream);
+  const audio = normalizeAudio(audioStream);
+  const kind = video ? probe.format?.format_name?.split(",").includes("image2") ? "image" : "video" : audio.present ? "audio" : "unknown";
+  const durationSeconds = toFiniteNumber(probe.format?.duration);
+  return {
+    path,
+    kind,
+    ...durationSeconds === void 0 ? {} : { durationSeconds },
+    ...probe.format?.format_name === void 0 ? {} : { container: probe.format.format_name.split(",")[0] },
+    sizeBytes: sourceStat.size,
+    ...video === void 0 ? {} : { video },
+    audio
+  };
+}
+function normalizeVideo(stream) {
+  if (stream?.width === void 0 || stream.height === void 0) return void 0;
+  const fps = parseFraction(stream.r_frame_rate);
+  const rotation = stream.side_data_list?.find((data) => data.rotation !== void 0)?.rotation;
+  const tagRotation = stream.tags?.rotate === void 0 ? void 0 : Number(stream.tags.rotate);
+  return {
+    width: stream.width,
+    height: stream.height,
+    aspectRatio: simplifyAspectRatio(stream.width, stream.height),
+    ...fps === void 0 ? {} : { fps },
+    ...stream.codec_name === void 0 ? {} : { codec: stream.codec_name },
+    ...stream.pix_fmt === void 0 ? {} : { pixelFormat: stream.pix_fmt },
+    ...rotation === void 0 && tagRotation === void 0 ? {} : { rotationDegrees: Math.round(rotation ?? tagRotation ?? 0) }
+  };
+}
+function normalizeAudio(stream) {
+  if (stream === void 0) return { present: false };
+  const sampleRate = toFiniteNumber(stream.sample_rate);
+  return {
+    present: true,
+    ...stream.codec_name === void 0 ? {} : { codec: stream.codec_name },
+    ...sampleRate === void 0 ? {} : { sampleRate },
+    ...stream.channels === void 0 ? {} : { channels: stream.channels }
+  };
+}
+function parseFraction(value) {
+  if (value === void 0) return void 0;
+  const [numerator, denominator] = value.split("/").map(Number);
+  if (numerator === void 0 || denominator === void 0 || !Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator === 0)
+    return void 0;
+  return numerator / denominator;
+}
+function toFiniteNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : void 0;
+}
+function simplifyAspectRatio(width, height) {
+  const divisor = gcd(width, height);
+  return `${width / divisor}:${height / divisor}`;
+}
+function gcd(left, right) {
+  return right === 0 ? left : gcd(right, left % right);
+}
+
+// src/progress.ts
+function createExecutionProgressReporter(totalSeconds, onProgress) {
+  let buffer = "";
+  let fields = {};
+  let lastPercent = -1;
+  let lastProcessedSeconds = -1;
+  const emit2 = (percent, message, processedSeconds, speed) => {
+    const normalizedPercent = Math.max(lastPercent, Math.min(100, Math.round(percent)));
+    if (normalizedPercent === lastPercent && (processedSeconds === void 0 || processedSeconds - lastProcessedSeconds < 0.25)) {
+      return;
+    }
+    lastPercent = normalizedPercent;
+    if (processedSeconds !== void 0) lastProcessedSeconds = processedSeconds;
+    safelyNotify(onProgress, {
+      phase: "executing",
+      percent: normalizedPercent,
+      message,
+      ...processedSeconds === void 0 ? {} : { processedSeconds },
+      ...totalSeconds === void 0 ? {} : { totalSeconds },
+      ...speed === void 0 ? {} : { speed }
+    });
+  };
+  const flushLine = (line) => {
+    const separator = line.indexOf("=");
+    if (separator === -1) return;
+    const key = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    fields[key] = value;
+    if (key !== "progress") return;
+    const processedSeconds = parseProcessedSeconds(fields);
+    const speed = parseSpeed(fields.speed);
+    const percent = processedSeconds === void 0 || totalSeconds === void 0 || totalSeconds <= 0 ? 0 : Math.min(99, processedSeconds / totalSeconds * 100);
+    emit2(percent, "FFmpeg is executing the media plan.", processedSeconds, speed);
+    fields = {};
+  };
+  return {
+    start: () => emit2(0, "FFmpeg started executing the media plan.", 0),
+    write: (chunk) => {
+      buffer += chunk;
+      let newline = buffer.indexOf("\n");
+      while (newline !== -1) {
+        flushLine(buffer.slice(0, newline).replace(/\r$/, ""));
+        buffer = buffer.slice(newline + 1);
+        newline = buffer.indexOf("\n");
+      }
+    },
+    complete: () => emit2(100, "FFmpeg completed the media plan.", totalSeconds, void 0)
+  };
+}
+function safelyNotify(onProgress, progress) {
+  try {
+    onProgress?.(progress);
+  } catch {
+  }
+}
+function parseProcessedSeconds(fields) {
+  const microseconds = Number(fields.out_time_us);
+  if (Number.isFinite(microseconds) && microseconds >= 0) return microseconds / 1e6;
+  const timestamp = fields.out_time;
+  if (timestamp === void 0) return void 0;
+  const match = /^(\d+):(\d+):(\d+(?:\.\d+)?)$/.exec(timestamp);
+  if (match === null) return void 0;
+  const hours = Number(match[1]);
+  const minutes = Number(match[2]);
+  const seconds = Number(match[3]);
+  const value = hours * 3600 + minutes * 60 + seconds;
+  return Number.isFinite(value) ? value : void 0;
+}
+function parseSpeed(value) {
+  if (value === void 0) return void 0;
+  const speed = Number(value.replace(/x$/, ""));
+  return Number.isFinite(speed) ? speed : void 0;
+}
+
+// src/executor.ts
+async function executePlan(planInput, options) {
+  const plan = validatePlan(planInput);
+  const output = resolve2(options.output);
+  if (output === resolve2(plan.source.path)) {
+    throw new MediaError4({
+      code: "PATH_NOT_ALLOWED",
+      message: "Output must not overwrite the source path.",
+      context: { source: plan.source.path, output },
+      suggestedActions: ["Choose a distinct output path."]
+    });
+  }
+  if (options.allowedOutputDirectory !== void 0 && !isWithin(output, resolve2(options.allowedOutputDirectory))) {
+    throw new MediaError4({
+      code: "PATH_NOT_ALLOWED",
+      message: "Output is outside the allowed output directory.",
+      context: { output, allowedOutputDirectory: resolve2(options.allowedOutputDirectory) },
+      suggestedActions: ["Choose a path within the configured output directory."]
+    });
+  }
+  if (!options.overwrite && await exists(output)) {
+    throw new MediaError4({
+      code: "OUTPUT_EXISTS",
+      message: "The output path already exists.",
+      context: { output },
+      suggestedActions: ["Choose a different output path or explicitly enable overwrite."]
+    });
+  }
+  const sourceMetadata = options.sourceMetadata ?? await inspectMedia(plan.source.path, {
+    ...options.ffprobePath === void 0 ? {} : { ffprobePath: options.ffprobePath },
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+  });
+  if (resolve2(sourceMetadata.path) !== resolve2(plan.source.path)) {
+    throw new MediaError4({
+      code: "INVALID_PLAN",
+      message: "Source metadata does not describe the Media Plan source.",
+      context: { planSource: plan.source.path, metadataSource: sourceMetadata.path },
+      suggestedActions: ["Inspect the planned source and pass that metadata to executePlan."]
+    });
+  }
+  await preflightConcatenation(plan, sourceMetadata, options);
+  const operation = compilePlan(plan, sourceMetadata, output);
+  const progress = createExecutionProgressReporter(
+    executionDuration(plan, sourceMetadata),
+    options.onProgress
+  );
+  progress.start();
+  let result;
+  try {
+    result = await runProcess(
+      options.ffmpegPath ?? operation.executable,
+      progressArgs(operation.args),
+      {
+        ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+        ...options.signal === void 0 ? {} : { signal: options.signal },
+        onStdout: progress.write
+      }
+    );
+  } catch (error) {
+    throw new MediaError4({
+      code: "FFMPEG_NOT_FOUND",
+      message: "FFmpeg could not be started for plan execution.",
+      context: { executable: options.ffmpegPath ?? operation.executable },
+      suggestedActions: ["Install FFmpeg and ensure ffmpeg is on PATH."],
+      debug: { backend: "ffmpeg", stderr: error instanceof Error ? error.message : String(error) }
+    });
+  }
+  if (result.aborted) {
+    await removePartialOutput(output);
+    throw new MediaError4({
+      code: "OPERATION_CANCELLED",
+      message: "Media execution was cancelled.",
+      context: { input: plan.source.path, output },
+      suggestedActions: ["Create a new execution request when ready."]
+    });
+  }
+  if (result.timedOut) {
+    await removePartialOutput(output);
+    throw new MediaError4({
+      code: "OPERATION_TIMEOUT",
+      message: "Media execution exceeded its configured timeout.",
+      context: { input: plan.source.path, output, timeoutMs: options.timeoutMs ?? 3e4 },
+      suggestedActions: ["Use a longer timeout or a smaller media operation."],
+      debug: { backend: "ffmpeg", stderr: result.stderr }
+    });
+  }
+  if (result.exitCode !== 0) {
+    await removePartialOutput(output);
+    throw new MediaError4({
+      code: "EXECUTION_FAILED",
+      message: "FFmpeg could not execute the media plan.",
+      context: { input: plan.source.path, output, directory: dirname(output) },
+      suggestedActions: ["Inspect the source and plan, then retry with a supported target."],
+      debug: { backend: "ffmpeg", stderr: result.stderr }
+    });
+  }
+  progress.complete();
+  return { output, operation };
+}
+function progressArgs(args) {
+  const result = [...args];
+  const insertionPoint = result.indexOf("-nostdin") + 1;
+  result.splice(insertionPoint, 0, "-progress", "pipe:1", "-nostats");
+  return result;
+}
+function executionDuration(plan, source) {
+  if (plan.expectations.durationSeconds !== void 0) return plan.expectations.durationSeconds;
+  const trim = plan.steps.find((step) => step.operation === "trim");
+  if (trim?.operation !== "trim") return source.durationSeconds;
+  if (trim.endSeconds !== void 0) return trim.endSeconds - trim.startSeconds;
+  return source.durationSeconds === void 0 ? void 0 : Math.max(0, source.durationSeconds - trim.startSeconds);
+}
+async function preflightConcatenation(plan, source, options) {
+  const concatenate = plan.steps.find((step) => step.operation === "concatenate");
+  if (concatenate?.operation !== "concatenate") return;
+  const metadata = await Promise.all(
+    concatenate.inputs.map(async (input, index) => {
+      if (index === 0) return source;
+      return inspectMedia(input, {
+        ...options.ffprobePath === void 0 ? {} : { ffprobePath: options.ffprobePath },
+        ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+      });
+    })
+  );
+  const baseline = metadata[0];
+  if (baseline === void 0) return;
+  for (const [index, candidate] of metadata.entries()) {
+    if (index === 0) continue;
+    const incompatibleFields = streamDifferences(baseline, candidate);
+    if (incompatibleFields.length === 0) continue;
+    throw new MediaError4({
+      code: "UNSUPPORTED_INPUT",
+      message: "Concatenation inputs have incompatible stream layouts.",
+      context: {
+        input: concatenate.inputs[index],
+        inputIndex: index,
+        incompatibleFields
+      },
+      suggestedActions: [
+        "Normalize the listed stream properties before concatenation.",
+        "Use inputs with matching video and audio stream layouts."
+      ]
+    });
+  }
+}
+function streamDifferences(baseline, candidate) {
+  const differences = [];
+  compare(
+    differences,
+    "video.present",
+    baseline.video !== void 0,
+    candidate.video !== void 0
+  );
+  compare(differences, "audio.present", baseline.audio.present, candidate.audio.present);
+  if (baseline.video !== void 0 && candidate.video !== void 0) {
+    compare(differences, "video.width", baseline.video.width, candidate.video.width);
+    compare(differences, "video.height", baseline.video.height, candidate.video.height);
+    compare(differences, "video.fps", baseline.video.fps, candidate.video.fps);
+    compare(
+      differences,
+      "video.pixelFormat",
+      baseline.video.pixelFormat,
+      candidate.video.pixelFormat
+    );
+  }
+  if (baseline.audio.present && candidate.audio.present) {
+    compare(differences, "audio.sampleRate", baseline.audio.sampleRate, candidate.audio.sampleRate);
+    compare(differences, "audio.channels", baseline.audio.channels, candidate.audio.channels);
+  }
+  return differences;
+}
+function compare(differences, field, baseline, candidate) {
+  if (baseline !== candidate) differences.push(field);
+}
+async function removePartialOutput(path) {
+  try {
+    await rm(path, { force: true });
+  } catch {
+  }
+}
+async function exists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isWithin(path, directory) {
+  const pathRelative = relative(directory, path);
+  return pathRelative === "" || !pathRelative.startsWith("..") && !pathRelative.includes("..\\");
+}
+
+// src/workflows.ts
+import { MediaError as MediaError5, planMedia, serializePlan, verifyMedia } from "@hadialmarzooq/agent-media-core";
+async function makeVertical(options) {
+  const dimensions = verticalDimensions(options.width, options.height);
+  const source = await inspectPhase(options, "vertical media");
+  const plan = await planningPhase(options, "vertical media", source, {
+    aspectRatio: "9:16",
+    width: dimensions.width,
+    height: dimensions.height,
+    compatibility: "high",
+    ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+    ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds },
+    ...options.maxSizeMB === void 0 ? {} : { maxSizeMB: options.maxSizeMB },
+    ...audioGoal(options, source)
+  });
+  return executeAndVerify(options, source, plan, "Vertical media is verified and ready.");
+}
+async function optimizeForWeb(options) {
+  const source = await inspectPhase(options, "web-optimized media");
+  const plan = await planningPhase(options, "web-optimized media", source, {
+    compatibility: "high",
+    quality: options.quality ?? "balanced",
+    ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+    ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds },
+    ...options.maxSizeMB === void 0 ? {} : { maxSizeMB: options.maxSizeMB },
+    ...audioGoal(options, source)
+  });
+  return executeAndVerify(options, source, plan, "Web-optimized media is verified and ready.");
+}
+async function normalize(options) {
+  const source = await inspectPhase(options, "normalized media");
+  const plan = await planningPhase(options, "normalized media", source, {
+    compatibility: "high",
+    ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+    ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds },
+    ...audioGoal(options, source)
+  });
+  return executeAndVerify(options, source, plan, "Normalized media is verified and ready.");
+}
+async function extractAudio(options) {
+  const source = await inspectPhase(options, "audio extraction");
+  const plan = await planningPhase(options, "audio extraction", source, {
+    extractAudio: { format: options.format ?? "m4a" },
+    ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+    ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds }
+  });
+  return executeAndVerify(options, source, plan, "Audio extraction is verified and ready.");
+}
+async function extractFrame(options) {
+  const source = await inspectPhase(options, "frame extraction");
+  const plan = await planningPhase(options, "frame extraction", source, {
+    extractFrame: {
+      atSeconds: options.atSeconds ?? 0,
+      format: options.format ?? "jpg"
+    }
+  });
+  return executeAndVerify(options, source, plan, "Frame extraction is verified and ready.");
+}
+function verticalDimensions(width, height) {
+  if (width === void 0 !== (height === void 0)) {
+    throw new MediaError5({
+      code: "INVALID_PLAN",
+      message: "Custom vertical dimensions require both width and height.",
+      suggestedActions: ["Provide both dimensions or use the default 1080x1920 output."]
+    });
+  }
+  return { width: width ?? 1080, height: height ?? 1920 };
+}
+function ffmpegOptions(options) {
+  return {
+    ...options.ffmpegPath === void 0 ? {} : { ffmpegPath: options.ffmpegPath },
+    ...options.ffprobePath === void 0 ? {} : { ffprobePath: options.ffprobePath },
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+  };
+}
+function audioGoal(options, source) {
+  if (options.audio !== void 0) return { audio: options.audio };
+  return source.audio.present ? { audio: "preserve" } : {};
+}
+async function inspectPhase(options, label) {
+  emit(options.onProgress, "inspecting", 0, `Inspecting the source media for ${label}.`);
+  const source = await inspectMedia(options.input, ffmpegOptions(options));
+  emit(options.onProgress, "inspecting", 10, "Source inspection completed.");
+  return source;
+}
+async function planningPhase(options, label, source, goals) {
+  emit(options.onProgress, "planning", 15, `Creating a semantic plan for ${label}.`);
+  const plan = planMedia({
+    source,
+    capabilities: await getCapabilities(ffmpegOptions(options)),
+    goals
+  });
+  emit(options.onProgress, "planning", 20, `${label} plan is ready.`);
+  return plan;
+}
+async function executeAndVerify(options, source, plan, completionMessage) {
+  const executeOptions = {
+    output: options.output,
+    sourceMetadata: source,
+    ...options.ffmpegPath === void 0 ? {} : { ffmpegPath: options.ffmpegPath },
+    ...options.ffprobePath === void 0 ? {} : { ffprobePath: options.ffprobePath },
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+    ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
+    ...options.allowedOutputDirectory === void 0 ? {} : { allowedOutputDirectory: options.allowedOutputDirectory },
+    ...options.signal === void 0 ? {} : { signal: options.signal },
+    onProgress: (progress) => {
+      const percent = 20 + Math.round(progress.percent * 0.7);
+      safelyNotify(options.onProgress, { ...progress, percent });
+    }
+  };
+  const execution = await executePlan(plan, executeOptions);
+  emit(options.onProgress, "verifying", 92, "Inspecting and verifying the output.");
+  const output = await inspectMedia(execution.output, ffmpegOptions(options));
+  const verification = verifyMedia(output, plan.expectations);
+  if (!verification.passed) {
+    throw new MediaError5({
+      code: "VERIFICATION_FAILED",
+      message: "The workflow completed, but the output did not satisfy its plan.",
+      context: { output: execution.output, verification },
+      suggestedActions: ["Inspect the failed checks, adjust the semantic goals, and retry."]
+    });
+  }
+  emit(options.onProgress, "completed", 100, completionMessage);
+  const serializedPlan = serializePlan(plan);
+  return { source, plan, serializedPlan, output, verification };
+}
+function emit(onProgress, phase, percent, message) {
+  safelyNotify(onProgress, { phase, percent, message });
+}
+export {
+  compilePlan,
+  executePlan,
+  extensionForPlan,
+  extractAudio,
+  extractFrame,
+  getCapabilities,
+  inspectMedia,
+  makeVertical,
+  normalize,
+  optimizeForWeb
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hadialmarzooq/agent-media-ffmpeg",
+  "version": "0.1.0",
+  "description": "Safe FFmpeg execution, progress, and verified media workflows for software agents.",
+  "keywords": [
+    "media",
+    "agents",
+    "ffmpeg",
+    "video",
+    "mcp"
+  ],
+  "homepage": "https://github.com/HadiAlMarzooq/agent-media#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HadiAlMarzooq/agent-media.git",
+    "directory": "packages/ffmpeg"
+  },
+  "bugs": {
+    "url": "https://github.com/HadiAlMarzooq/agent-media/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hadialmarzooq/agent-media-core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit"
+  }
+}