@gehdoc/svg-to-video 0.23.4 → 0.25.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
@@ -4,11 +4,11 @@
4
4
 
5
5
  # SVG to Video
6
6
 
7
- [![CI](https://github.com/GehDoc/svg-to-video/actions/workflows/ci.yml/badge.svg)](https://github.com/GehDoc/svg-to-video/actions/workflows/ci.yml)
8
- [![GitHub Release](https://img.shields.io/github/v/release/GehDoc/svg-to-video?color=blue)](https://github.com/GehDoc/svg-to-video/releases)
9
- [![npm version](https://img.shields.io/npm/v/@gehdoc/svg-to-video.svg?color=cb3837)](https://www.npmjs.com/package/@gehdoc/svg-to-video)
10
- [![Docker Image Version](https://img.shields.io/docker/v/gehdoc/svg-to-video?sort=semver&color=2496ed)](https://hub.docker.com/r/gehdoc/svg-to-video)
11
- [![Last Commit](https://img.shields.io/github/last-commit/GehDoc/svg-to-video)](https://gehdoc.github.io/svg-to-video/commits/main)
7
+ [![CI](https://img.shields.io/github/actions/workflow/status/GehDoc/svg-to-video/ci.yml?branch=main&logo=githubactions&logoColor=white&label=CI)](https://github.com/GehDoc/svg-to-video/actions/workflows/ci.yml)
8
+ [![GitHub Release](https://img.shields.io/github/v/release/GehDoc/svg-to-video?logo=github&logoColor=white&label=release&color=2b3137)](https://github.com/GehDoc/svg-to-video/releases)
9
+ [![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)
10
+ [![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)
11
+ [![Last Commit](https://img.shields.io/github/last-commit/GehDoc/svg-to-video?logo=github&logoColor=white)](https://github.com/GehDoc/svg-to-video/commits/main)
12
12
 
13
13
  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.
14
14
 
@@ -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
 
@@ -112,7 +112,15 @@ See **[docs/MCP.md](./docs/MCP.md)** for full setup instructions, tool schemas,
112
112
 
113
113
  ---
114
114
 
115
- ## 📦 Installation Options
115
+ ## 🔗 Official Package Distributions
116
+
117
+ - 📦 **npm Package**: [`@gehdoc/svg-to-video`](https://www.npmjs.com/package/@gehdoc/svg-to-video)
118
+ - 🐳 **Docker Hub Image**: [`gehdoc/svg-to-video`](https://hub.docker.com/r/gehdoc/svg-to-video)
119
+ - 🌐 **Web Studio**: [`gehdoc.github.io/svg-to-video/`](https://gehdoc.github.io/svg-to-video/)
120
+
121
+ ---
122
+
123
+ ## 📦 Quick Installation & Execution
116
124
 
117
125
  ```bash
118
126
  # Run on-demand via npx (no global installation required)
@@ -121,7 +129,7 @@ npx @gehdoc/svg-to-video input.svg 60 ./out-dir
121
129
  # Install globally via npm
122
130
  npm install -g @gehdoc/svg-to-video
123
131
 
124
- # Pull official Docker image
132
+ # Pull official Docker image from Docker Hub
125
133
  docker pull gehdoc/svg-to-video:latest
126
134
  ```
127
135
 
@@ -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';
@@ -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
@@ -8,10 +8,11 @@ import { seekAnimations } from '../shared/animation-engine.js';
8
8
  import { validateOptions } from './utils/validateOptions.js';
9
9
  import { analyzeSvgAnimation } 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();
@@ -94,6 +95,13 @@ async function run(svgPath, fps, outDir, options) {
94
95
  }
95
96
  logger.info(`✅ Auto-detected duration: ${duration}s`);
96
97
  }
98
+ trackEvent('file-load', {
99
+ // TODO : Add actual values for these properties based on the SVG (not options)
100
+ detectedDuration: 0,
101
+ hasAnimation: false,
102
+ aspectRatio: 'unknown',
103
+ isDimensionsDetected: false,
104
+ });
97
105
  const puppeteerArgs = (process.env.PUPPETEER_ARGS || '')
98
106
  .split(' ')
99
107
  .filter((arg) => arg.trim().length > 0);
@@ -108,20 +116,35 @@ async function run(svgPath, fps, outDir, options) {
108
116
  }
109
117
  logger.info(` Frames: ${totalFrames} total`);
110
118
  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,
119
+ const tracker = new ConversionTracker({
120
120
  format,
121
- totalFrames,
122
- resolution: options.resolution,
123
- transparent: options.transparent,
124
- });
121
+ isTransparent: options.transparent,
122
+ captureMethod: 'puppeteer',
123
+ fps,
124
+ videoDurationSec: duration,
125
+ }, trackEvent);
126
+ tracker.start();
127
+ try {
128
+ fs.mkdirSync(outDir, { recursive: true });
129
+ await createFrames(svg, fps, totalFrames, padWidth, outDir, puppeteerArgs, options.resolution, options.scale, options.transparent, options.bgColor, logger);
130
+ convertToOutput(outputFileName, format, fps, padWidth, options.hold, outDir, options.transparent, options.metadata, logger);
131
+ if (!options.keepFrames) {
132
+ cleanupFrames(totalFrames, padWidth, outDir, logger);
133
+ }
134
+ tracker.success(totalFrames);
135
+ logger.done(outputFullPath, {
136
+ duration,
137
+ fps,
138
+ format,
139
+ totalFrames,
140
+ resolution: options.resolution,
141
+ transparent: options.transparent,
142
+ });
143
+ }
144
+ catch (error) {
145
+ tracker.failed(error instanceof Error ? error : String(error));
146
+ throw error;
147
+ }
125
148
  }
126
149
  /**
127
150
  * create frame images by rendering the SVG in a headless browser and advancing the animation to the correct timestamp for each frame
package/dist/src/mcp.js CHANGED
@@ -10,8 +10,8 @@ import { fileURLToPath } from 'url';
10
10
  import { JSDOM } from 'jsdom';
11
11
  import { analyzeSvgAnimation } 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');
@@ -157,6 +157,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
157
157
  height = parseFloat(svgEl.getAttribute('height') || '');
158
158
  }
159
159
  }
160
+ trackEvent('file-load', {
161
+ detectedDuration: duration,
162
+ hasAnimation: duration !== undefined && duration > 0,
163
+ aspectRatio: width && height
164
+ ? width === height
165
+ ? 'square'
166
+ : width > height
167
+ ? 'landscape'
168
+ : 'portrait'
169
+ : 'unknown',
170
+ isDimensionsDetected: !!(width && height),
171
+ }, 'mcp');
160
172
  return {
161
173
  content: [
162
174
  {
@@ -223,6 +235,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
223
235
  const rawOutput = execFileSync(command, cliArgs, {
224
236
  encoding: 'utf-8',
225
237
  cwd: process.cwd(),
238
+ env: {
239
+ ...process.env,
240
+ SVG_TO_VIDEO_INTERFACE: 'mcp',
241
+ },
226
242
  });
227
243
  if (tempSvgFile && targetSvgPath) {
228
244
  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,6 +1,6 @@
1
1
  {
2
2
  "name": "@gehdoc/svg-to-video",
3
- "version": "0.23.4",
3
+ "version": "0.25.0",
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": {
@@ -53,6 +53,7 @@
53
53
  ],
54
54
  "dependencies": {
55
55
  "@modelcontextprotocol/sdk": "^1.30.0",
56
+ "@umami/node": "^0.4.0",
56
57
  "commander": "^15.0.0",
57
58
  "jsdom": "^29.1.1",
58
59
  "puppeteer": "^25.8.0",