Skip to main content
Version: 2.0 (Preview)

Screen Recording with ffmpeg

Automator can make recordings of studies with FFmpeg. The setup script and the Docker image already include it, unless you passed --skip-ffmpeg to the setup script.

Screen recording does not work with --display browser-headless or with GPU rendering, because there is nothing to record on the display.

Enabling Screen Recording​

surfmeter study start --studyId STUDY_YOUTUBE --enableScreenRecording

The recordings are stored as .mp4 files in ~/.surfmeter/recordings/. Use --screenRecordingDir to set a different directory.

Tip

You will find the name of the recording in the study.metadata.surfmeter.screenRecordingFilename field of the report. In the API, the attribute is called study.metadata.surfmeter.screen_recording_filename.

Writing to a Stream​

To stream the recording to an SRT URL instead of writing a file, for example to process it in real time, use --screenRecordingTargetUrl:

surfmeter study start --studyId STUDY_YOUTUBE \
    --enableScreenRecording \
    --screenRecordingTargetUrl "srt://localhost:6000?mode=caller&transtype=live&streamid=bc82bd9c-1307-4037-a097-298406b40699,mode:publish"

Encoding Options​

Recordings are encoded with x264. You can set the following options:

  • --ffmpegCrf: The CRF (lower is better quality, higher is better compression)
  • --ffmpegFps: The frame rate (inferred from the display refresh rate if not set)
  • --ffmpegPreset: The preset (slower gives a lower file size, with a higher CPU usage). The default is veryfast.
Recording can cause frame drops

Recording might cause frame drops on a slow machine. If that happens, set a lower frame rate with --ffmpegFps.

Recording Audio​

Audio recording requires PulseAudio, which is configured in the Docker image. For a native installation, enable a loopback device:

pactl load-module module-null-sink sink_name=loopback
pactl set-default-sink loopback

When Automator detects a loopback device, it uses it for the recording. Otherwise, it prints a warning, and continues without audio.

Audio recording can be slow in Docker

Some users report that screen recordings with audio are slow inside Docker. Set SURFMETER_DISABLE_PULSEAUDIO=1 in the environment of the container to disable audio.