Screen Recording with ffmpeg¶
If you have ffmpeg installed on your system, you can automatically make recordings of the studies.
Installing FFmpeg¶
We recommend using a recent version of FFmpeg. The version that comes with your system might be too old.
Download a static build of FFmpeg from here and extract it. Place the ffmpeg binary in your $PATH, e.g. /usr/local/bin.
FFmpeg is already part of our Docker image! 
Enabling Screen Recording¶
To enable screen recording, pass the following flag to the startStudy command:
Writing to a File¶
The recordings will, by default, be placed in your system's temporary directory, and the path to the recording will be printed in the log. The file name it is in the format:
Use --screenRecordingDir to set a different directory of your choice.
Writing to a Stream¶
Starting with v1.14.0, you can also stream the screen recording to a SRT URL. This is useful if you want to process the recording in real-time, e.g. for live streaming.
To enable this, use the --screenRecordingTargetUrl option. The URL must be in the format srt://<host>:<port>?<params>, e.g.:
./surfmeter-automator-headless \
startStudy --studyId STUDY_YOUTUBE \
--enableScreenRecording \
--screenRecordingTargetUrl "srt://localhost:6000?mode=caller&transtype=live&streamid=bc82bd9c-1307-4037-a097-298406b40699,mode:publish"
Encoding Options¶
At the moment, we use x264 for encoding the screen recordings due to its high quality and low CPU usage.
Currently the following options can be set:
| Option | Description |
|---|---|
--ffmpegCrf |
Set CRF for ffmpeg (lower is better quality, higher is better compression) [default: 23] |
--ffmpegFps |
Set FPS for ffmpeg (will be inferred from display refresh rate if not set) |
--ffmpegPreset |
Set preset for ffmpeg (slower is lower file size and higher CPU usage) |
Warning
Under Linux, the native frame rate is unbounded due to the virtualization of the display. We therefore set the frame rate to 60 FPS by default. This might cause frame drops in the recording. If you experience this, you can set the frame rate to something lower with --ffmpegFps.
For further options related to screen recording please consult the help:
Recording Audio¶
Starting with Surfmeter Automator v1.13.0, we support recording audio in the screen recordings. This currently only works under Linux, and if you have pulseaudio installed on your system. For more information, see this FFmpeg wiki article.
If you use our Docker image, this works out of the box.
If you set run Surfmeter Automator natively, you must enable a loopback device in pulseaudio:
When Surfmeter detects a loopback device, it will use that for audio encoding. Otherwise, it will print a warning and not record audio, but continue with the video recording.
Warning
Some users have noted that screen recording performance is low when using audio recording inside Docker. Set SURFMETER_DISABLE_PULSEAUDIO=1 as an environment variable to disable it.