wf-recorder

To record audio simultaneously with the screen, use the --audio flag. You can also specify a specific audio device or audio codec.

• --audio: Enable audio recording.
• -a<device> or --audio=<device>: Specify the audio device.
• -C <codec> or --audio-codec <codec>: Specify the audio codec.

To find available audio codecs on your system, use:

ffmpeg -hide_banner -encoders | grep -E '^ A' | grep -F '(codec' | cut -c 8- | sort

You can control the video encoding quality and format using the following flags:

• -c <codec>: Specify the video codec.
• -p <option_name>=<option_value>: Modify specific codec parameters.
• --muxer <muxer>: Set a specific output format (muxer).

To find available video codecs on your system, use:

ffmpeg -hide_banner -encoders | grep -E '^ V' | grep -F '(codec' | cut -c 8- | sort

Selecting Outputs

If your system has multiple outputs, wf-recorder will prompt you to select one. To bypass the prompt, use:

• -o <output name>: Specify the output name directly.
• -L or --list-output: List all available output options.

Selecting Screen Areas

To record a specific part of the screen:

• -g <geometry>: Specify a geometry string.
• Interactive selection: Use slurp to select an area with your mouse.

# Interactive area selection using slurp
wf-recorder -g "$(slurp)"

You can install wf-recorder using the package manager of your distribution:

• Alpine: apk add wf-recorder
• Arch / Artix: pacman -S wf-recorder
• Debian: apt install wf-recorder
• Fedora: dnf install wf-recorder
• Gentoo: Available in the official ::gentoo repository
• NixOS / Nix: Add wf-recorder to configuration or run nix-shell -p wf-recorder, nix shell nixpkgs#wfrecorder, or nix run nixpkgs#wf-recorder
• Void: xbps-install -S wf-recorder

To use GPU encoding via VAAPI, select a VAAPI codec (e.g., h264_vaapi) and specify the GPU device using the -d option.

Note on Pixel Formats: Some drivers claim to support rgb0 for VAAPI but only actually support yuv planar formats. If you encounter issues, force the pixel format using -x <format> or --pixel-format <format> (e.g., yuv420p) to convert the data before it reaches the GPU.

# Standard VAAPI recording
wf-recorder -f test-vaapi.mkv -c h264_vaapi -d /dev/dri/renderD128

# VAAPI recording with forced yuv420p pixel format
wf-recorder -f test-vaapi.mkv -c h264_vaapi -d /dev/dri/renderD128 -x yuv420p

When using the vaapi codec, wf-recorder can attempt to enable DMA-BUF capture for high-performance recording.

• Automatic Detection: If the vaapi codec is detected, the tool tries to enable DMA-BUF capture using the same DRM device as the compositor.
• Manual Override: If DMA-BUF causes issues, you can force it off using the & flag.
• Hardware Device: You can specify a specific hardware device if the automatic detection fails or if the compositor is running on a different device.
• Requirements: Using DMA-BUF with region capture may require wlroots >= 0.17.

Overview

wf-recorder is a screen recording tool designed for wlroots-based compositors. It can record the entire screen, specific outputs, or specific regions of the screen. It supports video-only or video-and-audio recording.

Basic Usage

Record the current screen (video only): By default, this saves to recording.mp4 in the current directory.

wf-recorder

Record to a specific file: The file format is determined by the extension provided.

wf-recorder -f my_recording.mkv

Record video and audio:

wf-recorder -a

Record video and audio to a specific file:

wf-recorder -a -f my_recording.mp4

Stopping a recording

Use Ctrl+C to stop the recording gracefully.

To start a simple recording, run wf-recorder. Press Ctrl+C to stop the recording. By default, this creates a file named recording.mp4 in the current directory using the default codec.

To specify a different output filename, use the -f <filename> flag.

When interacting with the audio subsystem, use the AudioReaderParams struct to define the properties of the audio source.

Key fields include:

• audio_frame_size: The size of the audio frames.
• sample_rate: The sampling rate of the audio.
• audio_source: A pointer to the audio source string (can be NULL).
• audio_backend: A string specifying the backend to use (defaults to DEFAULT_AUDIO_BACKEND).

struct AudioReaderParams
{
    size_t audio_frame_size;
    uint32_t sample_rate;
    /* Can be NULL */
    char *audio_source;

    std::string audio_backend = DEFAULT_AUDIO_BACKEND;
};

To see which outputs (monitors/screens) are available for recording, use the -L or --list-output flag. This is useful when you want to target a specific monitor using the -o flag or define a geometry that corresponds to a specific output.

wf-recorder -L