> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-rec

> Record your Wayland screen with hardware acceleration. Toggle with a hotkey, capture regions or windows, encode with NVENC, QSV, or VAAPI.

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.

```bash theme={null}
otter-rec                                             # toggle recording (start/stop)
otter-rec --output recording.mp4                      # specify output file
otter-rec --output ~/Videos/clip-YYYY-MM-DD-HH-MM-SS.mp4  # expand timestamp token
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 --source screen --output screen.mp4         # fullscreen capture
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](/apps/otter-screenshot) and [otter-shot](/apps/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.

| GPU vendor | Primary encoder family                               |
| ---------- | ---------------------------------------------------- |
| NVIDIA     | NVENC (`h264_nvenc`, `hevc_nvenc`, `av1_nvenc`)      |
| Intel      | Quick Sync / QSV (`h264_qsv`, `hevc_qsv`, `av1_qsv`) |
| AMD        | VAAPI (`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.

<Note>
  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.
</Note>

## Configuration

otter-rec reads `~/.config/otter-shell/otter-rec.conf` on startup.

```conf theme={null}
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`. 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

<Tip>
  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.
</Tip>

## 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.

<Note>
  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.
</Note>