Skip to main content
otter-rec is Otter Shell’s screen recorder. Run it once to start, run it 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 needed. Default output is ~/Videos/YYYY-MM-DD-HH-MM-SS.mp4. Override 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.

​
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.
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
  • bitrate: target bitrate in bits per second (default 12000000, 12 Mbps)

​
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 force an xdg-desktop-portal ScreenCast session before recording. The portal presents its own source picker (screen, window, or region, depending on your compositor). otter-rec records through its own in-process capture and encoder path once the session is established. 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.