Ffmpeg Chinese Subtitle

Windows 上使用 ffmpeg 正确生成中文字幕的解决方案。 用 Pillow 在图片上绘制字幕，ffmpeg 只负责图片转视频，完全避开编码问题。

Security Scan

The code implements the described Pillow + ffmpeg subtitle approach and looks non-malicious, but the package metadata and declared requirements are inconsistent (ffmpeg/ffprobe are used but not declared, package.json lists Python dependency), so review before installing.

Purpose & Capability

The skill's purpose (render Chinese subtitles with Pillow and use ffmpeg to make video) matches the code. However the metadata declares no required binaries while example.py and README call external tools ffmpeg and ffprobe via subprocess; those binaries should be declared as required. Also package.json is a Node manifest but lists the Python dependency 'Pillow', which is inconsistent with a Python-only package.

Instruction Scope

SKILL.md and the code instruct the agent to draw text onto images with Pillow and invoke ffmpeg/ffprobe to produce/inspect media. The instructions and code only touch input images, audio, and standard system font paths; they do not attempt to read unrelated system files or exfiltrate data. Commands are invoked via subprocess with argument lists (not shell strings), which reduces command-injection risk.

Install Mechanism

There is no install spec (instruction-only + included Python files), which is low-risk. Minor oddity: a package.json file exists (Node-style) that lists 'Pillow' in dependencies; there is no requirements.txt or setup.py. This is inconsistent but not directly dangerous—users must still pip-install Pillow and ensure ffmpeg/ffprobe are installed separately.

Credentials

The skill requests no environment variables or credentials. It accesses standard OS font paths to locate Chinese fonts, which is appropriate for its purpose and proportional to functionality.

Persistence & Privilege

The skill does not request persistent/always-on privileges and does not modify other skills or system-wide agent settings. It runs only when invoked.

What to consider before installing

This package appears to implement the stated Pillow + ffmpeg subtitle approach and is not obviously malicious, but take these precautions before installing or running it: - Ensure ffmpeg and ffprobe are installed and on PATH — the code calls them but the skill metadata does not declare them as required. - Install Python dependency manually (pip install Pillow) because package.json is a Node manifest and does not install Python packages for you. - Review the included Python files locally. The code runs subprocess.run to call ffmpeg/ffprobe; because it uses argument lists rather than shell=True the injection risk is lower, but you should still avoid passing untrusted strings as filenames. - Confirm font paths on your system (C:/Windows/Fonts/...) or supply a safe font_path when calling add_subtitle_to_image. - Run in an isolated environment (virtualenv/container) if you are unsure, and inspect repository URL or source origin (the package lists a GitHub URL) before trusting automated installs. If the maintainer updates metadata to declare required binaries (ffmpeg, ffprobe) and provides a proper Python install manifest (requirements.txt or setup.py), the package would be much clearer and easier to trust.

Windows 上使用 ffmpeg 正确生成中文字幕的解决方案。

问题背景

在 Windows 上使用 ffmpeg 的 drawtext、subtitles、ass 滤镜处理中文字幕时，会遇到以下问题：

错误码	原因
返回码 -22 (EINVAL)	字体路径转义问题
字幕不显示	中文编码被截断
乱码	字符集不匹配

解决方案

核心思路：用 Pillow 在图片上绘制字幕，ffmpeg 只负责图片转视频。

方案对比

方案	状态	原因
drawtext=text='中文'	❌ 失败	命令行参数截断
subtitles='中文.srt'	❌ 失败	路径编码问题
ass='中文.ass'	❌ 失败	同上
Pillow 绘制 + ffmpeg	✅ 成功	Python 原生支持 Unicode

快速使用

from ffmpeg_subtitle import add_subtitle_to_image

# 在图片上添加字幕
add_subtitle_to_image(
    image_path="input.png",
    subtitle_text="这是中文字幕",
    output_path="output.png",
    font_size=24,
    y_offset=50
)

参数说明

参数	默认值	说明
image_path	-	输入图片路径
subtitle_text	-	字幕文本
output_path	-	输出图片路径
font_size	24	字体大小
y_offset	50	距底部的偏移量（像素）
font_color	(255,255,255)	字体颜色 RGB
shadow_color	(0,0,0)	阴影颜色 RGB

依赖

Pillow>=10.0.0

字体

默认使用 Windows 系统字体：

• 主字体：C:/Windows/Fonts/msyh.ttc（微软雅黑）
• 备用字体：C:/Windows/Fonts/simhei.ttf（黑体）

触发词

ffmpeg字幕、中文字幕、视频字幕、字幕烧录

文件结构

ffmpeg-chinese-subtitle/
├── SKILL.md           # 技能说明文档
├── README.md          # 详细使用指南
├── ffmpeg_subtitle.py # 核心模块
├── example.py         # 完整示例
└── package.json       # 包信息

License

MIT

Author

systiger