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.
- Native Execution
- Docker
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:
--enableScreenRecording
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:
20230208T095840.371Z_1167ce7b-7a44-4034-a775-27247bf3a0ec_STUDY_YOUTUBE.mkv
Use --screenRecordingDir to set a different directory of your choice.
You will find the name of the recording in the study.metadata.surfmeter.screenRecordingFilename field of the report.
For API use, the metadata field will be part of the study object to which all measurements from that run belong. The attribute will be called study.metadata.surfmeter.screen_recording_filename (note that it's in snake case because our server-side APIs use that).
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) |
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:
./surfmeter-automator-headless startStudy --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:
pactl load-module module-null-sink sink_name=loopback
pactl set-default-sink loopback
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.
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.