GPU-SCREEN-RECORDER(1)

📦
version 6.1.6 · 2 versions
, in arch rolling, nixpkgs unstable

🎀 GPU-SCREEN-RECORDER(1) 🎀

okay bestie, welcome to the GPU Screen Recorder Manual — yes, that’s the manual name, and yes, we’re about to make screen recording make sense. 💖

✨ NAME ✨

gpu-screen-recorder — the fastest screen recording tool for Linux. That’s the whole name section, and honestly? Iconic. Periodt.

🌈 SYNOPSIS 🌈

gpu-screen-recorder -w window_id|monitor|focused|portal|region|v4l2_device_path [options] -o output_file

gpu-screen-recorder --help | --version | --info | --list-capture-options | --list-monitors | --list-v4l2-devices | --list-audio-devices | --list-application-audio

💫 DESCRIPTION 💫

okay so gpu-screen-recorder is literally the fastest screen recording tool for Linux. It uses the GPU only to record the screen to minimize system performance impact. It supports recording, live streaming, instant replay (similar to NVIDIA ShadowPlay), and screenshot capture. The tool works on both X11 and Wayland with AMD, Intel, and NVIDIA graphics cards.

Key features include:

  • GPU-accelerated encoding using H264, HEVC, AV1, VP8, or VP9 codecs
  • Support for HDR recording (HEVC HDR and AV1 HDR)
  • Instant replay buffer (last N seconds recording)
  • Live streaming capabilities
  • Audio recording from devices and applications (PipeWire required for app audio)
  • Plugin system for custom graphics overlay
  • Minimal performance impact compared to traditional screen recorders

💅 OPTIONS 💅

🎥 Capture Options 🎥

  • -w window_id|monitor|focused|portal|region|v4l2_device_path — specify what to record. This option is optional. When it’s not used then -a is required and only audio is recorded, for example: gpu-screen-recorder -a default_output -o audio.mp3. Audio-only recording doesn’t support replay mode (-r and -ro).

Formats:

  • window — record a specific window (use the window ID) (X11 only).
  • screen — record the first monitor found.
  • screen-direct — NVIDIA X11 only, for VRR/G-SYNC support (not recommended due to driver issues).
  • focused — record the currently focused window (X11 only) (use with -s option).
  • portal — use xdg-desktop-portal with PipeWire (Wayland only).
  • region — record a specific region (use with -region option).
  • Monitor name (e.g., DP-1) — record specific monitor.
  • V4L2 device path (e.g., /dev/video0) — record camera device (V4L2).

Other applications can’t use the camera when GPU Screen Recorder is using the camera and GPU Screen Recorder may not be able to use the camera if another application is already using the camera.

  • Combine sources with | (e.g., monitor:screen|v4l2:/dev/video0).

Run --list-capture-options to list available capture sources.

Additional options can be passed to each capture source by splitting the capture source with ; for example screen;x=50;y=50. These are the available options for all capture sources (optional):

  • x — The X position in pixels. If the number ends with % then this sets the X position relative to the video width (integer percentage where 100 = 100%).
  • y — The Y position in pixels. If the number ends with % then this sets the Y position relative to the video height (integer percentage where 100 = 100%).
  • width — The width in pixels. If the number ends with % then this sets the width relative to the video width (integer percentage where 100 = 100%).

A value of 0 means to not scale the capture source and instead use the original width.

  • height — The height in pixels. If the number ends with % then this sets the height relative to the video height (integer percentage where 100 = 100%).

A value of 0 means to not scale the capture source and instead use the original height.

  • halign — The horizontal alignment, should be either start, center or end.

Set to center by default when using one capture source, otherwise it’s set to start by default.

  • valign — The vertical alignment, should be either start, center or end.

Set to center by default when using one capture source, otherwise it’s set to start by default.

  • hflip — If the source should be flipped horizontally, should be either true or false. Set to false by default.
  • vflip — If the source should be flipped vertically, should be either true or false. Set to false by default.

These are the additional options available for camera (V4L2) sources (optional):

  • pixfmt — The pixel format, should be either auto, yuyv or mjpeg. Set to auto by default.
  • camera_fps — The camera fps. Has to match a camera fps returned in --info or --list-v4l2-devices for the device.

A value of 0 means to use the best option available.

  • camera_width — The camera width in pixels. Has to match a camera width returned in --info or --list-v4l2-devices for the device.

A value of 0 means to use the best option available.

  • camera_height — The camera height in pixels. Has to match a camera height returned in --info or --list-v4l2-devices for the device.

