SVG to Video

A high-fidelity tool to transform your CSS-animated SVGs into high-quality videos (MP4, WebM, MKV, MOV) or lightweight animated formats (aPNG, GIF) with perfect alpha-channel transparency directly in your browser or via CLI/MCP server.

🌟 Why SVG to Video?

• Transparent Backgrounds: Export your animations with a full alpha channel using WebM or aPNG, and optimized indexed transparency with GIF89a. Perfect for overlays in video editing tools or web use.
• Privacy-First: The Web Studio runs entirely in your browser—your SVG files never leave your computer.
• Frame-Accurate: Our engine scrubs the Web Animations API, ensuring every frame is captured exactly as rendered.
• AI Agent Native: Native Model Context Protocol (MCP) server and Agent Skill (SKILL.md) support to let AI assistants render their generated SVG animations into MP4/GIF automatically.
• Universal Animated Formats: Beyond video, generate lightweight Animated PNGs (aPNG) and GIFs perfect for documentation, Slack, or GitHub, with full control over background transparency.
• Copy to Clipboard: Instant export to Base64 Data URL—copy your video and embed it directly into your HTML, CSS, or JS code without manual downloads. Perfect for rapid prototyping and developers.
• Metadata Injection: Support for custom titles and comments across video (MP4, WebM, MKV, MOV) and animated image (aPNG, GIF) formats.
• Versatile: Whether you need an accessible Web Studio for quick conversions or a powerful CLI tool for batch automation and CI/CD pipelines, this project has you covered.

🚀 Getting Started

Choose the entry point that matches your needs:

• Web Studio: The easiest way to convert SVGs to video, high-fidelity aPNG, or optimized GIF in your browser without any installation.
• CLI / Docker Tool: For batch processing, server-side automation, and CI/CD integration.
• AI Agent & MCP Server: For Claude Desktop, Cursor, Antigravity, and autonomous LLM workflows.

🌐 Web Studio

🚀 Try the Web Studio

Our Web Studio is a serverless, client-side rendering tool. It runs entirely in your browser using WebCodecs—your SVG files never leave your computer, ensuring absolute privacy. The interface is optimized for high-productivity on screens starting from 720p resolution.

Automated Demo: The demo video at the top of this README is automatically generated and updated by our CI/CD pipeline using Playwright and Driver.js, ensuring it always reflects the latest UI changes.

Privacy Note: We use Umami Analytics to collect anonymous usage data across our Web Studio, CLI, and MCP server interfaces (e.g., number of conversions and format usage) to help us improve the tool. This tracking is cookie-less, respects standard "Do Not Track" settings (set the DO_NOT_TRACK=1 environment variable to opt out), and never collects personal information or SVG contents. See docs/ANALYTICS.md for details.

Explore our Visual Gallery (Storybook) to see how the engine handles complex CSS and fonts.

Quick Start

1. Open the Web Studio.
2. Drag and drop your .svg file.
3. Adjust resolution, duration, and FPS.
4. Select your format, toggle Transparent Background if needed, and ensure High-Fidelity Capture is enabled for best results.
5. Click Export.

🚀 CLI / Docker Tool

For automated or batch processing, use the CLI tool. It is built to run in a headless environment, making it perfect for CI/CD pipelines or server-side automation.

Quick Start

Ensure Node.js and FFmpeg are installed.

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

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

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

# Docker (zero local dependencies; add :Z to -v for SELinux / Fedora)
docker run --rm -v $(pwd):/data:Z gehdoc/svg-to-video /data/input.svg 60 /data/out-dir -d 5 --format gif

See docs/CLI.md for full usage, arguments, and options.

🤖 AI Agent & MCP Integration

Connect svg-to-video to AI Assistants (Claude Desktop, Cursor, Antigravity, AutoGPT) via Model Context Protocol:

1. Add to mcpServers config:

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

2. Prompt your AI Assistant:

   "Convert examples/example.svg into a 60fps transparent WebM video."

See docs/MCP.md for full setup instructions, tool schemas, Docker execution, and agent prompting guides.

🔗 Official Package Distributions

• 📦 npm Package: @gehdoc/svg-to-video
• 🐳 Docker Hub Image: gehdoc/svg-to-video
• 🌐 Web Studio: gehdoc.github.io/svg-to-video/

📦 Quick Installation & Execution

# Run on-demand via npx (no global installation required)
npx @gehdoc/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

🛠 Technical Details

For a deep dive into the rendering engine, algorithms, and infrastructure, see docs/ARCHITECTURE.md.

The tool works by isolating the SVG, scrubbing the Web Animations API, and capturing frames via WebCodecs or FFmpeg.

🤝 Contributing

Contributions are welcome! This project follows a Spec-Driven Development (SDD) workflow to ensure clear requirements and high quality. Please open an issue or pull request.

Check out our Active Roadmap to see what we're working on next.

For instructions on contributing, build commands, security standards, and the technical roadmap, please see CONTRIBUTING.md.

💖 Support the Project

If you find this tool helpful, please consider supporting its development:

Your support helps cover maintenance and further development of the tool. Thank you!

📜 License

This project is licensed under the MIT License.