@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.
package/dist/index.js CHANGED
@@ -2,11 +2,11 @@
2
2
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
3
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
4
  import { z } from "zod";
5
- import { probeMedia } from "./tools/probe.js";
6
- import { convertMedia } from "./tools/convert.js";
7
- import { trimMedia } from "./tools/trim.js";
8
- import { extractAudio } from "./tools/audio.js";
9
- import { extractThumbnail } from "./tools/thumbnail.js";
5
+ import { probeMedia, probeMediaSchema } from "./tools/probe.js";
6
+ import { convertMedia, convertMediaSchema } from "./tools/convert.js";
7
+ import { trimMedia, trimMediaSchema } from "./tools/trim.js";
8
+ import { extractAudio, extractAudioSchema } from "./tools/audio.js";
9
+ import { extractThumbnail, extractThumbnailSchema } from "./tools/thumbnail.js";
10
10
  import { compressMedia, compressMediaSchema } from "./tools/compress.js";
11
11
  import { concatMedia, concatMediaSchema } from "./tools/concat.js";
12
12
  import { generateWaveform, generateWaveformSchema } from "./tools/waveform.js";
@@ -15,16 +15,39 @@ import { changeSpeed, changeSpeedSchema } from "./tools/speed.js";
15
15
  import { reformatAspectRatio, reformatAspectSchema } from "./tools/reformat.js";
16
16
  import { trimSilence, trimSilenceSchema } from "./tools/silence.js";
17
17
  import { createSplitScreen, splitScreenSchema } from "./tools/split.js";
18
+ import { burnSubtitles, burnSubtitlesSchema } from "./tools/burn_subtitles.js";
19
+ import { extractKeyframes, extractKeyframesSchema } from "./tools/keyframes.js";
20
+ import { normalizeAudio, normalizeAudioSchema } from "./tools/normalize.js";
21
+ import { addOverlay, addOverlaySchema } from "./tools/overlay.js";
22
+ import { detectHwAccel } from "./utils/hwaccel.js";
23
+ import { runCommand } from "./utils/exec.js";
18
24
  const server = new McpServer({
19
25
  name: "ffmpeg-mcp-server",
20
- version: "0.4.0",
26
+ version: "0.5.0",
21
27
  });
28
+ function createProgressCallback(extra) {
29
+ return (p) => {
30
+ if (extra._meta?.progressToken !== undefined && typeof extra.sendNotification === "function") {
31
+ extra
32
+ .sendNotification({
33
+ method: "notifications/progress",
34
+ params: {
35
+ progressToken: extra._meta.progressToken,
36
+ progress: p.percent ?? (p.timeSeconds ? Math.round(p.timeSeconds) : 0),
37
+ total: 100,
38
+ message: p.percent
39
+ ? `Processing: ${p.percent}% (speed: ${p.speed || "N/A"})`
40
+ : `Processing media (${p.timeSeconds || 0}s rendered)...`,
41
+ },
42
+ })
43
+ .catch(() => { });
44
+ }
45
+ };
46
+ }
22
47
  // Tool 1: Probe Media
