wf-recorder

Record storing to an MP4 file

$ wf-recorder [[-f|--file]] [output.mp4]

$ wf-recorder [[-a|--audio]] [[-f|--file]] /[path/to/file_with_audio.webm]

$ wf-recorder [[-g|--geometry]] "$(slurp)"

wf-recorder [options] output-file

-c, --codec <codec>
    Specifies the video codec to use (e.g., libx264, vp9, h264_nvenc).

-f, --file-format <format>
    Sets the output file container format (e.g., mp4, mkv, webm).

-g, --geometry <WxH+X+Y>
    Defines the region of the screen to record, e.g., 1920x1080+0+0 for a full HD screen starting at top-left.

-F, --framerate <fps>
    Sets the recording framerate in frames per second.

-D, --device <device>
    Specifies the audio input device to capture from (e.g., a PipeWire or PulseAudio source).

-a, --audio-codec <codec>
    Determines the audio codec for encoding (e.g., aac, opus, flac).

-b, --bitrate <bitrate>
    Sets the target video bitrate, e.g., 5M for 5 Mbit/s.

-x, --extra-opts <opts>
    Passes arbitrary extra options directly to the underlying FFmpeg process for input/output.

--raw
    Outputs a raw video stream without a container format.

--no-audio
    Disables audio recording entirely.

--no-pipewire
    Forces wf-recorder to not use PipeWire for audio capture.

--pipewire-node <node_id>
    Specifies a particular PipeWire node ID for audio input.

--pixel-format <fmt>
    Sets the pixel format for the encoded video (e.g., yuv420p).

--hw-accel <api>
    Enables hardware acceleration using a specified API (e.g., cuda, vaapi).

--preset <preset>
    Uses an encoding preset for the video codec (e.g., ultrafast, fast, medium) to balance speed and compression.

--crf <value>
    Sets the Constant Rate Factor for quality-based encoding, applicable to codecs like libx264.

--2-pass
    Enables two-pass encoding for better quality at a given bitrate.

--help
    Displays the help message and exits.

--version
    Shows version information and exits.

wf-recorder is a screen recording utility specifically designed for Wayland compositors that implement the wlroots protocol, such as Sway, Wayfire, and others. It aims to be lightweight and efficient, providing a simple way to capture video and audio from your Wayland session. Unlike traditional X11 screen recorders, wf-recorder leverages Wayland's direct rendering capabilities, often resulting in smoother captures and better performance.

It supports various video codecs and container formats, allowing users to choose settings that best suit their needs for quality and file size. Its primary use case is straightforward screen capture without the overhead of more complex broadcasting or streaming software, making it ideal for creating tutorials, demos, or simply recording desktop activity. A common usage example is: wf-recorder -g 1920x1080+0+0 -F 60 output.mp4

Caveats:
wf-recorder requires a wlroots-based Wayland compositor (e.g., Sway, Wayfire) to function.
It relies on FFmpeg for all encoding and muxing tasks, which must be installed and accessible.
Audio recording typically requires a correctly configured PipeWire or PulseAudio setup.
It lacks advanced features such as live streaming, overlays, or complex scene management found in tools like OBS Studio.
There is no built-in graphical user interface; it is a command-line utility.

wf-recorder primarily depends on FFmpeg for its core multimedia processing capabilities. For screen capture, it requires a wlroots-compatible Wayland compositor. Audio input typically relies on PipeWire or PulseAudio being correctly configured on the system.

For recording specific regions of the screen, wf-recorder is often used in conjunction with the slurp(1) utility. slurp allows users to interactively select a rectangular area, and its output (geometry string) can be piped directly into wf-recorder. An example command is: slurp | wf-recorder -g $(cat) output.mp4

wf-recorder originated within the Wayfire project, a 3D Wayland compositor, to address the need for a simple, native screen recording tool specifically for wlroots-based Wayland environments. It was developed to fill a gap left by X11-centric recording solutions, aiming for efficient and direct integration with the Wayland ecosystem. Leveraging FFmpeg as its robust backend, it supports a wide array of audio and video codecs and container formats. Its ongoing development is community-driven, emphasizing a lightweight footprint and seamless operation within the Wayland desktop experience.

ffmpeg(1), grim(1), slurp(1), sway(1), wlroots(7)