A value of 0 means to use the best option available.

  • -region WxH+X+Y — specify region to capture when using -w region. Format is width x height + X offset + Y offset. Set width and height to 0 to capture the whole monitor that contains the position.

It is compatible with tools such as slop (X11) and slurp (Wayland).

  • -c container_format — container format (mp4, mkv, flv, webm, mp3). Defaults to extension from -o filename. The mp3 container holds audio only and can only be used when recording without the -w option.

With FFmpeg 8.1 or later .mp4 and .mov files are recorded in hybrid fragmented mode, which means that the video file is still playable if the system crashes or if GPU Screen Recorder is killed while recording, just like .mkv files. The file is converted into a regular non-fragmented file when the recording is stopped, so it stays compatible with software that doesn’t support fragmented mp4 files. GPU Screen Recorder shows a warning when recording to .mp4 or .mov with an older FFmpeg version, in which case the video file is unplayable if the recording is not stopped properly.

  • -s WxH — output resolution limit (e.g., 1920x1080). The captured content is scaled to fit within this resolution while keeping its aspect ratio and the video size shrinks to fit the scaled content. Use 0x0 for original resolution. Required for -w focused (where the video is exactly this resolution).
  • -f fps — frame rate (default: 60). For variable frame rate mode, this is maximum FPS.
  • -cursor yes|no — record cursor (default: yes).
  • -restore-portal-session yes|no — restore previous portal session (used with -w portal option, default: no).

🎧 Audio Options 🎧

  • -a audio_source — audio device or application to record. Can be specified multiple times. Formats:
    • default_output — default output device
    • default_input — default input device
    • device:name — specific device
    • app:name — application audio (case-insensitive)
    • app-inverse:name — all applications except specified
    • Combine sources with | (e.g., default_output|app:firefox)

Run --list-audio-devices to list available audio devices. Run --list-application-audio to list available applications for audio capture.

  • -ac aac|opus|flac|mp3 — audio codec (default: opus for mp4/mkv, aac otherwise). FLAC temporarily disabled. .mp3 files always use the mp3 audio codec. The mp3 audio codec requires FFmpeg to be built with libmp3lame.
  • -ab bitrate — audio bitrate in kbps (default: 128 for opus/flac, 160 for aac, 192 for mp3). 0 = automatic.

🔥 Video Quality Options 🔥

  • -k codec — video codec: auto, h264, hevc, av1, vp8, vp9, hevc_hdr, av1_hdr, hevc_10bit, av1_10bit, h264_vulkan, hevc_vulkan, hevc_10bit_vulkan, av1_vulkan, av1_hdr_vulkan, av1_10bit_vulkan.

HDR options not available on X11 or portal capture. 10-bit capture reduces banding but may not be supported properly by all video players. Vulkan codec options are experimental. They may not work properly on your system because of GPU driver issues. Using vulkan codecs may result in better gaming performance with older NVIDIA gpu drivers, as vulkan video encoding doesn’t suffer from an issue known as "cuda p2 state" where the GPU gets downclocked when using nvenc (regular video codecs on NVIDIA).

(default: auto → h264).

  • -q quality — quality preset (medium, high, very_high, ultra) for QP/VBR mode, or bitrate (kbps) for CBR mode (default: very_high).
  • -bm auto|qp|vbr|cbr — bitrate mode (default: auto → qp). CBR recommended for replay buffer and live streaming.

QP means to capture with constant quality, even in motion, while VBR and CBR means to capture with constant size.

  • -fm cfr|vfr|content — frame rate mode: cfr (constant), vfr (variable), or content (match content) (default: vfr). Content mode is only available on X11 or portal capture.

Content mode (-fm content) syncs video to the captured content and is recommended for smoothest video when the game is running at the same frame rate or lower than what you are trying to record at.

Constant framerate mode (-fm cfr) ensures that the framerate of the video is constant throughout the video, as set by the -f option. This might be needed by some video editors. This option is not recommended because for example if you’re trying to record at 60 fps and you play a heavy game and the game runs at below 60 fps, then the recording may capture at that framerate as well, which will overload the encoder and it may end up recording at 1-2 fps instead and may not be able to recover. Try recording to a mkv file instead in that case in variable framerate mode (-fm vfr), as Kdenlive supports variable framerate videos if they are in mkv files.

  • -cr limited|full — color range, and the default is limited. 💅 Heads up bestie: full range can get messy with some video players and websites, so pick it with intention.
  • -tune performance|quality — encoding tune, default performance ✨. Currently NVIDIA only, iykyk.
  • -keyint seconds — keyframe interval in seconds, default 2.0. This one controls how precise your seeking is, so tweak it if scrubbing matters to you 🎀.
  • -encoder gpu|cpu — which device does the encoding, default gpu. CPU encoding is only a thing for H264, no cap.
  • -fallback-cpu-encoding yes|no — fall back to CPU if GPU encoding isn't available. Default no. 🫶

