@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 CHANGED
@@ -10,6 +10,7 @@
10
10
  [![npm Version](https://img.shields.io/npm/v/@gehdoc/svg-to-video?logo=npm&logoColor=white&label=npm&color=CB3837)](https://www.npmjs.com/package/@gehdoc/svg-to-video)
11
11
  [![Docker Image](https://img.shields.io/docker/v/gehdoc/svg-to-video?label=docker&logo=docker&logoColor=white&sort=semver&color=2496ed)](https://hub.docker.com/r/gehdoc/svg-to-video)
12
12
  [![MCP Registry](https://img.shields.io/badge/MCP-io.github.GehDoc%2Fsvg--to--video-purple?logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/v0/servers/io.github.GehDoc%2Fsvg-to-video/versions/latest)
13
+ [![HuggingFace Space](https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Demo%20Space-yellow?style=flat)](https://huggingface.co/spaces/GehDoc/svg-to-video-mcp)
13
14
  [![llms.txt](https://img.shields.io/badge/llms.txt-available-blue)](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`) to let AI assistants render their generated SVG animations into MP4/GIF automatically.
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: 720p, 1080p, or original', 'original')
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
- if (resolutionPreset === '1080p') {
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', or 'original'.`);
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
- type: 'string',
59
- description: 'Absolute or relative path to the input .svg file (forbidden in hosted sandboxed mode).',
60
- },
61
- svgContent: {
62
- type: 'string',
63
- description: 'Raw SVG string content to render (required if svgFilePath is not provided).',
64
- },
65
- outDir: {
66
- type: 'string',
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
- enum: ['original', '1080p', '720p'],
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
- type: 'string',
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.scale !== 1 && options.resolution !== 'original') {
7
- throw new Error('--scale can only be used with --resolution original.');
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.28.3",
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": "^29.1.1",
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": "^28.0.3",
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`, and custom scaling factors (1x-4x).
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 gif --transparent --json
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**: