Skip to content

: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.

9.8 KB
Raw Blame
import * as fs from 'fs/promises'
import { capture as captureVideo } from 'puppeteer-capture'

import { RasterizationError } from '~/session-replay/recording-rasterizer/errors'
import { type Logger, createLogger } from '~/session-replay/recording-rasterizer/logger'
import {
    CaptureConfig,
    InactivityPeriod,
    RasterizationProgress,
    RecordingResult,
} from '~/session-replay/recording-rasterizer/types'
import { elapsed } from '~/session-replay/recording-rasterizer/utils'

import { PlayerController } from './player'

export async function capturePlayback(
    player: PlayerController,
    captureConfig: CaptureConfig,
    outputPath: string,
    onProgress: () => void,
    progress: RasterizationProgress | null = null,
    log: Logger = createLogger()
): Promise<
    Pick<
        RecordingResult,
        | 'capture_duration_s'
        | 'frame_count'
        | 'truncated'
        | 'inactivity_periods'
        | 'frame_session_ms'
        | 'navigation_samples'
        | 'pre_roll_frames'
        | 'timings'
    >
> {
    const captureStart = process.hrtime()
    const ffmpegStderr: string[] = []
    let frameCount = 0

    // Install CDP guards before captureVideo — it wraps createCDPSession
    // to inject screenshot format and gate beginFrame on pending stylesheets.
    player.prepareBrowserForCapture(captureConfig.screenshotFormat, captureConfig.screenshotQuality)

    const page = player.page

    // Start capture — installs virtual time shims before playback.
    // All format/codec options live in captureConfig.ffmpegOutputOpts so every
    // output format is configured in one place (buildCaptureConfig).
    const recorder = await captureVideo(page, {
        fps: captureConfig.captureFps,
        format: async () => {}, // no-op — ffmpegOutputOpts carries all format settings
        // eslint-disable-next-line @typescript-eslint/require-await
        customFfmpegConfig: async (ffmpeg: any) => {
            ffmpeg.outputOptions(captureConfig.ffmpegOutputOpts)
            for (const filter of captureConfig.ffmpegVideoFilters) {
                ffmpeg.videoFilters(filter)
            }
            ffmpeg.on('start', (cmd: string) => log.info({ cmd }, 'ffmpeg started'))
            ffmpeg.on('stderr', (line: string) => ffmpegStderr.push(line))
            ffmpeg.on('error', (err: Error) => log.error({ err, stderr: ffmpegStderr.slice(-20) }, 'ffmpeg error'))
        },
        ffmpeg: process.env.FFMPEG_PATH || undefined,
    })

    const progressInterval = Math.max(10, captureConfig.captureFps)
    recorder.on('frameCaptured', () => {
        frameCount++
        if (progress) {
            progress.frame = frameCount
        }
        if (frameCount % progressInterval === 0) {
            log.info(
                {
                    frame: frameCount,
                    virtual_s: +(frameCount / captureConfig.captureFps).toFixed(1),
                    wall_s: +elapsed(captureStart).toFixed(1),
                },
                'capture progress'
            )
            onProgress()
        }
    })

    // Log the actual rejection reason when a frame capture fails. This fires
    // with the original error from frame.evaluate() or beginFrame before
    // captureStopped is emitted.
    recorder.on('frameCaptureFailed', (reason: unknown) => {
        log.error({ err: reason, frames: frameCount }, 'frame capture failed')
    })

    // Monitor page lifecycle events that can terminate capture.
    // Named functions so we can remove them in the finally block; leaving them attached would
    // fire stale error logs when the page is closed on release.
    let captureDone = false
    const onPageClose = (): void => {
        if (!captureDone) {
            log.error({ frames: frameCount }, 'page closed during capture')
        }
    }
    const onPageError = (err: Error): void => {
        if (!captureDone) {
            log.error({ err, frames: frameCount }, 'page error during capture')
        }
    }
    page.on('close', onPageClose)
    page.on('error', onPageError)

    // When ffmpeg dies, puppeteer-capture stops capturing but waitForTimeout()
    // hangs forever. Listen for captureStopped to break out of the loop: settled with an error
    // on an unexpected stop, settled cleanly when ffmpeg exiting is the end of the render.
    // undefined = still capturing, null = stopped cleanly, Error = stopped with a failure.
    let stopResult: Error | null | undefined = undefined
    let captureStopSettle: ((err: Error | null) => void) | null = null
    const onCaptureStopped = (): void => {
        // ffmpeg exits on its own once -t reaches the trim duration, and can do so before the
        // 250ms loop observes trimFrameLimit; that is a completed render, not an abort.
        if (captureDone || player.isEnded() || frameCount >= captureConfig.trimFrameLimit) {
            // Playback finished naturally — ffmpeg exiting is expected.
            log.info({ frames: frameCount }, 'capture stopped after playback ended')
            stopResult = null
        } else {
            log.error({ stderr: ffmpegStderr.slice(-20), frames: frameCount }, 'capture stopped unexpectedly')
            stopResult =
                player.fatalError ?? new RasterizationError('capture stopped unexpectedly', true, 'CAPTURE_ABORTED')
        }
        captureStopSettle?.(stopResult)
    }
    recorder.on('captureStopped', onCaptureStopped)

    let virtualElapsed = 0
    let truncated = false
    let preRollFrames = 0
    try {
        await recorder.start(outputPath)
        const vp = page.viewport()
        log.info({ fps: captureConfig.captureFps, width: vp?.width, height: vp?.height }, 'capture started')

        // Install after recorder.start() — puppeteer-capture overrides rAF/setTimeout/setInterval
        // during start(), and this wraps those overrides with try/catch so individual player JS
        // errors are swallowed instead of killing the entire capture.
        await player.installCallbackErrorGuards()

        await player.startPlayback()
        // Frames captured before the player's loop exists have no sample, so the timeline starts here
        // rather than at video second zero.
        preRollFrames = frameCount
        log.info({ pre_roll_frames: preRollFrames }, 'playback started')

        const checkIntervalMs = 250

        while (virtualElapsed < captureConfig.maxVirtualTimeMs) {
            if (stopResult !== undefined) {
                if (stopResult) {
                    throw stopResult
                }
                log.info({ frames: frameCount }, 'capture already stopped, ending loop')
                break
            }
            await new Promise<void>((resolve, reject) => {
                captureStopSettle = (err) => (err ? reject(err) : resolve())
                // A rejection landing after captureStopSettle already settled the promise is
                // swallowed here instead of surfacing as an unhandled rejection.
                Promise.resolve(recorder.waitForTimeout(checkIntervalMs)).then(resolve, reject)
            })
            captureStopSettle = null
            virtualElapsed += checkIntervalMs

            if (frameCount >= captureConfig.trimFrameLimit) {
                log.info({ trim_s: captureConfig.trim, frames: frameCount }, 'trim limit reached')
                break
            }

            const playerError = player.getError()
            if (playerError) {
                throw playerError
            }

            if (player.isEnded()) {
                log.info({ virtual_s: virtualElapsed / 1000, frames: frameCount }, 'recording ended')
                break
            }
        }

        if (virtualElapsed >= captureConfig.maxVirtualTimeMs) {
            log.warn(
                { max_virtual_s: captureConfig.maxVirtualTimeMs / 1000, frames: frameCount },
                'max virtual time reached, truncating'
            )
            truncated = true
        }
    } finally {
        captureDone = true
        captureStopSettle = null
        page.off('close', onPageClose)
        page.off('error', onPageError)
        // puppeteer-capture's PuppeteerCapture extends EventEmitter but only
        // declares `on` in its type — `off` exists at runtime.
        ;(recorder as any).off('captureStopped', onCaptureStopped)
        try {
            await recorder.stop()
        } catch (stopErr) {
            if (stopErr instanceof Error && stopErr.message === 'Capture is not in progress') {
                // Recorder already stopped (ffmpeg exited before we called stop) — harmless.
                log.info({ frames: frameCount }, 'recorder already stopped')
            } else {
                // recorder.stop() throws the stored _error when capture was
                // terminated by page close, session disconnect, or ffmpeg crash.
                // Log it so we can see the actual root cause.
                log.error({ err: stopErr, frames: frameCount }, 'recorder.stop() error (root cause)')
            }
        }
    }

    let fileSize = 0
    try {
        const rawStat = await fs.stat(outputPath)
        fileSize = rawStat.size
    } catch {
        log.warn('output file missing after capture — ffmpeg may have failed to start')
    }
    log.info({ file_size_bytes: fileSize }, 'capture stopped')

    const inactivityPeriods: InactivityPeriod[] = player.getInactivityPeriods()

    const rawDurationS = frameCount / captureConfig.outputFps
    const captureDurationS = captureConfig.trim ? Math.min(rawDurationS, captureConfig.trim) : rawDurationS

    return {
        capture_duration_s: captureDurationS,
        frame_count: frameCount,
        truncated,
        inactivity_periods: inactivityPeriods,
        frame_session_ms: await player.readFrameTimeline(),
        navigation_samples: await player.readNavigation(),
        pre_roll_frames: preRollFrames,
        timings: { setup_s: 0, capture_s: elapsed(captureStart) },
    }
}