@ash_j1997/ffmpeg-mcp-server 0.4.2 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,13 +1,14 @@
1
1
  import { z } from "zod";
2
- import { ensureFileExists, ensureOutputDir, runFfmpeg } from "../utils/exec.js";
2
+ import { ensureFileExists, ensureOutputDir, runCommand, runFfmpeg } from "../utils/exec.js";
3
3
  import { probeMedia } from "./probe.js";
4
+ import { detectHwAccel } from "../utils/hwaccel.js";
4
5
  export const trimSilenceSchema = z.object({
5
6
  inputPath: z.string().describe("Path to the source audio or video file."),
6
7
  outputPath: z.string().describe("Destination path for the trimmed file (e.g. './recordings/cleaned.mp4')."),
7
8
  mode: z
8
9
  .enum(["start_end", "all_pauses"])
9
10
  .default("start_end")
10
- .describe("Trim mode: 'start_end' removes silence at the start and end; 'all_pauses' removes silent pauses across the file. Default: 'start_end'."),
11
+ .describe("Trim mode: 'start_end' removes silence at the start and end (preserving perfect A/V sync on videos); 'all_pauses' removes silent pauses across audio files. Default: 'start_end'."),
11
12
  thresholdDb: z
12
13
  .number()
13
14
  .min(-60)
@@ -21,36 +22,96 @@ export const trimSilenceSchema = z.object({
21
22
  .default(0.5)
22
23
  .describe("Minimum silence duration in seconds to trigger a cut. Default: 0.5."),
23
24
  });
24
- export async function trimSilence(args) {
25
+ export async function trimSilence(args, options) {
25
26
  const input = await ensureFileExists(args.inputPath);
26
27
  const output = await ensureOutputDir(args.outputPath);
27
28
  const mode = args.mode ?? "start_end";
28
29
  const thresholdDb = args.thresholdDb ?? -35;
29
30
  const minDuration = args.minDurationSeconds ?? 0.5;
30
- const originalProbe = await probeMedia(input);
31
+ const originalProbe = await probeMedia(input, { signal: options?.signal });
31
32
  if (originalProbe.audioStreams.length === 0) {
32
33
  throw new Error(`Cannot trim silence: input file '${input}' contains no audio streams.`);
33
34
  }
34
35
  const isVideo = originalProbe.videoStreams.length > 0;
35
- let audioFilter = "";
36
- if (mode === "start_end") {
37
- audioFilter = `silenceremove=start_periods=1:start_duration=${minDuration}:start_threshold=${thresholdDb}dB:detection=peak,areverse,silenceremove=start_periods=1:start_duration=${minDuration}:start_threshold=${thresholdDb}dB:detection=peak,areverse`;
36
+ const originalDuration = originalProbe.format.durationSeconds;
37
+ if (isVideo && mode === "all_pauses") {
38
+ throw new Error("Trimming internal pauses ('all_pauses') on video files causes severe audio/video desync. For video files, please use mode: 'start_end', or extract the audio track first with extract_audio.");
38
39
  }
39
- else {
40
- audioFilter = `silenceremove=stop_periods=-1:stop_duration=${minDuration}:stop_threshold=${thresholdDb}dB`;
40
+ let commandExecuted = "";
41
+ let durationSeconds = 0;
42
+ if (isVideo && mode === "start_end") {
43
+ // Detect silence intervals using silencedetect filter
44
+ const detectRes = await runCommand("ffmpeg", ["-i", input, "-af", `silencedetect=noise=${thresholdDb}dB:d=${minDuration}`, "-f", "null", "-"], { signal: options?.signal });
45
+ const log = `${detectRes.stdout}\n${detectRes.stderr}`;
46
+ const startEndRegex = /silence_end:\s*([\d.]+)/g;
47
+ const startSilenceRegex = /silence_start:\s*([\d.]+)/g;
48
+ let startTime = 0;
49
+ let endTime = originalDuration;
50
+ // Check if there was silence at the beginning (silence_start at 0)
51
+ const firstSilenceMatch = log.match(/silence_start:\s*([0-9.]+)/);
52
+ if (firstSilenceMatch && parseFloat(firstSilenceMatch[1]) < 0.2) {
53
+ const endMatch = log.match(/silence_end:\s*([0-9.]+)/);
54
+ if (endMatch) {
55
+ startTime = Math.min(originalDuration - 0.5, parseFloat(endMatch[1]));
56
+ }
57
+ }
58
+ // Check for silence at the end
59
+ const allSilenceStarts = [];
60
+ let m;
61
+ while ((m = startSilenceRegex.exec(log)) !== null) {
62
+ allSilenceStarts.push(parseFloat(m[1]));
63
+ }
64
+ if (allSilenceStarts.length > 0) {
65
+ const lastStart = allSilenceStarts[allSilenceStarts.length - 1];
66
+ // If the last silence starts near the end and doesn't end before original duration
67
+ if (lastStart > startTime && originalDuration - lastStart <= minDuration * 2 + 1) {
68
+ endTime = lastStart;
69
+ }
70
+ }
71
+ const hwInfo = await detectHwAccel();
72
+ const ffmpegArgs = ["-ss", startTime.toFixed(3), "-i", input];
73
+ if (endTime < originalDuration) {
74
+ ffmpegArgs.push("-to", endTime.toFixed(3));
75
+ }
76
+ if (hwInfo.isAvailable) {
77
+ ffmpegArgs.push("-c:v", hwInfo.h264Encoder, "-b:v", "4M", "-c:a", "aac", "-b:a", "192k");
78
+ }
79
+ else {
80
+ ffmpegArgs.push("-c:v", "libx264", "-crf", "22", "-preset", "fast", "-c:a", "aac", "-b:a", "192k");
81
+ }
82
+ ffmpegArgs.push("-movflags", "+faststart", "-y", output);
83
+ const res = await runFfmpeg(ffmpegArgs, {
84
+ signal: options?.signal,
85
+ onProgress: options?.onProgress,
86
+ expectedDurationSeconds: originalDuration,
87
+ });
88
+ commandExecuted = res.command;
89
+ durationSeconds = res.durationSeconds;
41
90
  }
42
- const ffmpegArgs = ["-i", input, "-af", audioFilter];
43
- if (isVideo) {
44
- ffmpegArgs.push("-c:v", "copy", "-c:a", "aac", "-b:a", "192k");
91
+ else {
92
+ // Audio file or fallback
93
+ let audioFilter = "";
94
+ if (mode === "start_end") {
95
+ audioFilter = `silenceremove=start_periods=1:start_duration=${minDuration}:start_threshold=${thresholdDb}dB:detection=peak,areverse,silenceremove=start_periods=1:start_duration=${minDuration}:start_threshold=${thresholdDb}dB:detection=peak,areverse`;
96
+ }
97
+ else {
98
+ audioFilter = `silenceremove=stop_periods=-1:stop_duration=${minDuration}:stop_threshold=${thresholdDb}dB`;
99
+ }
100
+ const ffmpegArgs = ["-i", input, "-af", audioFilter, "-y", output];
101
+ const res = await runFfmpeg(ffmpegArgs, {
102
+ signal: options?.signal,
103
+ onProgress: options?.onProgress,
104
+ expectedDurationSeconds: originalDuration,
105
+ });
106
+ commandExecuted = res.command;
107
+ durationSeconds = res.durationSeconds;
45
108
  }
46
- ffmpegArgs.push("-y", output);
47
- const res = await runFfmpeg(ffmpegArgs);
48
109
  let timeSaved = 0;
49
- let newDuration = 0;
110
+ let newDuration = originalDuration;
50
111
  try {
51
- const newProbe = await probeMedia(output);
112
+ const newProbe = await probeMedia(output, { signal: options?.signal });
52
113
  newDuration = newProbe.format.durationSeconds;
53
- timeSaved = Number(Math.max(0, originalProbe.format.durationSeconds - newDuration).toFixed(2));
114
+ timeSaved = Number(Math.max(0, originalDuration - newDuration).toFixed(2));
54
115
  }
55
116
  catch {
56
117
  // Optional
@@ -59,11 +120,11 @@ export async function trimSilence(args) {
59
120
  success: true,
60
121
  outputPath: output,
61
122
  mode,
62
- originalDurationSeconds: originalProbe.format.durationSeconds,
123
+ originalDurationSeconds: originalDuration,
63
124
  newDurationSeconds: newDuration,
64
125
  timeSavedSeconds: timeSaved,
65
126
  thresholdDb,
66
- commandExecuted: res.command,
67
- durationSeconds: res.durationSeconds,
127
+ commandExecuted,
128
+ durationSeconds,
68
129
  };
69
130
  }
@@ -1,5 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import { runFfmpeg, ensureFileExists, ensureOutputDir } from "../utils/exec.js";
3
+ import { detectHwAccel } from "../utils/hwaccel.js";
4
+ import { probeMedia } from "./probe.js";
3
5
  export const changeSpeedSchema = z.object({
4
6
  inputPath: z.string().describe("Path to the source video or audio file"),
5
7
  outputPath: z.string().describe("Target output file path"),
@@ -20,10 +22,19 @@ function getAtempoFilter(speed) {
20
22
  filters.push(`atempo=${s.toFixed(4)}`);
21
23
  return filters.join(",");
22
24
  }
23
- export async function changeSpeed(params) {
25
+ export async function changeSpeed(params, options) {
24
26
  const { inputPath, outputPath, speed, muteAudio = false } = params;
25
27
  const input = await ensureFileExists(inputPath);
26
28
  const output = await ensureOutputDir(outputPath);
29
+ let expectedDuration;
30
+ try {
31
+ const probe = await probeMedia(input, { signal: options?.signal });
32
+ if (probe.format.durationSeconds > 0) {
33
+ expectedDuration = probe.format.durationSeconds / speed;
34
+ }
35
+ }
36
+ catch { }
37
+ const hwInfo = await detectHwAccel();
27
38
  const videoFilter = `setpts=${(1 / speed).toFixed(6)}*PTS`;
28
39
  const args = ["-i", input, "-filter:v", videoFilter];
29
40
  if (muteAudio) {
@@ -33,8 +44,18 @@ export async function changeSpeed(params) {
33
44
  const audioFilter = getAtempoFilter(speed);
34
45
  args.push("-filter:a", audioFilter);
35
46
  }
36
- args.push("-c:v", "libx264", "-pix_fmt", "yuv420p", "-movflags", "+faststart", "-y", output);
37
- const result = await runFfmpeg(args);
47
+ if (hwInfo.isAvailable) {
48
+ args.push("-c:v", hwInfo.h264Encoder, "-b:v", "4M");
49
+ }
50
+ else {
51
+ args.push("-c:v", "libx264", "-crf", "22", "-preset", "fast");
52
+ }
53
+ args.push("-pix_fmt", "yuv420p", "-movflags", "+faststart", "-y", output);
54
+ const result = await runFfmpeg(args, {
55
+ signal: options?.signal,
56
+ onProgress: options?.onProgress,
57
+ expectedDurationSeconds: expectedDuration,
58
+ });
38
59
  return {
39
60
  success: true,
40
61
  outputPath: output,
@@ -21,9 +21,9 @@ export const splitScreenSchema = z.object({
21
21
  hardwareAcceleration: z
22
22
  .boolean()
23
23
  .optional()
24
- .describe("Use Apple Silicon VideoToolbox encoding when available. Default: true."),
24
+ .describe("Use hardware-accelerated video encoding (VideoToolbox, NVENC, QSV, etc.) when available. Default: true."),
25
25
  });
26
- export async function createSplitScreen(params) {
26
+ export async function createSplitScreen(params, options) {
27
27
  const { firstVideoPath, secondVideoPath, outputPath, layout = "vertical_9_16", audioSource = "mix", subtitlesPath, hardwareAcceleration = true, } = params;
28
28
  const firstInput = await ensureFileExists(firstVideoPath);
29
29
  const secondInput = await ensureFileExists(secondVideoPath);
@@ -33,14 +33,16 @@ export async function createSplitScreen(params) {
33
33
  subInput = await ensureFileExists(subtitlesPath);
34
34
  }
35
35
  const [firstProbe, secondProbe] = await Promise.all([
36
- probeMedia(firstInput),
37
- probeMedia(secondInput),
36
+ probeMedia(firstInput, { signal: options?.signal }),
37
+ probeMedia(secondInput, { signal: options?.signal }),
38
38
  ]);
39
39
  const firstHasAudio = firstProbe.audioStreams.length > 0;
40
40
  const secondHasAudio = secondProbe.audioStreams.length > 0;
41
+ const estimatedDuration = Math.max(firstProbe.format.durationSeconds, secondProbe.format.durationSeconds);
41
42
  const hwInfo = await detectHwAccel();
42
43
  const useHw = hardwareAcceleration && hwInfo.isAvailable;
43
- const videoEncoder = useHw ? hwInfo.h264Encoder : "libx264";
44
+ const isHwUsed = useHw;
45
+ const videoEncoder = isHwUsed ? hwInfo.h264Encoder : "libx264";
44
46
  // Compute dimensions per tile
45
47
  let filter = "";
46
48
  let totalResolution = "1080x1920";
@@ -95,11 +97,11 @@ export async function createSplitScreen(params) {
95
97
  }
96
98
  if (hasSubtitles) {
97
99
  args.push("-map", "2:s");
98
- const isMp4 = output.endsWith(".mp4") || output.endsWith(".mov");
100
+ const isMp4 = output.toLowerCase().endsWith(".mp4") || output.toLowerCase().endsWith(".mov");
99
101
  args.push("-c:s", isMp4 ? "mov_text" : "srt");
100
102
  }
101
103
  args.push("-c:v", videoEncoder);
102
- if (videoEncoder === "h264_videotoolbox") {
104
+ if (isHwUsed) {
103
105
  args.push("-b:v", "4M", "-pix_fmt", "yuv420p");
104
106
  }
105
107
  else {
@@ -109,7 +111,11 @@ export async function createSplitScreen(params) {
109
111
  args.push("-c:a", "aac", "-b:a", "192k");
110
112
  }
111
113
  args.push("-movflags", "+faststart", "-y", output);
112
- const res = await runFfmpeg(args);
114
+ const res = await runFfmpeg(args, {
115
+ signal: options?.signal,
116
+ onProgress: options?.onProgress,
117
+ expectedDurationSeconds: estimatedDuration,
118
+ });
113
119
  return {
114
120
  success: true,
115
121
  outputPath: output,
@@ -118,7 +124,7 @@ export async function createSplitScreen(params) {
118
124
  audioSource,
119
125
  subtitlesEmbedded: hasSubtitles,
120
126
  encoderUsed: videoEncoder,
121
- hardwareAccelerated: videoEncoder.includes("videotoolbox"),
127
+ hardwareAccelerated: isHwUsed,
122
128
  commandExecuted: res.command,
123
129
  durationSeconds: res.durationSeconds,
124
130
  };
@@ -4,10 +4,20 @@ export const addSubtitlesSchema = z.object({
4
4
  videoPath: z.string().describe("Path to the source video file"),
5
5
  subtitlesPath: z.string().describe("Path to subtitle file (.srt or .vtt)"),
6
6
  outputPath: z.string().describe("Target output video path (.mp4, .mkv, or .mov)"),
7
- language: z.string().optional().default("eng").describe("ISO 639-2 three-letter language code (e.g. 'eng', 'spa', 'fra', 'deu')"),
8
- title: z.string().optional().default("English").describe("Subtitle track label displayed in video players"),
7
+ language: z
8
+ .string()
9
+ .regex(/^[a-zA-Z]{2,4}$/, "Must be an ISO 2-4 letter language code (e.g. 'eng')")
10
+ .optional()
11
+ .default("eng")
12
+ .describe("ISO 639-2 three-letter language code (e.g. 'eng', 'spa', 'fra', 'deu')"),
13
+ title: z
14
+ .string()
15
+ .max(100)
16
+ .optional()
17
+ .default("English")
18
+ .describe("Subtitle track label displayed in video players"),
9
19
  });
10
- export async function addSubtitles(params) {
20
+ export async function addSubtitles(params, options) {
11
21
  const { videoPath, subtitlesPath, outputPath, language = "eng", title = "English" } = params;
12
22
  const video = await ensureFileExists(videoPath);
13
23
  const subs = await ensureFileExists(subtitlesPath);
@@ -24,7 +34,10 @@ export async function addSubtitles(params) {
24
34
  "-metadata:s:s:0", `title=${title}`,
25
35
  "-y", output
26
36
  ];
27
- const result = await runFfmpeg(args);
37
+ const result = await runFfmpeg(args, {
38
+ signal: options?.signal,
39
+ onProgress: options?.onProgress,
40
+ });
28
41
  return {
29
42
  success: true,
30
43
  outputPath: output,
@@ -1,13 +1,29 @@
1
1
  import fs from "node:fs/promises";
2
- import { ensureFileExists, ensureOutputDir, runCommand } from "../utils/exec.js";
2
+ import { z } from "zod";
3
+ import { ensureFileExists, ensureOutputDir, runFfmpeg } from "../utils/exec.js";
3
4
  import { probeMedia } from "./probe.js";
4
- export async function extractThumbnail(options) {
5
- const input = await ensureFileExists(options.inputPath);
6
- const output = await ensureOutputDir(options.outputPath);
7
- let timestamp = options.timestamp || "00:00:01";
5
+ export const extractThumbnailSchema = z.object({
6
+ inputPath: z.string().describe("Path to the source video file."),
7
+ outputPath: z.string().describe("Destination image path ending in .png or .jpg (e.g. './thumb.png')."),
8
+ timestamp: z
9
+ .string()
10
+ .regex(/^((\d{1,2}:)?\d{1,2}:\d{1,2}(\.\d+)?|\d+(\.\d+)?|midpoint)$/i, "Timestamp must be 'HH:MM:SS', seconds (e.g. '10'), or 'midpoint'")
11
+ .optional()
12
+ .describe("Timestamp to capture, such as '00:00:05', '10', or 'midpoint' for the middle frame. Default: '00:00:01'."),
13
+ resolution: z
14
+ .string()
15
+ .regex(/^\d{2,5}x\d{2,5}$/, "Resolution must be formatted as 'WIDTHxHEIGHT' (e.g. '1280x720')")
16
+ .optional()
17
+ .describe("Optional scaled size formatted as 'WIDTHxHEIGHT', such as '1280x720'. Defaults to source resolution."),
18
+ includeBase64: z.boolean().optional().describe("Return base64 image data in response for vision models. Default: true."),
19
+ });
20
+ export async function extractThumbnail(params, options) {
21
+ const input = await ensureFileExists(params.inputPath);
22
+ const output = await ensureOutputDir(params.outputPath);
23
+ let timestamp = params.timestamp || "00:00:01";
8
24
  if (timestamp === "midpoint") {
9
25
  try {
10
- const info = await probeMedia(input);
26
+ const info = await probeMedia(input, { signal: options?.signal });
11
27
  const midpointSeconds = Math.max(0, Math.floor(info.format.durationSeconds / 2));
12
28
  timestamp = String(midpointSeconds);
13
29
  }
@@ -16,19 +32,18 @@ export async function extractThumbnail(options) {
16
32
  }
17
33
  }
18
34
  const args = [
19
- "-y",
20
35
  "-ss", timestamp,
21
36
  "-i", input,
22
37
  "-vframes", "1",
23
38
  ];
24
- if (options.resolution) {
25
- args.push("-vf", `scale=${options.resolution.replace("x", ":")}`);
39
+ if (params.resolution) {
40
+ args.push("-vf", `scale=${params.resolution.replace("x", ":")}`);
26
41
  }
27
- args.push(output);
28
- await runCommand("ffmpeg", args);
42
+ args.push("-y", output);
43
+ const res = await runFfmpeg(args, { signal: options?.signal });
29
44
  let base64;
30
45
  let mimeType;
31
- const shouldInclude = options.includeBase64 ?? true;
46
+ const shouldInclude = params.includeBase64 ?? true;
32
47
  if (shouldInclude) {
33
48
  try {
34
49
  const buffer = await fs.readFile(output);
@@ -44,7 +59,8 @@ export async function extractThumbnail(options) {
44
59
  return {
45
60
  outputPath: output,
46
61
  timestampUsed: timestamp,
47
- commandExecuted: `ffmpeg ${args.join(" ")}`,
62
+ commandExecuted: res.command,
63
+ durationSeconds: res.durationSeconds,
48
64
  base64,
49
65
  mimeType,
50
66
  };
@@ -1,29 +1,62 @@
1
- import { ensureFileExists, ensureOutputDir, runCommand } from "../utils/exec.js";
2
- export async function trimMedia(options) {
3
- const input = await ensureFileExists(options.inputPath);
4
- const output = await ensureOutputDir(options.outputPath);
1
+ import { z } from "zod";
2
+ import { ensureFileExists, ensureOutputDir, runFfmpeg } from "../utils/exec.js";
3
+ import { detectHwAccel } from "../utils/hwaccel.js";
4
+ export const trimMediaSchema = z.object({
5
+ inputPath: z.string().describe("Path to the source media file to cut."),
6
+ outputPath: z.string().describe("Destination path for the trimmed output file (e.g. './clip.mp4')."),
7
+ startTime: z
8
+ .string()
9
+ .regex(/^((\d{1,2}:)?\d{1,2}:\d{1,2}(\.\d+)?|\d+(\.\d+)?)$/, "startTime must be 'HH:MM:SS' (e.g. '00:01:30') or seconds (e.g. '90')")
10
+ .describe("Start timestamp formatted as 'HH:MM:SS' (e.g. '00:01:30') or seconds (e.g. '90')."),
11
+ endTime: z
12
+ .string()
13
+ .regex(/^((\d{1,2}:)?\d{1,2}:\d{1,2}(\.\d+)?|\d+(\.\d+)?)$/, "endTime must be 'HH:MM:SS' or seconds")
14
+ .optional()
15
+ .describe("Optional end timestamp formatted as 'HH:MM:SS' or seconds. Do not combine with duration."),
16
+ duration: z
17
+ .string()
18
+ .regex(/^(\d+(\.\d+)?)$/, "duration must be a positive number of seconds (e.g. '30')")
19
+ .optional()
20
+ .describe("Optional duration in seconds from startTime (e.g. '30'). If neither endTime nor duration is set, trims to end of file."),
21
+ accurateReencode: z
22
+ .boolean()
23
+ .optional()
24
+ .describe("Re-encode video for cuts between keyframes. Default: false (uses fast stream copy)."),
25
+ });
26
+ export async function trimMedia(params, options) {
27
+ const input = await ensureFileExists(params.inputPath);
28
+ const output = await ensureOutputDir(params.outputPath);
5
29
  const args = ["-y"];
6
30
  // Fast seek before -i
7
- args.push("-ss", options.startTime);
31
+ args.push("-ss", params.startTime);
8
32
  args.push("-i", input);
9
- if (options.endTime) {
10
- args.push("-to", options.endTime);
33
+ if (params.endTime) {
34
+ args.push("-to", params.endTime);
11
35
  }
12
- else if (options.duration) {
13
- args.push("-t", options.duration);
36
+ else if (params.duration) {
37
+ args.push("-t", params.duration);
14
38
  }
15
- if (options.accurateReencode) {
16
- // Re-encode for frame-accurate cut
17
- args.push("-c:v", "libx264", "-c:a", "aac");
39
+ if (params.accurateReencode) {
40
+ const hwInfo = await detectHwAccel();
41
+ if (hwInfo.isAvailable) {
42
+ args.push("-c:v", hwInfo.h264Encoder, "-b:v", "4M", "-c:a", "aac");
43
+ }
44
+ else {
45
+ args.push("-c:v", "libx264", "-crf", "22", "-preset", "fast", "-c:a", "aac");
46
+ }
18
47
  }
19
48
  else {
20
49
  // Lossless instantaneous stream copy
21
50
  args.push("-c", "copy");
22
51
  }
23
52
  args.push(output);
24
- await runCommand("ffmpeg", args);
53
+ const res = await runFfmpeg(args, {
54
+ signal: options?.signal,
55
+ onProgress: options?.onProgress,
56
+ });
25
57
  return {
26
58
  outputPath: output,
27
- commandExecuted: `ffmpeg ${args.join(" ")}`,
59
+ commandExecuted: res.command,
60
+ durationSeconds: res.durationSeconds,
28
61
  };
29
62
  }
@@ -6,11 +6,16 @@ export const generateWaveformSchema = z.object({
6
6
  outputPath: z.string().describe("Destination path for the PNG image."),
7
7
  width: z.number().int().positive().optional().default(1200).describe("Image width in pixels. Default: 1200."),
8
8
  height: z.number().int().positive().optional().default(280).describe("Image height in pixels. Default: 280."),
9
- color: z.string().optional().default("0x6366f1").describe("Waveform color in hex or name (such as '0x6366f1', 'white', or 'black'). Default: '0x6366f1'."),
9
+ color: z
10
+ .string()
11
+ .regex(/^(0x[0-9a-fA-F]{6}|#[0-9a-fA-F]{6}|[a-zA-Z]{3,20})$/, "Color must be hex (e.g. '0x6366f1', '#6366f1') or color name (e.g. 'white', 'black')")
12
+ .optional()
13
+ .default("0x6366f1")
14
+ .describe("Waveform color in hex or name (such as '0x6366f1', 'white', or 'black'). Default: '0x6366f1'."),
10
15
  scale: z.enum(["lin", "log", "sqrt"]).optional().default("lin").describe("Amplitude scale: 'lin', 'log', or 'sqrt'. Default: 'lin'."),
11
- includeBase64: z.boolean().optional().describe("Return base64 image data in the response for vision models. Default: true."),
16
+ includeBase64: z.boolean().optional().default(true).describe("Return base64 image data in the response for vision models. Default: true."),
12
17
  });
13
- export async function generateWaveform(params) {
18
+ export async function generateWaveform(params, options) {
14
19
  const { inputPath, outputPath, width = 1200, height = 280, color = "0x6366f1", scale = "lin", includeBase64 = true } = params;
15
20
  const input = await ensureFileExists(inputPath);
16
21
  const output = await ensureOutputDir(outputPath);
@@ -21,7 +26,7 @@ export async function generateWaveform(params) {
21
26
  "-vframes", "1",
22
27
  "-y", output
23
28
  ];
24
- const result = await runFfmpeg(args);
29
+ const result = await runFfmpeg(args, { signal: options?.signal });
25
30
  let base64;
26
31
  if (includeBase64) {
27
32
  try {
@@ -2,23 +2,102 @@ import { spawn } from "node:child_process";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  /**
5
- * Execute a command using spawn, capturing stdout and stderr.
5
+ * Execute a command using spawn, capturing stdout and stderr with cancellation and timeout support.
6
6
  */
7
- export async function runCommand(command, args) {
7
+ export async function runCommand(command, args, options) {
8
+ if (options?.signal?.aborted) {
9
+ throw new Error(`Command cancelled before launch: ${command}`);
10
+ }
8
11
  return new Promise((resolve, reject) => {
9
12
  const child = spawn(command, args);
10
13
  let stdout = "";
11
14
  let stderr = "";
15
+ let stdoutBuffer = "";
16
+ let stderrBuffer = "";
17
+ let timer = null;
18
+ let isCancelled = false;
19
+ const cleanup = () => {
20
+ if (timer) {
21
+ clearTimeout(timer);
22
+ timer = null;
23
+ }
24
+ if (options?.signal) {
25
+ options.signal.removeEventListener("abort", onAbort);
26
+ }
27
+ };
28
+ const onAbort = () => {
29
+ isCancelled = true;
30
+ try {
31
+ child.kill("SIGTERM");
32
+ setTimeout(() => {
33
+ try {
34
+ child.kill("SIGKILL");
35
+ }
36
+ catch { }
37
+ }, 1500);
38
+ }
39
+ catch { }
40
+ };
41
+ if (options?.signal) {
42
+ options.signal.addEventListener("abort", onAbort, { once: true });
43
+ }
44
+ if (options?.timeoutMs && options.timeoutMs > 0) {
45
+ timer = setTimeout(() => {
46
+ isCancelled = true;
47
+ try {
48
+ child.kill("SIGTERM");
49
+ setTimeout(() => {
50
+ try {
51
+ child.kill("SIGKILL");
52
+ }
53
+ catch { }
54
+ }, 1500);
55
+ }
56
+ catch { }
57
+ cleanup();
58
+ reject(new Error(`Command timed out after ${options.timeoutMs}ms: ${command}`));
59
+ }, options.timeoutMs);
60
+ }
12
61
  child.stdout.on("data", (data) => {
13
- stdout += data.toString();
62
+ const str = data.toString();
63
+ stdout += str;
64
+ if (options?.onStdoutLine) {
65
+ stdoutBuffer += str;
66
+ const lines = stdoutBuffer.split(/\r?\n/);
67
+ stdoutBuffer = lines.pop() || "";
68
+ for (const line of lines) {
69
+ options.onStdoutLine(line);
70
+ }
71
+ }
14
72
  });
15
73
  child.stderr.on("data", (data) => {
16
- stderr += data.toString();
74
+ const str = data.toString();
75
+ stderr += str;
76
+ if (options?.onStderrLine) {
77
+ stderrBuffer += str;
78
+ const lines = stderrBuffer.split(/\r?\n/);
79
+ stderrBuffer = lines.pop() || "";
80
+ for (const line of lines) {
81
+ options.onStderrLine(line);
82
+ }
83
+ }
17
84
  });
18
85
  child.on("error", (error) => {
86
+ cleanup();
19
87
  reject(new Error(`Failed to launch ${command}: ${error.message}`));
20
88
  });
21
89
  child.on("close", (code) => {
90
+ cleanup();
91
+ if (options?.onStdoutLine && stdoutBuffer.length > 0) {
92
+ options.onStdoutLine(stdoutBuffer);
93
+ }
94
+ if (options?.onStderrLine && stderrBuffer.length > 0) {
95
+ options.onStderrLine(stderrBuffer);
96
+ }
97
+ if (isCancelled || options?.signal?.aborted) {
98
+ reject(new Error(`FFmpeg operation was cancelled by client.`));
99
+ return;
100
+ }
22
101
  const exitCode = code ?? 0;
23
102
  if (exitCode !== 0) {
24
103
  reject(new Error(`${command} exited with code ${exitCode}:\n${stderr || stdout}`));
@@ -30,14 +109,66 @@ export async function runCommand(command, args) {
30
109
  });
31
110
  }
32
111
  /**
33
- * Convenience wrapper for running ffmpeg commands with execution timing.
112
+ * Convenience wrapper for running ffmpeg commands with execution timing,
113
+ * progress tracking (-progress pipe:1), and cancellation.
34
114
  */
35
- export async function runFfmpeg(args) {
115
+ export async function runFfmpeg(args, options) {
36
116
  const startTime = Date.now();
37
- const res = await runCommand("ffmpeg", args);
117
+ const effectiveArgs = [...args];
118
+ let currentProgress = {};
119
+ const onStdoutLine = (line) => {
120
+ const trimmed = line.trim();
121
+ if (!trimmed)
122
+ return;
123
+ const [key, value] = trimmed.split("=");
124
+ if (!key || value === undefined)
125
+ return;
126
+ if (key === "frame") {
127
+ const frameNum = parseInt(value, 10);
128
+ if (!isNaN(frameNum))
129
+ currentProgress.frame = frameNum;
130
+ }
131
+ else if (key === "fps") {
132
+ const fpsNum = parseFloat(value);
133
+ if (!isNaN(fpsNum))
134
+ currentProgress.fps = fpsNum;
135
+ }
136
+ else if (key === "speed") {
137
+ currentProgress.speed = value.trim();
138
+ }
139
+ else if (key === "out_time_us") {
140
+ const us = parseInt(value, 10);
141
+ if (!isNaN(us)) {
142
+ currentProgress.timeSeconds = Number((us / 1_000_000).toFixed(2));
143
+ if (options?.expectedDurationSeconds && options.expectedDurationSeconds > 0) {
144
+ const pct = Math.min(100, Math.max(0, Math.round((currentProgress.timeSeconds / options.expectedDurationSeconds) * 100)));
145
+ currentProgress.percent = pct;
146
+ }
147
+ }
148
+ }
149
+ else if (key === "progress") {
150
+ if (value === "end") {
151
+ currentProgress.isEnd = true;
152
+ if (options?.expectedDurationSeconds) {
153
+ currentProgress.percent = 100;
154
+ }
155
+ }
156
+ if (options?.onProgress) {
157
+ options.onProgress({ ...currentProgress });
158
+ }
159
+ }
160
+ };
161
+ // If progress callback provided, inject -progress pipe:1 before output arguments
162
+ if (options?.onProgress && !effectiveArgs.includes("-progress")) {
163
+ effectiveArgs.unshift("-progress", "pipe:1");
164
+ }
165
+ const res = await runCommand("ffmpeg", effectiveArgs, {
166
+ ...options,
167
+ onStdoutLine: options?.onProgress ? onStdoutLine : options?.onStdoutLine,
168
+ });
38
169
  const durationSeconds = Number(((Date.now() - startTime) / 1000).toFixed(2));
39
170
  return {
40
- command: `ffmpeg ${args.join(" ")}`,
171
+ command: `ffmpeg ${effectiveArgs.join(" ")}`,
41
172
  stdout: res.stdout,
42
173
  stderr: res.stderr,
43
174
  durationSeconds,