# SVG to PNG 渲染工具

## 功能

将 SVG 矢量图文件渲染为 PNG 位图，解决本机缺少 SVG 渲染工具、FFmpeg 无 SVG 解码器的问题。

## 依赖

- Python 3.8+
- CairoSVG 2.9.0+
- Pillow 12.0.0+
- 系统 cairo 库（macOS: `brew install cairo`）

## 安装

```bash
# 1. 安装系统 cairo 库（macOS）
brew install cairo

# 2. 安装 Python 依赖
pip install cairosvg Pillow
```

## 用法

### 单文件转换

```bash
# 基本用法（自动读取 SVG 原始尺寸）
python tools/svg-to-png.py input.svg output.png

# 指定输出宽度（高度等比缩放）
python tools/svg-to-png.py input.svg output.png --width 1920

# 指定输出高度（宽度等比缩放）
python tools/svg-to-png.py input.svg output.png --height 1080

# 指定缩放因子（基于 SVG 原始尺寸放大/缩小）
python tools/svg-to-png.py input.svg output.png --scale 2

# 透明背景
python tools/svg-to-png.py input.svg output.png --background none
```

### 批量转换

```bash
# 转换目录下所有 SVG 文件
python tools/svg-to-png.py ./svg-dir/ ./png-dir/ --batch

# 批量转换并指定缩放因子
python tools/svg-to-png.py ./svg-dir/ ./png-dir/ --batch --scale 2
```

### 作为模块导入

```python
from tools.svg_to_png import convert_svg_to_png

# 转换单个文件
convert_svg_to_png("input.svg", "output.png", scale=2)

# 指定宽度（高度等比）
convert_svg_to_png("input.svg", "output.png", width=1920)
```

## 路径

```
video-ai-system/tools/svg-to-png.py
```

## 视频处理流水线集成

在视频处理流水线中，使用该工具将 SVG 字幕/特效渲染为 PNG 序列，再通过 FFmpeg 合成到视频中：

```bash
# 1. 渲染 SVG 字幕为 PNG 序列
python tools/svg-to-png.py ./subtitles/ ./subtitles-png/ --batch --width 1920

# 2. 用 FFmpeg 将 PNG 序列合成到视频
ffmpeg -i input.mp4 -i ./subtitles-png/frame-%04d.png -filter_complex overlay output.mp4
```

## 故障排查

### OSError: no library called "cairo-2" was found

**原因**：Python 找不到系统 cairo 库。

**解决**：

```bash
# macOS（Apple Silicon）
export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"

# macOS（Intel）
export DYLD_LIBRARY_PATH="/usr/local/lib:$DYLD_LIBRARY_PATH"

# 然后重新运行
python tools/svg-to-png.py input.svg output.png
```

### 建议在 `~/.zshrc` 中添加：

```bash
# video-ai-system SVG 渲染工具依赖
export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"
```

## 更新记录

- 2026-06-23：初始版本，支持单文件/批量 SVG→PNG 转换