23
- server.tool("media_probe", "Inspect audio and video files with ffprobe. Returns container metadata, stream details, codecs, resolution, bitrate, and duration as JSON.", {
24
- inputPath: z.string().describe("Path to the media file to inspect (e.g. './video.mp4')"),
25
- }, async ({ inputPath }) => {
48
+ server.tool("media_probe", "Inspect audio and video files with ffprobe. Returns container metadata, stream details, codecs, resolution, bitrate, and duration as JSON.", probeMediaSchema.shape, async ({ inputPath }, extra) => {
26
49
  try {
27
- const result = await probeMedia(inputPath);
50
+ const result = await probeMedia(inputPath, { signal: extra.signal });
28
51
  return {
29
52
  content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
30
53
  };
@@ -37,40 +60,15 @@ server.tool("media_probe", "Inspect audio and video files with ffprobe. Returns
37
60
  }
38
61
  });
39
62
  // Tool 2: Convert Media
40
- server.tool("media_convert", "Convert video and audio files between formats. Includes presets for web MP4 (H.264/AAC), WebM (VP9/Opus), and animated GIF. Supports Apple Silicon hardware encoding.", {
41
- inputPath: z.string().describe("Path to the source media file to convert"),
42
- outputPath: z.string().describe("Destination path for the converted file (e.g. ./output.mp4, ./output.webm, ./animation.gif)"),
43
- preset: z
44
- .enum(["web_mp4", "webm", "gif", "auto"])
45
- .optional()
46
- .describe("Encoding preset: 'web_mp4' for browser playback, 'webm' for WebM video, 'gif' for animated GIF, or 'auto'. Default: 'auto'."),
47
- crf: z
48
- .number()
49
- .min(0)
50
- .max(51)
51
- .optional()
52
- .describe("Quality factor from 0 to 51. Lower numbers mean higher quality. Default: 23 for MP4, 30 for WebM."),
53
- resolution: z
54
- .string()
55
- .optional()
56
- .describe("Target size formatted as 'WIDTHxHEIGHT', such as '1920x1080' or '1280x720'"),
57
- fps: z
58
- .number()
59
- .positive()
60
- .optional()
61
- .describe("Target frame rate in frames per second, such as 30, 60, or 15"),
62
- hardwareAcceleration: z
63
- .boolean()
64
- .optional()
65
- .describe("Use Apple Silicon VideoToolbox encoding when available. Default: true."),
66
- }, async (args) => {
63
+ server.tool("media_convert", "Convert video and audio files between formats. Includes presets for web MP4 (H.264/AAC), WebM (VP9/Opus), and animated GIF. Supports hardware acceleration on Apple Silicon, NVIDIA, Intel, and AMD.", convertMediaSchema.shape, async (args, extra) => {
67
64
  try {
68
- const result = await convertMedia(args);
65
+ const onProgress = createProgressCallback(extra);
66
+ const result = await convertMedia(args, { signal: extra.signal, onProgress });
69
67
  return {
70
68
  content: [
71
69
  {
72
70
  type: "text",
73
- text: `Successfully converted media:\nOutput: ${result.outputPath}\nHardware Accelerated: ${result.hardwareAccelerated}\nCommand: ${result.commandExecuted}`,
71
+ text: `Successfully converted media:\nOutput: ${result.outputPath}\nEncoder: ${result.encoderUsed} (Hardware Accelerated: ${result.hardwareAccelerated})\nCommand: ${result.commandExecuted}`,
74
72
  },
75
73
  ],
76
74
  };
@@ -83,19 +81,10 @@ server.tool("media_convert", "Convert video and audio files between formats. Inc
83
81
  }
84
82
  });
85
83
  // Tool 3: Trim Media
86
- server.tool("trim_media", "Cut a segment from a video or audio file. Uses stream copy without re-encoding by default, or re-encodes when accurate cuts are needed.", {
87
- inputPath: z.string().describe("Path to the source media file to cut."),
88
- outputPath: z.string().describe("Destination path for the trimmed output file (e.g. './clip.mp4')."),
89
- startTime: z.string().describe("Start timestamp formatted as 'HH:MM:SS' (e.g. '00:01:30') or seconds (e.g. '90')."),
90
- endTime: z.string().optional().describe("Optional end timestamp formatted as 'HH:MM:SS' or seconds. Do not combine with duration."),
91
- duration: z.string().optional().describe("Optional duration in seconds from startTime (e.g. '30'). If neither endTime nor duration is set, trims to end of file."),
92
- accurateReencode: z
93
- .boolean()
94
- .optional()
95
- .describe("Re-encode video for cuts between keyframes. Default: false (uses fast stream copy)."),
96
- }, async (args) => {
84
+ server.tool("trim_media", "Cut a segment from a video or audio file. Uses stream copy without re-encoding by default, or re-encodes when accurate cuts are needed.", trimMediaSchema.shape, async (args, extra) => {
97
85
  try {
98
- const result = await trimMedia(args);
86
+ const onProgress = createProgressCallback(extra);
87
+ const result = await trimMedia(args, { signal: extra.signal, onProgress });
99
88
  return {
100
89
  content: [
101
90
  {
@@ -113,22 +102,15 @@ server.tool("trim_media", "Cut a segment from a video or audio file. Uses stream
113
102
  }
114
103
  });
115
104
  // Tool 4: Extract Audio
116
- server.tool("extract_audio", "Extract an audio track from a video file into a standalone audio file. Supports the 'whisper_wav' preset (16kHz mono WAV) for speech recognition models, plus MP3, AAC, FLAC, and stream copy.", {
117
- inputPath: z.string().describe("Path to the source video or audio file."),
118
- outputPath: z.string().describe("Destination path for the output audio file (e.g. './extracted.wav' or './audio.mp3')."),
119
- format: z
120
- .enum(["whisper_wav", "mp3", "aac", "flac", "copy"])
121
- .optional()
122
- .describe("Audio format: 'whisper_wav' (16kHz mono WAV for Whisper), 'mp3', 'aac', 'flac', or 'copy' (extract without re-encoding)."),
123
- bitrate: z.string().optional().describe("Target audio bitrate for MP3 or AAC (e.g. '128k', '192k', '320k')."),
124
- }, async (args) => {
105
+ server.tool("extract_audio", "Extract an audio track from a video file into a standalone audio file. Supports the 'whisper_wav' preset (16kHz mono WAV) for speech recognition models, plus MP3, AAC, FLAC, and stream copy.", extractAudioSchema.shape, async (args, extra) => {
125
106
  try {
126
- const result = await extractAudio(args);
107
+ const onProgress = createProgressCallback(extra);
108
+ const result = await extractAudio(args, { signal: extra.signal, onProgress });
127
109
  return {
128
110
  content: [
129
111
  {
130
112
  type: "text",
131
- text: `Successfully extracted audio:\nOutput: ${result.outputPath}\nCommand: ${result.commandExecuted}`,
113
+ text: `Successfully extracted audio:\nOutput: ${result.outputPath}\nFormat: ${result.format}\nCommand: ${result.commandExecuted}`,
132
114
  },
133
115
  ],
134
116
  };
@@ -141,18 +123,9 @@ server.tool("extract_audio", "Extract an audio track from a video file into a st
141
123
  }
142
124
  });
143
125
  // Tool 5: Extract Thumbnail
144
- server.tool("extract_thumbnail", "Capture a still image from a video. Returns the saved image path and inlined base64 image data so vision models can inspect the frame.", {
145
- inputPath: z.string().describe("Path to the source video file."),
146
- outputPath: z.string().describe("Destination image path ending in .png or .jpg (e.g. './thumb.png')."),
147
- timestamp: z
148
- .string()
149
- .optional()
150
- .describe("Timestamp to capture, such as '00:00:05', '10', or 'midpoint' for the middle frame. Default: '00:00:01'."),
151
- resolution: z.string().optional().describe("Optional scaled size formatted as 'WIDTHxHEIGHT', such as '1280x720'. Defaults to source resolution."),
152
- includeBase64: z.boolean().optional().describe("Return base64 image data in response for vision models. Default: true."),
153
- }, async (args) => {
126
+ server.tool("extract_thumbnail", "Capture a single still image from a video. Returns the saved image path and inlined base64 image data so vision models can inspect the frame.", extractThumbnailSchema.shape, async (args, extra) => {
154
127
  try {
155
- const result = await extractThumbnail(args);
128
+ const result = await extractThumbnail(args, { signal: extra.signal });
156
129
  const content = [];
157
130
  if (result.base64 && result.mimeType) {
158
131
  content.push({
@@ -175,9 +148,10 @@ server.tool("extract_thumbnail", "Capture a still image from a video. Returns th
175
148
  }
176
149
  });
177
150
  // Tool 6: Compress Video
178
- server.tool("compress_video", "Compress video files to fit upload limits (such as GitHub PRs under 10MB or Discord under 25MB) using target file sizes or CRF quality levels. Does not modify the original file.", compressMediaSchema.shape, async (args) => {
151
+ server.tool("compress_video", "Compress video files to fit upload limits (such as GitHub PRs under 10MB or Discord under 25MB) using target file sizes or CRF quality levels. Does not modify the original file.", compressMediaSchema.shape, async (args, extra) => {
179
152
  try {
180
- const result = await compressMedia(args);
153
+ const onProgress = createProgressCallback(extra);
154
+ const result = await compressMedia(args, { signal: extra.signal, onProgress });
181
155
  return {
182
156
  content: [
183
157
  {
@@ -195,9 +169,10 @@ server.tool("compress_video", "Compress video files to fit upload limits (such a
195
169
  }
196
170
  });
197
171
  // Tool 7: Concat Media
198
- server.tool("concat_media", "Join multiple video or audio files in order into a single file. Uses stream copy for matching files or re-encodes when formats differ.", concatMediaSchema.shape, async (args) => {
172
+ server.tool("concat_media", "Join multiple video or audio files in order into a single file. Uses stream copy for matching files or re-encodes when formats differ.", concatMediaSchema.shape, async (args, extra) => {
199
173
  try {
200
- const result = await concatMedia(args);
174
+ const onProgress = createProgressCallback(extra);
175
+ const result = await concatMedia(args, { signal: extra.signal, onProgress });
201
176
  return {
202
177
  content: [
203
178
  {
@@ -215,9 +190,9 @@ server.tool("concat_media", "Join multiple video or audio files in order into a
215
190
  }
216
191
  });
217
192
  // Tool 8: Generate Waveform
218
- server.tool("generate_waveform", "Generate a PNG waveform image from an audio or video file. Returns the file path and inlined base64 image data.", generateWaveformSchema.shape, async (args) => {
193
+ server.tool("generate_waveform", "Generate a PNG waveform image from an audio or video file. Returns the file path and inlined base64 image data.", generateWaveformSchema.shape, async (args, extra) => {
219
194
  try {
220
- const result = await generateWaveform(args);
195
+ const result = await generateWaveform(args, { signal: extra.signal });
221
196
  const content = [];
222
197
  if (result.base64) {
223
198
  content.push({
@@ -239,10 +214,11 @@ server.tool("generate_waveform", "Generate a PNG waveform image from an audio or
239
214
  };
240
215
  }
241
216
  });
242
- // Tool 9: Add Subtitles
243
- server.tool("add_subtitles", "Embed an SRT or VTT subtitle track into a video file without re-encoding the video stream.", addSubtitlesSchema.shape, async (args) => {
217
+ // Tool 9: Add Subtitles (Soft Embedded)
218
+ server.tool("add_subtitles", "Embed an SRT or VTT subtitle track into a video container (mov_text for MP4, srt for MKV) without re-encoding the video stream.", addSubtitlesSchema.shape, async (args, extra) => {
244
219
  try {
245
- const result = await addSubtitles(args);
220
+ const onProgress = createProgressCallback(extra);
221
+ const result = await addSubtitles(args, { signal: extra.signal, onProgress });
246
222
  return {
247
223
  content: [
248
224
  {
@@ -260,9 +236,10 @@ server.tool("add_subtitles", "Embed an SRT or VTT subtitle track into a video fi
260
236
  }
261
237
  });
262
238
  // Tool 10: Change Speed
263
- server.tool("change_speed", "Change video and audio playback speed (such as 2x for fast forward or 0.5x for slow motion) with pitch correction.", changeSpeedSchema.shape, async (args) => {
239
+ server.tool("change_speed", "Change video and audio playback speed (such as 2x for fast forward or 0.5x for slow motion) with pitch correction.", changeSpeedSchema.shape, async (args, extra) => {
264
240
  try {
265
- const result = await changeSpeed(args);
241
+ const onProgress = createProgressCallback(extra);
242
+ const result = await changeSpeed(args, { signal: extra.signal, onProgress });
266
243
  return {
267
244
  content: [
268
245
  {
@@ -280,9 +257,10 @@ server.tool("change_speed", "Change video and audio playback speed (such as 2x f
280
257
  }
281
258
  });
282
259
  // Tool 11: Reformat Aspect Ratio
283
- server.tool("reformat_aspect_ratio", "Change video aspect ratio to 9:16 vertical, 1:1 square, or 4:5 portrait. Adds blurred video borders, solid padding, or center crops.", reformatAspectSchema.shape, async (args) => {
260
+ server.tool("reformat_aspect_ratio", "Change video aspect ratio to 9:16 vertical, 1:1 square, or 4:5 portrait. Adds blurred video borders, solid padding, or center crops.", reformatAspectSchema.shape, async (args, extra) => {
284
261
  try {
285
- const result = await reformatAspectRatio(args);
262
+ const onProgress = createProgressCallback(extra);
263
+ const result = await reformatAspectRatio(args, { signal: extra.signal, onProgress });
286
264
  return {
287
265
  content: [
288
266
  {
@@ -300,9 +278,10 @@ server.tool("reformat_aspect_ratio", "Change video aspect ratio to 9:16 vertical
300
278
  }
301
279
  });
302
280
  // Tool 12: Trim Silence
303
- server.tool("trim_silence", "Detect and remove silent pauses from audio or video files. Returns the duration and seconds saved.", trimSilenceSchema.shape, async (args) => {
281
+ server.tool("trim_silence", "Detect and remove silent pauses from audio or video files. Preserves video & audio lip-sync in 'start_end' mode. Returns original duration and seconds saved.", trimSilenceSchema.shape, async (args, extra) => {
304
282
  try {
305
- const result = await trimSilence(args);
283
+ const onProgress = createProgressCallback(extra);
284
+ const result = await trimSilence(args, { signal: extra.signal, onProgress });
306
285
  return {
307
286
  content: [
308
287
  {
@@ -320,9 +299,10 @@ server.tool("trim_silence", "Detect and remove silent pauses from audio or video
320
299
  }
321
300
  });
322
301
  // Tool 13: Create Split Screen
323
- server.tool("create_split_screen", "Combine two video files into a split-screen video. Stacks clips vertically (1080x1920 for Reels and TikTok) or places them side-by-side. Supports audio mixing and subtitle embedding.", splitScreenSchema.shape, async (args) => {
302
+ server.tool("create_split_screen", "Combine two video files into a split-screen video. Stacks clips vertically (1080x1920 for Reels and TikTok) or places them side-by-side. Supports audio mixing and subtitle embedding.", splitScreenSchema.shape, async (args, extra) => {
324
303
  try {
325
- const result = await createSplitScreen(args);
304
+ const onProgress = createProgressCallback(extra);
305
+ const result = await createSplitScreen(args, { signal: extra.signal, onProgress });
326
306
  return {
327
307
  content: [
328
308
  {
@@ -339,10 +319,222 @@ server.tool("create_split_screen", "Combine two video files into a split-screen
339
319
  };
340
320
  }
341
321
  });
322
+ // Tool 14: Burn Subtitles (Hardcoded)
323
+ server.tool("burn_subtitles", "Hardcode/burn subtitles directly into video frames with customizable font size, colors, and positioning. Unlike soft subtitles, burned subtitles render on all platforms including TikTok, Instagram Reels, and YouTube Shorts.", burnSubtitlesSchema.shape, async (args, extra) => {
324
+ try {
325
+ const onProgress = createProgressCallback(extra);
326
+ const result = await burnSubtitles(args, { signal: extra.signal, onProgress });
327
+ return {
328
+ content: [
329
+ {
330
+ type: "text",
331
+ text: `Successfully burned subtitles into video:\nOutput: ${result.outputPath}\nSubtitles: ${result.subtitlesBurned}\nFont Size: ${result.fontSize}pt (${result.fontColor})\nEncoder: ${result.encoderUsed} (Hardware Accelerated: ${result.hardwareAccelerated})\nCommand: ${result.commandExecuted}`,
332
+ },
333
+ ],
334
+ };
335
+ }
336
+ catch (err) {
337
+ return {
338
+ isError: true,
339
+ content: [{ type: "text", text: `Error burning subtitles: ${err.message}` }],
340
+ };
341
+ }
342
+ });
343
+ // Tool 15: Extract Keyframes (Multi-Frame / Contact Sheet)
344
+ server.tool("extract_keyframes", "Extract multiple representative frames across a video's timeline. In 'montage' mode, merges frames into a single contact-sheet grid image and inlines base64 for vision models to inspect the whole video at once.", extractKeyframesSchema.shape, async (args, extra) => {
345
+ try {
346
+ const result = await extractKeyframes(args, { signal: extra.signal });
347
+ const content = [];
348
+ if (result.base64 && result.mimeType) {
349
+ content.push({
350
+ type: "image",
351
+ data: result.base64,
352
+ mimeType: result.mimeType,
353
+ });
354
+ }
355
+ content.push({
356
+ type: "text",
357
+ text: `Successfully extracted ${result.frameCount} keyframes:\nOutput: ${result.outputPath}\nLayout: ${result.layout}${result.gridDimensions ? ` (${result.gridDimensions} grid)` : ""}\nCommand: ${result.commandExecuted}`,
358
+ });
359
+ return { content };
360
+ }
361
+ catch (err) {
362
+ return {
363
+ isError: true,
364
+ content: [{ type: "text", text: `Error extracting keyframes: ${err.message}` }],
365
+ };
366
+ }
367
+ });
368
+ // Tool 16: Normalize Audio (Loudnorm / EBU R128)
369
+ server.tool("normalize_audio", "Normalize audio loudness using the broadcast standard EBU R128 (loudnorm). Supports -16 LUFS (podcasts/Reels), -14 LUFS (YouTube), and optional voice clarity enhancement (80Hz high-pass to remove mic rumble). Works on audio or video files.", normalizeAudioSchema.shape, async (args, extra) => {
370
+ try {
371
+ const onProgress = createProgressCallback(extra);
372
+ const result = await normalizeAudio(args, { signal: extra.signal, onProgress });
373
+ return {
374
+ content: [
375
+ {
376
+ type: "text",
377
+ text: `Successfully normalized audio loudness:\nOutput: ${result.outputPath}\nTarget LUFS: ${result.targetLufs} LUFS (Peak: ${result.targetPeakDb} dBTP)\nVoice Clarity: ${result.voiceClarityEnabled ? "Enabled" : "Disabled"}\nMedia Type: ${result.isVideo ? "Video (lossless video stream copy)" : "Audio"}\nCommand: ${result.commandExecuted}`,
378
+ },
379
+ ],
380
+ };
381
+ }
382
+ catch (err) {
383
+ return {
384
+ isError: true,
385
+ content: [{ type: "text", text: `Error normalizing audio: ${err.message}` }],
386
+ };
387
+ }
388
+ });
389
+ // Tool 17: Add Overlay (Watermark / Branding)
390
+ server.tool("add_overlay", "Place a watermark image, logo PNG, or branding graphic over a video with customizable position, padding, scaling, and opacity.", addOverlaySchema.shape, async (args, extra) => {
391
+ try {
392
+ const onProgress = createProgressCallback(extra);
393
+ const result = await addOverlay(args, { signal: extra.signal, onProgress });
394
+ return {
395
+ content: [
396
+ {
397
+ type: "text",
398
+ text: `Successfully added overlay:\nOutput: ${result.outputPath}\nPosition: ${result.position} (padding: ${result.padding}px)\nOpacity: ${result.opacity}\nEncoder: ${result.encoderUsed} (Hardware Accelerated: ${result.hardwareAccelerated})\nCommand: ${result.commandExecuted}`,
399
+ },
400
+ ],
401
+ };
402
+ }
403
+ catch (err) {
404
+ return {
405
+ isError: true,
406
+ content: [{ type: "text", text: `Error adding overlay: ${err.message}` }],
407
+ };
408
+ }
409
+ });
410
+ // Resource 1: Capabilities & Hardware Info
411
+ server.registerResource("system_capabilities", "media://capabilities", {
412
+ title: "FFmpeg System Capabilities",
413
+ description: "Detected FFmpeg version, hardware acceleration devices, and available video encoders.",
414
+ mimeType: "application/json",
415
+ }, async () => {
416
+ const hwInfo = await detectHwAccel();
417
+ let versionStr = "unknown";
418
+ try {
419
+ const res = await runCommand("ffmpeg", ["-version"]);
420
+ const firstLine = res.stdout.split("\n")[0] || "";
421
+ versionStr = firstLine.replace(/^ffmpeg version\s*/, "").split(" ")[0];
422
+ }
423
+ catch { }
424
+ const data = {
425
+ ffmpegVersion: versionStr,
426
+ hardwareAcceleration: {
427
+ isAvailable: hwInfo.isAvailable,
428
+ primaryType: hwInfo.hardwareType,
429
+ supportedTypes: hwInfo.availableTypes,
430
+ h264Encoder: hwInfo.h264Encoder,
431
+ hevcEncoder: hwInfo.hevcEncoder,
432
+ },
433
+ availableEncoders: hwInfo.encoders,
434
+ totalToolsActive: 17,
435
+ };
436
+ return {
437
+ contents: [
438
+ {
439
+ uri: "media://capabilities",
440
+ mimeType: "application/json",
441
+ text: JSON.stringify(data, null, 2),
442
+ },
443
+ ],
444
+ };
445
+ });
446
+ // Resource 2: Social Presets & Standards
447
+ server.registerResource("social_presets", "media://presets", {
448
+ title: "Media Presets and Guidelines",
449
+ description: "Aspect ratio standards, loudness limits, and upload specifications for social media platforms.",
450
+ mimeType: "application/json",
451
+ }, async () => {
452
+ const presets = {
453
+ aspectRatios: {
454
+ vertical_9_16: { resolution: "1080x1920", platforms: ["TikTok", "Instagram Reels", "YouTube Shorts"] },
455
+ horizontal_16_9: { resolution: "1920x1080", platforms: ["YouTube", "Twitter/X", "Vimeo"] },
456
+ square_1_1: { resolution: "1080x1080", platforms: ["Instagram Post", "LinkedIn"] },
457
+ portrait_4_5: { resolution: "1080x1350", platforms: ["Instagram Feed"] },
458
+ },
459
+ targetSizes: {
460
+ github_pr: { maxMB: 10, recommendedPreset: "github_pr" },
461
+ discord_free: { maxMB: 25, recommendedPreset: "discord" },
462
+ email_attachment: { maxMB: 15, recommendedPreset: "email" },
463
+ },
464
+ audioStandards: {
465
+ podcast_and_shorts: { lufs: -16, peakDb: -1.5 },
466
+ youtube: { lufs: -14, peakDb: -1.0 },
467
+ broadcast_ebu_r128: { lufs: -23, peakDb: -1.0 },
468
+ speech_recognition: { sampleRate: 16000, channels: 1, codec: "pcm_s16le" },
469
+ },
470
+ };
471
+ return {
472
+ contents: [
473
+ {
474
+ uri: "media://presets",
475
+ mimeType: "application/json",
476
+ text: JSON.stringify(presets, null, 2),
477
+ },
478
+ ],
479
+ };
480
+ });
481
+ // Prompt 1: Social Media Clip Generator
482
+ server.registerPrompt("social_clip_generator", {
483
+ title: "Generate Viral Social Media Clip",
484
+ description: "Step-by-step workflow for turning landscape footage into a 9:16 vertical short with burned subtitles.",
485
+ argsSchema: {
486
+ inputPath: z.string().describe("Path to the source landscape video"),
487
+ subtitlesPath: z.string().optional().describe("Optional path to subtitles file (.srt)"),
488
+ },
489
+ }, async ({ inputPath, subtitlesPath }) => {
490
+ return {
491
+ messages: [
492
+ {
493
+ role: "user",
494
+ content: {
495
+ type: "text",
496
+ text: `Please convert this video into a 9:16 vertical reel suitable for TikTok, Instagram Reels, and YouTube Shorts:
497
+ Source Video: ${inputPath}
498
+ ${subtitlesPath ? `Subtitles: ${subtitlesPath}` : "No separate subtitles provided."}
499
+
500
+ Recommended workflow:
501
+ 1. Use 'media_probe' to check duration and resolution.
502
+ 2. Use 'reformat_aspect_ratio' with targetRatio: '9:16' and mode: 'blur_background'.
503
+ 3. Use 'trim_silence' with mode: 'start_end' to eliminate dead air at the beginning and end.
504
+ 4. If subtitles are available, use 'burn_subtitles' to hardcode visible captions for mobile viewers.
505
+ 5. Use 'normalize_audio' with targetLufs: -16 to ensure consistent loudness.`,
506
+ },
507
+ },
508
+ ],
509
+ };
510
+ });
511
+ // Prompt 2: Whisper Transcription Prep
512
+ server.registerPrompt("whisper_audio_prep", {
513
+ title: "Prepare Media for Whisper Speech Recognition",
514
+ description: "Extract and normalize 16kHz mono audio optimized for Whisper and local STT models.",
515
+ argsSchema: {
516
+ inputPath: z.string().describe("Path to video or audio file"),
517
+ },
518
+ }, async ({ inputPath }) => {
519
+ return {
520
+ messages: [
521
+ {
522
+ role: "user",
523
+ content: {
524
+ type: "text",
525
+ text: `Extract the audio from '${inputPath}' for speech-to-text processing:
526
+ 1. Use 'extract_audio' with format: 'whisper_wav' (16kHz mono PCM WAV).
527
+ 2. If the audio is quiet, use 'normalize_audio' with voiceClarity: true.
528
+ 3. Pass the resulting WAV to your speech recognition tool.`,
529
+ },
530
+ },
531
+ ],
532
+ };
533
+ });
342
534
  async function main() {
343
535
  const transport = new StdioServerTransport();
344
536
  await server.connect(transport);
345
- console.error("FFmpeg MCP Server running on stdio (13 tools active)");
537
+ console.error("FFmpeg MCP Server running on stdio (17 tools, 2 resources, 2 prompts active)");
346
538
  }
347
539
  main().catch((err) => {
348
540
  console.error("Fatal error starting FFmpeg MCP server:", err);
@@ -1,8 +1,18 @@
1
- import { ensureFileExists, ensureOutputDir, runCommand } from "../utils/exec.js";
2
- export async function extractAudio(options) {
3
- const input = await ensureFileExists(options.inputPath);
4
- const output = await ensureOutputDir(options.outputPath);
5
- const format = options.format || "mp3";
1
+ import { z } from "zod";
2
+ import { ensureFileExists, ensureOutputDir, runFfmpeg } from "../utils/exec.js";
3
+ export const extractAudioSchema = z.object({
4
+ inputPath: z.string().describe("Path to the source video or audio file."),
5
+ outputPath: z.string().describe("Destination path for the output audio file (e.g. './extracted.wav' or './audio.mp3')."),
6
+ format: z
7
+ .enum(["whisper_wav", "mp3", "aac", "flac", "copy"])
8
+ .optional()
9
+ .describe("Audio format: 'whisper_wav' (16kHz mono WAV for Whisper), 'mp3', 'aac', 'flac', or 'copy' (extract without re-encoding). Default: 'mp3'."),
10
+ bitrate: z.string().optional().describe("Target audio bitrate for MP3 or AAC (e.g. '128k', '192k', '320k')."),
11
+ });
12
+ export async function extractAudio(params, options) {
13
+ const input = await ensureFileExists(params.inputPath);
14
+ const output = await ensureOutputDir(params.outputPath);
15
+ const format = params.format || "mp3";
6
16
  const args = ["-y", "-i", input, "-vn"]; // -vn drops the video track
7
17
  switch (format) {
8
18
  case "whisper_wav":
@@ -10,10 +20,10 @@ export async function extractAudio(options) {
10
20
  args.push("-ar", "16000", "-ac", "1", "-c:a", "pcm_s16le");
11
21
  break;
12
22
  case "mp3":
13
- args.push("-c:a", "libmp3lame", "-b:a", options.bitrate || "192k");
23
+ args.push("-c:a", "libmp3lame", "-b:a", params.bitrate || "192k");
14
24
  break;
15
25
  case "aac":
16
- args.push("-c:a", "aac", "-b:a", options.bitrate || "192k");
26
+ args.push("-c:a", "aac", "-b:a", params.bitrate || "192k");
17
27
  break;
18
28
  case "flac":
19
29
  args.push("-c:a", "flac");
@@ -23,9 +33,14 @@ export async function extractAudio(options) {
23
33
  break;
24
34
  }
25
35
  args.push(output);
26
- await runCommand("ffmpeg", args);
36
+ const res = await runFfmpeg(args, {
37
+ signal: options?.signal,
38
+ onProgress: options?.onProgress,
39
+ });
27
40
  return {
28
41
  outputPath: output,
29
- commandExecuted: `ffmpeg ${args.join(" ")}`,
42
+ format,
43
+ commandExecuted: res.command,
44
+ durationSeconds: res.durationSeconds,
30
45
  };
31
46
  }
@@ -0,0 +1,94 @@
1
+ import { z } from "zod";
2
+ import { ensureFileExists, ensureOutputDir, runFfmpeg } from "../utils/exec.js";
3
+ import { detectHwAccel, hasFilter } from "../utils/hwaccel.js";
4
+ import { probeMedia } from "./probe.js";
5
+ export const burnSubtitlesSchema = z.object({
6
+ videoPath: z.string().describe("Path to the source video file."),
7
+ subtitlesPath: z.string().describe("Path to the subtitle file (.srt, .vtt, or .ass) to burn into the video."),
8
+ outputPath: z.string().describe("Target output video path (.mp4, .mov, or .mkv)."),
9
+ fontSize: z.number().int().min(8).max(120).optional().default(24).describe("Subtitle font size in points. Default: 24."),
10
+ fontColor: z
11
+ .string()
12
+ .regex(/^(white|yellow|cyan|red|green|blue|black|&[hH][0-9a-fA-F]{6,8})$/i, "Color must be a recognized color name or ASS hex code (e.g. '&H00FFFFFF')")
13
+ .optional()
14
+ .default("white")
15
+ .describe("Primary subtitle text color: 'white', 'yellow', 'cyan', or ASS hex e.g. '&H00FFFFFF'. Default: 'white'."),
16
+ outlineColor: z
17
+ .string()
18
+ .regex(/^(white|yellow|cyan|red|green|blue|black|&[hH][0-9a-fA-F]{6,8})$/i, "Outline color must be a recognized color name or ASS hex code (e.g. '&H00000000')")
19
+ .optional()
20
+ .default("black")
21
+ .describe("Subtitle border/outline color: 'black', 'white', or ASS hex. Default: 'black'."),
22
+ outlineWidth: z.number().int().min(0).max(10).optional().default(2).describe("Outline thickness in pixels. Default: 2."),
23
+ marginV: z.number().int().min(0).max(500).optional().default(35).describe("Vertical margin distance in pixels from the bottom edge. Default: 35."),
24
+ hardwareAcceleration: z
25
+ .boolean()
26
+ .optional()
27
+ .default(true)
28
+ .describe("Use hardware-accelerated video encoding when available. Default: true."),
29
+ });
30
+ function toAssColor(color) {
31
+ const c = color.trim();
32
+ if (/^&[hH][0-9a-fA-F]{6,8}$/.test(c))
33
+ return color;
34
+ const map = {
35
+ white: "&H00FFFFFF",
36
+ black: "&H00000000",
37
+ yellow: "&H0000FFFF",
38
+ cyan: "&H00FFFF00",
39
+ red: "&H000000FF",
40
+ green: "&H0000FF00",
41
+ blue: "&H00FF0000",
42
+ };
43
+ return map[c.toLowerCase()] || "&H00FFFFFF";
44
+ }
45
+ export async function burnSubtitles(params, options) {
46
+ const { videoPath, subtitlesPath, outputPath, fontSize = 24, fontColor = "white", outlineColor = "black", outlineWidth = 2, marginV = 35, hardwareAcceleration = true, } = params;
47
+ const video = await ensureFileExists(videoPath);
48
+ const subs = await ensureFileExists(subtitlesPath);
49
+ const output = await ensureOutputDir(outputPath);
50
+ const filterAvailable = await hasFilter("subtitles");
51
+ if (!filterAvailable) {
52
+ throw new Error("FFmpeg installation is missing the 'subtitles' filter (requires FFmpeg compiled with --enable-libass). To hardcode subtitles, please install an FFmpeg build with libass. Alternatively, use 'add_subtitles' to embed soft subtitle tracks into MP4/MKV without re-encoding.");
53
+ }
54
+ const probe = await probeMedia(video, { signal: options?.signal });
55
+ const duration = probe.format.durationSeconds;
56
+ const hwInfo = await detectHwAccel();
57
+ const useHw = hardwareAcceleration && hwInfo.isAvailable;
58
+ const isHwUsed = useHw;
59
+ const videoEncoder = isHwUsed ? hwInfo.h264Encoder : "libx264";
60
+ // Escape special characters in path for FFmpeg filter syntax
61
+ const escapedSubPath = subs.replace(/\\/g, "/").replace(/:/g, "\\:").replace(/'/g, "\\'");
62
+ const primaryAssColor = toAssColor(fontColor);
63
+ const outlineAssColor = toAssColor(outlineColor);
64
+ const style = `FontSize=${fontSize},PrimaryColour=${primaryAssColor},OutlineColour=${outlineAssColor},Outline=${outlineWidth},MarginV=${marginV},Alignment=2`;
65
+ const filter = `subtitles=filename='${escapedSubPath}':force_style='${style}'`;
66
+ const args = [
67
+ "-i", video,
68
+ "-vf", filter,
69
+ "-c:v", videoEncoder,
70
+ ];
71
+ if (isHwUsed) {
72
+ args.push("-b:v", "4M", "-pix_fmt", "yuv420p");
73
+ }
74
+ else {
75
+ args.push("-crf", "22", "-preset", "fast", "-pix_fmt", "yuv420p");
76
+ }
77
+ args.push("-c:a", "copy", "-movflags", "+faststart", "-y", output);
78
+ const res = await runFfmpeg(args, {
79
+ signal: options?.signal,
80
+ onProgress: options?.onProgress,
81
+ expectedDurationSeconds: duration,
82
+ });
83
+ return {
84
+ success: true,
85
+ outputPath: output,
86
+ subtitlesBurned: subs,
87
+ fontSize,
88
+ fontColor,
89
+ encoderUsed: videoEncoder,
90
+ hardwareAccelerated: isHwUsed,
91
+ commandExecuted: res.command,
92
+ durationSeconds: res.durationSeconds,
93
+ };
94
+ }