Heuristic:DevExpress Testcafe Video Encoding Defaults
| Knowledge Sources | |
|---|---|
| Domains | Video_Recording, Optimization |
| Last Updated | 2026-02-12 03:30 GMT |
Overview
FFmpeg video encoding uses H.264 codec with ultrafast preset, yuv420p pixel format, and 30fps for maximum compatibility and minimal CPU overhead.
Description
TestCafe's video recorder spawns an FFmpeg child process that receives PNG frames via stdin and encodes them to an MP4 video file. The default encoding options prioritize speed over compression quality (ultrafast preset) and compatibility (yuv420p pixel format, 30fps). A scale filter ensures frame dimensions are divisible by 2 (required by yuv420p). FFmpeg is resolved from: (1) `FFMPEG_PATH` environment variable, (2) `@ffmpeg-installer/ffmpeg` npm package in CWD, (3) the same npm package globally, (4) system PATH. The 500ms start delay allows FFmpeg to initialize before frames are sent.
Usage
Apply this knowledge when configuring video recording for test runs or troubleshooting video quality/size issues. The default options produce large files quickly; override with custom options to balance quality and file size. Video recording requires FFmpeg to be installed separately (not bundled with TestCafe).
The Insight (Rule of Thumb)
- Action: Enable video recording via `--video` CLI flag or `video` runner option. Customize encoding with `--video-options` or `videoOptions` (e.g., `r=15` for lower framerate, `preset=medium` for better compression).
- Value: Defaults: codec=libx264, preset=ultrafast, pix_fmt=yuv420p, framerate=30fps, format=image2pipe.
- Trade-off: `ultrafast` preset produces large files but uses minimal CPU. Changing to `medium` or `slow` reduces file size by 50-70% but increases CPU usage significantly. Reducing framerate from 30 to 15 halves file size.
- FFmpeg resolution order: `FFMPEG_PATH` env var > `@ffmpeg-installer/ffmpeg` in CWD > global npm package > system PATH.
Reasoning
Test video recordings are primarily used for debugging failed tests, not for distribution. The ultrafast preset minimizes encoding latency so frame capture does not slow down test execution. The yuv420p pixel format ensures the resulting video plays in all major video players and browsers. The frame scaling filter (`scale=trunc(iw/2)*2:trunc(ih/2)*2`) prevents encoding errors when browser window dimensions are odd numbers. The 30fps default ensures smooth playback while the `use_wallclock_as_timestamps` flag preserves real-world timing of events.
Code Evidence
FFmpeg default options from `src/video-recorder/process.js:10-39`:
const DEFAULT_OPTIONS = {
// NOTE: use to force stdin and stdout formats
'f': 'image2pipe',
// NOTE: don't ask confirmation for rewriting the output file
'y': true,
// NOTE: use the time when a frame is read from the source as its timestamp
// IMPORTANT: must be specified before configuring the source
'use_wallclock_as_timestamps': 1,
// NOTE: use stdin as a source
'i': 'pipe:0',
// NOTE: use the H.264 video codec
'c:v': 'libx264',
// NOTE: use the 'ultrafast' compression preset
'preset': 'ultrafast',
// NOTE: use the yuv420p pixel format (the most widely supported)
'pix_fmt': 'yuv420p',
// NOTE: scale input frames to make the frame height divisible by 2 (yuv420p's requirement)
'vf': 'scale=trunc(iw/2)*2:trunc(ih/2)*2',
// NOTE: set the frame rate to 30 in the output video (the most widely supported)
'r': 30,
};
FFmpeg resolution priority from `src/utils/detect-ffmpeg.js:40-44`:
export default async function () {
return process.env.FFMPEG_PATH ||
await requireFFMPEGModuleFromCwd() ||
await requireFFMPEGModule() ||
await findFFMPEGinPath();
}