@gehdoc/svg-to-video 0.24.0 → 0.25.1

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
@@ -50,7 +50,7 @@ Our **Web Studio** is a serverless, client-side rendering tool. It runs entirely
50
50
 
51
51
  > **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.
52
52
 
53
- > **Privacy Note**: We use [Umami Analytics](https://umami.is/) to collect anonymous usage data (e.g., number of conversions) to help us improve the tool. This tracking is cookie-less, respects "Do Not Track" settings, and never collects personal information.
53
+ > **Privacy Note**: We use [Umami Analytics](https://umami.is/) 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](./docs/ANALYTICS.md)** for details.
54
54
 
55
55
  Explore our **[Visual Gallery (Storybook)](https://gehdoc.github.io/svg-to-video/storybook/)** to see how the engine handles complex CSS and fonts.
56
56
 
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Unified Analytics Telemetry Event Schemas (Umami)
3
+ * Shared contract between Web Studio, CLI, and MCP Server.
4
+ */
5
+ export const UMAMI_HOST_URL = 'https://cloud.umami.is';
6
+ export const UMAMI_WEBSITE_HOSTNAME = 'gehdoc.github.io';
7
+ export const UMAMI_WEBSITE_ID = '4489aba4-cf29-439e-9491-e36f2a531a63';
@@ -216,3 +216,57 @@ export const analyzeSvgAnimation = (svgContent, parserOverride) => {
216
216
  }
217
217
  return undefined;
218
218
  };
219
+ /**
220
+ * Parses SVG content to extract width and height from width/height attributes or viewBox.
221
+ * Accepts an optional DOMParser override for non-browser environments.
222
+ */
223
+ export const parseSvgDimensions = (svgContent, parserOverride) => {
224
+ const Parser = parserOverride ||
225
+ (typeof DOMParser !== 'undefined' ? DOMParser : undefined);
226
+ if (!Parser) {
227
+ throw new Error('DOMParser is not available. Provide it via parserOverride.');
228
+ }
229
+ const parser = new Parser();
230
+ const doc = parser.parseFromString(svgContent, 'image/svg+xml');
231
+ const svg = doc.querySelector('svg');
232
+ if (!svg)
233
+ throw new Error('Invalid SVG content');
234
+ let width = parseFloat(svg.getAttribute('width') || '');
235
+ let height = parseFloat(svg.getAttribute('height') || '');
236
+ const viewBox = svg.getAttribute('viewBox');
237
+ let isDimensionsDetected = !(isNaN(width) || isNaN(height));
238
+ if (!isDimensionsDetected && viewBox) {
239
+ const parts = viewBox
240
+ .trim()
241
+ .split(/[\s,]+/)
242
+ .map(parseFloat);
243
+ if (parts.length === 4 && !isNaN(parts[2]) && !isNaN(parts[3])) {
244
+ width = parts[2];
245
+ height = parts[3];
246
+ isDimensionsDetected = true;
247
+ }
248
+ }
249
+ if (isNaN(width) || isNaN(height) || width <= 0 || height <= 0) {
250
+ width = 1920;
251
+ height = 1080;
252
+ isDimensionsDetected = false;
253
+ }
254
+ return { width, height, isDimensionsDetected };
255
+ };
256
+ /**
257
+ * Calculates aspect ratio category ('square', 'landscape', 'portrait', or 'unknown').
258
+ */
259
+ export function calculateAspectRatio(width, height, isDimensionsDetected = true) {
260
+ if (!isDimensionsDetected ||
261
+ isNaN(width) ||
262
+ isNaN(height) ||
263
+ width <= 0 ||
264
+ height <= 0) {
265
+ return 'unknown';
266
+ }
267
+ if (width === height)
268
+ return 'square';
269
+ if (width > height)
270
+ return 'landscape';
271
+ return 'portrait';
272
+ }
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Calculates elapsed duration in seconds.
3
+ * Uses performance.now() if available, otherwise Date.now().
4
+ */
5
+ export function calculateElapsedSec(startTimeMs) {
6
+ const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
7
+ return parseFloat(((now - startTimeMs) / 1000).toFixed(2));
8
+ }
9
+ /**
10
+ * Shared ConversionTracker class that manages timing state and telemetry dispatch
11
+ * for video/image rendering across Web Studio, CLI, and MCP interfaces.
12
+ */
13
+ export class ConversionTracker {
14
+ options;
15
+ trackFn;
16
+ startTimeMs;
17
+ constructor(options, trackFn) {
18
+ this.options = options;
19
+ this.trackFn = trackFn;
20
+ this.startTimeMs =
21
+ typeof performance !== 'undefined' ? performance.now() : Date.now();
22
+ }
23
+ start() {
24
+ this.trackFn('conversion-start', {
25
+ format: this.options.format,
26
+ isTransparent: this.options.isTransparent,
27
+ captureMethod: this.options.captureMethod,
28
+ fps: this.options.fps,
29
+ videoDurationSec: this.options.videoDurationSec,
30
+ });
31
+ }
32
+ success(totalFrames) {
33
+ const processDurationSec = calculateElapsedSec(this.startTimeMs);
34
+ this.trackFn('conversion-success', {
35
+ format: this.options.format,
36
+ isTransparent: this.options.isTransparent,
37
+ captureMethod: this.options.captureMethod,
38
+ fps: this.options.fps,
39
+ videoDurationSec: this.options.videoDurationSec,
40
+ totalFrames,
41
+ processDurationSec,
42
+ });
43
+ }
44
+ failed(error) {
45
+ const processDurationSec = calculateElapsedSec(this.startTimeMs);
46
+ const errorMessage = typeof error === 'string' ? error : error.message;
47
+ this.trackFn('conversion-failed', {
48
+ error: errorMessage,
49
+ format: this.options.format,
50
+ isTransparent: this.options.isTransparent,
51
+ captureMethod: this.options.captureMethod,
52
+ processDurationSec,
53
+ });
54
+ }
55
+ cancel() {
56
+ const processDurationSec = calculateElapsedSec(this.startTimeMs);
57
+ this.trackFn('conversion-cancel', {
58
+ format: this.options.format,
59
+ isTransparent: this.options.isTransparent,
60
+ captureMethod: this.options.captureMethod,
61
+ processDurationSec,
62
+ });
63
+ }
64
+ }
package/dist/src/index.js CHANGED
@@ -4,14 +4,15 @@ import child_process from 'child_process';
4
4
  import puppeteer from 'puppeteer';
5
5
  import { Command } from 'commander';
6
6
  import path from 'path';
7
- import { seekAnimations } from '../shared/animation-engine.js';
7
+ import { seekAnimations } from '@shared/animation-engine.js';
8
8
  import { validateOptions } from './utils/validateOptions.js';
9
- import { analyzeSvgAnimation } from '../shared/analyzeSvgAnimation.js';
9
+ import { analyzeSvgAnimation, parseSvgDimensions, calculateAspectRatio, } from '@shared/analyzeSvgAnimation.js';
10
10
  import { formatRegistry } from './formats/registry.js';
11
- import { getPackageJson } from './utils/packageInfo.js';
12
- const pkg = getPackageJson(import.meta.url);
11
+ import { pkg } from './utils/packageInfo.js';
13
12
  import { JSDOM } from 'jsdom'; // For duration detection in Node environment
14
13
  import { Logger } from './utils/logger.js';
14
+ import { trackEvent } from './utils/analytics.js';
15
+ import { ConversionTracker } from '@shared/rendererTracking.js';
15
16
  const frameFileExtension = 'png';
16
17
  async function main() {
17
18
  const program = new Command();
@@ -84,16 +85,25 @@ async function run(svgPath, fps, outDir, options) {
84
85
  throw logger.fatal(`Input SVG file "${svgPath}" does not exist.`);
85
86
  }
86
87
  const svg = fs.readFileSync(svgPath, 'utf-8');
88
+ const dom = new JSDOM('');
89
+ const parsedDim = parseSvgDimensions(svg, dom.window.DOMParser);
90
+ const detectedDuration = analyzeSvgAnimation(svg, dom.window.DOMParser);
87
91
  let duration = options.duration;
88
92
  if (duration === undefined) {
89
93
  logger.info('🔍 Duration not provided, attempting to auto-detect...');
90
- const dom = new JSDOM('');
91
- duration = analyzeSvgAnimation(svg, dom.window.DOMParser);
94
+ duration = detectedDuration;
92
95
  if (duration === undefined) {
93
96
  throw logger.fatal('Could not detect duration. Please provide a duration using -d or --duration.');
94
97
  }
95
98
  logger.info(`✅ Auto-detected duration: ${duration}s`);
96
99
  }
100
+ const aspectRatio = calculateAspectRatio(parsedDim.width, parsedDim.height, parsedDim.isDimensionsDetected);
101
+ trackEvent('file-load', {
102
+ detectedDuration: detectedDuration ?? 0,
103
+ hasAnimation: detectedDuration !== undefined && detectedDuration > 0,
104
+ aspectRatio,
105
+ isDimensionsDetected: parsedDim.isDimensionsDetected,
106
+ });
97
107
  const puppeteerArgs = (process.env.PUPPETEER_ARGS || '')
98
108
  .split(' ')
99
109
  .filter((arg) => arg.trim().length > 0);
@@ -108,25 +118,40 @@ async function run(svgPath, fps, outDir, options) {
108
118
  }
109
119
  logger.info(` Frames: ${totalFrames} total`);
110
120
  logger.info('---');
111
- fs.mkdirSync(outDir, { recursive: true });
112
- await createFrames(svg, fps, totalFrames, padWidth, outDir, puppeteerArgs, options.resolution, options.scale, options.transparent, options.bgColor, logger);
113
- convertToOutput(outputFileName, format, fps, padWidth, options.hold, outDir, options.transparent, options.metadata, logger);
114
- if (!options.keepFrames) {
115
- cleanupFrames(totalFrames, padWidth, outDir, logger);
116
- }
117
- logger.done(outputFullPath, {
118
- duration,
119
- fps,
121
+ const tracker = new ConversionTracker({
120
122
  format,
121
- totalFrames,
122
- resolution: options.resolution,
123
- transparent: options.transparent,
124
- });
123
+ isTransparent: options.transparent,
124
+ captureMethod: 'puppeteer',
125
+ fps,
126
+ videoDurationSec: duration,
127
+ }, trackEvent);
128
+ tracker.start();
129
+ try {
130
+ fs.mkdirSync(outDir, { recursive: true });
131
+ await createFrames(svg, parsedDim, fps, totalFrames, padWidth, outDir, puppeteerArgs, options.resolution, options.scale, options.transparent, options.bgColor, logger);
132
+ convertToOutput(outputFileName, format, fps, padWidth, options.hold, outDir, options.transparent, options.metadata, logger);
133
+ if (!options.keepFrames) {
134
+ cleanupFrames(totalFrames, padWidth, outDir, logger);
135
+ }
136
+ tracker.success(totalFrames);
137
+ logger.done(outputFullPath, {
138
+ duration,
139
+ fps,
140
+ format,
141
+ totalFrames,
142
+ resolution: options.resolution,
143
+ transparent: options.transparent,
144
+ });
145
+ }
146
+ catch (error) {
147
+ tracker.failed(error instanceof Error ? error : String(error));
148
+ throw error;
149
+ }
125
150
  }
126
151
  /**
127
152
  * create frame images by rendering the SVG in a headless browser and advancing the animation to the correct timestamp for each frame
128
153
  */
129
- async function createFrames(svg, fps, totalFrames, padWidth, outDir, puppeteerArgs, resolutionPreset, scaleFactor, transparent, bgColor, logger) {
154
+ async function createFrames(svg, parsedDim, fps, totalFrames, padWidth, outDir, puppeteerArgs, resolutionPreset, scaleFactor, transparent, bgColor, logger) {
130
155
  logger.info('📸 Rendering frames with Puppeteer...');
131
156
  let width = 0;
132
157
  let height = 0;
@@ -139,32 +164,11 @@ async function createFrames(svg, fps, totalFrames, padWidth, outDir, puppeteerAr
139
164
  height = 720;
140
165
  }
141
166
  else if (resolutionPreset === 'original') {
142
- const dom = new JSDOM(svg);
143
- const svgEl = dom.window.document.querySelector('svg');
144
- if (!svgEl) {
145
- throw new Error('Invalid SVG: No <svg> root element found.');
146
- }
147
- const viewBox = svgEl.getAttribute('viewBox');
148
- const widthAttr = svgEl.getAttribute('width');
149
- const heightAttr = svgEl.getAttribute('height');
150
- if (viewBox) {
151
- const parts = viewBox.trim().split(/[\s,]+/);
152
- if (parts.length === 4) {
153
- width = parseFloat(parts[2]);
154
- height = parseFloat(parts[3]);
155
- }
156
- }
157
- if ((!width || !height) && widthAttr && heightAttr) {
158
- width = parseFloat(widthAttr);
159
- height = parseFloat(heightAttr);
160
- }
161
- if (!width || !height) {
162
- logger.warn('⚠️ Warning: Could not detect SVG dimensions. Defaulting to 1280x720.');
163
- width = 1280;
164
- height = 720;
167
+ if (!parsedDim.isDimensionsDetected) {
168
+ logger.warn('⚠️ Warning: Could not detect SVG dimensions. Defaulting to 1920x1080.');
165
169
  }
166
- width = Math.round(width * scaleFactor);
167
- height = Math.round(height * scaleFactor);
170
+ width = Math.round(parsedDim.width * scaleFactor);
171
+ height = Math.round(parsedDim.height * scaleFactor);
168
172
  }
169
173
  else {
170
174
  throw new Error(`Invalid resolution preset: ${resolutionPreset}. Expected '1080p', '720p', or 'original'.`);
package/dist/src/mcp.js CHANGED
@@ -8,10 +8,10 @@ import os from 'os';
8
8
  import { execFileSync } from 'child_process';
9
9
  import { fileURLToPath } from 'url';
10
10
  import { JSDOM } from 'jsdom';
11
- import { analyzeSvgAnimation } from '../shared/analyzeSvgAnimation.js';
11
+ import { analyzeSvgAnimation, parseSvgDimensions, calculateAspectRatio, } from '@shared/analyzeSvgAnimation.js';
12
12
  import { isLoggerJsonOutput } from './utils/logger.js';
13
- import { getPackageJson } from './utils/packageInfo.js';
14
- const pkg = getPackageJson(import.meta.url);
13
+ import { trackEvent } from './utils/analytics.js';
14
+ import { pkg } from './utils/packageInfo.js';
15
15
  const __filename = fileURLToPath(import.meta.url);
16
16
  const __dirname = path.dirname(__filename);
17
17
  const cliJsPath = path.join(__dirname, 'index.js');
@@ -138,25 +138,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
138
138
  ],
139
139
  };
140
140
  }
141
- const dom = new JSDOM(svgContent);
141
+ const dom = new JSDOM('');
142
142
  const duration = analyzeSvgAnimation(svgContent, dom.window.DOMParser);
143
- const svgEl = dom.window.document.querySelector('svg');
144
- let width;
145
- let height;
146
- if (svgEl) {
147
- const viewBox = svgEl.getAttribute('viewBox');
148
- if (viewBox) {
149
- const parts = viewBox.trim().split(/[\s,]+/);
150
- if (parts.length === 4) {
151
- width = parseFloat(parts[2]);
152
- height = parseFloat(parts[3]);
153
- }
154
- }
155
- if (!width || !height) {
156
- width = parseFloat(svgEl.getAttribute('width') || '');
157
- height = parseFloat(svgEl.getAttribute('height') || '');
158
- }
159
- }
143
+ const parsedDim = parseSvgDimensions(svgContent, dom.window.DOMParser);
144
+ const aspectRatio = calculateAspectRatio(parsedDim.width, parsedDim.height, parsedDim.isDimensionsDetected);
145
+ trackEvent('file-load', {
146
+ detectedDuration: duration ?? 0,
147
+ hasAnimation: duration !== undefined && duration > 0,
148
+ aspectRatio,
149
+ isDimensionsDetected: parsedDim.isDimensionsDetected,
150
+ }, 'mcp');
160
151
  return {
161
152
  content: [
162
153
  {
@@ -164,7 +155,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
164
155
  text: JSON.stringify({
165
156
  hasAnimation: duration !== undefined && duration > 0,
166
157
  estimatedDurationSeconds: duration ?? null,
167
- dimensions: width && height ? { width, height } : null,
158
+ dimensions: parsedDim.isDimensionsDetected
159
+ ? { width: parsedDim.width, height: parsedDim.height }
160
+ : null,
168
161
  hasStyles: svgContent.includes('<style>'),
169
162
  }, null, 2),
170
163
  },
@@ -223,6 +216,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
223
216
  const rawOutput = execFileSync(command, cliArgs, {
224
217
  encoding: 'utf-8',
225
218
  cwd: process.cwd(),
219
+ env: {
220
+ ...process.env,
221
+ SVG_TO_VIDEO_INTERFACE: 'mcp',
222
+ },
226
223
  });
227
224
  if (tempSvgFile && targetSvgPath) {
228
225
  try {
@@ -0,0 +1,61 @@
1
+ import { Umami } from '@umami/node';
2
+ import { pkg } from './packageInfo.js';
3
+ import { UMAMI_HOST_URL, UMAMI_WEBSITE_HOSTNAME, UMAMI_WEBSITE_ID, } from '../../shared/analytics-schema.js';
4
+ const umami = new Umami({
5
+ hostUrl: UMAMI_HOST_URL,
6
+ websiteId: UMAMI_WEBSITE_ID,
7
+ });
8
+ export function isOptedOut() {
9
+ const dnt = process.env.DO_NOT_TRACK;
10
+ if (dnt) {
11
+ const normalized = dnt.trim().toLowerCase();
12
+ if (normalized === '1' || normalized === 'true') {
13
+ return true;
14
+ }
15
+ }
16
+ if (process.env.CI || process.env.NODE_ENV === 'test') {
17
+ return true;
18
+ }
19
+ return false;
20
+ }
21
+ export function resolveInterfaceType(defaultType = 'cli') {
22
+ if (process.env.SVG_TO_VIDEO_INTERFACE === 'mcp') {
23
+ return 'mcp';
24
+ }
25
+ return defaultType;
26
+ }
27
+ export function trackEvent(eventName, properties, interfaceType) {
28
+ if (isOptedOut()) {
29
+ return;
30
+ }
31
+ sendEvent(eventName, properties, interfaceType).catch(() => {
32
+ // Silent fail-safe
33
+ });
34
+ }
35
+ export async function sendEvent(eventName, properties, interfaceType) {
36
+ if (isOptedOut()) {
37
+ return false;
38
+ }
39
+ const resolvedInterface = resolveInterfaceType(interfaceType);
40
+ const controller = new AbortController();
41
+ const timeoutId = setTimeout(() => controller.abort(), 3000);
42
+ try {
43
+ const response = await umami.track({
44
+ website: UMAMI_WEBSITE_ID,
45
+ hostname: UMAMI_WEBSITE_HOSTNAME,
46
+ url: `/${resolvedInterface}`,
47
+ name: eventName,
48
+ data: {
49
+ ...properties,
50
+ version: pkg.version,
51
+ },
52
+ });
53
+ return response.ok;
54
+ }
55
+ catch {
56
+ return false;
57
+ }
58
+ finally {
59
+ clearTimeout(timeoutId);
60
+ }
61
+ }
@@ -1,16 +1,20 @@
1
- import fs from 'fs';
2
- import path from 'path';
3
- import { fileURLToPath } from 'url';
4
1
  import { createRequire } from 'module';
5
- export function getPackageJson(importMetaUrl) {
6
- const require = createRequire(importMetaUrl);
7
- const filename = fileURLToPath(importMetaUrl);
8
- const dirname = path.dirname(filename);
9
- const localPkg = path.join(dirname, '../package.json');
10
- const parentPkg = path.join(dirname, '../../package.json');
11
- if (fs.existsSync(localPkg))
12
- return require(localPkg);
13
- if (fs.existsSync(parentPkg))
14
- return require(parentPkg);
15
- return require('../package.json');
2
+ import { fileURLToPath } from 'url';
3
+ import path from 'path';
4
+ import fs from 'fs';
5
+ // Resolve package.json at module load time.
6
+ // This file lives at one of:
7
+ // src/utils/packageInfo.ts (tsx / dev) → root is 2 levels up
8
+ // dist/src/utils/packageInfo.js (built) → root is 3 levels up
9
+ // We try both depths and throw a clear error if neither exists.
10
+ const _require = createRequire(import.meta.url);
11
+ const _dir = path.dirname(fileURLToPath(import.meta.url));
12
+ function findPkg() {
13
+ for (const rel of ['../../package.json', '../../../package.json']) {
14
+ const candidate = path.resolve(_dir, rel);
15
+ if (fs.existsSync(candidate))
16
+ return _require(candidate);
17
+ }
18
+ throw new Error(`Could not locate package.json from: ${_dir}`);
16
19
  }
20
+ export const pkg = findPkg();
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "@gehdoc/svg-to-video",
3
- "version": "0.24.0",
3
+ "version": "0.25.1",
4
4
  "type": "module",
5
5
  "description": "Professional animated SVG to Video (MP4/WebM/MKV/MOV) and Animated Image (aPNG/GIF) converter featuring frame-accurate rendering, CLI automation, and a serverless Web Studio.",
6
6
  "imports": {
7
- "#shared/*": "./dist/shared/*"
7
+ "#shared/*": "./dist/shared/*",
8
+ "@shared/*": "./dist/shared/*"
8
9
  },
9
10
  "author": "GehDoc",
10
11
  "repository": {
@@ -53,6 +54,7 @@
53
54
  ],
54
55
  "dependencies": {
55
56
  "@modelcontextprotocol/sdk": "^1.30.0",
57
+ "@umami/node": "^0.4.0",
56
58
  "commander": "^15.0.0",
57
59
  "jsdom": "^29.1.1",
58
60
  "puppeteer": "^25.8.0",