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. 
otter-rec                                             # toggle recording (start/stop)
otter-rec --output recording.mp4                      # specify output file
otter-rec --region select --output region.mp4         # interactive region selection
otter-rec --region X,Y,W,H                            # fixed region (global logical coordinates)
otter-rec --window active --output window.mp4         # capture the active window
otter-rec --hevc                                      # encode with HEVC instead of H.264
otter-rec --av1                                       # encode with AV1
otter-rec --portal --source screen --output out.mp4   # force xdg-desktop-portal source picker
otter-rec --dry-run --source screen --output out.mp4  # print resolved settings, do not record
--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.

​
Hardware Encoding

otter-rec probes your GPU at startup and selects the best available hardware encoder.
GPU vendorPrimary encoder family
NVIDIANVENC (h264_nvenc, hevc_nvenc, av1_nvenc)
IntelQuick Sync / QSV (h264_qsv, hevc_qsv, av1_qsv)
AMDVAAPI (h264_vaapi, hevc_vaapi, av1_vaapi)
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 = ""
source = ""
mode = "region"
codec = "h264"
force_portal = false
fps = 30
seconds = 0
bitrate = 12000000
  • output: destination file path. Empty writes to ~/Videos/YYYY-MM-DD-HH-MM-SS.mp4
  • source: capture source hint for encoder path selection
  • mode: fullscreen, region, or window
  • 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.