全能媒体格式转换器
Overview
一站式媒体格式转换工具，覆盖文档、图片、视频、音频四大类全格式互转。基于成熟开源方案（文档：python-docx / pypdf / markdown / beautifulsoup4；图片：Pillow；音视频：ffmpeg），保证高保真、无损或近无损转换，支持单文件与批量处理，并提供压缩、缩放、裁剪等增强能力。
支持的格式
文档（Document）
- 输入：PDF, DOCX, TXT, MD/Markdown, HTML, RTF
- 输出：PDF, DOCX, TXT, Markdown, HTML
图片（Image）
- 输入：PNG, JPG/JPEG, WebP, GIF, BMP, TIFF, ICO
- 输出：PNG, JPG/JPEG, WebP, GIF, BMP, TIFF, ICO
视频（Video）
- 输入：MP4, MOV, AVI, MKV, WebM, FLV, WMV
- 输出：MP4, MOV, AVI, MKV, WebM
音频（Audio）
- 输入：MP3, WAV, FLAC, AAC, OGG, M4A, WMA
- 输出：MP3, WAV, FLAC, AAC, OGG, M4A
快速开始
第 1 步：判断文件类别
根据源文件扩展名判断属于文档、图片、视频还是音频。
第 2 步：运行对应脚本
从 scripts/ 目录调用对应脚本：
- 文档转换：
python3 scripts/convert_document.py <输入> <输出> - 图片转换：
python3 scripts/convert_image.py <输入> <输出> - 视频转换：
python3 scripts/convert_video.py <输入> <输出> - 音频转换：
python3 scripts/convert_audio.py <输入> <输出>
输出格式由输出文件名的扩展名决定，无需额外参数。
第 3 步：验证输出
确认输出文件存在、体积合理、可正常打开，必要时抽样检查内容保真度。
文档转换
用法
python3 scripts/convert_document.py <input_file> <output_file> [--compress]
支持的转换组合
| 从 → 到 | 说明 |
|---|---|
| PDF → DOCX | 文本抽取 + 基础排版 |
| PDF → TXT | 纯文本抽取 |
| DOCX → PDF | 完整排版保留 |
| DOCX → TXT | 纯文本 |
| DOCX → Markdown | 标题、列表、表格转换 |
| TXT → DOCX | 纯文本到 Word |
| TXT → PDF | 简单文本到 PDF |
| Markdown → DOCX | 渲染后的 Markdown 到 Word |
| Markdown → PDF | 渲染后的 Markdown 到 PDF |
| HTML → PDF | 网页到 PDF |
| HTML → TXT | 去除 HTML 标签 |
注意事项
- PDF 转 DOCX：复杂排版可能出现格式漂移，务必校验输出。
- 扫描版 PDF（图片型）需要 OCR，本技能不含 OCR。
- 加密 PDF 不支持。
图片转换
用法
python3 scripts/convert_image.py <input_file> <output_file> [--quality 85] [--resize 1920x1080] [--crop x,y,w,h] [--grayscale] [--rotate 90]
参数
--quality：JPG/WebP 质量 1-100（默认 85）。--resize：缩放到 宽x高（如 1920x1080）。--crop：裁剪区域 x,y,宽,高。--grayscale：转灰度。--rotate：旋转角度（90/180/270）。
注意事项
- 透明通道：PNG/WebP 支持 alpha，JPG 不支持——透明区域会变白。
- GIF 动图：默认只转首帧；GIF 转动态输出需使用
--all-frames。 - ICO：图标格式，推荐 16x16、32x32、48x48。
视频转换
用法
python3 scripts/convert_video.py <input_file> <output_file> [--crf 23] [--resolution 1920x1080] [--fps 30] [--audio-bitrate 128k] [--preset medium]
参数
--crf：质量因子（18 高质量，23 默认，28 更小体积）。--resolution：输出分辨率 宽x高。--fps：帧率。--audio-bitrate：音频码率（如 128k、192k）。--preset：ffmpeg 预设（ultrafast / medium / slow）。
注意事项
- 需要系统安装 ffmpeg。
- MP4（H.264 + AAC）是兼容性最好的输出格式。
- MKV 支持多音轨与字幕。
- 转换耗时随视频时长线性增长，长视频可能需数分钟。
音频转换
用法
python3 scripts/convert_audio.py <input_file> <output_file> [--bitrate 192k] [--sample-rate 44100] [--channels 2]
参数
--bitrate：输出码率（如 128k、192k、320k）。--sample-rate：采样率（如 44100、48000）。--channels：声道数（1 单声道、2 立体声）。
注意事项
- 需要系统安装 ffmpeg。
- WAV 为无损格式，输出体积大；MP3/AAC 适合流式与压缩需求。
- FLAC 为无损压缩格式。
批量转换
将多个文件一次转换，遍历目录中的文件并逐个调用脚本：
# 示例：将文件夹内所有 PNG 转为 WebP
for f in *.png; do
python3 scripts/convert_image.py "$f" "${f%.png}.webp" --quality 80
done
# 示例：将文件夹内所有 MP4 转为 WebM
for f in *.mp4; do
python3 scripts/convert_video.py "$f" "${f%.mp4}.webm" --crf 28
done
也可传入目录：脚本会扫描目录下同类型文件并批量转换到输出目录。
错误处理
| 错误 | 原因 | 处理 |
|---|---|---|
| File not found | 路径错误 | 核对输入文件路径是否存在 |
| Unsupported format | 扩展名不在支持列表 | 对照支持格式表 |
| Missing dependency | 依赖库未安装 | 安装 requirements.txt 中的依赖 |
| ffmpeg not found | 音视频转换 | 安装 ffmpeg 并加入 PATH |
| Permission denied | 输出目录无权限 | 检查写入权限 |
依赖安装
使用前安装（由脚本 --check 自动提示缺失项）：
pip install -r requirements.txt
# 音视频转换还需要系统 ffmpeg：
# Ubuntu/Debian: sudo apt install ffmpeg
# macOS: brew install ffmpeg
# Windows: choco install ffmpeg 或官网下载加入 PATH
目录结构
.
├── SKILL.md # 本技能定义
├── requirements.txt # Python 依赖清单
├── scripts/
│ ├── convert_document.py # 文档转换
│ ├── convert_image.py # 图片转换
│ ├── convert_video.py # 视频转换
│ └── convert_audio.py # 音频转换
└── README.md # 使用说明
