YM-MediaToolkit(媒体处理工具集)

核心用法

ym-mediatoolkit 是一个基于 FFmpeg 的流式视频处理 Skill，支持三种核心功能：

1. 视频压缩 (compress)

• 流式边下载边压缩，目标体积可压缩至原文件的 1/10
• 支持自适应 CRF 调整（18-28）和编码预设控制
• 输出格式为 H.264/MP4

2. 封面提取 (thumbnail)

• 支持按时间点（秒）或帧号精确提取
• 可选 JPEG 质量控制和缩放输出
• 返回视频元数据（分辨率、时长、编码、帧率等）

3. 音频提取 (audio / audio_batch)

• 支持 MP3 / WAV / AAC / M4A 四种格式
• 可指定比特率、采样率、声道数
• 支持时间裁剪和批量处理

调用方式：CLI 命令行（-a 参数）、JSON 配置文件、HTTP REST API（默认 127.0.0.1:8080）。

---

显著优点

• 流式架构：无需等待完整下载，大幅降低时间和磁盘开销
• 安全设计完善：
• 多层 URL 验证（协议白名单、IDN/Punycode 拦截、IPv4/IPv6 私有 IP 检测、DNS 解析后二次校验）
• 路径穿越防护（.. 过滤、保留设备名拦截、工作目录边界检查）
• DNS 失败时采用 fail-close 策略（拒绝而非放行）
• 防御 SSRF：覆盖 IP 直连、DNS 重绑定、IPv6 映射等攻击向量
• 模块化设计：音频/视频/帧提取分离，便于维护和扩展
• 批量处理：原生支持多视频批量音频提取和通用批量操作

---

潜在缺点与局限性

| 问题 | 说明 |

|------|------|

| **DNS 重绑定残余风险** | 验证通过后若 DNS 快速切换仍可能攻击内网，需配合网络层出口控制 |

| **HTTP 重定向风险** | ffmpeg 可能跟随 302 跳转至未验证地址，依赖反向代理缓解 |

| **非标准 IP 格式** | 十六进制/八进制 IP（如 `0x7f000001`）可能绕过部分校验 |

| **FFmpeg 沙箱缺失** | 子进程执行不可完全隔离，依赖容器化部署降低影响 |

| **临时文件风险** | `download_video_to_temp()` 完整下载至磁盘，若启用需磁盘配额 |

| **HTTP 默认本地绑定** | 直接暴露 `--host 0.0.0.0` 需配合反向代理认证，否则无内置鉴权 |

---

适合人群

• 内容创作者/运营团队：快速提取视频封面、生成音频播客版本
• 企业媒体处理平台：需要安全可控的远程视频转码服务
• SaaS 开发者：集成视频预处理流水线（压缩→存储→分发）
• 安全敏感场景：对 SSRF 有严格要求的内部工具部署

---

常规风险

1. 供应链风险：依赖系统级 FFmpeg，需从可信源（apt/brew/choco）安装，防范恶意二进制
2. 资源耗尽：长时间视频流处理可能消耗大量带宽和 CPU，需设置超时和并发限制
3. 信息泄露：视频元数据（info 端点）可能暴露敏感来源信息，建议日志脱敏
4. 部署配置风险：开发者若忽略 127.0.0.1 警告直接公网暴露，将失去 URL 验证的最后一道防线价值

核心用法

ym-mediatoolkit 是一款面向 Agent 的高性能视频处理 Skill，采用流式架构实现边下载边处理，避免传统方案需完整下载视频后再处理的高延迟问题。通过统一入口 run.py 支持 CLI 命令行和 HTTP API 两种调用模式。

主要功能模块包括：

• 视频压缩：支持自定义 CRF、预设档位，可将视频体积压缩至原大小的 1/10 同时保持清晰度
• 封面提取：支持按时间点或帧号精确提取，可配置输出尺寸与 JPEG 质量
• 音频提取：支持 MP3/WAV/AAC/M4A 四种格式，可裁剪指定时间段
• 批量处理：支持多视频并行处理，适合内容运营场景

API 设计遵循 RESTful 风格，所有端点接收 JSON 参数并返回结构化响应，便于 Agent 集成调用。

显著优点

性能优势突出：流式处理架构省去完整下载等待时间，对于大体积视频（如 4K 素材）效果尤为明显，可节省 50%-90% 的处理时间。

安全防护完善：实现了六层 URL 验证机制（协议过滤、Unicode 同形字拦截、IP 段正则匹配、DNS 解析验证、IPv6 防护、失败即拒绝策略），以及路径穿越、系统保留名、越界写入三重输出防护，有效防御 SSRF、LFI 等常见攻击向量。

部署灵活：支持独立 CLI 使用、本地 HTTP 服务、容器化部署三种模式，默认绑定 127.0.0.1 避免误暴露风险。

依赖生态成熟：基于 ffmpeg/ffprobe 工业标准工具链，而非自研编解码器，稳定性和兼容性有保障。

潜在缺点与局限性

DNS 重绑定攻击残留风险：尽管验证逻辑完善，但攻击者仍可能在验证通过后快速切换 DNS 记录指向内网地址，需配合网络层出口控制缓解。

HTTP 重定向跟随：ffmpeg 可能跟随 302 跳转至验证时未检查的地址，依赖反向代理层二次校验。

十六进制 IP 绕过：如 0x7f000001 等特殊格式可能绕过 ipaddress 库识别，虽 getaddrinfo 可部分捕获，但存在平台差异。

子进程沙箱缺失：ffmpeg 通过 subprocess 以非受信 URL 参数执行，缺乏进程级沙箱隔离，需依赖容器/系统级隔离。

功能边界限制：当前版本不支持视频剪辑合并、水印叠加、分辨率动态调整等进阶编辑功能。

适合的目标群体

• 内容运营团队：需要批量提取视频封面、转换音频格式用于多平台分发
• 电商/直播从业者：快速压缩商品视频、提取精彩片段用于广告投放
• 开发者/技术型 Agent：需要集成视频预处理能力的自动化工作流
• 教育培训机构：批量处理课程视频，提取音频生成播客版本

使用风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 资源耗尽 | 大视频流处理可能耗尽内存/磁盘 | 配置磁盘配额、设置流缓冲区上限 |

| 依赖安全 | ffmpeg 本身可能存在漏洞 | 使用官方源安装、及时更新版本 |

| 网络滥用 | 被用于恶意视频下载/分发 | 启用访问日志、配置速率限制、URL 域名白名单 |

| 临时文件残留 | 异常中断导致 /tmp 堆积 | 配置 TMPDIR 定期清理任务 |

| 公网暴露风险 | HTTP 服务直接暴露无认证 | 前置反向代理 + Basic Auth/API Key |

建议生产环境采用 Docker 容器 + 非 root 用户 + 网络出口 ACL + 反向代理认证的四层防护架构。