Skip to main content
otter-rec records your Wayland screen. Run it once to start, then again to stop and save. At startup it probes your GPU and picks the fastest hardware encoder: NVENC on NVIDIA, Quick Sync on Intel, VAAPI on AMD. It falls back to software when hardware encoding is unavailable. The default output is ~/Videos/YYYY-MM-DD-HH-MM-SS.mp4. Override it with --output or the config file.

​
Basic usage

otter-rec is a toggle. One invocation starts recording, the next stops it.
--region select opens the same drag-to-select UI as otter-screenshot and otter-shot. Drag a rectangle, or pass --region X,Y,W,H for fixed global logical coordinates. --window active captures the focused window through ext_foreign_toplevel_image_capture_source_manager_v1. --source screen selects fullscreen. CLI capture selectors override the configured mode; when you pass more than one, the last one wins. YYYY-MM-DD-HH-MM-SS in a configured or CLI --output path expands to the local start time.

​
Audio

Recordings include system output by default, using the PipeWire default sink monitor. otter-rec captures 48 kHz stereo audio and muxes 128 kbit/s AAC into the output file in process, without calling ffmpeg. Use --audio-source microphone to record the default input instead, --no-audio for video only, or --audio to override a disabled audio config. There is no individual device selector. Portal recording uses separate PipeWire connections for video and audio because the ScreenCast portal only supplies video nodes. If audio cannot start, recording continues with video only.

​
Hardware encoding

otter-rec probes your GPU at startup and selects the best available hardware encoder. Within whichever family is selected, H.264 is preferred by default. Pass --hevc for HEVC, or --av1 for AV1. Both flags work for any vendor. Native output and region capture converts PQ HDR to SDR when the capture metadata identifies it. NVIDIA’s KMS path performs the conversion on the GPU. Portal and window streams without HDR metadata are not automatically treated as HDR.
Hardware encoders come from your distribution’s FFmpeg packages. Make sure libavcodec, libavformat, libavutil, and libswscale are installed and built with the encoder backends you need.

​
Configuration

otter-rec reads ~/.config/otter-shell/otter-rec.conf on startup.
  • output: destination file path. Empty writes to ~/Videos/YYYY-MM-DD-HH-MM-SS.mp4. The YYYY-MM-DD-HH-MM-SS token expands to the local start time
  • source: capture source hint for encoder path selection
  • mode: fullscreen, region, or window (CLI --region, --window, and --source override this; last selector wins)
  • codec: h264, hevc, or av1
  • force_portal: true always uses xdg-desktop-portal source selection (same as --portal)
  • fps: target frame rate (default 30)
  • seconds: fixed duration in seconds; 0 records until stopped
  • rate_control: crf for constant quality (default), or bitrate for a target bitrate
  • crf: quality from 0 to 51; lower is higher quality (default 20). Settings shows a Quality slider
  • bitrate: ceiling in CRF mode or target in bitrate mode, in bits per second (default 8500000, 8.5 Mbps)
  • audio: include audio (default true)
  • audio_source: system for desktop output (default), or microphone for the default input
CLI quality controls are --rate-control crf|bitrate, --crf N, and --bitrate N.

​
Hotkey setup

Bind otter-rec to a compositor keyboard shortcut for a global recording toggle. Press once to start, press again to stop. No UI required. Most Wayland compositors let you assign any shell command to a key combination in their shortcuts settings.

​
Portal mode

Pass --portal to record the PipeWire video stream selected through an xdg-desktop-portal ScreenCast session. The portal presents its own source picker, depending on the backend and compositor. Otter’s in-process encoder records that stream; the recorder itself does not need image-copy-capture protocols in portal mode. Portal detection checks for a live Wayland socket, PipeWire and session bus sockets in the runtime directory, then verifies org.freedesktop.portal.ScreenCast.version before proceeding. Set force_portal = true in the config file to make portal mode the default.
otter-rec uses only Wayland capture paths. X11 is not supported. If you are running under XWayland, make sure your compositor exposes the required Wayland protocols.