@wity/scene-to-pdf

Server-side document renderer. Snapshots a wity-scene document at one or more timestamps and produces a PDF using node-canvas and pdf-lib. Node.js / Lambda only, not browser-compatible.

Entry point: Call witySceneRender with outputFormat: "pdf" — do not invoke this Lambda directly. See the Deployment guide.

Install

npm install @wity/scene-to-pdf
# peer deps:
npm install @wity/scene-core @xmldom/xmldom

---

render(sceneXml, fontManifest, options)

Render a scene snapshot to a PDF file on disk.

render(
  sceneXml:     string,
  fontManifest: Record<string, string>,
  options: {
    ts?:         number,
    timestamps?: number[],
    variant?:    'standard' | 'print',
    dpi?:        number,
  }
): Promise<{ pdfPath: string, cleanup: () => Promise<void> }>

Argument	Type	Description
sceneXml	string	Raw <wity-scene> XML
fontManifest	Record<string, string>	Font family name → URL. Pass {} if no custom fonts.
options.ts	number (default 0)	Scene time in seconds to snapshot. Ignored when timestamps is provided.
options.timestamps	number[]	Array of scene times — each produces one PDF page.
options.variant	'standard' | 'print' (default 'standard')	standard: screen-optimised, 96 DPI. print: high-resolution, 300 DPI.
options.dpi	number	Override render DPI. Defaults: 96 for standard, 300 for print.

Returns:

Field	Description
pdfPath	Absolute path of the rendered PDF in /tmp
cleanup	Call after upload to remove temp files

import { render } from '@wity/scene-to-pdf';

// Single-page snapshot at t=2s, print-ready
const { pdfPath, cleanup } = await render(sceneXml, {}, {
  ts:      2.0,
  variant: 'print',
});

// upload pdfPath to storage...
await cleanup();

// Multi-page: one page per timestamp
const { pdfPath, cleanup } = await render(sceneXml, {}, {
  timestamps: [0, 3.0, 6.0, 9.0],
  variant:    'standard',
});

---

Output variants

Variant	DPI	Use for
standard	96 (default)	Digital sharing, web embedding, screen viewing
print	300 (default)	Print shops, physical output, high-fidelity archival

PDF page dimensions are derived from the scene's pixel dimensions and the effective DPI, preserving the exact aspect ratio.

---

What is rendered

Element type	Rendered?
ws-rect	Yes — filled rectangles, stroke, border-radius
ws-text	Yes — font, color, animation state at ts
ws-image	Yes — image with fit modes
ws-video	No — skipped silently (graphics snapshot only)
ws-audio	No — skipped silently

Animation and keyframe state is fully resolved at ts — evaluate(scene, ts) produces the exact visual frame.

---

Lambda deployment

The witySceneToPdf Lambda wraps this package.

Input:

{
  "sceneXml":    "<wity-scene>...</wity-scene>",
  "fontManifest": {},
  "ts":           2.0,
  "variant":      "print",
  "dpi":          300
}

Response:

{ "url": "https://...", "fileSize": 234567, "pages": 1 }

Config	Value
Function name	witySceneToPdf
Memory	2048 MB
Timeout	120 s
Ephemeral storage	1024 MB
Runtime	Node.js 20
FFmpeg layer	Not required