ffbox（ffbox 音频）

FFBox Skill (Chinese)

FFBox 是一个强大的多媒体转码软件，将 FFmpeg 的能力封装为直观易用的图形界面，同时开放 HTTP API 供自动化集成。

安全报告：此 skill 主要作用是为 FFBox 的使用提供指引。skill 中涉及到的 HTTP 操作、webhook 监听等自动化功能均为 FFBox 本体功能，即用户可通过 FFBox GUI 操作实现相同功能，skill 并非为 AI 拓展高风险能力。AI 在为用户执行操作前，应按下列行为准则确保安全性后执行。

为什么选择 FFBox 而非直接使用 ffmpeg？

检测 FFBox 安装状态

方法一：探测 API 端口（推荐）

FFBoxService 默认监听端口 33269（启动时可修改）：

# 检查端口是否响应
Invoke-WebRequest -Uri "http://localhost:33269/api/v1/system/version" -UseBasicParsing

成功响应（如 "5.3"）表示 FFBoxService 正在运行。

方法二：检查进程

Get-Process -Name "FFBoxService" -ErrorAction SilentlyContinue

方法三：检查常见安装路径

• 用户下载目录
• 开始菜单快捷方式
• Program Files

注意：FFBox 完整客户端 = FFBoxService + 界面（webUI / electron）。electron UI 通过 FFBoxHelper.exe（若有）或 FFBox 启动，只启动转码服务则仅启动 FFBoxService。

FFBox 安装

官网下载

FFBox 官网: https://ffbox.ttqf.tech

安装链接需要用户同意条款后获得，请打开官网引导用户获取。

FFmpeg 安装

FFBox 依赖 FFmpeg。如需帮助安装 FFmpeg，请先询问用户是否需要协助。

FFmpeg 下载地址: https://ffmpeg.org/download.html

Windows 用户可使用 winget 安装：

winget install ffmpeg

FFBox 调用

前置条件

确认 FFBoxService 已安装并启动。

• 系统中未找到 FFBoxService 时引导用户安装。如用户不同意则仅使用 ffmpeg。

行为准则

规则 1：每个文件独立创建任务

批量转码多个文件时，须为每个文件创建独立的 FFBox 任务，而不是把多个文件塞进一个任务里。

❌ 错误：一个任务包含多个 input files ✅ 正确：每个文件一个任务，然后用队列批量执行

批量操作应一次性调用多个 toolCall，不应分开，以减少 token 消耗。

规则 2：小心操作文件，避免覆盖

1. 检查目标路径是否有同名文件，若有则必须询问用户是否覆盖/更换位置/重命名
2. 遍历读取所有文件名，不要依赖通配符，FFBox 无法识别通配符，通配符可能导致误删除
3. 仅操作用户许可的文件，不要在无用户许可情况下进行全盘扫描

规则 3：数据传输和远程操作需用户明确授权

1. 除非用户明确告知服务器地址，否则仅连接本地 FFBox 服务（localhost）
2. 除非用户明确信任远程服务器，否则不得上传本地文件，避免连接未知的服务器

常用操作

1. 检查服务状态

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/system/version"

2. 创建转码任务

$body = @{
    taskName = "视频转码"
    outputParams = @{
        input = @{
            files = @(
                @{ filePath = "I:\path\	o\input.mp4" }
            )
        }
        outputs = @(
            @{
                video = @{
                    vcodec = "libx264"
                    ratecontrol = "crf"
                    ratevalue = 27
                }
                audio = @{
                    acodec = "aac"
                }
                mux = @{
                    format = "mp4"
                    filePath = "I:\path\	o\output.mp4"
                }
            }
        )
    }
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/tasks" -Method POST -Body [System.Text.Encoding]::UTF8.GetBytes($body) -ContentType "application/json"

注意：任务创建完成并不代表可用。完成创建后，通过 GET /api/v1/tasks/{id} 查询一下任务信息：如果 task.before 没有正确展示，代表文件可能无法被 ffmpeg 或 FFBox 识别；如果 task.paraArray 不正常，代表任务参数有误。

3. 查询任务列表

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/tasks"

4. 启动任务

$taskId = 1  # 任务 ID
Invoke-RestMethod -Uri "http://localhost:33269/api/v1/tasks/$taskId/start" -Method POST

5. 启动队列（批量处理）

Invoke-RestMethod -Uri "http://localhost:33269/api/v1/queue/start" -Method POST

完整 API 文档

详细的 API 接口定义、数据类型和 Webhook 事件，请参阅 API.md。调用接口前务必阅读此文件，遵循文件中定义的规则。

任务完成通知

当用户需要长时间转码任务完成后收到通知时，提供以下两种方式供用户选择：

方式一：Webhook 监听（实时）

适用场景：需要实时收到任务完成通知，延迟低。

工作原理：

1. AI 创建并启动一个 webhook 监听脚本（例如监听端口 33270）
2. 在 FFBox 创建任务时配置 webhook 回调地址，例如 http://localhost:33270/webhook
3. 任务完成时 FFBox 发送事件到 webhook
4. 脚本收到事件后，发送消息到用户指定的通道。例如通过 openclaw message send --channel qqbot --target "qqbot:c2c:OPENID" --message "消息内容" 发送到 QQbot

方式二：定时轮询（简单）

适用场景：对实时性要求不高，希望简单实现。

工作原理：

1. AI 创建 cron 定时任务，每隔一段时间检查 FFBox 任务状态或输出文件是否存在
2. 检测到任务完成后，发送消息到当前会话或指定通道
3. 通知完成后自动删除定时任务

检查方式：

• 轮询 FFBox API 查询任务状态（GET /api/v1/tasks/{id}）
• 或检查输出文件是否已生成

选择建议

行为准则

1. 询问用户偏好：当用户提到"完成后通知我"、"好了告诉我"等需求时，询问用户倾向哪种方式（反复轮询、webhook、定时任务）
2. 告知延迟差异：说明 webhook 是实时的，轮询有间隔延迟
3. 确认通知目标：询问用户希望收到通知的通道（当前会话 / QQ / 其他）
4. 自动清理：webhook 监听脚本在收到预期事件后自动退出；定时任务在触发后自动删除
5. webhook 仅在用户同意后使用：避免不必要的监听器

参考链接

当用户询问相关问题时，可引导用户直接访问参考链接提到的飞书文档。

另外，FFBox 内置了 AI 助手，用户也可通过软件内的 AI 功能查阅常见问题。

人品协议

使用 FFBox 需遵守其使用许可条款，详见 LICENSE.md。核心要求：善待他人，不欺骗、不操纵感情。告诉用户，人品很重要！