Skip to main content
Glama
GehDoc

svg-to-video

by GehDoc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

SVG to Video

CI Last Commit GitHub Release npm Version Docker Image MCP Registry HuggingFace Space llms.txt

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 indexed on the official MCP Registry (mcp.json) and hosted live on HuggingFace Spaces.

  • 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.

Related MCP server: ClipACanvas

🚀 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, or test the engine instantly with 1-click built-in samples.

  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 -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 --width 1080 --height 1920

# 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

See docs/CLI.md for full usage, arguments, and options. For local building and source execution, see CONTRIBUTING.md.

🤖 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", "-p", "@gehdoc/svg-to-video", "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

📦 Quick Installation & Execution

# 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

🛠 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.

❓ FAQ

Common questions about privacy, how frame scrubbing works, CI/CD automation, and transparency support are answered in docs/FAQ.md.

🤝 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:

Donate

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

📜 License

This project is licensed under the MIT License.

Available Tools

2 tools
inspect_svg_animationA

Analyze an SVG file or raw SVG content to detect CSS keyframe animations, estimate duration, and extract viewBox dimensions. Call this tool first before rendering to discover animation parameters and calculate optimal resolution.

ParametersJSON Schema
NameRequiredDescriptionDefault
svgContentNoRaw SVG content to inspect.
svgFilePathNoPath to the .svg file to inspect (forbidden in hosted sandboxed mode).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses the analytical outputs (animation detection, duration, viewBox) and implies a non-mutating read, but says nothing about error behavior on malformed SVG, side effects, or how the two input modes differ beyond the schema's own note. Adequate but incomplete for a zero-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no waste, and the primary purpose is front-loaded before the usage directive. Every clause earns its place by naming a distinct extracted artifact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey return content, and it does by listing animations, duration, and viewBox dimensions. Minor gap: it does not describe the shape of the result or what happens when no animation is detected, but it is sufficient to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (svgContent, svgFilePath) are already fully documented in the schema, including the hosted-sandbox restriction. The description adds no syntax, format, or precedence detail beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Analyze) plus the resource (SVG file or raw SVG content) and enumerates the concrete outputs: CSS keyframe animations, duration estimate, viewBox dimensions. This clearly distinguishes it from the sibling render_svg_to_video, which produces video rather than analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Call this tool first before rendering" gives explicit ordering guidance relative to the render step, which effectively routes the agent away from render_svg_to_video until inspection is done. It stops short of naming the sibling or stating exclusions (e.g. what to do if no animation is found).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

render_svg_to_videoA

Render an animated SVG (from raw SVG code or file path) into a high-quality video (MP4, WebM, MKV, MOV) or animated image (aPNG, GIF) with in-band Base64 media delivery. Use this tool when you need to convert animated SVG graphics into video or image files. First use inspect_svg_animation to detect duration and dimensions if unknown. Specify svgContent for raw XML input or svgFilePath for local files. Pass transparent: true for WebM/GIF/aPNG transparency.

ParametersJSON Schema
NameRequiredDescriptionDefault
fpsNoFrames per second (e.g. 24, 30, 60). Default: 60.
holdNoSeconds to freeze the last frame at the end of the video.
scaleNoScale factor (1-4) when using original resolution. Default: 1.
formatNoOutput media format. Defaults to webm if transparent is true, otherwise mp4.
outDirNoOutput directory to preserve generated file locally. Omit to deliver purely in-band via ephemeral storage (forbidden in hosted sandboxed mode).
bgColorNoBackground color hex code (e.g. #ffffff). Cannot be used with transparent.
durationNoDesired animation duration in seconds. If omitted, duration is auto-detected.
resolutionNoResolution preset. Default: original.original
svgContentNoRaw SVG string content to render (required if svgFilePath is not provided).
svgFilePathNoAbsolute or relative path to the input .svg file (forbidden in hosted sandboxed mode).
transparentNoRender with full alpha-channel transparency (supported for webm, gif, apng, mov).

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does meaningful work: it discloses in-band Base64 media delivery, the ephemeral-vs-local outDir tradeoff, format-dependent transparency support, and the auto-detection of duration. It omits cost/latency characteristics and failure behavior, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences with the core verb and output formats front-loaded, then usage, prerequisites, and input-selection rules. No filler, though the final sentence is largely redundant with schema text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter tool with no annotations and no output schema, the description covers the essential decision points: input source, output format, transparency, and delivery mode. Defaults and per-format constraints live in the schema, but nothing about error handling or resource limits is addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description only restates the svgContent-vs-svgFilePath selection and the transparent flag guidance, both of which the schema already documents; it adds no new syntax, ranges, or interaction rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Render an animated SVG ... into a high-quality video ... or animated image') and enumerates concrete output formats (MP4, WebM, MKV, MOV, aPNG, GIF). It also distinguishes itself from its only sibling by noting inspect_svg_animation is for detection, not conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('Use this tool when you need to convert animated SVG graphics into video or image files') and a prerequisite/alternative step ('First use inspect_svg_animation to detect duration and dimensions if unknown'). No explicit when-not guidance beyond the sibling pointer, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.28.0
    • Changedinspect_svg_animation1 field changed
      • changedInput schema / properties / svgFilePath / description
        Previous value: -"Path to the .svg file to inspect."New value: +"Path to the .svg file to inspect (forbidden in hosted sandboxed mode)."
    • Changedrender_svg_to_video3 fields changed
      • changedInput schema / properties / outDir / description
        Previous value: -"Output directory for the generated media file. Defaults to current working directory."New value: +"Output directory to preserve generated file locally. Omit to deliver purely in-band via ephemeral storage (forbidden in hosted sandboxed mode)."
      • changedInput schema / properties / svgContent / description
        Previous value: -"Raw SVG string content to render (if svgFilePath is not provided)."New value: +"Raw SVG string content to render (required if svgFilePath is not provided)."
      • changedInput schema / properties / svgFilePath / description
        Previous value: -"Absolute or relative path to the input .svg file."New value: +"Absolute or relative path to the input .svg file (forbidden in hosted sandboxed mode)."
  2. 2 tool updatesv0.27.8
    • First observedinspect_svg_animation
    • First observedrender_svg_to_video
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one inspects SVG animation metadata, the other renders SVG to video/image. Their scopes do not overlap, and the render tool explicitly directs users to call inspect first when parameters are unknown.

Naming Consistency5/5

Both tool names follow a consistent snake_case verb_noun pattern: render_svg_to_video and inspect_svg_animation. The naming is predictable and readable.

Tool Count4/5

For a narrowly focused SVG-to-video conversion server, two tools cover the core inspect-then-render workflow without redundancy. The count is slightly below the typically ideal 3-15 range but is reasonable for this simple domain.

Completeness5/5

The surface covers the full conversion lifecycle: inspecting an SVG for animation duration/dimensions and rendering it to multiple video or animated image formats. No obvious gaps or dead ends are apparent for the stated purpose.

Maintenance

ActivityActive
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers