Add man page

Thanks Seyed.

1 files changed, 402 insertions, 0 deletions

diff --git a/gpu-screen-recorder.1 b/gpu-screen-recorder.1
new file mode 100644
index 0000000..e8873ce
--- /dev/null
+++ b/gpu-screen-recorder.1
@@ -0,0 +1,402 @@
+.TH GPU-SCREEN-RECORDER 1 "2025-12-22" "5.10.2" "GPU Screen Recorder Manual"
+.SH NAME
+gpu-screen-recorder \- The fastest screen recording tool for Linux
+.SH SYNOPSIS
+.B gpu-screen-recorder
+.RI [ options ]
+.B \-w
+.I window_id|monitor|focused|portal|region
+.RI [ options ]
+.B \-o
+.I output_file
+.PP
+.B gpu-screen-recorder
+.B \-\-help
+|
+.B \-\-version
+|
+.B \-\-list\-capture\-options
+|
+.B \-\-list\-audio\-devices
+|
+.B \-\-list\-application\-audio
+|
+.B \-\-info
+.SH DESCRIPTION
+.B gpu-screen-recorder
+is 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.
+.PP
+Key features include:
+.RS
+.IP \(bu 3
+GPU-accelerated encoding using H264, HEVC, AV1, VP8, or VP9 codecs
+.IP \(bu 3
+Support for HDR recording (HEVC HDR and AV1 HDR)
+.IP \(bu 3
+Instant replay buffer (last N seconds recording)
+.IP \(bu 3
+Live streaming capabilities
+.IP \(bu 3
+Audio recording from devices and applications (PipeWire required for app audio)
+.IP \(bu 3
+Plugin system for custom graphics overlay
+.IP \(bu 3
+Minimal performance impact compared to traditional screen recorders
+.RE
+.SH OPTIONS
+.SS Capture Options
+.TP
+.BI \-w " window_id|monitor|focused|portal|region"
+Specify what to record. Valid values are:
+.RS
+.IP \(bu 3
+.B window
+- Record a specific window (use window ID, X11 only)
+.IP \(bu 3
+.B screen
+- Record the first monitor found
+.IP \(bu 3
+.B screen\-direct
+- NVIDIA X11 only, for VRR/G-SYNC support (not recommended due to driver issues)
+.IP \(bu 3
+.B focused
+- Record the currently focused window (X11 only)
+.IP \(bu 3
+.B portal
+- Use xdg-desktop-portal with PipeWire (Wayland only)
+.IP \(bu 3
+.B region
+- Record a specific region (use with
+.B \-region
+option)
+.IP \(bu 3
+Monitor name (e.g.,
+.BR DP\-1 )
+- Record specific monitor
+.RE
+Run
+.B \-\-list\-capture\-options
+to see available options.
+.TP
+.BI \-region " WxH+X+Y"
+Specify region to capture when using
+.BR \-w " region."
+Format is width x height + X offset + Y offset. Use 0x0 for full monitor.
+
+It is compatible with tools such as slop (X11) and slurp (Wayland).
+.TP
+.BI \-c " container_format"
+Container format (mp4, mkv, flv, webm). Defaults to extension from
+.B \-o
+filename.
+.TP
+.BI \-s " WxH"
+Output resolution limit (e.g., 1920x1080). Use 0x0 for original resolution.
+Required for
+.BR \-w " focused."
+.TP
+.BI \-f " fps"
+Frame rate (default: 60). For variable frame rate mode, this is maximum FPS.
+.TP
+.BI \-cursor " yes|no"
+Record cursor (default: yes).
+.SS Audio Options
+.TP
+.BI \-a " audio_source"
+Audio device or application to record. Can be specified multiple times.
+Formats:
+.RS
+.IP \(bu 3
+.B default_output
+- Default output device
+.IP \(bu 3
+.B default_input
+- Default input device
+.IP \(bu 3
+.B device:name
+- Specific device
+.IP \(bu 3
+.B app:name
+- Application audio (case-insensitive)
+.IP \(bu 3
+.B app\-inverse:name
+- All applications except specified
+.IP \(bu 3
+Combine sources with | (e.g.,
+.BR "default_output|app:firefox" )
+.RE
+.TP
+.BI \-ac " aac|opus|flac"
+Audio codec (default: opus for mp4/mkv, aac otherwise). FLAC temporarily disabled.
+.TP
+.BI \-ab " bitrate"
+Audio bitrate in kbps (default: 128 for opus/flac, 160 for aac). 0 = automatic.
+.SS Video Quality Options
+.TP
+.BI \-k " codec"
+Video codec:
+.BR auto ", " h264 ", " hevc ", " av1 ", " vp8 ", " vp9 ", " hevc_hdr ", " av1_hdr ", " hevc_10bit ", " av1_10bit
+(default: auto → h264). HDR options not available on X11 or portal capture.
+
+10-bit capture reduces banding but may not be supported properly by all video players.
+.TP
+.BI \-q " quality"
+Quality preset (medium, high, very_high, ultra) for QP/VBR mode, or bitrate (kbps) for CBR mode (default: very_high).
+.TP
+.BI \-bm " auto|qp|vbr|cbr"
+Bitrate mode (default: auto → qp). CBR recommended for replay buffer.
+.TP
+.BI \-fm " cfr|vfr|content"
+Frame rate mode: constant, variable, or match content (default: vfr). Content mode only on X11 or portal.
+
+Content mode 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.
+.TP
+.BI \-cr " limited|full"
+Color range (default: limited). Full range may cause issues with some video players/websites.
+.TP
+.BI \-tune " performance|quality"
+Encoding tune (default: performance). Currently NVIDIA only.
+.TP
+.BI \-keyint " seconds"
+Keyframe interval in seconds (default: 2.0). Affects seeking precision.
+.TP
+.BI \-encoder " gpu|cpu"
+Encoding device (default: gpu). CPU encoding only for H264.
+.TP
+.BI \-fallback\-cpu\-encoding " yes|no"
+Fallback to CPU if GPU encoding unavailable (default: no).
+.SS Replay Buffer Options
+.TP
+.BI \-r " seconds"
+Replay buffer duration (2-86400 seconds). When set, only saves on command.
+.TP
+.BI \-replay\-storage " ram|disk"
+Buffer storage location (default: ram). Disk mode may reduce SSD lifespan.
+.TP
+.BI \-restart\-replay\-on\-save " yes|no"
+Clear buffer after saving replay (default: no).
+.TP
+.BI \-df " yes|no"
+Organize replays in date-based folders (default: no).
+.SS Advanced Options
+.TP
+.BI \-oc " yes|no"
+Overclock NVIDIA memory (X11 only). Requires Coolbits=12. Use at own risk.
+.TP
+.BI \-p " plugin.so"
+Load plugin (.so file). Can be specified multiple times.
+.TP
+.BI \-sc " script_path"
+Script to run after saving video. Receives filepath and type ("regular", "replay", "screenshot").
+.TP
+.BI \-restore\-portal\-session " yes|no"
+Restore previous portal session (Wayland portal, default: no).
+.TP
+.BI \-portal\-session\-token\-filepath " path"
+Portal session token file (default: ~/.config/gpu-screen-recorder/restore_token).
+.TP
+.BI \-gl\-debug " yes|no"
+OpenGL debug output (default: no).
+.TP
+.BI \-v " yes|no"
+Print FPS and damage info (default: yes).
+.SS Output Options
+.TP
+.BI \-o " output"
+Output file path (or directory for replay mode). Required except when outputting to stdout.
+.TP
+.BI \-ro " directory"
+Output directory for regular recordings during replay/streaming mode.
+.SS Information Commands
+.TP
+.B \-\-help
+Show help message.
+.TP
+.B \-\-version
+Show version (5.10.2).
+.TP
+.B \-\-info
+Show system info (codecs, capture options).
+.TP
+.B \-\-list\-capture\-options
+List available windows and monitors.
+.TP
+.B \-\-list\-audio\-devices
+List PulseAudio devices.
+.TP
+.B \-\-list\-application\-audio
+List applications for audio capture.
+.SH SIGNALS
+GPU Screen Recorder can be controlled via signals:
+.TP
+.B SIGINT (Ctrl+C)
+Stop and save recording (stop without save in replay mode).
+.TP
+.B SIGUSR1
+Save replay (replay mode only).
+.TP
+.B SIGUSR2
+Pause/unpause recording (not for streaming/replay).
+.TP
+.B SIGRTMIN
+Start/stop regular recording during replay/streaming.
+.TP
+.B SIGRTMIN+1
+Save last 10 seconds (replay mode).
+.TP
+.B SIGRTMIN+2
+Save last 30 seconds (replay mode).
+.TP
+.B SIGRTMIN+3
+Save last 60 seconds (replay mode).
+.TP
+.B SIGRTMIN+4
+Save last 5 minutes (replay mode).
+.TP
+.B SIGRTMIN+5
+Save last 10 minutes (replay mode).
+.TP
+.B SIGRTMIN+6
+Save last 30 minutes (replay mode).
+.PP
+Use
+.B pkill
+to send signals (e.g.,
+.BR "pkill -SIGUSR1 -f gpu-screen-recorder" ).
+.SH EXAMPLES
+Record monitor at 60 FPS with desktop audio:
+.PP
+.nf
+.RS
+gpu-screen-recorder -w screen -f 60 -a default_output -o video.mp4
+.RE
+.fi
+.PP
+Record monitor at 60 FPS with desktop audio and microphone:
+.PP
+.nf
+.RS
+gpu-screen-recorder -w screen -f 60 -a "default_output|default_input" -o video.mp4
+.RE
+.fi
+.PP
+Record specific window (X11 only):
+.PP
+.nf
+.RS
+gpu-screen-recorder -w $(xdotool selectwindow) -f 60 -o video.mp4
+.RE
+.fi
+.PP
+Instant replay (last 60 seconds):
+.PP
+.nf
+.RS
+gpu-screen-recorder -w screen -f 60 -c mkv -r 60 -o ~/Videos
+.RE
+.fi
+.PP
+Record region using slop:
+.PP
+.nf
+.RS
+gpu-screen-recorder -w region -region $(slop) -o video.mp4
+.RE
+.fi
+.PP
+Record region using slurp:
+.PP
+.nf
+.RS
+gpu-screen-recorder -w region -region $(slurp -f "%wx%h+%x+%y") -o video.mp4
+.RE
+.fi
+.PP
+Instant replay and launch a script when saving replay
+.PP
+.nf
+.RS
+gpu-screen-recorder -w screen -f 60 -c mkv -r 60 -sc ./script.sh -o ~/Videos
+.RE
+.fi
+.PP
+Stream to Twitch:
+.PP
+.nf
+.RS
+gpu-screen-recorder -w screen -f 60 -a default_output -o "rtmp://live.twitch.tv/app/stream_key"
+.RE
+.fi
+.PP
+Take screenshot:
+.PP
+.nf
+.RS
+gpu-screen-recorder -w screen -o screenshot.jpg
+.RE
+.fi
+.SH FILES
+.TP
+.I ~/.config/gpu-screen-recorder.env
+Environment variables for systemd service (optional).
+.TP
+.I /usr/lib/modprobe.d/gsr-nvidia.conf
+NVIDIA suspend/resume fix.
+.TP
+.I ~/.config/gpu-screen-recorder/restore_token
+Portal session token storage (default location).
+.SH TIPS
+.IP \(bu 3
+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
+.IP \(bu 3
+Variable frame rate may cause issues in some video players (use MPV)
+.IP \(bu 3
+H.265/HEVC not supported in browsers/Discord (use H264 for sharing)
+.IP \(bu 3
+Some distros disable hardware codecs (use Flatpak version)
+.IP \(bu 3
+Use CBR mode (
+.B \-bm cbr
+) for replay buffer to control RAM usage
+.SH PERFORMANCE TIPS
+.IP \(bu 3
+Save to SSD (HDD may be too slow)
+.IP \(bu 3
+Close other screen recorders (including idle OBS)
+.SH KNOWN ISSUES
+.IP \(bu 3
+NVIDIA: CUDA breaks after suspend (install gsr-nvidia.conf fix)
+.IP \(bu 3
+AMD: Possible black bars colors with HEVC/AV1 (use H264 or FFmpeg >=8)
+.SH SEE ALSO
+.UR https://git.dec05eba.com/gpu-screen-recorder
+Project homepage
+.UE
+.br
+.UR https://git.dec05eba.com/gpu-screen-recorder-gtk
+GTK GUI version (will be removed in the future)
+.UE
+.br
+.UR https://git.dec05eba.com/gpu-screen-recorder-ui
+ShadowPlay-style UI
+.UE
+.br
+.BR xdotool (1),
+.BR slop (1),
+.BR slurp (1),
+.SH AUTHORS
+Developed by dec05eba and contributors.
+.SH COPYRIGHT
+Copyright © dec05eba. Licensed under GPL3-only.
+.SH BUGS
+Report bugs at
+.UR mailto:dec05eba@protonmail.com
+dec05eba@protonmail.com
+.UE .