🎀 Replay Buffer Options 🎀

  • -r seconds — replay buffer duration, valid range is 2-86400 seconds. When you set this, it only saves on command — like, it's not out here saving on its own 💀.
  • -replay-storage ram|disk — where the buffer lives, default ram. Disk mode may reduce your SSD's lifespan, so know that going in 😭.
  • -restart-replay-on-save yes|no — clear the buffer after saving a replay, default no.
  • -df yes|no — organize your replays into date-based folders, default no. Cute and tidy 🌸.

🔥 Advanced Options 🔥

  • -p plugin.so — load a plugin (.so file). You can specify it multiple times, stack 'em up 💜.
  • -sc script_path — a script to run after saving a video. It receives the filepath and the type, where type is "regular", "replay", or "screenshot" 👑.
  • -portal-session-token-filepath path — the portal session token file. Default is ~/.config/gpu-screen-recorder/restore_token.
  • -ffmpeg-opts options — extra arguments passed to FFmpeg for the file, given as a list of key-value pairs in the format "key=value;key=value". Example time:
-ffmpeg-opts "hls_list_size=3;hls_time=1;hls_flags=delete_segments"
Note: this overwrites options set by GPU Screen Recorder with the same name. So like, it wins. 🫣
  • -ffmpeg-video-opts options — same deal but for the video specifically, key-value pairs in "key=value;key=value" format. Example:
-ffmpeg-video-opts "codec=cabac;rc_mode=CQP;qp=16"
Note: this overwrites options set by GPU Screen Recorder with the same name.
  • -ffmpeg-audio-opts options — same deal but for the audio, key-value pairs in "key=value;key=value" format. Example:
-ffmpeg-audio-opts "aac_coder=fast;aac_pce=true"
Note: this overwrites options set by GPU Screen Recorder with the same name.
  • -auth token — the optional bearer token for authorization when streaming, like when you're using the whip protocol (-c whip). For servers with username/password authentication, the token can be set to "username:password". Whip streaming requires FFmpeg version 8.0 or later, fyi. ✨ You can alternatively provide the token in the GSR_AUTH environment variable to keep it out of the process command line — and the -auth option takes precedence over the environment variable. When streaming with whip, the muxer option ts_buffer_size is set to 4194304 by default, and you can override it with -ffmpeg-opts "ts_buffer_size=<value>". The kernel silently caps the buffer at the net.core.wmem_max sysctl (usually only ~208kb 😭). If whip streaming stops with "UDP send blocked" errors then raise it, for example:
