@gehdoc/svg-to-video 0.28.3 → 0.29.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -2
- package/dist/src/index.js +28 -5
- package/dist/src/mcp.js +44 -22
- package/dist/src/utils/validateOptions.js +38 -2
- package/package.json +3 -3
- package/skills/svg-to-video/SKILL.md +3 -2
package/README.md
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
[](https://www.npmjs.com/package/@gehdoc/svg-to-video)
|
|
11
11
|
[](https://hub.docker.com/r/gehdoc/svg-to-video)
|
|
12
12
|
[](https://registry.modelcontextprotocol.io/v0/servers/io.github.GehDoc%2Fsvg-to-video/versions/latest)
|
|
13
|
+
[](https://huggingface.co/spaces/GehDoc/svg-to-video-mcp)
|
|
13
14
|
[](https://gehdoc.github.io/svg-to-video/llms.txt)
|
|
14
15
|
|
|
15
16
|
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.
|
|
@@ -26,7 +27,7 @@ A high-fidelity tool to transform your CSS-animated SVGs into high-quality video
|
|
|
26
27
|
- **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.
|
|
27
28
|
- **Privacy-First**: The Web Studio runs entirely in your browser—your SVG files never leave your computer.
|
|
28
29
|
- **Frame-Accurate**: Our engine scrubs the **Web Animations API**, ensuring every frame is captured exactly as rendered.
|
|
29
|
-
- **AI Agent Native**: Native **Model Context Protocol (MCP)** server and **Agent Skill (`SKILL.md`)** support indexed on the official [MCP Registry](https://registry.modelcontextprotocol.io/) (`mcp.json`)
|
|
30
|
+
- **AI Agent Native**: Native **Model Context Protocol (MCP)** server and **Agent Skill (`SKILL.md`)** support indexed on the official [MCP Registry](https://registry.modelcontextprotocol.io/) (`mcp.json`) and hosted live on [HuggingFace Spaces](https://huggingface.co/spaces/GehDoc/svg-to-video-mcp).
|
|
30
31
|
- **Universal Animated Formats**: Beyond video, generate lightweight **Animated PNGs (aPNG)** and **GIFs** perfect for documentation, Slack, or GitHub, with full control over background transparency.
|
|
31
32
|
- **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.
|
|
32
33
|
- **Metadata Injection**: Support for custom titles and comments across video (MP4, WebM, MKV, MOV) and animated image (aPNG, GIF) formats.
|
|
@@ -81,6 +82,9 @@ npx @gehdoc/svg-to-video input.svg 60 ./out-dir
|
|
|
81
82
|
# Node.js (explicit duration & GIF output)
|
|
82
83
|
npx @gehdoc/svg-to-video input.svg 60 ./out-dir -d 5 --format gif --transparent
|
|
83
84
|
|
|
85
|
+
# Node.js (custom resolution dimensions e.g. vertical 1080x1920)
|
|
86
|
+
npx @gehdoc/svg-to-video input.svg 60 ./out-dir --width 1080 --height 1920
|
|
87
|
+
|
|
84
88
|
# Node.js (animated PNG output)
|
|
85
89
|
npx @gehdoc/svg-to-video input.svg 60 ./out-dir -d 5 --format apng
|
|
86
90
|
|
|
@@ -102,7 +106,7 @@ Connect `svg-to-video` to AI Assistants (Claude Desktop, Cursor, Antigravity, Au
|
|
|
102
106
|
"mcpServers": {
|
|
103
107
|
"svg-to-video": {
|
|
104
108
|
"command": "npx",
|
|
105
|
-
"args": ["-y", "@gehdoc/svg-to-video", "mcp"]
|
|
109
|
+
"args": ["-y", "-p", "@gehdoc/svg-to-video", "svg-to-video-mcp"]
|
|
106
110
|
}
|
|
107
111
|
}
|
|
108
112
|
}
|
|
@@ -120,6 +124,7 @@ See **[docs/MCP.md](./docs/MCP.md)** for full setup instructions, tool schemas,
|
|
|
120
124
|
- 🐳 **Docker Hub Image**: [`gehdoc/svg-to-video`](https://hub.docker.com/r/gehdoc/svg-to-video)
|
|
121
125
|
- 🌐 **Web Studio**: [`gehdoc.github.io/svg-to-video/`](https://gehdoc.github.io/svg-to-video/)
|
|
122
126
|
- 🤖 **MCP Registry**: [`io.github.GehDoc/svg-to-video`](https://registry.modelcontextprotocol.io/v0/servers/io.github.GehDoc%2Fsvg-to-video/versions/latest)
|
|
127
|
+
- 🤗 **HuggingFace Space**: [`GehDoc/svg-to-video-mcp`](https://huggingface.co/spaces/GehDoc/svg-to-video-mcp)
|
|
123
128
|
|
|
124
129
|
---
|
|
125
130
|
|
package/dist/src/index.js
CHANGED
|
@@ -39,8 +39,10 @@ Resources:
|
|
|
39
39
|
}, 0)
|
|
40
40
|
.option('--keep-frames', 'keep temporary frames after creating video', false)
|
|
41
41
|
.option('-f, --force', 'overwrite existing output files without asking', false)
|
|
42
|
-
.option('--resolution <preset>', 'resolution preset
|
|
42
|
+
.option('--resolution <preset>', 'resolution preset (720p, 1080p, original) or custom dimensions (e.g. 1080x1080)', 'original')
|
|
43
43
|
.option('--scale <number>', 'scale factor for original resolution (1-4)', (v) => parseFloat(v), 1)
|
|
44
|
+
.option('-w, --width <pixels>', 'custom width in pixels', (v) => parseInt(v, 10))
|
|
45
|
+
.option('-H, --height <pixels>', 'custom height in pixels', (v) => parseInt(v, 10))
|
|
44
46
|
.option('--transparent', 'render with a transparent background', false)
|
|
45
47
|
.option('--bg-color <hex>', 'background color for the video (e.g., #FFFFFF)', '#ffffff')
|
|
46
48
|
.option('--metadata <items...>', 'metadata tags (e.g., --metadata title="My Video" author="Me")')
|
|
@@ -149,7 +151,7 @@ async function run(svgPath, fps, outDir, options) {
|
|
|
149
151
|
process.once('SIGTERM', sigtermListener);
|
|
150
152
|
try {
|
|
151
153
|
fs.mkdirSync(outDir, { recursive: true });
|
|
152
|
-
await createFrames(svg, parsedDim, fps, totalFrames, padWidth, outDir, puppeteerArgs, options.resolution, options.scale, options.transparent, options.bgColor, logger);
|
|
154
|
+
await createFrames(svg, parsedDim, fps, totalFrames, padWidth, outDir, puppeteerArgs, options.resolution, options.scale, options.width, options.height, options.transparent, options.bgColor, logger);
|
|
153
155
|
convertToOutput(outputFileName, format, fps, padWidth, options.hold, outDir, options.transparent, options.metadata, logger);
|
|
154
156
|
if (!options.keepFrames) {
|
|
155
157
|
cleanupFrames(totalFrames, padWidth, outDir, logger);
|
|
@@ -188,11 +190,31 @@ async function run(svgPath, fps, outDir, options) {
|
|
|
188
190
|
/**
|
|
189
191
|
* create frame images by rendering the SVG in a headless browser and advancing the animation to the correct timestamp for each frame
|
|
190
192
|
*/
|
|
191
|
-
async function createFrames(svg, parsedDim, fps, totalFrames, padWidth, outDir, puppeteerArgs, resolutionPreset, scaleFactor, transparent, bgColor, logger) {
|
|
193
|
+
async function createFrames(svg, parsedDim, fps, totalFrames, padWidth, outDir, puppeteerArgs, resolutionPreset, scaleFactor, customWidth, customHeight, transparent, bgColor, logger) {
|
|
192
194
|
logger.info('📸 Rendering frames with Puppeteer...');
|
|
193
195
|
let width = 0;
|
|
194
196
|
let height = 0;
|
|
195
|
-
|
|
197
|
+
const svgAspect = parsedDim.height > 0 ? parsedDim.width / parsedDim.height : 16 / 9;
|
|
198
|
+
if (customWidth !== undefined || customHeight !== undefined) {
|
|
199
|
+
if (customWidth !== undefined && customHeight !== undefined) {
|
|
200
|
+
width = customWidth;
|
|
201
|
+
height = customHeight;
|
|
202
|
+
}
|
|
203
|
+
else if (customWidth !== undefined) {
|
|
204
|
+
width = customWidth;
|
|
205
|
+
height = Math.round(customWidth / svgAspect);
|
|
206
|
+
}
|
|
207
|
+
else if (customHeight !== undefined) {
|
|
208
|
+
height = customHeight;
|
|
209
|
+
width = Math.round(customHeight * svgAspect);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
else if (/^\d+x\d+$/i.test(resolutionPreset)) {
|
|
213
|
+
const [wStr, hStr] = resolutionPreset.toLowerCase().split('x');
|
|
214
|
+
width = parseInt(wStr, 10);
|
|
215
|
+
height = parseInt(hStr, 10);
|
|
216
|
+
}
|
|
217
|
+
else if (resolutionPreset === '1080p') {
|
|
196
218
|
width = 1920;
|
|
197
219
|
height = 1080;
|
|
198
220
|
}
|
|
@@ -208,8 +230,9 @@ async function createFrames(svg, parsedDim, fps, totalFrames, padWidth, outDir,
|
|
|
208
230
|
height = Math.round(parsedDim.height * scaleFactor);
|
|
209
231
|
}
|
|
210
232
|
else {
|
|
211
|
-
throw new Error(`Invalid resolution preset: ${resolutionPreset}. Expected '1080p', '720p',
|
|
233
|
+
throw new Error(`Invalid resolution preset: ${resolutionPreset}. Expected '1080p', '720p', 'original', or custom dimensions.`);
|
|
212
234
|
}
|
|
235
|
+
logger.info(` Viewport: ${width}x${height}`);
|
|
213
236
|
logger.info('🚀 Preparing Puppeteer browser...');
|
|
214
237
|
const launchOptions = {
|
|
215
238
|
headless: true,
|
package/dist/src/mcp.js
CHANGED
|
@@ -21,6 +21,14 @@ const cliIndexPath = fs.existsSync(cliJsPath) ? cliJsPath : cliTsPath;
|
|
|
21
21
|
const isHosted = process.env.MCP_HOSTED === 'true' ||
|
|
22
22
|
process.env.MCP_HOSTED === '1' ||
|
|
23
23
|
process.argv.includes('--hosted');
|
|
24
|
+
const SVG_FILE_PATH_PARAM = {
|
|
25
|
+
type: 'string',
|
|
26
|
+
description: 'Path to the input .svg file (required if svgContent is not provided).',
|
|
27
|
+
};
|
|
28
|
+
const SVG_CONTENT_PARAM = {
|
|
29
|
+
type: 'string',
|
|
30
|
+
description: 'Raw SVG XML string content.',
|
|
31
|
+
};
|
|
24
32
|
function trackSecurityRejection() {
|
|
25
33
|
trackEvent('file-load', {
|
|
26
34
|
aspectRatio: 'unknown',
|
|
@@ -54,18 +62,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
|
54
62
|
inputSchema: {
|
|
55
63
|
type: 'object',
|
|
56
64
|
properties: {
|
|
57
|
-
svgFilePath:
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
description: 'Output directory to preserve generated file locally. Omit to deliver purely in-band via ephemeral storage (forbidden in hosted sandboxed mode).',
|
|
68
|
-
},
|
|
65
|
+
...(isHosted ? {} : { svgFilePath: SVG_FILE_PATH_PARAM }),
|
|
66
|
+
svgContent: SVG_CONTENT_PARAM,
|
|
67
|
+
...(isHosted
|
|
68
|
+
? {}
|
|
69
|
+
: {
|
|
70
|
+
outDir: {
|
|
71
|
+
type: 'string',
|
|
72
|
+
description: 'Output directory to preserve generated file locally. Omit to deliver purely in-band via ephemeral storage.',
|
|
73
|
+
},
|
|
74
|
+
}),
|
|
69
75
|
fps: {
|
|
70
76
|
type: 'number',
|
|
71
77
|
description: 'Frames per second (e.g. 24, 30, 60). Default: 60.',
|
|
@@ -87,8 +93,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
|
87
93
|
},
|
|
88
94
|
resolution: {
|
|
89
95
|
type: 'string',
|
|
90
|
-
|
|
91
|
-
description: 'Resolution preset. Default: original.',
|
|
96
|
+
description: 'Resolution preset (original, 1080p, 720p) or formatted string (e.g. 1080x1080, 1080x1920). Default: original.',
|
|
92
97
|
default: 'original',
|
|
93
98
|
},
|
|
94
99
|
scale: {
|
|
@@ -96,6 +101,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
|
96
101
|
description: 'Scale factor (1-4) when using original resolution. Default: 1.',
|
|
97
102
|
default: 1,
|
|
98
103
|
},
|
|
104
|
+
width: {
|
|
105
|
+
type: 'number',
|
|
106
|
+
description: 'Custom output video width in pixels.',
|
|
107
|
+
},
|
|
108
|
+
height: {
|
|
109
|
+
type: 'number',
|
|
110
|
+
description: 'Custom output video height in pixels.',
|
|
111
|
+
},
|
|
99
112
|
bgColor: {
|
|
100
113
|
type: 'string',
|
|
101
114
|
description: 'Background color hex code (e.g. #ffffff). Cannot be used with transparent.',
|
|
@@ -106,6 +119,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
|
106
119
|
default: 0,
|
|
107
120
|
},
|
|
108
121
|
},
|
|
122
|
+
...(isHosted
|
|
123
|
+
? { required: ['svgContent'] }
|
|
124
|
+
: {
|
|
125
|
+
anyOf: [
|
|
126
|
+
{ required: ['svgContent'] },
|
|
127
|
+
{ required: ['svgFilePath'] },
|
|
128
|
+
],
|
|
129
|
+
}),
|
|
109
130
|
},
|
|
110
131
|
},
|
|
111
132
|
{
|
|
@@ -114,15 +135,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
|
114
135
|
inputSchema: {
|
|
115
136
|
type: 'object',
|
|
116
137
|
properties: {
|
|
117
|
-
svgFilePath:
|
|
118
|
-
|
|
119
|
-
description: 'Path to the .svg file to inspect (forbidden in hosted sandboxed mode).',
|
|
120
|
-
},
|
|
121
|
-
svgContent: {
|
|
122
|
-
type: 'string',
|
|
123
|
-
description: 'Raw SVG content to inspect.',
|
|
124
|
-
},
|
|
138
|
+
...(isHosted ? {} : { svgFilePath: SVG_FILE_PATH_PARAM }),
|
|
139
|
+
svgContent: SVG_CONTENT_PARAM,
|
|
125
140
|
},
|
|
141
|
+
required: ['svgContent'],
|
|
126
142
|
},
|
|
127
143
|
},
|
|
128
144
|
],
|
|
@@ -268,6 +284,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
|
268
284
|
if (params.scale) {
|
|
269
285
|
cliArgs.push('--scale', String(params.scale));
|
|
270
286
|
}
|
|
287
|
+
if (params.width) {
|
|
288
|
+
cliArgs.push('--width', String(params.width));
|
|
289
|
+
}
|
|
290
|
+
if (params.height) {
|
|
291
|
+
cliArgs.push('--height', String(params.height));
|
|
292
|
+
}
|
|
271
293
|
if (params.bgColor) {
|
|
272
294
|
cliArgs.push('--bg-color', params.bgColor);
|
|
273
295
|
}
|
|
@@ -1,10 +1,46 @@
|
|
|
1
1
|
import { formatRegistry } from '../formats/registry.js';
|
|
2
|
+
const MAX_DIMENSION_PIXELS = 7680; // Maximum supported resolution dimension (8K UHD)
|
|
2
3
|
export function validateOptions(options) {
|
|
3
4
|
if (options.duration !== undefined && options.duration <= 0) {
|
|
4
5
|
throw new Error('Duration must be a positive number.');
|
|
5
6
|
}
|
|
6
|
-
if (options.
|
|
7
|
-
|
|
7
|
+
if (options.width !== undefined &&
|
|
8
|
+
(isNaN(options.width) || options.width <= 0)) {
|
|
9
|
+
throw new Error('Width must be a positive number.');
|
|
10
|
+
}
|
|
11
|
+
if (options.width !== undefined && options.width > MAX_DIMENSION_PIXELS) {
|
|
12
|
+
throw new Error(`Width exceeds maximum supported limit of ${MAX_DIMENSION_PIXELS} pixels.`);
|
|
13
|
+
}
|
|
14
|
+
if (options.height !== undefined &&
|
|
15
|
+
(isNaN(options.height) || options.height <= 0)) {
|
|
16
|
+
throw new Error('Height must be a positive number.');
|
|
17
|
+
}
|
|
18
|
+
if (options.height !== undefined && options.height > MAX_DIMENSION_PIXELS) {
|
|
19
|
+
throw new Error(`Height exceeds maximum supported limit of ${MAX_DIMENSION_PIXELS} pixels.`);
|
|
20
|
+
}
|
|
21
|
+
const isPreset = ['original', '1080p', '720p'].includes(options.resolution);
|
|
22
|
+
const resMatch = /^(\d+)x(\d+)$/i.exec(options.resolution);
|
|
23
|
+
if (!isPreset) {
|
|
24
|
+
if (!resMatch) {
|
|
25
|
+
throw new Error(`Invalid resolution option "${options.resolution}". Expected 'original', '1080p', '720p', or a custom dimension string like '1080x1080'.`);
|
|
26
|
+
}
|
|
27
|
+
const resW = parseInt(resMatch[1], 10);
|
|
28
|
+
const resH = parseInt(resMatch[2], 10);
|
|
29
|
+
if (resW <= 0 || resH <= 0) {
|
|
30
|
+
throw new Error('Custom resolution dimensions must be positive numbers.');
|
|
31
|
+
}
|
|
32
|
+
if (resW > MAX_DIMENSION_PIXELS || resH > MAX_DIMENSION_PIXELS) {
|
|
33
|
+
throw new Error(`Custom resolution dimensions must not exceed ${MAX_DIMENSION_PIXELS} pixels.`);
|
|
34
|
+
}
|
|
35
|
+
if (options.width !== undefined || options.height !== undefined) {
|
|
36
|
+
throw new Error('--width and --height cannot be used when a custom resolution string (e.g. 1080x1080) is provided.');
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
if (options.scale !== 1 &&
|
|
40
|
+
(options.resolution !== 'original' ||
|
|
41
|
+
options.width !== undefined ||
|
|
42
|
+
options.height !== undefined)) {
|
|
43
|
+
throw new Error('--scale can only be used with --resolution original and without custom width or height options.');
|
|
8
44
|
}
|
|
9
45
|
if (options.transparent && options.bgColor !== '#ffffff') {
|
|
10
46
|
throw new Error('--transparent and --bg-color cannot be used together.');
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gehdoc/svg-to-video",
|
|
3
3
|
"mcpName": "io.github.GehDoc/svg-to-video",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.29.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Professional animated SVG to Video (MP4/WebM/MKV/MOV) and Animated Image (aPNG/GIF) converter featuring frame-accurate rendering, CLI automation, Model Context Protocol (MCP) server integration, and a serverless Web Studio.",
|
|
7
7
|
"imports": {
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
57
57
|
"@umami/node": "^0.4.0",
|
|
58
58
|
"commander": "^15.0.0",
|
|
59
|
-
"jsdom": "^
|
|
59
|
+
"jsdom": "^30.1.1",
|
|
60
60
|
"supergateway": "^4.1.0",
|
|
61
61
|
"puppeteer": "^25.8.0",
|
|
62
62
|
"tsx": "^4.23.0"
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
"devDependencies": {
|
|
65
65
|
"@eslint/js": "^9.39.4",
|
|
66
66
|
"@types/ffprobe-static": "^2.0.3",
|
|
67
|
-
"@types/jsdom": "^
|
|
67
|
+
"@types/jsdom": "^30.0.0",
|
|
68
68
|
"@types/node": "^25.4.0",
|
|
69
69
|
"@types/pngjs": "^6.0.5",
|
|
70
70
|
"@vitest/coverage-v8": "4.1.11",
|
|
@@ -17,7 +17,7 @@ This skill enables AI agents to render animated vector graphics (SVGs with CSS a
|
|
|
17
17
|
1. **Format Export**: Converts SVGs into `mp4`, `webm`, `gif`, `apng`, `mkv`, and `mov`.
|
|
18
18
|
2. **Transparent Backgrounds**: Supports full alpha-channel transparency for `webm`, `gif`, `apng`, and `mov`.
|
|
19
19
|
3. **Auto-Duration Detection**: Automatically detects CSS keyframe and animation loop durations if not specified.
|
|
20
|
-
4. **Resolution Presets**: Supports `original`, `1080p`, `720p`,
|
|
20
|
+
4. **Resolution Presets & Custom Dimensions**: Supports `original`, `1080p`, `720p`, custom scaling factors (1x-4x), explicit `--width` and `--height` parameters (e.g. 1080x1920), or formatted resolution strings (e.g., `1080x1080`).
|
|
21
21
|
|
|
22
22
|
## Usage Guidelines for AI Agents
|
|
23
23
|
|
|
@@ -26,11 +26,12 @@ When asked to generate a video or GIF from an SVG animation:
|
|
|
26
26
|
1. **Option A: Via MCP Tools (Recommended)**:
|
|
27
27
|
- Call `render_svg_to_video` directly passing either `svgContent` (raw XML string) or `svgFilePath`.
|
|
28
28
|
- Set `transparent: true` and `format: "webm"` or `format: "gif"` if a transparent overlay is requested.
|
|
29
|
+
- Set `width` and `height` parameters or custom `resolution: "1080x1920"` for specific video aspect ratios (e.g. square 1080x1080, vertical 1080x1920).
|
|
29
30
|
|
|
30
31
|
2. **Option B: Via CLI Command**:
|
|
31
32
|
|
|
32
33
|
```bash
|
|
33
|
-
npx @gehdoc/svg-to-video input.svg 60 ./out-dir -d 5 --format
|
|
34
|
+
npx @gehdoc/svg-to-video input.svg 60 ./out-dir -d 5 --width 1080 --height 1920 --format webm --transparent --json
|
|
34
35
|
```
|
|
35
36
|
|
|
36
37
|
3. **Option C: Via Docker**:
|