SVG to Video

SVG 转视频

一款高保真工具，可将 CSS 和 SMIL 动画 SVG 转换为高质量视频（MP4、WebM、MKV、MOV）或轻量级动画格式（aPNG、GIF），支持完美的 Alpha 通道透明效果，可直接在浏览器中或通过 CLI/MCP 服务使用。

---

🌟 为什么选择 SVG to Video？

• 透明背景：导出动画时，可使用 WebM 或 aPNG 保留完整 Alpha 通道，也可使用 GIF89a 实现经过优化的索引透明效果。非常适合用于视频编辑工具中的叠加内容或网页。
• 隐私优先：Web Studio 完全在浏览器中运行，SVG 文件不会离开你的计算机。
• 帧级精准：我们的引擎会逐帧处理 Web Animations API 和原生 SVG SMIL，确保准确捕获每一帧的渲染效果。
• 原生支持 AI Agent：原生支持 Model Context Protocol (MCP) 服务和 Agent Skill（SKILL.md），已通过官方 MCP Registry（mcp.json）索引，并在 HuggingFace Spaces 上实时托管。
• 通用动画格式：除视频外，还可生成轻量级 动画 PNG（aPNG） 和 GIF，非常适合用于文档、Slack 或 GitHub，并可全面控制背景透明度。
• 复制到剪贴板：即时导出为 Base64 Data URL，无需手动下载，即可复制视频并直接嵌入 HTML、CSS 或 JS 代码。非常适合快速原型开发和开发者使用。
• 元数据注入：支持为视频（MP4、WebM、MKV、MOV）和动画图像（aPNG、GIF）格式添加自定义标题和备注。
• 用途广泛：无论你需要用于快速转换的便捷 Web Studio，还是用于批量自动化和 CI/CD 流水线的强大 CLI 工具，本项目都能满足你的需求。

---

🚀 快速开始

选择符合您需求的入口：

• Web Studio：在浏览器中将 SVG 转换为视频、高保真 aPNG 或优化 GIF，无需安装，简单便捷。
• CLI / Docker 工具：用于批量处理、服务器端自动化和 CI/CD 集成。
• AI Agent 与 MCP 服务：适用于 Claude Desktop、Cursor、Antigravity 和自主大模型工作流。

---

🌐 Web Studio

🚀 试用 Web Studio

我们的 Web Studio 是一款无服务器的客户端渲染工具。它完全在您的浏览器中通过 WebCodecs 运行——您的 SVG 文件不会离开您的电脑，从而确保绝对隐私。其界面针对 720p 分辨率及以上的屏幕进行了优化，可提升工作效率。

自动生成演示：本 README 顶部的演示视频由我们的 CI/CD 管道使用 Playwright 和 Driver.js 自动生成并更新，确保其始终反映最新的 UI 变更。

隐私说明：我们使用 Umami Analytics 收集 Web Studio、CLI 和 MCP 服务界面的匿名使用数据（例如转换次数和格式使用情况），以帮助我们改进工具。此跟踪不使用 Cookie，遵循标准的“请勿跟踪”设置（设置 DO_NOT_TRACK=1 环境变量即可选择退出），且绝不会收集个人信息或 SVG 内容。详情请参阅 docs/ANALYTICS.md。

访问我们的 可视化图库（Storybook），了解引擎如何处理复杂 CSS、SMIL 和字体。

快速开始

1. 打开 Web Studio。
2. 拖放您的 .svg 文件，或通过内置示例一键立即测试引擎。
3. 调整分辨率、时长和 FPS。
4. 选择格式；如有需要，启用 透明背景，并确保启用 高保真捕获以获得最佳效果。
5. 点击 导出。

---

🚀 CLI / Docker 工具

如需自动化或批量处理，请使用 CLI 工具。它专为无头环境运行而构建，非常适合 CI/CD 管道或服务器端自动化。

快速开始

确保已安装 Node.js 和 FFmpeg。

# Node.js (auto-detected duration)
npx -y -p @gehdoc/svg-to-video svg-to-video input.svg 60 ./out-dir

# Node.js (explicit duration & GIF output)
npx -y -p @gehdoc/svg-to-video svg-to-video input.svg 60 ./out-dir -d 5 --format gif --transparent

# Node.js (custom resolution dimensions e.g. vertical 1080x1920)
npx -y -p @gehdoc/svg-to-video svg-to-video input.svg 60 ./out-dir --resolution 1080x1920

# Node.js (animated PNG output)
npx -y -p @gehdoc/svg-to-video svg-to-video input.svg 60 ./out-dir -d 5 --format apng

# Docker (zero local dependencies; requires --shm-size=2gb for Chromium rendering; add :Z to -v for SELinux / Fedora)
docker run --rm --shm-size=2gb -e PUPPETEER_ARGS="--no-sandbox" -v $(pwd):/data:Z gehdoc/svg-to-video /data/input.svg 60 /data/out-dir -d 5 --format gif

完整用法、参数和选项请参阅 docs/CLI.md。有关本地构建和运行源代码的信息，请参阅 CONTRIBUTING.md。

---

🤖 AI Agent 与 MCP 集成

通过模型上下文协议，将 svg-to-video 连接到 AI 助手（Claude Desktop、Cursor、Antigravity、AutoGPT）：

1. 添加到 mcpServers 配置中：

   {
     "mcpServers": {
       "svg-to-video": {
         "command": "npx",
         "args": ["-y", "-p", "@gehdoc/svg-to-video", "svg-to-video-mcp"]
       }
     }
   }
   

2. 向 AI 助手发送提示词：

   “将 examples/example.svg 转换为 60fps 的透明 WebM 视频。”

完整设置说明、工具架构、Docker 执行方式和 Agent 提示词指南，请参阅 docs/MCP.md。

---

🔗 官方软件包分发渠道

• 📦 npm 软件包：@gehdoc/svg-to-video
• 🐳 Docker Hub 镜像：gehdoc/svg-to-video
• 🌐 Web Studio：gehdoc.github.io/svg-to-video/
• 🤖 MCP Registry：io.github.GehDoc/svg-to-video
• 🤗 HuggingFace Space：GehDoc/svg-to-video-mcp

---

📦 快速安装与运行

# Run on-demand via npx (no global installation required)
npx -y -p @gehdoc/svg-to-video svg-to-video input.svg 60 ./out-dir

# Install globally via npm
npm install -g @gehdoc/svg-to-video

# Pull official Docker image from Docker Hub
docker pull gehdoc/svg-to-video:latest

---

🛠 技术详情

深入了解渲染引擎、算法和基础设施，请参阅 docs/ARCHITECTURE.md。

该工具通过隔离 SVG、清理 Web Animations API 和原生 SVG SMIL DOM，并使用 WebCodecs 或 FFmpeg 捕获帧来工作。

---

❓ 常见问题

关于隐私、帧拖动的工作原理、CI/CD 自动化和透明度支持的常见问题，请参阅 docs/FAQ.md。

---

🤝 贡献

欢迎贡献！本项目采用 规范驱动开发（SDD） 工作流，以确保需求明确、质量上乘。请提交 issue 或拉取请求。

查看我们的当前路线图，了解接下来的工作计划。

有关贡献指南、构建命令、安全标准和技术路线图，请参阅 CONTRIBUTING.md。

---

💖 支持项目

如果您觉得这个工具有帮助，请考虑支持其开发：

您的支持有助于支付维护费用并推动工具进一步开发。感谢！

---

📜 许可证

本项目采用 MIT 许可证。