@hadialmarzooq/agent-media-ffmpeg 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+# @hadialmarzooq/agent-media-ffmpeg
+
+Safe FFmpeg execution, progress reporting, and verified media workflows for software agents.
+
+## What it does
+
+The FFmpeg backend for [Agent Media](https://github.com/HadiAlMarzooq/agent-media). Compiles semantic Media IR plans into deterministic FFmpeg invocations, executes them with progress reporting, and inspects outputs for verification.
+
+### Five high-level workflows
+
+All workflows share the same contract: **inspect → plan → serialize → execute → verify**. Each returns `{ source, plan, serializedPlan, output, verification }`.
+
+```ts
+import {
+  makeVertical,
+  optimizeForWeb,
+  normalize,
+  extractAudio,
+  extractFrame,
+} from '@hadialmarzooq/agent-media-ffmpeg';
+
+// 9:16 vertical, H.264/yuv420p, faststart, size-constrained
+const vertical = await makeVertical({
+  input: 'demo.mp4',
+  output: 'vertical.mp4',
+  maxSizeMB: 25,
+  onProgress: ({ phase, percent }) => console.error(`${phase}: ${percent}%`),
+});
+
+// Web-optimized: balanced quality, H.264, faststart
+const web = await optimizeForWeb({
+  input: 'demo.mp4',
+  output: 'web.mp4',
+  maxSizeMB: 10,
+});
+
+// Normalized high-compatibility copy
+const norm = await normalize({ input: 'demo.mp4', output: 'normalized.mp4' });
+
+// Extract audio
+const audio = await extractAudio({ input: 'demo.mp4', output: 'audio.m4a' });
+
+// Extract a still frame
+const frame = await extractFrame({ input: 'demo.mp4', output: 'frame.jpg', atSeconds: 2 });
+```
+
+### Explicit plan and replay
+
+```ts
+import { inspectMedia, executePlan, getCapabilities } from '@hadialmarzooq/agent-media-ffmpeg';
+import { planMedia, serializePlan, parsePlan, verifyMedia } from '@hadialmarzooq/agent-media-core';
+
+const source = await inspectMedia('demo.mp4');
+const plan = planMedia({
+  source,
+  capabilities: await getCapabilities(),
+  goals: { aspectRatio: '9:16', compatibility: 'high', maxSizeMB: 25 },
+});
+
+// Save and replay
+const json = serializePlan(plan);
+const replayed = parsePlan(json);
+const result = await executePlan(replayed, { output: 'vertical.mp4' });
+const output = await inspectMedia(result.output);
+const report = verifyMedia(output, replayed.expectations);
+```
+
+## Install
+
+```bash
+npm install @hadialmarzooq/agent-media-core @hadialmarzooq/agent-media-ffmpeg
+```
+
+Prerequisites: Node.js 22+, `ffmpeg` and `ffprobe` on `PATH`.
+
+## Safety
+
+- Rejects source overwrite, output collisions, and directory escape
+- Cancellation and timeout controls with partial cleanup
+- Concatenation preflight rejects incompatible streams before execution
+- Progress is monotonic and isolated — UI callbacks can't change execution semantics
+
+## Documentation
+
+- [Full docs](https://github.com/HadiAlMarzooq/agent-media/tree/main/docs)
+- [Workflows](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/workflows.md)
+- [API reference](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/api.md)
+- [Reliability](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/reliability.md)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -80,6 +80,9 @@ interface ExtractFrameOptions extends WorkflowOptions {
     atSeconds?: number;
     format?: 'jpg' | 'png';
 }
+interface ConcatenateOptions extends WorkflowOptions {
+    inputs: string[];
+}
 interface WorkflowResult {
     source: MediaMetadata;
     plan: MediaPlan;
@@ -110,5 +113,9 @@ declare function extractAudio(options: ExtractAudioOptions): Promise<WorkflowRes
  * Inspect, plan, execute, and verify a still frame extraction from a video source.
  */
 declare function extractFrame(options: ExtractFrameOptions): Promise<WorkflowResult>;
+/**
+ * Inspect, plan, execute, and verify concatenation of multiple media sources.
+ */
+declare function concatenate(options: ConcatenateOptions): 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 };
+export { type CompiledOperation, type ConcatenateOptions, 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, concatenate, executePlan, extensionForPlan, extractAudio, extractFrame, getCapabilities, inspectMedia, makeVertical, normalize, optimizeForWeb };

package/dist/index.js

@@ -254,12 +254,12 @@ function extensionForPlan(plan) {
 
 // src/executor.ts
 import { access, constants, rm } from "fs/promises";
-import { dirname, relative, resolve as resolve2 } from "path";
+import { dirname, extname as extname2, 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 { resolve } from "path";
 import { MediaError as MediaError3 } from "@hadialmarzooq/agent-media-core";
 async function inspectMedia(input, options = {}) {
   const path = resolve(input);
@@ -269,7 +269,7 @@ async function inspectMedia(input, options = {}) {
   } catch {
     throw new MediaError3({
       code: "UNSUPPORTED_INPUT",
-      message: `The input file does not exist: ${basename(input)}.`,
+      message: `The input file does not exist: ${path}.`,
       context: { input: path },
       suggestedActions: ["Check the source path and permissions."]
     });
@@ -442,6 +442,14 @@ function parseSpeed(value) {
 async function executePlan(planInput, options) {
   const plan = validatePlan(planInput);
   const output = resolve2(options.output);
+  const release = await acquireOutputLock(output);
+  try {
+    return await executePlanInternal(plan, options, output);
+  } finally {
+    releaseOutputLock(output, release);
+  }
+}
+async function executePlanInternal(plan, options, output) {
   if (output === resolve2(plan.source.path)) {
     throw new MediaError4({
       code: "PATH_NOT_ALLOWED",
@@ -466,6 +474,25 @@ async function executePlan(planInput, options) {
       suggestedActions: ["Choose a different output path or explicitly enable overwrite."]
     });
   }
+  const outputDir = dirname(output);
+  if (!await exists(outputDir)) {
+    throw new MediaError4({
+      code: "OUTPUT_DIR_MISSING",
+      message: "The output directory does not exist.",
+      context: { output, directory: outputDir },
+      suggestedActions: ["Create the output directory before execution."]
+    });
+  }
+  const expectedExt = extensionForPlan(plan);
+  const actualExt = extname2(output);
+  if (expectedExt && actualExt && expectedExt !== actualExt) {
+    throw new MediaError4({
+      code: "OUTPUT_EXTENSION_MISMATCH",
+      message: `The output extension "${actualExt}" does not match the plan's expected "${expectedExt}".`,
+      context: { output, expectedExtension: expectedExt, actualExtension: actualExt },
+      suggestedActions: [`Use a "${expectedExt}" output extension, or adjust the plan.`]
+    });
+  }
   const sourceMetadata = options.sourceMetadata ?? await inspectMedia(plan.source.path, {
     ...options.ffprobePath === void 0 ? {} : { ffprobePath: options.ffprobePath },
     ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
@@ -551,10 +578,10 @@ function executionDuration(plan, source) {
   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 concatenate2 = plan.steps.find((step) => step.operation === "concatenate");
+  if (concatenate2?.operation !== "concatenate") return;
   const metadata = await Promise.all(
-    concatenate.inputs.map(async (input, index) => {
+    concatenate2.inputs.map(async (input, index) => {
       if (index === 0) return source;
       return inspectMedia(input, {
         ...options.ffprobePath === void 0 ? {} : { ffprobePath: options.ffprobePath },
@@ -572,7 +599,7 @@ async function preflightConcatenation(plan, source, options) {
       code: "UNSUPPORTED_INPUT",
       message: "Concatenation inputs have incompatible stream layouts.",
       context: {
-        input: concatenate.inputs[index],
+        input: concatenate2.inputs[index],
         inputIndex: index,
         incompatibleFields
       },
@@ -630,6 +657,24 @@ function isWithin(path, directory) {
   const pathRelative = relative(directory, path);
   return pathRelative === "" || !pathRelative.startsWith("..") && !pathRelative.includes("..\\");
 }
+var outputLocks = /* @__PURE__ */ new Map();
+async function acquireOutputLock(output) {
+  const prev = outputLocks.get(output) ?? Promise.resolve();
+  let release = () => void 0;
+  const next = new Promise((resolve3) => {
+    release = resolve3;
+  });
+  outputLocks.set(
+    output,
+    prev.then(() => next)
+  );
+  await prev;
+  return release;
+}
+function releaseOutputLock(output, release) {
+  release();
+  outputLocks.delete(output);
+}
 
 // src/workflows.ts
 import { MediaError as MediaError5, planMedia, serializePlan, verifyMedia } from "@hadialmarzooq/agent-media-core";
@@ -689,6 +734,13 @@ async function extractFrame(options) {
   });
   return executeAndVerify(options, source, plan, "Frame extraction is verified and ready.");
 }
+async function concatenate(options) {
+  const source = await inspectPhase(options, "concatenation");
+  const plan = await planningPhase(options, "concatenation", source, {
+    concatenate: options.inputs
+  });
+  return executeAndVerify(options, source, plan, "Concatenation is verified and ready.");
+}
 function verticalDimensions(width, height) {
   if (width === void 0 !== (height === void 0)) {
     throw new MediaError5({
@@ -762,6 +814,7 @@ function emit(onProgress, phase, percent, message) {
 }
 export {
   compilePlan,
+  concatenate,
   executePlan,
   extensionForPlan,
   extractAudio,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadialmarzooq/agent-media-ffmpeg",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Safe FFmpeg execution, progress, and verified media workflows for software agents.",
   "keywords": [
     "media",
@@ -32,13 +32,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@hadialmarzooq/agent-media-core": "0.1.0"
+    "@hadialmarzooq/agent-media-core": "0.2.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",