sysctl -w net.core.wmem_max=8388608
  • -gl-debug yes|no — OpenGL debug output, default no.
  • -v yes|no — print FPS and damage info, default yes 💅.
  • -low-power yes|no — run in low power mode. This currently only has an affect on AMD (because it's only an issue on AMD) and lets the GPU go into a lower power mode when recording, default no. Setting it to yes might not always be ideal because of AMD driver issues where, after playing a video with VAAPI on the system, the video encoding performance also reduces — which affects GPU Screen Recorder 🙈. It's recommended to also use the option -fm content when this is set to yes, so it only encodes frames when the screen content updates, which lowers GPU and video encoding usage when the system is idle. Iconic combo, honestly 🌈.
  • -exclude-metadata yes|no — exclude personal metadata from the video file, like the audio track title that's composed from the name of the audio device by default. Default no. Protect your vibe 🫶.
  • -write-first-frame-ts yes|no — when enabled, writes a timestamp file with the extra extension .ts next to the output video, containing:
monotonic_microsec  realtime_microsec
<monotonic_microsec>     <realtime_microsec>

Default no. Ignored for live streaming and when the output is piped, fyi.

  • -ipc socket_path — listen for commands on a unix domain socket at socket_path instead of only accepting signals. The socket is created when GPU Screen Recorder starts and removed when it exits. See the IPC section for the protocol 💖. Has no effect when taking a screenshot.

🌸 Output Options 🌸

  • -o output — output file path (or a directory for replay mode). Required, except when you're outputting to stdout. Don't forget it bestie 😭.
  • -ro directory — output directory for regular recordings during replay/streaming mode.

⭐ Information Commands ⭐

  • --help — show help message.
  • --version — show version (5.10.2).
  • --info — show system info (codecs, capture options).
Note that this command can be slow on some systems 😴. It's recommended in applications that you use it once to list supported video codecs, and then use --list-capture-options or --list-monitors, which is faster. Work smarter, not harder ✨.
  • --list-capture-options — list available capture sources (window, monitors, portal, v4l2 device path).
  • --list-monitors — list available monitors.
  • --list-v4l2-devices — list available cameras devices (V4L2).
  • --list-audio-devices — list available audio devices.
  • --list-application-audio — list available applications for audio capture.

💀 SIGNALS 💀

GPU Screen Recorder can be controlled via signals, and honestly it's giving main character energy:

  • SIGINT (Ctrl+C) — stop and save recording (stop without save in replay mode).
  • SIGUSR1 — save replay (replay mode only).
  • SIGUSR2 — pause/unpause recording (not for streaming/replay).
  • SIGRTMIN — start/stop regular recording during replay/streaming.
  • SIGRTMIN+1 — save last 10 seconds (replay mode).
  • SIGRTMIN+2 — save last 30 seconds (replay mode).
  • SIGRTMIN+3 — save last 60 seconds (replay mode).
  • SIGRTMIN+4 — save last 5 minutes (replay mode).
  • SIGRTMIN+5 — save last 10 minutes (replay mode).
  • SIGRTMIN+6 — save last 30 minutes (replay mode).

Use pkill to send signals, like:

pkill -SIGUSR1 -f "^gpu-screen-recorder"

🦋 IPC 🦋

When you use the -ipc option, GPU Screen Recorder also listens for commands on a unix domain socket. This gives you the same control as signals, except that a replay can be saved with an arbitrary number of seconds 😌. The socket can only be used by the user that started GPU Screen Recorder, and it's removed when GPU Screen Recorder exits.

gsr-cli(1) is a program that sends these commands and reports the reply, so the protocol below only has to be implemented by programs that want to talk to the socket directly. iykyk 💅

Requests and replies are json objects terminated by a newline. Every request is replied to, no ghosting 👑.

A request has these fields:

  • id — number that identifies the request. The reply to the request has the same id.
  • name — string with the name of the request.
  • data — optional, the type depends on the request.

A reply has these fields:

  • id — the id of the request that this is a reply to, or 0 when the request had no valid id.
  • result — either ok or error.
  • data — optional. For an error result this is a string that describes what went wrong. For an ok result to stop, save-replay or stop-replay-recording this is a string with the path of the saved file.

The stop, save-replay and stop-replay-recording requests save a file, and they are replied to when the file has been saved and the script given with the -sc option has been started. The other requests are replied to as soon as they are accepted ✨.

These requests are available:

  • stop — stop and save recording (stop without save in replay mode). The reply contains the path of the saved file, except in replay mode where nothing is saved.
  • save-replay — save replay (replay mode only). data is an object with these optional fields:
    • seconds — the number of seconds to save, which has to be larger than 0.
    • restart-replay — true/false, which overrides the -restart-replay-on-save option for this save. Just like that option, the replay buffer is only cleared when the whole replay buffer is saved.

The whole replay buffer is saved when data is omitted or null, or when seconds is omitted or null. The reply contains the path of the saved file 💖.

  • toggle-pause — pause/unpause recording (not for streaming/replay).
  • set-paused — pause/unpause recording (not for streaming/replay). data has to be true to pause or false to unpause. Unlike toggle-pause this doesn't fail when the recording is already paused/unpaused 🫶.
  • toggle-replay-recording — start/stop regular recording during replay/streaming, which requires the -ro option.
  • start-replay-recording — start regular recording during replay/streaming, which requires the -ro option. Does nothing when a recording is already running.
  • stop-replay-recording — stop the regular recording that runs during replay/streaming. Fails when no recording is running. The reply contains the path of the saved file.

Example:

gpu-screen-recorder -w screen -f 60 -c mp4 -r 60 -o ~/Videos -ipc "$XDG_RUNTIME_DIR/gsr.sock" &
echo '{"id":1,"name":"save-replay","data":{"seconds":30}}' | socat - "UNIX-CONNECT:$XDG_RUNTIME_DIR/gsr.sock"

which replies with the following when the replay has been saved:

{"id":1,"result":"ok","data":"/home/user/Videos/Replay_2026-08-05_14-04-22.mp4"}

✨ EXAMPLES ✨

okay bestie, this is the copy-paste buffet — every command below is exactly the vibe you need, no cap 💅

Record monitor at 60 FPS with desktop audio — the classic main-character recording setup 🎀

gpu-screen-recorder -w screen -f 60 -a default_output -o video.mp4

Record monitor at 60 FPS with desktop audio and microphone — now you can hear yourself being iconic 🎤✨

gpu-screen-recorder -w screen -f 60 -a "default_output|default_input" -o video.mp4

Record specific window (X11 only) — pick one window like you're choosing your fave child 👑

gpu-screen-recorder -w $(xdotool selectwindow) -f 60 -o video.mp4

Record desktop audio only, without video — audio-only era, lowkey a mood 🎧

gpu-screen-recorder -a default_output -o audio.mp3

Instant replay (last 60 seconds) — the "wait what just happened" button, but make it useful 🌀

gpu-screen-recorder -w screen -c mp4 -r 60 -o ~/Videos

Instant replay with constant framerate (recommended for predictable RAM usage) — this one's giving responsible queen behavior 🧚

gpu-screen-recorder -w screen -c mp4 -r 60 -bm cbr -q 40000 -o ~/Videos

Record region using slop — crop the chaos, select the moment 🪄

gpu-screen-recorder -w $(slop) -o video.mp4

Record region using slurp — another region-selector bestie, we love options 💖

gpu-screen-recorder -w $(slurp -f "%wx%h+%x+%y") -o video.mp4

Instant replay and launch a script when saving replay — replay buffer plus a little automation moment ✨

gpu-screen-recorder -w screen -c mp4 -r 60 -sc ./script.sh -o ~/Videos

Stream to Twitch with constant bitrate mode — go live, bestie, the timeline needs you 🔴

gpu-screen-recorder -w screen -c flv -a default_output -bm cbr -q 8000 -o "rtmp://live.twitch.tv/app/stream_key"

Take screenshot — one frame, served fresh 📸

gpu-screen-recorder -w screen -o screenshot.jpg

Record screen and camera — face cam and desktop, both main characters 🫶

gpu-screen-recorder -w "screen|/dev/video0" -o video.mp4

Record screen and camera. The camera is located at the bottom right and flipped horizontally — tiny flipped cam, absolutely iconic placement 💅

gpu-screen-recorder -w "screen|/dev/video0;halign=end;valign=end;hflip=true;width=30%;height=30%" -o video.mp4

Record two monitors, side by side (assuming the first monitor has a resolution of 1920x1080) — dual-monitor supremacy 🌈

gpu-screen-recorder -w "DP-1|DP-2;x=1920" -o video.mp4

Stream whip with an authorization key — whip it, whip it real good, with -auth "streamtest" in the mix 🍓

gpu-screen-recorder -w screen -bm cbr -q 3500 -auth "streamtest" -c whip -o https://b.siobud.com/api/whip

🎀 FILES 🎀

  • ~/.config/gpu-screen-recorder/gpu-screen-recorder.env — Environment variables for systemd service (optional).
  • /usr/lib/modprobe.d/gsr-nvidia.conf — NVIDIA suspend/resume fix.
  • ~/.config/gpu-screen-recorder/restore_token — Portal session token storage (default location).

🌸 TIPS 🌸

  • Some video editors don't support videos in variable frame rate mode. Change video container to .mkv or capture in constant frame rate mode instead to workaround this issue.
  • .mp4, .mov and .mkv files are still playable if the system crashes while recording (FFmpeg 8.1 or later is required for .mp4 and .mov).
  • Variable frame rate may cause issues in some video players (use MPV).
  • H.265/HEVC not supported in browsers/Discord (use H264 for sharing).
  • Some distros disable hardware codecs (use Flatpak version).
  • Use CBR mode (-bm cbr) for replay buffer to control RAM usage.

🔥 PERFORMANCE TIPS 🔥

  • Save to SSD (HDD may be too slow).
  • Close other screen recorders (including idle OBS).

💀 KNOWN ISSUES 💀

  • NVIDIA: CUDA breaks after suspend (install gsr-nvidia.conf fix).
  • AMD: Possible black bars in output video with HEVC/AV1 (use H264 or FFmpeg >=8).

🫶 AUTHORS 🫶

Developed by dec05eba and contributors.

📬 REPORTING BUGS 📬

Report bugs to: dec05eba@protonmail.com.

See more information about reporting bugs at the gpu-screen-recorder website: https://git.de05eba.com/?p=about.

Please take a look at the FAQ part of the README before reporting a bug: https://git.de05eba.com/gpu-screen-recorder/about.

The bug may have been previously reported or may not be related to gpu-screen-recorder (such as a driver issue).

Copyright © dec05eba. Licensed under GPL-3.0-only.

🌈 SEE ALSO 🌈

and that's the whole page, bestie — gpu-screen-recorder version 6.1.5, dated 2026-10-22. now go record something iconic ✨💅

📦 where this page comes from