:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Session replay rasterizer
Temporal worker that converts session replays into MP4 videos using puppeteer-capture's
HeadlessExperimental.beginFrame for deterministic virtual-time frame capture.
Runs on a dedicated rasterization-task-queue.
Architecture
Temporal workflow (Python)
└─ dispatches activity to rasterization-task-queue
└─ Node.js worker picks it up
├─ rasterizeRecording (puppeteer-capture: deterministic frame capture)
├─ computeVideoTimestamps (map session time → video time)
├─ uploadToS3
└─ return metadata
The worker maintains a warm Chromium browser pool — a single browser instance is reused across exports and recycled after N uses.
Screenshots default to JPEG (q=80) via a CDP session monkey-patch, giving ~30% faster frame capture than the hardcoded PNG in puppeteer-capture.
Directory structure
recording-rasterizer/
├── index.ts ← thin entry point, delegates to temporal/worker.ts
├── rasterize-file.ts ← offline render of a JSONL file (bin/rasterize-recording-file)
├── config.ts ← environment variable configuration
├── errors.ts ← RasterizationError class
├── logger.ts ← pino logger factory
├── metrics.ts ← Prometheus metrics
├── types.ts ← input/output contracts
├── utils.ts ← timing utilities
├── storage.ts ← S3 upload and download
├── postprocess.ts ← map inactivity periods to video timestamps
│
├── temporal/ ← Temporal integration
│ ├── worker.ts ← worker bootstrap (browser pool, Temporal connection, metrics server)
│ └── activities.ts ← activity handler (record → upload → cleanup)
│
├── capture/ ← Puppeteer capture pipeline
│ ├── browser-pool.ts ← warm Chromium lifecycle manager
│ ├── recorder.ts ← orchestrates page setup → player load → capture
│ ├── capture-page.ts ← viewport, CDP guards, callback error guards
│ ├── player.ts ← PlayerController: message bridge, playback lifecycle
│ ├── capture.ts ← frame capture loop with abort/timeout handling
│ ├── request-interceptor.ts ← request interception + stylesheet proxying
│ ├── block-proxy.ts ← recording block fetcher (recording-api)
│ ├── file-block-source.ts ← serves one JSONL file or allowlisted S3 object (source_s3_uri)
│ └── config.ts ← input validation + capture config builder
│
└── __tests__/ ← all tests
Running locally
The rasterizer runs in Docker since beginFrame requires Linux chrome-headless-shell:
bin/temporal-recording-rasterizer-worker
This builds TypeScript locally, builds the Docker image (with hash-based caching), and starts the container with volume mounts for fast iteration.
Configuration
Key environment variables (see config.ts for full list):
| Variable | Default | Description |
|---|---|---|
SCREENSHOT_FORMAT |
jpeg |
Screenshot format for frame capture (jpeg or png) |
SCREENSHOT_JPEG_QUALITY |
80 |
JPEG quality (1-100), only used when format is jpeg |
MAX_CONCURRENT_ACTIVITIES |
4 |
Max parallel activities; fewer while memory or CPU is above target |
TUNER_TARGET_MEMORY_USAGE |
0.7 |
Above this fraction of pod memory, take only the first activity |
TUNER_TARGET_CPU_USAGE |
0.9 |
Above this fraction of pod CPU, take only the first activity |
TUNER_RAMP_THROTTLE_MS |
10000 |
Minimum wait between new activity slots above the first |
BROWSER_RECYCLE_AFTER |
100 |
Recycle Chromium after N page uses |
MAX_IDLE_BROWSERS |
2 |
Warm Chromiums kept alive; extras close on release |
CAPTURE_BROWSER_LOGS |
0 |
Forward browser console/error logs to worker logger |
ENABLE_PLAYER_CSP |
1 |
Script-locking CSP on the player page (0 disables) |
Egress from the browser and the S3 client is routed through the proxy in HTTPS_PROXY/HTTP_PROXY.
In production a missing proxy URL is a startup error; RASTERIZER_USE_PROXY=false explicitly disables containment.
Activity inputs
The rasterize-recording activity accepts RasterizeRecordingInput (see types.ts):
| Field | Required | Default | Description |
|---|---|---|---|
session_id |
yes | — | Session to rasterize |
team_id |
yes | — | Team ID |
s3_bucket |
yes | — | S3 bucket for output |
s3_key_prefix |
yes | — | S3 key prefix |
playback_speed |
no | 4 |
Playback speed multiplier |
recording_fps |
no | 24 |
Output video framerate |
start_offset_s |
no | — | Start playback N seconds from session start |
end_offset_s |
no | — | Stop playback N seconds from session start |
trim |
no | — | Max output duration in seconds |
max_virtual_time |
no | — | Max virtual time in seconds before stopping |
output_format |
no | mp4 |
Output video format (mp4, webm or gif) |
recording_api_token |
no | — | Team-scoped read JWT relayed to recording-api |
viewport_width |
no | 1280 |
Capture viewport width |
viewport_height |
no | 720 |
Capture viewport height |
show_metadata_footer |
no | false |
Include metadata footer in output |
skip_inactivity |
no | true |
Skip inactive periods during playback |
mouse_tail |
no | true |
Show mouse trail in replay |