@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 CHANGED
@@ -1,299 +1,155 @@
1
1
  # @deepfish-ai/ffmpeg7-media-tools
2
2
 
3
- 基于FFmpeg 7的音频视频处理工具函数集,包含23个媒体处理函数,支持视频格式转换、音频提取、视频编辑等常见媒体处理任务。
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
- - **全面覆盖**: 23个精心设计的FFmpeg函数,覆盖常见媒体处理需求
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
- 需要先安装FFmpeg 7或更高版本:
17
+ ### Prerequisites
18
18
 
19
- #### Windows
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
- # 使用Homebrew安装FFmpeg 7
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
- 或者安装最新版本(可能包含FFmpeg 7):
35
- ```bash
36
- brew install ffmpeg
37
- ```
25
+ ### Installation
38
26
 
39
- #### Linux (Ubuntu/Debian)
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
- # 添加PPA
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
- 安装完成后,请验证FFmpeg版本是否为7.0或更高:
69
- ```bash
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
- 如果版本低于7.0,请参考上述安装方法重新安装FFmpeg 7。
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
- ## 📋 API参考
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
- ```javascript
166
- const result = await functions.ffmpeg_resizeVideo({
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
- ```javascript
189
- const result = await functions.ffmpeg_addWatermark({
190
- inputPath: 'video.mp4',
191
- outputPath: 'video_with_logo.mp4',
192
- watermarkPath: 'logo.png',
193
- position: 'top-right',
194
- opacity: 0.7
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
- ```javascript
209
- // 批量压缩视频
210
- const videos = ['video1.mp4', 'video2.mp4', 'video3.mp4'];
211
-
212
- for (const video of videos) {
213
- await functions.ffmpeg_compressVideo({
214
- videoPath: video,
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 # 23个FFmpeg功能函数实现
227
- ├── ffmpeg-descriptions.js # AI智能体描述信息
228
- ├── index.js # 主入口文件,重新导出功能
229
- ├── package.json # 项目配置
230
- └── README.md # 本文档
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版本**: 本工具集基于FFmpeg 7设计,建议使用FFmpeg 7.0或更高版本
242
- 2. **文件路径**: 所有文件路径建议使用绝对路径,相对路径可能因工作目录不同而产生问题
243
- 3. **错误处理**: 所有函数都包含错误处理,执行失败时会抛出详细的错误信息
244
- 4. **资源消耗**: 视频处理是CPU密集型任务,大文件处理时请注意系统资源
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
- - 确认FFmpeg已正确安装
255
- - FFmpeg添加到系统PATH环境变量
256
- - 重启终端或IDE使环境变量生效
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
- 欢迎提交Issue和Pull Request来改进这个项目。在提交PR前,请确保:
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. 更新文档(包括API文档和示例)
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 - 详见LICENSE文件
142
+ MIT License - See LICENSE file
287
143
 
288
- ## 📞 支持
144
+ ## 📞 Support
289
145
 
290
- 如有问题或建议,请:
291
- 1. 查看本文档的故障排除部分
292
- 2. 提交GitHub Issue
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
- **最后更新**: 2026
298
- **版本**: 1.0.0
299
- **FFmpeg版本**: 7.0+
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+
@@ -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
 
@@ -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
@@ -3,7 +3,7 @@
3
3
  * 重新导出拆分的功能函数和描述文件,提供向后兼容性
4
4
  */
5
5
 
6
- const functions = require('./ffmpeg-functions.js').functions;
6
+ const functions = require('./ffmpeg-functions.js');
7
7
  const descriptions = require('./ffmpeg-descriptions.js');
8
8
 
9
9
  // 导出
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deepfish-ai/ffmpeg7-media-tools",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "基于FFmpeg 7的音频视频处理工具函数集",
5
5
  "main": "index.js",
6
6
  "scripts": {},