@ash_j1997/ffmpeg-mcp-server 0.6.2 → 0.6.3

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/README.ko.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](README.md) | [한국어](README.ko.md)
4
4
 
5
- [![CI](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions) [![Release](https://img.shields.io/github/v/release/Ashutos1997/ffmpeg-mcp-server?color=blue)](https://github.com/Ashutos1997/ffmpeg-mcp-server/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE) [![npm version](https://img.shields.io/npm/v/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm downloads](https://img.shields.io/npm/dw/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm total downloads](https://img.shields.io/npm/dt/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![Glama](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server/badge)](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server) [![FFmpeg MCP server](https://mcprush.com/badge/ashutos1997-ffmpeg-mcp/card.svg)](https://mcprush.com/to/ashutos1997-ffmpeg-mcp?ref=badge)
5
+ [![CI](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions) [![Release](https://img.shields.io/github/v/release/Ashutos1997/ffmpeg-mcp-server?color=blue)](https://github.com/Ashutos1997/ffmpeg-mcp-server/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE) [![npm version](https://img.shields.io/npm/v/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm downloads](https://img.shields.io/npm/dw/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm total downloads](https://img.shields.io/npm/dt/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![Glama](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server/badge)](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server) [![FFmpeg MCP server](https://mcprush.com/badge/ashutos1997-ffmpeg-mcp/card.svg)](https://mcprush.com/to/ashutos1997-ffmpeg-mcp?ref=badge)
6
6
 
7
7
  AI 에이전트와 도구가 로컬에서 비디오 및 오디오를 처리할 수 있도록 FFmpeg 및 FFprobe 기능을 제공하는 Model Context Protocol (MCP) 서버입니다.
8
8
 
@@ -47,6 +47,7 @@ AI 에이전트에게 영상 처리를 직접 명령하면 잘못된 플래그,
47
47
  * **숏폼/소셜 포맷 자동화:** 가로 영상을 배경 블러 처리된 9:16 세로 숏폼 영상으로 변환하고, 스타일이 적용된 자막을 하드코딩(버닝)하며, 틱톡/릴스용 상하 분할 스플릿 스크린 영상을 제작합니다.
48
48
  * **오디오 엔지니어링:** 스트리밍/방송 표준(EBU R128 / -16 LUFS)에 맞춰 음량을 정규화하고, 80Hz 럼블 제거 필터로 음성을 선명하게 보정하며, 립싱크를 유지하면서 무음 구간을 자동으로 잘라냅니다.
49
49
  * **장면 감지 및 스트림 결합:** 시각적 장면 전환(컷 편집 지점)을 감지하여 타임스탬프와 콘택트 시트를 반환하고, 무손실 스트림 복사로 비디오와 오디오를 즉시 결합/교체합니다.
50
+ * **지능형 사전 검증(Smart Input Guards):** FFmpeg 실행 전 미디어 스트림 유무, 오디오 트랙, 재생 시간 한계를 사전에 검증하여 `trim_media`, `extract_audio`, `generate_waveform`, `extract_thumbnail` 등에서 무음 영상이나 범위 초과로 인한 런타임 오류를 사전에 방지합니다.
50
51
 
51
52
  ---
52
53
 
@@ -140,7 +141,7 @@ AI 에이전트에게 영상 처리를 직접 명령하면 잘못된 플래그,
140
141
  ## 감사의 글 (Acknowledgements & Community)
141
142
 
142
143
  - 단순 포맷 변환을 넘어 스트림 멀티플렉싱(`mux_media`) 및 장면 전환 감지 기능(`detect_scenes`)을 제안해 주신 [@rajarshidattapy](https://github.com/rajarshidattapy) 님께 감사드립니다.
143
- - 입력 스트림 속성이 다를 때 발생하는 파일 손상을 방지하도록 `concat_media`의 자동 감지(auto-probe) 모드를 제안해 주신 Reddit 사용자 [u/QuanTradin](https://www.reddit.com/user/QuanTradin/) 님께 감사드립니다.
144
+ - 사전 스트림 검증 및 오디오 샘플 레이트 체크(Smart Input Guards) 아이디어와 `concat_media`의 자동 감지(auto-probe) 모드를 제안해 주신 Reddit 사용자 [u/QuanTradin](https://www.reddit.com/user/QuanTradin/) 님께 감사드립니다.
144
145
 
145
146
  ---
146
147
 
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](README.md) | [한국어](README.ko.md)
4
4
 
5
- [![CI](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions) [![Release](https://img.shields.io/github/v/release/Ashutos1997/ffmpeg-mcp-server?color=blue)](https://github.com/Ashutos1997/ffmpeg-mcp-server/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE) [![npm version](https://img.shields.io/npm/v/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm downloads](https://img.shields.io/npm/dw/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm total downloads](https://img.shields.io/npm/dt/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![Glama](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server/badge)](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server) [![FFmpeg MCP server](https://mcprush.com/badge/ashutos1997-ffmpeg-mcp/card.svg)](https://mcprush.com/to/ashutos1997-ffmpeg-mcp?ref=badge)
5
+ [![CI](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Ashutos1997/ffmpeg-mcp-server/actions) [![Release](https://img.shields.io/github/v/release/Ashutos1997/ffmpeg-mcp-server?color=blue)](https://github.com/Ashutos1997/ffmpeg-mcp-server/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE) [![npm version](https://img.shields.io/npm/v/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm downloads](https://img.shields.io/npm/dw/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![npm total downloads](https://img.shields.io/npm/dt/@ash_j1997/ffmpeg-mcp-server.svg)](https://www.npmjs.com/package/@ash_j1997/ffmpeg-mcp-server) [![Glama](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server/badge)](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server) [![FFmpeg MCP server](https://mcprush.com/badge/ashutos1997-ffmpeg-mcp/card.svg)](https://mcprush.com/to/ashutos1997-ffmpeg-mcp?ref=badge)
6
6
 
7
7
  A Model Context Protocol (MCP) server that gives AI tools access to FFmpeg and FFprobe to process video and audio locally.
8
8
 
@@ -47,6 +47,7 @@ Add directly to your client configuration (no manual cloning required):
47
47
  * **Social Formats & Automation:** Reformats landscape video to 9:16 vertical video with blurred backgrounds, burns customizable hardcoded subtitles, and stacks top/bottom split-screen reels for TikTok and Instagram Reels.
48
48
  * **Audio Engineering:** Normalizes loudness to broadcast/streaming standards (EBU R128 / -16 LUFS), cleans vocal audio with 80Hz rumble removal, and trims dead air while preserving lip-sync.
49
49
  * **Scene Intelligence & Multiplexing:** Detects visual scene changes and cut points for smart editing workflows, and combines or replaces video/audio tracks with zero-loss stream copy.
50
+ * **Smart Input Guards & Validation:** Pre-probes streams and duration limits before execution — safeguarding `trim_media`, `extract_audio`, `generate_waveform`, and `extract_thumbnail` from cryptic errors on silent or out-of-bounds media.
50
51
 
51
52
  ---
52
53
 
@@ -140,7 +141,7 @@ Run directly with `npx` (no manual cloning or building required):
140
141
  ## Acknowledgements & Community
141
142
 
142
143
  - Special thanks to [@rajarshidattapy](https://github.com/rajarshidattapy) for suggesting stream multiplexing (`mux_media`) and scene transition detection (`detect_scenes`) to expand the server beyond format conversion.
143
- - Special thanks to Reddit user [u/QuanTradin](https://www.reddit.com/user/QuanTradin/) for suggesting smart auto-probing in `concat_media` to prevent corrupted outputs when input stream parameters differ.
144
+ - Special thanks to Reddit user [u/QuanTradin](https://www.reddit.com/user/QuanTradin/) for inspiring smart input guards (pre-flight stream validation & sample rate checking) and auto-probing in `concat_media` to prevent corrupted outputs and catch bugs before execution.
144
145
 
145
146
  ---
146
147
 
package/dist/index.js CHANGED
@@ -25,7 +25,7 @@ import { detectHwAccel } from "./utils/hwaccel.js";
25
25
  import { runCommand } from "./utils/exec.js";
26
26
  const server = new McpServer({
27
27
  name: "ffmpeg-mcp-server",
28
- version: "0.6.2",
28
+ version: "0.6.3",
29
29
  });
30
30
  function createProgressCallback(extra) {
31
31
  return (p) => {
@@ -1,5 +1,6 @@
1
1
  import { z } from "zod";
2
2
  import { ensureFileExists, ensureOutputDir, runFfmpeg } from "../utils/exec.js";
3
+ import { probeMedia } from "./probe.js";
3
4
  export const extractAudioSchema = z.object({
4
5
  inputPath: z.string().describe("Path to the source video or audio file."),
5
6
  outputPath: z.string().describe("Destination path for the output audio file (e.g. './extracted.wav' or './audio.mp3')."),
@@ -12,6 +13,10 @@ export const extractAudioSchema = z.object({
12
13
  export async function extractAudio(params, options) {
13
14
  const input = await ensureFileExists(params.inputPath);
14
15
  const output = await ensureOutputDir(params.outputPath);
16
+ const probe = await probeMedia(input, { signal: options?.signal });
17
+ if (probe.audioStreams.length === 0) {
18
+ throw new Error(`Cannot extract audio from "${params.inputPath}": file contains no audio streams.`);
19
+ }
15
20
  const format = params.format || "mp3";
16
21
  const args = ["-y", "-i", input, "-vn"]; // -vn drops the video track
17
22
  switch (format) {
@@ -36,6 +41,7 @@ export async function extractAudio(params, options) {
36
41
  const res = await runFfmpeg(args, {
37
42
  signal: options?.signal,
38
43
  onProgress: options?.onProgress,
44
+ expectedDurationSeconds: probe.format.durationSeconds,
39
45
  });
40
46
  return {
41
47
  outputPath: output,
@@ -74,7 +74,14 @@ export async function burnSubtitles(params, options) {
74
74
  else {
75
75
  args.push("-crf", "22", "-preset", "fast", "-pix_fmt", "yuv420p");
76
76
  }
77
- args.push("-c:a", "copy", "-movflags", "+faststart", "-y", output);
77
+ const hasAudio = probe.audioStreams.length > 0;
78
+ if (hasAudio) {
79
+ args.push("-c:a", "copy");
80
+ }
81
+ else {
82
+ args.push("-an");
83
+ }
84
+ args.push("-movflags", "+faststart", "-y", output);
78
85
  const res = await runFfmpeg(args, {
79
86
  signal: options?.signal,
80
87
  onProgress: options?.onProgress,
@@ -27,17 +27,19 @@ export async function changeSpeed(params, options) {
27
27
  const input = await ensureFileExists(inputPath);
28
28
  const output = await ensureOutputDir(outputPath);
29
29
  let expectedDuration;
30
+ let hasAudio = false;
30
31
  try {
31
32
  const probe = await probeMedia(input, { signal: options?.signal });
32
33
  if (probe.format.durationSeconds > 0) {
33
34
  expectedDuration = probe.format.durationSeconds / speed;
34
35
  }
36
+ hasAudio = probe.audioStreams.length > 0;
35
37
  }
36
38
  catch { }
37
39
  const hwInfo = await detectHwAccel();
38
40
  const videoFilter = `setpts=${(1 / speed).toFixed(6)}*PTS`;
39
41
  const args = ["-i", input, "-filter:v", videoFilter];
40
- if (muteAudio) {
42
+ if (muteAudio || !hasAudio) {
41
43
  args.push("-an");
42
44
  }
43
45
  else {
@@ -17,18 +17,31 @@ export const extractThumbnailSchema = z.object({
17
17
  .describe("Optional scaled size formatted as 'WIDTHxHEIGHT', such as '1280x720'. Defaults to source resolution."),
18
18
  includeBase64: z.boolean().optional().describe("Return base64 image data in response for vision models. Default: true."),
19
19
  });
20
+ function parseTimestampToSeconds(ts) {
21
+ const parts = ts.split(":").map(Number);
22
+ if (parts.length === 1)
23
+ return parts[0];
24
+ if (parts.length === 2)
25
+ return parts[0] * 60 + parts[1];
26
+ return parts[0] * 3600 + parts[1] * 60 + parts[2];
27
+ }
20
28
  export async function extractThumbnail(params, options) {
21
29
  const input = await ensureFileExists(params.inputPath);
22
30
  const output = await ensureOutputDir(params.outputPath);
31
+ const probe = await probeMedia(input, { signal: options?.signal });
32
+ if (probe.videoStreams.length === 0) {
33
+ throw new Error(`Cannot extract thumbnail from "${params.inputPath}": file contains no video streams.`);
34
+ }
23
35
  let timestamp = params.timestamp || "00:00:01";
36
+ const duration = probe.format.durationSeconds;
24
37
  if (timestamp === "midpoint") {
25
- try {
26
- const info = await probeMedia(input, { signal: options?.signal });
27
- const midpointSeconds = Math.max(0, Math.floor(info.format.durationSeconds / 2));
28
- timestamp = String(midpointSeconds);
29
- }
30
- catch {
31
- timestamp = "00:00:01";
38
+ const midpointSeconds = Math.max(0, Math.floor(duration / 2));
39
+ timestamp = String(midpointSeconds);
40
+ }
41
+ else if (duration > 0) {
42
+ const tsSec = parseTimestampToSeconds(timestamp);
43
+ if (!isNaN(tsSec) && tsSec >= duration) {
44
+ timestamp = String(Math.max(0, Number((duration - 0.1).toFixed(2))));
32
45
  }
33
46
  }
34
47
  const args = [
@@ -1,6 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import { ensureFileExists, ensureOutputDir, runFfmpeg } from "../utils/exec.js";
3
3
  import { detectHwAccel } from "../utils/hwaccel.js";
4
+ import { probeMedia } from "./probe.js";
4
5
  export const trimMediaSchema = z.object({
5
6
  inputPath: z.string().describe("Path to the source media file to cut."),
6
7
  outputPath: z.string().describe("Destination path for the trimmed output file (e.g. './clip.mp4')."),
@@ -34,19 +35,34 @@ function timestampToSeconds(timestamp) {
34
35
  export async function trimMedia(params, options) {
35
36
  const input = await ensureFileExists(params.inputPath);
36
37
  const output = await ensureOutputDir(params.outputPath);
37
- const args = ["-y"];
38
- // Fast seek before -i
39
- args.push("-ss", params.startTime);
40
- args.push("-i", input);
38
+ const probe = await probeMedia(input, { signal: options?.signal });
39
+ const fileDuration = probe.format.durationSeconds;
40
+ const startSec = timestampToSeconds(params.startTime);
41
+ if (fileDuration > 0 && startSec >= fileDuration) {
42
+ throw new Error(`startTime (${params.startTime} / ${startSec}s) is greater than or equal to file duration (${fileDuration.toFixed(2)}s).`);
43
+ }
44
+ let durationToCut;
41
45
  if (params.endTime) {
42
- const duration = timestampToSeconds(params.endTime) - timestampToSeconds(params.startTime);
43
- if (duration <= 0) {
44
- throw new Error("endTime must be later than startTime");
46
+ const endSec = timestampToSeconds(params.endTime);
47
+ if (endSec <= startSec) {
48
+ throw new Error(`endTime (${params.endTime}) must be later than startTime (${params.startTime}).`);
45
49
  }
46
- args.push("-t", String(duration));
50
+ const effectiveEndSec = fileDuration > 0 ? Math.min(endSec, fileDuration) : endSec;
51
+ durationToCut = Math.max(0.001, effectiveEndSec - startSec);
47
52
  }
48
53
  else if (params.duration) {
49
- args.push("-t", params.duration);
54
+ const reqDuration = Number(params.duration);
55
+ if (reqDuration <= 0) {
56
+ throw new Error("duration must be a positive number of seconds");
57
+ }
58
+ durationToCut = fileDuration > 0 ? Math.min(reqDuration, Math.max(0.001, fileDuration - startSec)) : reqDuration;
59
+ }
60
+ const args = ["-y"];
61
+ // Fast seek before -i
62
+ args.push("-ss", params.startTime);
63
+ args.push("-i", input);
64
+ if (durationToCut !== undefined) {
65
+ args.push("-t", String(durationToCut));
50
66
  }
51
67
  if (params.accurateReencode) {
52
68
  const hwInfo = await detectHwAccel();
@@ -65,6 +81,7 @@ export async function trimMedia(params, options) {
65
81
  const res = await runFfmpeg(args, {
66
82
  signal: options?.signal,
67
83
  onProgress: options?.onProgress,
84
+ expectedDurationSeconds: durationToCut,
68
85
  });
69
86
  return {
70
87
  outputPath: output,
@@ -1,6 +1,7 @@
1
1
  import fs from "node:fs/promises";
2
2
  import { z } from "zod";
3
3
  import { runFfmpeg, ensureFileExists, ensureOutputDir } from "../utils/exec.js";
4
+ import { probeMedia } from "./probe.js";
4
5
  export const generateWaveformSchema = z.object({
5
6
  inputPath: z.string().describe("Path to the audio or video file."),
6
7
  outputPath: z.string().describe("Destination path for the PNG image."),
@@ -19,6 +20,10 @@ export async function generateWaveform(params, options) {
19
20
  const { inputPath, outputPath, width = 1200, height = 280, color = "0x6366f1", scale = "lin", includeBase64 = true } = params;
20
21
  const input = await ensureFileExists(inputPath);
21
22
  const output = await ensureOutputDir(outputPath);
23
+ const probe = await probeMedia(input, { signal: options?.signal });
24
+ if (probe.audioStreams.length === 0) {
25
+ throw new Error(`Cannot generate waveform: input file '${inputPath}' contains no audio streams.`);
26
+ }
22
27
  const filter = `aformat=channel_layouts=mono,showwavespic=s=${width}x${height}:colors=${color}:scale=${scale}`;
23
28
  const args = [
24
29
  "-i", input,
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@ash_j1997/ffmpeg-mcp-server",
3
- "version": "0.6.2",
3
+ "version": "0.6.3",
4
4
  "description": "MCP server for FFmpeg and FFprobe media processing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "bin": {
8
- "ffmpeg-mcp-server": "./dist/index.js"
8
+ "ffmpeg-mcp-server": "dist/index.js"
9
9
  },
10
10
  "files": [
11
11
  "dist"