@deepfish-ai/ffmpeg7-media-tools 1.0.0 → 1.0.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.md +101 -245
- package/README_CN.md +155 -0
- package/ffmpeg-descriptions.js +24 -0
- package/ffmpeg-functions.js +26 -0
- package/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,299 +1,155 @@
|
|
|
1
1
|
# @deepfish-ai/ffmpeg7-media-tools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
English | [中文](./README_CN.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A comprehensive FFmpeg 7 based audio and video processing toolkit with 24 media processing functions, supporting video format conversion, audio extraction, video editing, and other common media processing tasks.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **易于使用**: 统一的参数格式,清晰的错误处理
|
|
9
|
-
- **AI友好**: 包含完整的AI智能体描述信息
|
|
10
|
-
- **跨平台**: 支持Windows、macOS和Linux系统
|
|
11
|
-
- **TypeScript友好**: 完整的JSDoc注释和类型提示
|
|
7
|
+
## ✨ Features
|
|
12
8
|
|
|
13
|
-
|
|
9
|
+
- **Comprehensive Coverage**: 24 carefully designed FFmpeg functions covering common media processing needs
|
|
10
|
+
- **Easy to Use**: Unified parameter format, clear error handling
|
|
11
|
+
- **AI Friendly**: Complete AI agent description information included
|
|
12
|
+
- **Cross-Platform**: Supports Windows, macOS, and Linux systems
|
|
13
|
+
- **TypeScript Friendly**: Complete JSDoc comments and type hints
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
## 🚀 Quick Start
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
### Prerequisites
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
1. 下载FFmpeg 7:https://ffmpeg.org/download.html(选择包含版本7的构建)
|
|
21
|
-
2. 解压并添加到系统PATH环境变量
|
|
22
|
-
3. 验证安装:`ffmpeg -version`
|
|
19
|
+
First, install the global deepfish-ai library:
|
|
23
20
|
|
|
24
|
-
#### macOS
|
|
25
21
|
```bash
|
|
26
|
-
|
|
27
|
-
brew install ffmpeg@7
|
|
28
|
-
|
|
29
|
-
# 如果找不到ffmpeg@7,可以先更新Homebrew再尝试
|
|
30
|
-
brew update
|
|
31
|
-
brew install ffmpeg@7
|
|
22
|
+
npm install deepfish-ai -g
|
|
32
23
|
```
|
|
33
24
|
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
brew install ffmpeg
|
|
37
|
-
```
|
|
25
|
+
### Installation
|
|
38
26
|
|
|
39
|
-
|
|
40
|
-
**方法一:使用官方静态构建(推荐)**
|
|
41
|
-
```bash
|
|
42
|
-
# 下载最新FFmpeg 7静态构建
|
|
43
|
-
wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz
|
|
44
|
-
# 解压
|
|
45
|
-
tar xf ffmpeg-release-amd64-static.tar.xz
|
|
46
|
-
# 进入解压目录
|
|
47
|
-
cd ffmpeg-*-amd64-static
|
|
48
|
-
# 复制二进制文件到系统路径
|
|
49
|
-
sudo cp ffmpeg ffprobe /usr/local/bin/
|
|
50
|
-
```
|
|
27
|
+
Install this package globally:
|
|
51
28
|
|
|
52
|
-
**方法二:使用PPA安装(适用于Ubuntu 22.04+)**
|
|
53
29
|
```bash
|
|
54
|
-
|
|
55
|
-
sudo add-apt-repository ppa:jonathonf/ffmpeg-7
|
|
56
|
-
sudo apt update
|
|
57
|
-
sudo apt install ffmpeg
|
|
30
|
+
npm install @deepfish-ai/ffmpeg7-media-tools -g
|
|
58
31
|
```
|
|
59
32
|
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
sudo apt update
|
|
63
|
-
sudo apt install ffmpeg
|
|
64
|
-
```
|
|
33
|
+
### FFmpeg Installation
|
|
65
34
|
|
|
35
|
+
This toolkit requires FFmpeg 7 or higher. Please install FFmpeg 7 before using:
|
|
66
36
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
ffmpeg -version | head -n 1
|
|
71
|
-
```
|
|
72
|
-
应该输出类似:`ffmpeg version 7.0.1 Copyright (c) 2000-2024...`
|
|
37
|
+
- **Windows**: Download FFmpeg 7 from https://ffmpeg.org/download.html and add to system PATH
|
|
38
|
+
- **macOS**: `brew install ffmpeg@7` or `brew install ffmpeg`
|
|
39
|
+
- **Linux**: Use static builds or distribution packages
|
|
73
40
|
|
|
74
|
-
|
|
41
|
+
Verify installation: `ffmpeg -version` should show version 7.0 or higher.
|
|
75
42
|
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
npm install @deepfish-ai/ffmpeg7-media-tools
|
|
79
|
-
```
|
|
43
|
+
## 📋 Function List
|
|
80
44
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
```javascript
|
|
84
|
-
const { functions } = require('@deepfish-ai/ffmpeg7-media-tools');
|
|
85
|
-
|
|
86
|
-
// 1. 检查FFmpeg安装
|
|
87
|
-
const checkResult = await functions.ffmpeg_checkFfmpegInstallation({
|
|
88
|
-
minVersion: '7.0.0'
|
|
89
|
-
});
|
|
90
|
-
|
|
91
|
-
// 2. 转换视频格式
|
|
92
|
-
const convertResult = await functions.ffmpeg_convertVideoFormat({
|
|
93
|
-
inputPath: '/path/to/input.avi',
|
|
94
|
-
outputPath: '/path/to/output.mp4',
|
|
95
|
-
format: 'mp4',
|
|
96
|
-
quality: '-crf 23'
|
|
97
|
-
});
|
|
98
|
-
|
|
99
|
-
// 3. 从视频中提取音频
|
|
100
|
-
const audioResult = await functions.ffmpeg_extractAudioFromVideo({
|
|
101
|
-
videoPath: '/path/to/video.mp4',
|
|
102
|
-
audioPath: '/path/to/audio.mp3',
|
|
103
|
-
audioFormat: 'mp3'
|
|
104
|
-
});
|
|
105
|
-
```
|
|
45
|
+
The toolkit provides 24 functions divided into the following categories:
|
|
106
46
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
### 安装检测 (1个)
|
|
110
|
-
|
|
111
|
-
| 函数名 | 描述 | 主要参数 |
|
|
112
|
-
|--------|------|----------|
|
|
113
|
-
| `ffmpeg_checkFfmpegInstallation` | 检测FFmpeg是否安装和版本检测 | `minVersion` |
|
|
114
|
-
|
|
115
|
-
### 视频处理 (17个)
|
|
116
|
-
|
|
117
|
-
| 函数名 | 描述 | 主要参数 |
|
|
118
|
-
|--------|------|----------|
|
|
119
|
-
| `ffmpeg_convertVideoFormat` | 转换视频格式 | `inputPath`, `outputPath`, `format`, `quality` |
|
|
120
|
-
| `ffmpeg_resizeVideo` | 调整视频尺寸 | `inputPath`, `outputPath`, `width`, `height`, `keepAspectRatio` |
|
|
121
|
-
| `ffmpeg_trimVideo` | 剪切视频片段 | `inputPath`, `outputPath`, `startTime`, `duration` |
|
|
122
|
-
| `ffmpeg_mergeVideos` | 合并多个视频文件 | `videoPaths`, `outputPath`, `method` |
|
|
123
|
-
| `ffmpeg_adjustBitrate` | 调整视频比特率 | `inputPath`, `outputPath`, `bitrate`, `audioBitrate` |
|
|
124
|
-
| `ffmpeg_addWatermark` | 添加水印 | `inputPath`, `outputPath`, `watermarkPath`, `position`, `opacity` |
|
|
125
|
-
| `ffmpeg_mergeVideoAudio` | 合并视频和音频 | `videoPath`, `audioPath`, `outputPath`, `sync` |
|
|
126
|
-
| `ffmpeg_videoToGif` | 将视频转换为GIF动图 | `videoPath`, `outputPath`, `startTime`, `duration`, `fps`, `width` |
|
|
127
|
-
| `ffmpeg_cropVideo` | 裁剪视频区域 | `videoPath`, `outputPath`, `x`, `y`, `width`, `height` |
|
|
128
|
-
| `ffmpeg_rotateVideo` | 旋转视频 | `videoPath`, `outputPath`, `angle` |
|
|
129
|
-
| `ffmpeg_changeVideoSpeed` | 改变视频播放速度 | `videoPath`, `outputPath`, `speed` |
|
|
130
|
-
| `ffmpeg_addSubtitles` | 添加字幕到视频 | `videoPath`, `subtitlePath`, `outputPath`, `encoding` |
|
|
131
|
-
| `ffmpeg_addTextOverlay` | 添加文本叠加到视频 | `videoPath`, `outputPath`, `text`, `x`, `y`, `fontSize`, `fontColor`, `startTime`, `duration` |
|
|
132
|
-
| `ffmpeg_extractVideoFrames` | 提取视频帧为图片序列 | `videoPath`, `outputDir`, `fps`, `format`, `startTime`, `duration` |
|
|
133
|
-
| `ffmpeg_extractVideoThumbnail` | 提取视频缩略图 | `videoPath`, `outputPath`, `time`, `size` |
|
|
134
|
-
| `ffmpeg_compressVideo` | 压缩视频(调整CRF) | `videoPath`, `outputPath`, `crf`, `preset` |
|
|
135
|
-
| `ffmpeg_concatVideos` | 拼接多个视频文件 | `videoPaths`, `outputPath`, `transition` |
|
|
136
|
-
|
|
137
|
-
### 音频处理 (5个)
|
|
138
|
-
|
|
139
|
-
| 函数名 | 描述 | 主要参数 |
|
|
140
|
-
|--------|------|----------|
|
|
141
|
-
| `ffmpeg_extractAudioFromVideo` | 从视频中提取音频 | `videoPath`, `audioPath`, `audioFormat` |
|
|
142
|
-
| `ffmpeg_convertAudioFormat` | 转换音频格式 | `inputPath`, `outputPath`, `format`, `bitrate` |
|
|
143
|
-
| `ffmpeg_adjustAudioVolume` | 调整音频音量 | `inputPath`, `outputPath`, `volume` |
|
|
144
|
-
| `ffmpeg_mixAudios` | 混合多个音频文件 | `audioPaths`, `outputPath`, `volumes` |
|
|
145
|
-
|
|
146
|
-
### 媒体信息 (1个)
|
|
147
|
-
|
|
148
|
-
| 函数名 | 描述 | 主要参数 |
|
|
149
|
-
|--------|------|----------|
|
|
150
|
-
| `ffmpeg_getMediaInfo` | 获取媒体文件信息 | `mediaPath` |
|
|
151
|
-
|
|
152
|
-
## 🔧 详细使用示例
|
|
153
|
-
|
|
154
|
-
### 视频格式转换
|
|
155
|
-
```javascript
|
|
156
|
-
const result = await functions.ffmpeg_convertVideoFormat({
|
|
157
|
-
inputPath: 'input.avi',
|
|
158
|
-
outputPath: 'output.mp4',
|
|
159
|
-
format: 'mp4',
|
|
160
|
-
quality: '-crf 23'
|
|
161
|
-
});
|
|
162
|
-
```
|
|
47
|
+
### Installation Detection (1 function)
|
|
163
48
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
inputPath: 'input.mp4',
|
|
168
|
-
outputPath: 'output_720p.mp4',
|
|
169
|
-
width: 1280,
|
|
170
|
-
height: 720,
|
|
171
|
-
keepAspectRatio: true
|
|
172
|
-
});
|
|
173
|
-
```
|
|
49
|
+
| Function Name | Description |
|
|
50
|
+
|---------------|-------------|
|
|
51
|
+
| `ffmpeg_checkFfmpegInstallation` | Check FFmpeg installation and version detection |
|
|
174
52
|
|
|
175
|
-
###
|
|
176
|
-
```javascript
|
|
177
|
-
const result = await functions.ffmpeg_cropVideo({
|
|
178
|
-
videoPath: 'input.mp4',
|
|
179
|
-
outputPath: 'output_cropped.mp4',
|
|
180
|
-
x: 100,
|
|
181
|
-
y: 100,
|
|
182
|
-
width: 800,
|
|
183
|
-
height: 600
|
|
184
|
-
});
|
|
185
|
-
```
|
|
53
|
+
### Video Processing (18 functions)
|
|
186
54
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
55
|
+
| Function Name | Description |
|
|
56
|
+
|---------------|-------------|
|
|
57
|
+
| `ffmpeg_convertVideoFormat` | Convert video format |
|
|
58
|
+
| `ffmpeg_resizeVideo` | Resize video dimensions |
|
|
59
|
+
| `ffmpeg_trimVideo` | Trim video segment |
|
|
60
|
+
| `ffmpeg_mergeVideos` | Merge multiple video files |
|
|
61
|
+
| `ffmpeg_adjustBitrate` | Adjust video bitrate |
|
|
62
|
+
| `ffmpeg_addWatermark` | Add watermark to video |
|
|
63
|
+
| `ffmpeg_mergeVideoAudio` | Merge video and audio |
|
|
64
|
+
| `ffmpeg_videoToGif` | Convert video to animated GIF |
|
|
65
|
+
| `ffmpeg_cropVideo` | Crop video region |
|
|
66
|
+
| `ffmpeg_rotateVideo` | Rotate video |
|
|
67
|
+
| `ffmpeg_changeVideoSpeed` | Change video playback speed |
|
|
68
|
+
| `ffmpeg_addSubtitles` | Add subtitles to video |
|
|
69
|
+
| `ffmpeg_addTextOverlay` | Add text overlay to video |
|
|
70
|
+
| `ffmpeg_adjustVideoVolume` | Adjust video volume |
|
|
71
|
+
| `ffmpeg_extractVideoFrames` | Extract video frames as image sequence |
|
|
72
|
+
| `ffmpeg_extractVideoThumbnail` | Extract video thumbnail |
|
|
73
|
+
| `ffmpeg_compressVideo` | Compress video (adjust CRF) |
|
|
74
|
+
| `ffmpeg_concatVideos` | Concatenate multiple video files |
|
|
197
75
|
|
|
198
|
-
###
|
|
199
|
-
```javascript
|
|
200
|
-
const result = await functions.ffmpeg_extractAudioFromVideo({
|
|
201
|
-
videoPath: 'video.mp4',
|
|
202
|
-
audioPath: 'audio.mp3',
|
|
203
|
-
audioFormat: 'mp3'
|
|
204
|
-
});
|
|
205
|
-
```
|
|
76
|
+
### Audio Processing (5 functions)
|
|
206
77
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
outputPath: `compressed_${video}`,
|
|
216
|
-
crf: 28, // 更高的CRF值表示更强的压缩
|
|
217
|
-
preset: 'slow'
|
|
218
|
-
});
|
|
219
|
-
}
|
|
220
|
-
```
|
|
78
|
+
| Function Name | Description |
|
|
79
|
+
|---------------|-------------|
|
|
80
|
+
| `ffmpeg_extractAudioFromVideo` | Extract audio from video |
|
|
81
|
+
| `ffmpeg_convertAudioFormat` | Convert audio format |
|
|
82
|
+
| `ffmpeg_adjustAudioVolume` | Adjust audio volume |
|
|
83
|
+
| `ffmpeg_mixAudios` | Mix multiple audio files |
|
|
84
|
+
|
|
85
|
+
### Media Information (1 function)
|
|
221
86
|
|
|
222
|
-
|
|
87
|
+
| Function Name | Description |
|
|
88
|
+
|---------------|-------------|
|
|
89
|
+
| `ffmpeg_getMediaInfo` | Get media file information |
|
|
90
|
+
|
|
91
|
+
## 🏗️ Project Structure
|
|
223
92
|
|
|
224
93
|
```
|
|
225
94
|
ffmpeg7-media-tools/
|
|
226
|
-
├── ffmpeg-functions.js #
|
|
227
|
-
├── ffmpeg-descriptions.js # AI
|
|
228
|
-
├── index.js #
|
|
229
|
-
├── package.json #
|
|
230
|
-
|
|
95
|
+
├── ffmpeg-functions.js # 24 FFmpeg function implementations
|
|
96
|
+
├── ffmpeg-descriptions.js # AI agent description information
|
|
97
|
+
├── index.js # Main entry file, re-exports functions
|
|
98
|
+
├── package.json # Project configuration
|
|
99
|
+
├── README.md # English documentation (this file)
|
|
100
|
+
└── README_CN.md # Chinese documentation
|
|
231
101
|
```
|
|
232
102
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
- **ffmpeg-functions.js**: 包含所有23个FFmpeg媒体处理函数的实现,每个函数都有完整的错误处理和参数验证
|
|
236
|
-
- **ffmpeg-descriptions.js**: 为AI智能体提供的函数描述信息,包含详细的参数说明和功能描述
|
|
237
|
-
- **index.js**: 统一导出接口,便于模块化使用
|
|
238
|
-
|
|
239
|
-
## ⚠️ 注意事项
|
|
103
|
+
## ⚠️ Notes
|
|
240
104
|
|
|
241
|
-
1. **FFmpeg
|
|
242
|
-
2.
|
|
243
|
-
3.
|
|
244
|
-
4.
|
|
245
|
-
5.
|
|
105
|
+
1. **FFmpeg Version**: This toolkit is designed for FFmpeg 7, recommended to use FFmpeg 7.0 or higher
|
|
106
|
+
2. **File Paths**: Use absolute paths for all file operations
|
|
107
|
+
3. **Error Handling**: All functions include error handling with detailed error messages
|
|
108
|
+
4. **Resource Consumption**: Video processing is CPU-intensive, monitor system resources when processing large files
|
|
109
|
+
5. **Output Directory**: Ensure output directories exist before processing
|
|
246
110
|
|
|
247
|
-
## 🔍
|
|
111
|
+
## 🔍 Troubleshooting
|
|
248
112
|
|
|
249
|
-
### FFmpeg
|
|
113
|
+
### FFmpeg Not Found
|
|
250
114
|
```
|
|
251
115
|
Error: FFmpeg is not installed or not in system PATH
|
|
252
116
|
```
|
|
253
|
-
|
|
254
|
-
-
|
|
255
|
-
-
|
|
256
|
-
-
|
|
117
|
+
**Solution**:
|
|
118
|
+
- Confirm FFmpeg is correctly installed
|
|
119
|
+
- Add FFmpeg to system PATH environment variable
|
|
120
|
+
- Restart terminal or IDE for environment variables to take effect
|
|
257
121
|
|
|
258
|
-
###
|
|
122
|
+
### File Does Not Exist
|
|
259
123
|
```
|
|
260
124
|
Error: Input file does not exist: /path/to/file.mp4
|
|
261
125
|
```
|
|
262
|
-
|
|
263
|
-
-
|
|
264
|
-
-
|
|
265
|
-
-
|
|
266
|
-
|
|
267
|
-
### 格式不支持
|
|
268
|
-
```
|
|
269
|
-
Error: Unsupported video format: .xyz
|
|
270
|
-
```
|
|
271
|
-
**解决方案**:
|
|
272
|
-
- 检查输入文件格式是否被FFmpeg支持
|
|
273
|
-
- 尝试使用`ffmpeg_convertVideoFormat`先转换格式
|
|
126
|
+
**Solution**:
|
|
127
|
+
- Confirm file path is correct
|
|
128
|
+
- Use absolute paths instead of relative paths
|
|
129
|
+
- Check file permissions
|
|
274
130
|
|
|
275
|
-
## 🤝
|
|
131
|
+
## 🤝 Contributing
|
|
276
132
|
|
|
277
|
-
|
|
133
|
+
Welcome to submit Issues and Pull Requests to improve this project. Before submitting a PR, please ensure:
|
|
278
134
|
|
|
279
|
-
1.
|
|
280
|
-
2.
|
|
281
|
-
3.
|
|
282
|
-
4.
|
|
135
|
+
1. Code style is consistent
|
|
136
|
+
2. Add appropriate tests
|
|
137
|
+
3. Update documentation (including API docs and examples)
|
|
138
|
+
4. Function parameter formats are unified
|
|
283
139
|
|
|
284
|
-
## 📄
|
|
140
|
+
## 📄 License
|
|
285
141
|
|
|
286
|
-
MIT License -
|
|
142
|
+
MIT License - See LICENSE file
|
|
287
143
|
|
|
288
|
-
## 📞
|
|
144
|
+
## 📞 Support
|
|
289
145
|
|
|
290
|
-
|
|
291
|
-
1.
|
|
292
|
-
2.
|
|
293
|
-
3.
|
|
146
|
+
For questions or suggestions, please:
|
|
147
|
+
1. Check the Troubleshooting section in this documentation
|
|
148
|
+
2. Submit a GitHub Issue
|
|
149
|
+
3. Contact the maintenance team
|
|
294
150
|
|
|
295
151
|
---
|
|
296
152
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
**FFmpeg
|
|
153
|
+
**Last Updated**: 2026
|
|
154
|
+
**Version**: 1.0.0
|
|
155
|
+
**FFmpeg Version**: 7.0+
|
package/README_CN.md
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# @deepfish-ai/ffmpeg7-media-tools
|
|
2
|
+
|
|
3
|
+
[English](./README.md) | 中文
|
|
4
|
+
|
|
5
|
+
基于FFmpeg 7的音频视频处理工具函数集,包含24个媒体处理函数,支持视频格式转换、音频提取、视频编辑等常见媒体处理任务。
|
|
6
|
+
|
|
7
|
+
## ✨ 特性
|
|
8
|
+
|
|
9
|
+
- **全面覆盖**: 24个精心设计的FFmpeg函数,覆盖常见媒体处理需求
|
|
10
|
+
- **易于使用**: 统一的参数格式,清晰的错误处理
|
|
11
|
+
- **AI友好**: 包含完整的AI智能体描述信息
|
|
12
|
+
- **跨平台**: 支持Windows、macOS和Linux系统
|
|
13
|
+
- **TypeScript友好**: 完整的JSDoc注释和类型提示
|
|
14
|
+
|
|
15
|
+
## 🚀 快速开始
|
|
16
|
+
|
|
17
|
+
### 前提条件
|
|
18
|
+
|
|
19
|
+
首先,安装全局deepfish-ai库:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install deepfish-ai -g
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### 安装
|
|
26
|
+
|
|
27
|
+
全局安装本包:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install @deepfish-ai/ffmpeg7-media-tools -g
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### FFmpeg安装
|
|
34
|
+
|
|
35
|
+
本工具集需要FFmpeg 7或更高版本。使用前请先安装FFmpeg 7:
|
|
36
|
+
|
|
37
|
+
- **Windows**: 从 https://ffmpeg.org/download.html 下载FFmpeg 7并添加到系统PATH
|
|
38
|
+
- **macOS**: `brew install ffmpeg@7` 或 `brew install ffmpeg`
|
|
39
|
+
- **Linux**: 使用静态构建或发行版软件包
|
|
40
|
+
|
|
41
|
+
验证安装:`ffmpeg -version` 应显示版本7.0或更高。
|
|
42
|
+
|
|
43
|
+
## 📋 函数列表
|
|
44
|
+
|
|
45
|
+
工具集提供24个函数,分为以下类别:
|
|
46
|
+
|
|
47
|
+
### 安装检测 (1个函数)
|
|
48
|
+
|
|
49
|
+
| 函数名 | 描述 |
|
|
50
|
+
|--------|------|
|
|
51
|
+
| `ffmpeg_checkFfmpegInstallation` | 检测FFmpeg是否安装和版本检测 |
|
|
52
|
+
|
|
53
|
+
### 视频处理 (18个函数)
|
|
54
|
+
|
|
55
|
+
| 函数名 | 描述 |
|
|
56
|
+
|--------|------|
|
|
57
|
+
| `ffmpeg_convertVideoFormat` | 转换视频格式 |
|
|
58
|
+
| `ffmpeg_resizeVideo` | 调整视频尺寸 |
|
|
59
|
+
| `ffmpeg_trimVideo` | 剪切视频片段 |
|
|
60
|
+
| `ffmpeg_mergeVideos` | 合并多个视频文件 |
|
|
61
|
+
| `ffmpeg_adjustBitrate` | 调整视频比特率 |
|
|
62
|
+
| `ffmpeg_addWatermark` | 添加水印 |
|
|
63
|
+
| `ffmpeg_mergeVideoAudio` | 合并视频和音频 |
|
|
64
|
+
| `ffmpeg_videoToGif` | 将视频转换为GIF动图 |
|
|
65
|
+
| `ffmpeg_cropVideo` | 裁剪视频区域 |
|
|
66
|
+
| `ffmpeg_rotateVideo` | 旋转视频 |
|
|
67
|
+
| `ffmpeg_changeVideoSpeed` | 改变视频播放速度 |
|
|
68
|
+
| `ffmpeg_addSubtitles` | 添加字幕到视频 |
|
|
69
|
+
| `ffmpeg_addTextOverlay` | 添加文本叠加到视频 |
|
|
70
|
+
| `ffmpeg_adjustVideoVolume` | 调整视频音量 |
|
|
71
|
+
| `ffmpeg_extractVideoFrames` | 提取视频帧为图片序列 |
|
|
72
|
+
| `ffmpeg_extractVideoThumbnail` | 提取视频缩略图 |
|
|
73
|
+
| `ffmpeg_compressVideo` | 压缩视频(调整CRF) |
|
|
74
|
+
| `ffmpeg_concatVideos` | 拼接多个视频文件 |
|
|
75
|
+
|
|
76
|
+
### 音频处理 (5个函数)
|
|
77
|
+
|
|
78
|
+
| 函数名 | 描述 |
|
|
79
|
+
|--------|------|
|
|
80
|
+
| `ffmpeg_extractAudioFromVideo` | 从视频中提取音频 |
|
|
81
|
+
| `ffmpeg_convertAudioFormat` | 转换音频格式 |
|
|
82
|
+
| `ffmpeg_adjustAudioVolume` | 调整音频音量 |
|
|
83
|
+
| `ffmpeg_mixAudios` | 混合多个音频文件 |
|
|
84
|
+
|
|
85
|
+
### 媒体信息 (1个函数)
|
|
86
|
+
|
|
87
|
+
| 函数名 | 描述 |
|
|
88
|
+
|--------|------|
|
|
89
|
+
| `ffmpeg_getMediaInfo` | 获取媒体文件信息 |
|
|
90
|
+
|
|
91
|
+
## 🏗️ 项目结构
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
ffmpeg7-media-tools/
|
|
95
|
+
├── ffmpeg-functions.js # 24个FFmpeg功能函数实现
|
|
96
|
+
├── ffmpeg-descriptions.js # AI智能体描述信息
|
|
97
|
+
├── index.js # 主入口文件,重新导出功能
|
|
98
|
+
├── package.json # 项目配置
|
|
99
|
+
├── README.md # 英文文档
|
|
100
|
+
└── README_CN.md # 中文文档(本文档)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## ⚠️ 注意事项
|
|
104
|
+
|
|
105
|
+
1. **FFmpeg版本**: 本工具集基于FFmpeg 7设计,建议使用FFmpeg 7.0或更高版本
|
|
106
|
+
2. **文件路径**: 所有文件路径建议使用绝对路径,相对路径可能因工作目录不同而产生问题
|
|
107
|
+
3. **错误处理**: 所有函数都包含错误处理,执行失败时会抛出详细的错误信息
|
|
108
|
+
4. **资源消耗**: 视频处理是CPU密集型任务,大文件处理时请注意系统资源
|
|
109
|
+
5. **输出目录**: 请确保输出目录存在,否则某些函数可能无法正常创建输出文件
|
|
110
|
+
|
|
111
|
+
## 🔍 故障排除
|
|
112
|
+
|
|
113
|
+
### FFmpeg未找到
|
|
114
|
+
```
|
|
115
|
+
Error: FFmpeg is not installed or not in system PATH
|
|
116
|
+
```
|
|
117
|
+
**解决方案**:
|
|
118
|
+
- 确认FFmpeg已正确安装
|
|
119
|
+
- 将FFmpeg添加到系统PATH环境变量
|
|
120
|
+
- 重启终端或IDE使环境变量生效
|
|
121
|
+
|
|
122
|
+
### 文件不存在
|
|
123
|
+
```
|
|
124
|
+
Error: Input file does not exist: /path/to/file.mp4
|
|
125
|
+
```
|
|
126
|
+
**解决方案**:
|
|
127
|
+
- 确认文件路径正确
|
|
128
|
+
- 使用绝对路径而非相对路径
|
|
129
|
+
- 检查文件权限
|
|
130
|
+
|
|
131
|
+
## 🤝 贡献
|
|
132
|
+
|
|
133
|
+
欢迎提交Issue和Pull Request来改进这个项目。在提交PR前,请确保:
|
|
134
|
+
|
|
135
|
+
1. 代码风格一致
|
|
136
|
+
2. 添加相应的测试
|
|
137
|
+
3. 更新文档(包括API文档和示例)
|
|
138
|
+
4. 函数参数格式统一
|
|
139
|
+
|
|
140
|
+
## 📄 许可证
|
|
141
|
+
|
|
142
|
+
MIT License - 详见LICENSE文件
|
|
143
|
+
|
|
144
|
+
## 📞 支持
|
|
145
|
+
|
|
146
|
+
如有问题或建议,请:
|
|
147
|
+
1. 查看本文档的故障排除部分
|
|
148
|
+
2. 提交GitHub Issue
|
|
149
|
+
3. 联系维护团队
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
**最后更新**: 2026
|
|
154
|
+
**版本**: 1.0.0
|
|
155
|
+
**FFmpeg版本**: 7.0+
|
package/ffmpeg-descriptions.js
CHANGED
|
@@ -672,6 +672,30 @@ descriptions.push({
|
|
|
672
672
|
]
|
|
673
673
|
}
|
|
674
674
|
});
|
|
675
|
+
|
|
676
|
+
descriptions.push({
|
|
677
|
+
name: 'ffmpeg_adjustVideoVolume',
|
|
678
|
+
description: 'FFmpeg工具:调整视频音量',
|
|
679
|
+
parameters: {
|
|
680
|
+
type: 'object',
|
|
681
|
+
properties: {
|
|
682
|
+
videoPath: {
|
|
683
|
+
type: 'string',
|
|
684
|
+
description: '输入视频文件路径',
|
|
685
|
+
},
|
|
686
|
+
outputPath: {
|
|
687
|
+
type: 'string',
|
|
688
|
+
description: '输出视频文件路径',
|
|
689
|
+
},
|
|
690
|
+
volume: {
|
|
691
|
+
type: 'number',
|
|
692
|
+
description: '音量倍数(如0.5为一半音量,2.0为两倍音量)',
|
|
693
|
+
},
|
|
694
|
+
},
|
|
695
|
+
required: ['videoPath', 'outputPath', 'volume'],
|
|
696
|
+
},
|
|
697
|
+
});
|
|
698
|
+
|
|
675
699
|
|
|
676
700
|
|
|
677
701
|
|
package/ffmpeg-functions.js
CHANGED
|
@@ -980,6 +980,32 @@ functions.ffmpeg_addTextOverlay = async (params) => {
|
|
|
980
980
|
throw new Error(`${name.replace('ffmpeg_', '')}失败: ${error.message}`);
|
|
981
981
|
}
|
|
982
982
|
};
|
|
983
|
+
|
|
984
|
+
/**
|
|
985
|
+
* 调整视频音量
|
|
986
|
+
* @param {object} params 参数对象
|
|
987
|
+
* @param {string} params.videoPath 输入视频文件路径
|
|
988
|
+
* @param {string} params.outputPath 输出视频文件路径
|
|
989
|
+
* @param {number} params.volume 音量倍数(如0.5为一半音量,2.0为两倍音量)
|
|
990
|
+
*/
|
|
991
|
+
functions.ffmpeg_adjustVideoVolume = async (params) => {
|
|
992
|
+
const { videoPath, outputPath, volume } = params;
|
|
993
|
+
// 检查ffmpeg安装
|
|
994
|
+
const checkResult = await functions.ffmpeg_checkFfmpegInstallation({ minVersion: '7.0.0' });
|
|
995
|
+
if (!checkResult.installed || !checkResult.versionOk) {
|
|
996
|
+
throw new Error(`FFmpeg检查失败: ${checkResult.message}`);
|
|
997
|
+
}
|
|
998
|
+
// 构建调整视频音量命令
|
|
999
|
+
// 使用-filter:a调整音频,-c:v copy保持视频流不重新编码
|
|
1000
|
+
const command = `ffmpeg -i "${videoPath}" -filter:a "volume=${volume}" -c:v copy "${outputPath}"`;
|
|
1001
|
+
await this.Tools.executeCommand(command);
|
|
1002
|
+
return {
|
|
1003
|
+
success: true,
|
|
1004
|
+
message: `视频音量调整完成: ${volume}倍`,
|
|
1005
|
+
outputPath: outputPath
|
|
1006
|
+
};
|
|
1007
|
+
};
|
|
1008
|
+
|
|
983
1009
|
|
|
984
1010
|
|
|
985
1011
|
|
package/index.js
CHANGED