@ash_j1997/ffmpeg-mcp-server 0.5.0 → 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/README.ko.md ADDED
@@ -0,0 +1,120 @@
1
+ # ffmpeg-mcp-server
2
+
3
+ [English](README.md) | [한국어](README.ko.md)
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)
6
+
7
+ AI 에이전트와 도구가 로컬에서 비디오 및 오디오를 처리할 수 있도록 FFmpeg 및 FFprobe 기능을 제공하는 Model Context Protocol (MCP) 서버입니다.
8
+
9
+ 크로스 플랫폼 GPU 하드웨어 가속(Apple Silicon VideoToolbox, NVIDIA NVENC, Intel QuickSync, AMD AMF), MCP 진행률 토큰을 통한 실시간 진행 상황 보고, `AbortSignal` 기반의 즉각적인 작업 취소, 멀티모달 비전 모델을 위한 이미지 프리뷰 인라인 반환을 완벽하게 지원합니다.
10
+
11
+ ---
12
+
13
+ ## 개발 배경 (Why This Exists)
14
+
15
+ AI 에이전트에게 영상 처리를 직접 명령하면 잘못된 플래그, 문법 오류, 지원되지 않는 픽셀 포맷 등을 만들어내어 작업이 실패하기 쉽습니다.
16
+
17
+ 본 서버는 Zod 스키마로 정의된 **17가지 타입 안전한 도구(Typed Tools)**를 제공합니다. AI가 `{ inputPath: "video.mov", preset: "web_mp4" }`와 같은 구조화된 매개변수를 전달하면, 서버가 유효한 FFmpeg 명령어를 로컬에서 직접 실행하며 안정적인 에러 처리, 하드웨어 가속 및 진행률 알림을 수행합니다.
18
+
19
+ ---
20
+
21
+ ## 주요 기능 (Key Features)
22
+
23
+ * **범용 하드웨어 가속:** macOS(VideoToolbox), Linux/Windows GPU(NVIDIA NVENC, Intel QuickSync, AMD AMF, VA-API)를 자동 감지하여 낮은 CPU 점유율로 5배~20배 빠른 인코딩을 지원합니다.
24
+ * **실시간 진행률 보고:** 표준 MCP 진행률 토큰(`notifications/progress`)을 통해 실시간 백분율(%)을 전송하여 클라이언트 UI에 진행 바를 표시합니다.
25
+ * **즉각적인 작업 취소:** 클라이언트의 `AbortSignal` 이벤트를 감지하여 사용자가 생성을 중단하면 실행 중인 하위 FFmpeg 프로세스를 즉시 종료합니다.
26
+ * **멀티모달 비전 모델용 프리뷰:** 썸네일, 오디오 파형, 멀티 프레임 콘택트 시트를 base64 이미지 데이터로 인라인 반환하여 Claude 3.7, GPT-4o, Gemini 등의 비전 모델이 미디어를 직접 "볼" 수 있습니다.
27
+ * **숏폼/소셜 포맷 자동화:** 가로 영상을 배경 블러 처리된 9:16 세로 숏폼 영상으로 변환하고, 스타일이 적용된 자막을 하드코딩(버닝)하며, 틱톡/릴스용 상하 분할 스플릿 스크린 영상을 제작합니다.
28
+ * **오디오 엔지니어링:** 스트리밍/방송 표준(EBU R128 / -16 LUFS)에 맞춰 음량을 정규화하고, 80Hz 럼블 제거 필터로 음성을 선명하게 보정하며, 립싱크를 유지하면서 무음 구간을 자동으로 잘라냅니다.
29
+
30
+ ---
31
+
32
+ ## 제공 도구 목록 (총 17개)
33
+
34
+ | 도구명 | 설명 | 주요 매개변수 |
35
+ | :--- | :--- | :--- |
36
+ | **`media_probe`** | ffprobe로 미디어 파일을 검사하여 메타데이터, 스트림, 코덱, 해상도, 재생 시간을 JSON으로 반환합니다. | `inputPath` |
37
+ | **`media_convert`** | 비디오 및 오디오 포맷을 변환합니다. 웹용 MP4, WebM, 애니메이션 GIF 프리셋 및 GPU 가속을 지원합니다. | `inputPath`, `outputPath`, `preset`, `crf`, `resolution`, `fps`, `hardwareAcceleration` |
38
+ | **`trim_media`** | 스트림 복사(무손실/초고속) 또는 재인코딩 방식으로 비디오/오디오의 특정 구간을 자릅니다. | `inputPath`, `outputPath`, `startTime`, `endTime`, `duration`, `accurateReencode` |
39
+ | **`extract_audio`** | 비디오에서 오디오 트랙을 추출합니다. Whisper 음성 인식에 최적화된 16kHz 모노 WAV 프리셋을 포함합니다. | `inputPath`, `outputPath`, `format`, `bitrate` |
40
+ | **`extract_thumbnail`** | 특정 타임스탬프 또는 중간 지점의 스틸 컷을 캡처합니다. 비전 모델을 위해 base64 이미지 데이터를 함께 반환할 수 있습니다. | `inputPath`, `outputPath`, `timestamp`, `resolution`, `includeBase64` |
41
+ | **`compress_video`** | 대상 크기(예: GitHub PR용 10MB 미만, Discord용 25MB 미만)에 맞게 비디오를 압축합니다. | `inputPath`, `outputPath`, `targetSizeMB`, `preset`, `crf`, `maxWidth`, `hardwareAcceleration` |
42
+ | **`reformat_aspect_ratio`** | 배경 블러 패딩 또는 중앙 크롭을 적용해 영상 비율을 9:16(세로), 1:1(정사각형), 4:5(포트레이트)로 변환합니다. | `inputPath`, `outputPath`, `targetRatio`, `mode`, `blurAmount`, `padColor`, `hardwareAcceleration` |
43
+ | **`create_split_screen`** | 두 개의 영상을 상하(9:16 숏폼/릴스) 또는 좌우로 배치하고 오디오 믹싱 및 자막을 합성합니다. | `firstVideoPath`, `secondVideoPath`, `outputPath`, `layout`, `audioSource`, `subtitlesPath` |
44
+ | **`trim_silence`** | 영상과 음성의 립싱크를 완벽히 유지하면서 녹음/녹화 영상의 무음 구간(침묵)을 감지해 자동으로 잘라냅니다. | `inputPath`, `outputPath`, `mode`, `thresholdDb`, `minDurationSeconds` |
45
+ | **`concat_media`** | 여러 비디오 또는 오디오 파일을 순서대로 병합합니다. 스트림 복사 및 재인코딩 방식을 지원합니다. | `inputPaths`, `outputPath`, `mode` |
46
+ | **`generate_waveform`** | 오디오 파형(Waveform) PNG 이미지를 생성합니다. 비전 모델을 위한 base64 데이터를 반환할 수 있습니다. | `inputPath`, `outputPath`, `width`, `height`, `color`, `scale`, `includeBase64` |
47
+ | **`add_subtitles`** | 비디오 재인코딩 없이 SRT 또는 VTT 자막 트랙을 MP4/MKV 파일에 소프트웨어 자막으로 삽입합니다. | `videoPath`, `subtitlesPath`, `outputPath`, `language`, `title` |
48
+ | **`burn_subtitles`** *(신규)* | 폰트 크기, 글자 색상, 외곽선, 여백을 커스텀하여 비디오 프레임에 자막을 직접 하드코딩(버닝)합니다. | `videoPath`, `subtitlesPath`, `outputPath`, `fontSize`, `fontColor`, `outlineColor`, `marginV` |
49
+ | **`extract_keyframes`** *(신규)* | 영상 전반에 걸쳐 대표 키프레임을 추출하고 비전 AI가 한눈에 볼 수 있는 그리드형 콘택트 시트를 생성합니다. | `inputPath`, `outputPath`, `count`, `layout`, `includeBase64` |
50
+ | **`normalize_audio`** *(신규)* | EBU R128 표준(기본 -16 LUFS)을 적용해 오디오 음량을 균일하게 정규화하고 80Hz 고역 통과 필터로 음성을 선명하게 다듬습니다. | `inputPath`, `outputPath`, `targetLufs`, `targetPeakDb`, `voiceClarity` |
51
+ | **`add_overlay`** *(신규)* | 워터마크 이미지나 로고 PNG를 영상 모서리에 오버레이하며 위치, 여백, 크기 비율, 투명도를 조절할 수 있습니다. | `videoPath`, `overlayPath`, `outputPath`, `position`, `padding`, `scaleWidth`, `opacity` |
52
+ | **`change_speed`** | 피치(음높이) 왜곡 없이 재생 속도를 배속(2배속 고속, 0.5배속 슬로우 모션 등)으로 조절합니다. | `inputPath`, `outputPath`, `speed`, `muteAudio` |
53
+
54
+ ---
55
+
56
+ ## MCP 리소스 및 프롬프트 (Resources & Prompts)
57
+
58
+ ### 리소스 (Resources)
59
+ * **`media://capabilities`**: 로컬 FFmpeg 설치 상태, 버전, 감지된 하드웨어 가속기(VideoToolbox, NVENC, QSV, AMF, VAAPI) 및 지원 비디오 인코더를 조회합니다.
60
+ * **`media://presets`**: 소셜 미디어 종횡비, 플랫폼별 업로드 용량 제한, 방송 음량 타깃 기준표를 제공합니다.
61
+
62
+ ### 프롬프트 (Prompts)
63
+ * **`social_clip_generator`**: 원본 가로 영상을 블러 패딩, 무음 구간 편집, 자막 버닝이 적용된 세로형 숏폼 클립으로 변환하는 인터랙티브 워크플로우입니다.
64
+ * **`whisper_audio_prep`**: Whisper 음성 인식 모델에 최적화된 16kHz 모노 WAV 오디오 추출 및 음량 정규화 파이프라인입니다.
65
+
66
+ ---
67
+
68
+ ## 요구 사항 (Requirements)
69
+
70
+ * **Node.js** >= 18.0.0
71
+ * 로컬에 **FFmpeg & FFprobe** 설치 필요:
72
+ * **macOS:** `brew install ffmpeg`
73
+ * **Linux (Ubuntu/Debian):** `sudo apt update && sudo apt install ffmpeg libass-dev`
74
+ * **Windows:** `winget install Gyan.FFmpeg` 또는 `choco install ffmpeg`
75
+
76
+ ---
77
+
78
+ ## 설치 및 설정 (Installation)
79
+
80
+ ### 빠른 시작 (Claude Desktop, Cursor, Antigravity)
81
+
82
+ 별도의 저장소 클론이나 빌드 없이 `npx`로 바로 실행할 수 있습니다:
83
+
84
+ ```json
85
+ {
86
+ "mcpServers": {
87
+ "ffmpeg": {
88
+ "command": "npx",
89
+ "args": ["-y", "@ash_j1997/ffmpeg-mcp-server"]
90
+ }
91
+ }
92
+ }
93
+ ```
94
+
95
+ #### 설정 파일 위치 안내:
96
+ * **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
97
+ * **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
98
+ * **Antigravity IDE:** `~/.gemini/config/mcp_config.json`
99
+ * **Cursor / Windsurf:** stdio 서버 유형 선택 후 Command: `npx`, Args: `["-y", "@ash_j1997/ffmpeg-mcp-server"]` 추가
100
+
101
+ ---
102
+
103
+ ## 로컬 개발 및 테스트 (Local Development)
104
+
105
+ 1. **의존성 설치:**
106
+ ```bash
107
+ npm install
108
+ ```
109
+
110
+ 2. **빌드 및 자동화 테스트 실행:**
111
+ ```bash
112
+ npm test
113
+ ```
114
+
115
+ ---
116
+
117
+ ## 라이선스 (License)
118
+
119
+ MIT © [Ashutos1997](https://github.com/Ashutos1997)
120
+
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # ffmpeg-mcp-server
2
2
 
3
- [![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) [![Glama](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server/badge)](https://glama.ai/mcp/servers/@Ashutos1997/ffmpeg-mcp-server)
3
+ [English](README.md) | [한국어](README.ko.md)
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)
4
6
 
5
7
  A Model Context Protocol (MCP) server that gives AI tools access to FFmpeg and FFprobe to process video and audio locally.
6
8
 
@@ -9,11 +9,13 @@ export const burnSubtitlesSchema = z.object({
9
9
  fontSize: z.number().int().min(8).max(120).optional().default(24).describe("Subtitle font size in points. Default: 24."),
10
10
  fontColor: z
11
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')")
12
13
  .optional()
13
14
  .default("white")
14
15
  .describe("Primary subtitle text color: 'white', 'yellow', 'cyan', or ASS hex e.g. '&H00FFFFFF'. Default: 'white'."),
15
16
  outlineColor: z
16
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')")
17
19
  .optional()
18
20
  .default("black")
19
21
  .describe("Subtitle border/outline color: 'black', 'white', or ASS hex. Default: 'black'."),
@@ -26,8 +28,8 @@ export const burnSubtitlesSchema = z.object({
26
28
  .describe("Use hardware-accelerated video encoding when available. Default: true."),
27
29
  });
28
30
  function toAssColor(color) {
29
- const c = color.toLowerCase().trim();
30
- if (c.startsWith("&h"))
31
+ const c = color.trim();
32
+ if (/^&[hH][0-9a-fA-F]{6,8}$/.test(c))
31
33
  return color;
32
34
  const map = {
33
35
  white: "&H00FFFFFF",
@@ -38,7 +40,7 @@ function toAssColor(color) {
38
40
  green: "&H0000FF00",
39
41
  blue: "&H00FF0000",
40
42
  };
41
- return map[c] || "&H00FFFFFF";
43
+ return map[c.toLowerCase()] || "&H00FFFFFF";
42
44
  }
43
45
  export async function burnSubtitles(params, options) {
44
46
  const { videoPath, subtitlesPath, outputPath, fontSize = 24, fontColor = "white", outlineColor = "black", outlineWidth = 2, marginV = 35, hardwareAcceleration = true, } = params;
@@ -17,6 +17,7 @@ export const convertMediaSchema = z.object({
17
17
  .describe("Quality factor from 0 to 51. Lower numbers mean higher quality. Default: 23 for MP4, 30 for WebM."),
18
18
  resolution: z
19
19
  .string()
20
+ .regex(/^\d{2,5}x\d{2,5}$/, "Resolution must be formatted as 'WIDTHxHEIGHT' (e.g. '1920x1080')")
20
21
  .optional()
21
22
  .describe("Target size formatted as 'WIDTHxHEIGHT', such as '1920x1080' or '1280x720'"),
22
23
  fps: z
@@ -15,6 +15,7 @@ export const reformatAspectSchema = z.object({
15
15
  .describe("Format mode: 'blur_background' adds blurred video borders, 'fit_pad' adds solid color padding, and 'crop_center' zooms and crops the center. Default: 'blur_background'."),
16
16
  padColor: z
17
17
  .string()
18
+ .regex(/^(0x[0-9a-fA-F]{6}|#[0-9a-fA-F]{6}|[a-zA-Z]{3,20})$/, "padColor must be hex (e.g. '0x1e1e2e') or color name (e.g. 'black', 'white')")
18
19
  .default("black")
19
20
  .describe("Background color for fit_pad mode, such as 'black', 'white', or hex '0x1e1e2e'. Default: 'black'."),
20
21
  blurAmount: z
@@ -4,8 +4,18 @@ 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
20
  export async function addSubtitles(params, options) {
11
21
  const { videoPath, subtitlesPath, outputPath, language = "eng", title = "English" } = params;
@@ -7,9 +7,14 @@ export const extractThumbnailSchema = z.object({
7
7
  outputPath: z.string().describe("Destination image path ending in .png or .jpg (e.g. './thumb.png')."),
8
8
  timestamp: z
9
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'")
10
11
  .optional()
11
12
  .describe("Timestamp to capture, such as '00:00:05', '10', or 'midpoint' for the middle frame. Default: '00:00:01'."),
12
- resolution: z.string().optional().describe("Optional scaled size formatted as 'WIDTHxHEIGHT', such as '1280x720'. Defaults to source resolution."),
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."),
13
18
  includeBase64: z.boolean().optional().describe("Return base64 image data in response for vision models. Default: true."),
14
19
  });
15
20
  export async function extractThumbnail(params, options) {
@@ -4,9 +4,20 @@ import { detectHwAccel } from "../utils/hwaccel.js";
4
4
  export const trimMediaSchema = z.object({
5
5
  inputPath: z.string().describe("Path to the source media file to cut."),
6
6
  outputPath: z.string().describe("Destination path for the trimmed output file (e.g. './clip.mp4')."),
7
- startTime: z.string().describe("Start timestamp formatted as 'HH:MM:SS' (e.g. '00:01:30') or seconds (e.g. '90')."),
8
- endTime: z.string().optional().describe("Optional end timestamp formatted as 'HH:MM:SS' or seconds. Do not combine with duration."),
9
- 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."),
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."),
10
21
  accurateReencode: z
11
22
  .boolean()
12
23
  .optional()
@@ -6,7 +6,12 @@ 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
16
  includeBase64: z.boolean().optional().default(true).describe("Return base64 image data in the response for vision models. Default: true."),
12
17
  });
@@ -1,6 +1,22 @@
1
1
  import os from "node:os";
2
2
  import { runCommand } from "./exec.js";
3
3
  let cachedInfo = null;
4
+ async function canEncodeWith(encoder) {
5
+ try {
6
+ await runCommand("ffmpeg", [
7
+ "-v", "quiet",
8
+ "-f", "lavfi",
9
+ "-i", "color=c=black:s=16x16:d=0.04",
10
+ "-c:v", encoder,
11
+ "-f", "null",
12
+ "-"
13
+ ]);
14
+ return true;
15
+ }
16
+ catch {
17
+ return false;
18
+ }
19
+ }
4
20
  /**
5
21
  * Detects available hardware-accelerated video encoders across macOS, Linux, and Windows.
6
22
  * Supports Apple Silicon (VideoToolbox), NVIDIA (NVENC), Intel (QuickSync), AMD (AMF), and Linux (VAAPI).
@@ -74,35 +90,50 @@ export async function detectHwAccel() {
74
90
  let chosenType = "none";
75
91
  let h264Encoder = "libx264";
76
92
  let hevcEncoder = "libx265";
93
+ const candidates = [];
77
94
  if (isDarwin && detectedTypes.includes("videotoolbox")) {
78
- chosenType = "videotoolbox";
79
- h264Encoder = "h264_videotoolbox";
80
- hevcEncoder = detectedHevc.includes("hevc_videotoolbox") ? "hevc_videotoolbox" : "libx265";
95
+ candidates.push({
96
+ type: "videotoolbox",
97
+ h264: "h264_videotoolbox",
98
+ hevc: detectedHevc.includes("hevc_videotoolbox") ? "hevc_videotoolbox" : "libx265",
99
+ });
81
100
  }
82
- else if (detectedTypes.includes("nvenc")) {
83
- chosenType = "nvenc";
84
- h264Encoder = "h264_nvenc";
85
- hevcEncoder = detectedHevc.includes("hevc_nvenc") ? "hevc_nvenc" : "libx265";
101
+ if (detectedTypes.includes("nvenc")) {
102
+ candidates.push({
103
+ type: "nvenc",
104
+ h264: "h264_nvenc",
105
+ hevc: detectedHevc.includes("hevc_nvenc") ? "hevc_nvenc" : "libx265",
106
+ });
86
107
  }
87
- else if (detectedTypes.includes("qsv")) {
88
- chosenType = "qsv";
89
- h264Encoder = "h264_qsv";
90
- hevcEncoder = detectedHevc.includes("hevc_qsv") ? "hevc_qsv" : "libx265";
108
+ if (detectedTypes.includes("qsv")) {
109
+ candidates.push({
110
+ type: "qsv",
111
+ h264: "h264_qsv",
112
+ hevc: detectedHevc.includes("hevc_qsv") ? "hevc_qsv" : "libx265",
113
+ });
91
114
  }
92
- else if (detectedTypes.includes("amf")) {
93
- chosenType = "amf";
94
- h264Encoder = "h264_amf";
95
- hevcEncoder = detectedHevc.includes("hevc_amf") ? "hevc_amf" : "libx265";
115
+ if (detectedTypes.includes("amf")) {
116
+ candidates.push({
117
+ type: "amf",
118
+ h264: "h264_amf",
119
+ hevc: detectedHevc.includes("hevc_amf") ? "hevc_amf" : "libx265",
120
+ });
96
121
  }
97
- else if (detectedTypes.includes("vaapi")) {
98
- chosenType = "vaapi";
99
- h264Encoder = "h264_vaapi";
100
- hevcEncoder = detectedHevc.includes("hevc_vaapi") ? "hevc_vaapi" : "libx265";
122
+ if (detectedTypes.includes("vaapi")) {
123
+ candidates.push({
124
+ type: "vaapi",
125
+ h264: "h264_vaapi",
126
+ hevc: detectedHevc.includes("hevc_vaapi") ? "hevc_vaapi" : "libx265",
127
+ });
101
128
  }
102
- else if (detectedTypes.length > 0) {
103
- chosenType = detectedTypes[0];
104
- h264Encoder = detectedH264[0] || "libx264";
105
- hevcEncoder = detectedHevc[0] || "libx265";
129
+ // Verify that the driver/device actually initializes (e.g. NVENC compiled in ffmpeg on runner without GPU)
130
+ for (const candidate of candidates) {
131
+ if (await canEncodeWith(candidate.h264)) {
132
+ chosenType = candidate.type;
133
+ h264Encoder = candidate.h264;
134
+ hevcEncoder = candidate.hevc;
135
+ break;
136
+ }
106
137
  }
107
138
  cachedInfo = {
108
139
  isAvailable: chosenType !== "none",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ash_j1997/ffmpeg-mcp-server",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "MCP server for FFmpeg and FFprobe media processing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",