https://github.com/alonso-herreros/hyprcap
HyprCap is a utility to easily capture screenshots and screen recordings on Hyprland
https://github.com/alonso-herreros/hyprcap
bash-script hyprland recording screenshot
Last synced: about 2 months ago
JSON representation
HyprCap is a utility to easily capture screenshots and screen recordings on Hyprland
- Host: GitHub
- URL: https://github.com/alonso-herreros/hyprcap
- Owner: alonso-herreros
- License: gpl-3.0
- Created: 2025-06-08T17:49:42.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-15T15:02:01.000Z (11 months ago)
- Last Synced: 2025-08-15T15:41:33.913Z (11 months ago)
- Topics: bash-script, hyprland, recording, screenshot
- Language: Shell
- Homepage:
- Size: 110 KB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HyprCap
[![AUR version][aur-shield]][aur-link]
[![AUR git version][aur-git-shield]][aur-git-link]
[![Latest GitHub release][release-shield]][release-link]
HyprCap is a utility to easily capture screenshots and screen recordings on
[Hyprland](https://hyprland.org/).
It allows selecting windows, regions and monitors with your mouse, command line
arguments, or an interactive [`fuzzel`][fuzzel] menu.
## Installation
### Arch Linux
This utility is available in the [AUR](https://aur.archlinux.org/packages/hyprcap). You can install it
using an AUR helper like `yay`:
```bash
yay -S hyprcap
```
### Nix Flake
HyprCap is distributed as a Nix flake. You can install or run it directly from the GitHub source.
#### Prerequisites
Nix with flakes enabled
(set `experimental-features = nix-command flakes` in your Nix config)
#### Install to your profile
To install HyprCap into your user environment:
```bash
nix profile install github:alonso-herreros/hyprcap
```
#### Use in a flake
You can add HyprCap as an input to your own flake:
```nix
{
inputs = {
hyprcap.url = "github:alonso-herreros/hyprcap";
};
}
```
#### Using with Home Manager
Add HyprCap to your Home Manager configuration:
```nix
{
inputs.hyprcap.url = "github:alonso-herreros/hyprcap";
outputs = { self, nixpkgs, home-manager, hyprcap, ... }: {
homeConfigurations.your-user = home-manager.lib.homeManagerConfiguration {
# ...
home.packages = [
hyprcap.packages.${pkgs.stdenv.hostPlatform.system}.default
];
};
};
}
```
### Manual installation
#### Dependencies
Install the required dependencies using your package manager. For example, on
Arch Linux, you can use:
```bash
sudo pacman -S wf-recorder grim slurp hyprland jq wl-clipboard hyprpicker libnotify
```
The following dependencies are **required** to run HyprCap:
- `wf-recorder`
- `grim`
- `slurp`
- `hyprland`
- `jq`
The following extras are not essential, but required for some features
- `wl-clipboard` to copy to clipboard
- `hyprpicker` to freeze the screen
- `libnotify` + a notification daemon to get notified
- `fuzzel` to use an interactive menu
#### Copy the script
Copy the `hyprcap` script to a folder in your `PATH`:
```bash
git clone https://github.com/alonso-herreros/hyprcap.git HyprCap
cd HyprCap
make all
sudo make install
```
For user-level installation, you can use:
```bash
git clone https://github.com/alonso-herreros/hyprcap.git HyprCap
cd HyprCap
make all
make install PREFIX="$HOME/.local"
```
You're free to delete the cloned repository after copying the script.
## Usage
You can get help on how to use HyprCap by running `hyprcap -h`:
```
$ hyprcap -h
Usage: hyprcap [options...] [[-s] ] [-- [capturer_args]]
HyprCap is a utility to easily capture screenshots and screen recordings on
Hyprland.
Please report bugs and issues at
https://github.com/alonso-herreros/hyprcap/issues
Commands:
shot | screenshot Take a screenshot
rec | record Toggle screen recording
rec-start | record-start Start a screen recording
rec-stop | record-stop Stop a screen recording
A selection can be specified after the command, with the -s or --selection
option, or using a fuzzel (dmenu-like) menu if neither is specified.
Selection:
monitor Select an entire monitor interactively.
monitor:active Select the currently focused monitor.
monitor: Select the monitor with the exact given name
window Select a visible window interactively.
window:active Select the currently focused window.
window: Select the first window that contains the title.
region Select a region manually using 'slurp'.
region:X,Y,WxH Select the specified region.
* Note: Any selection will be trimmed to a single monitor when recording due
to limitations in 'wf-recorder'
Selection options:
-s, --select Alternative way to specify the selection.
Saving options:
-w, --write Save the capture to a file using the default
filename and directory.
-W, --no-write Don't save captures to a file (default).
-F, --no-file Same as `--no-write`
-o, --output-dir Directory in which to save captures.
Default: $XDG_PICTURES_DIR/Screenshots or
$XDG_VIDEOS_DIR/Captures
-f, --filename The file name for the resulting capture within
the output directory. The file extension
(everything after the last dot) is used to
determine the file type, unless overridden with
`--filetype`.
Default:
YYYY-MM-DD-hhmmss_hyprcap.
where is determined by the command
(see the `--filetype` defaults).
--filetype Force a file type for the capture. For
supported types, see the documentation for grim
and wf-recorder.
Defaults: png for screenshots, mp4 for
recordings.
-c, --copy Copy capture to clipboard with 'wl-copy'.
Capture options:
-d, --delay
Notification options:
-n, --notify Send a notification when capture is done.
(default).
-N, --no-notify Don't send notifications.
-a, --actions Show actions in the notification (default).
Requires --notify.
-A, --no-actions Don't show actions in the notification. Requires
--notify.
-t, --notif-timeout
Output options:
-r, --raw Output raw capture data to stdout.
-v, --verbose Print extra information. Specify multiple times
to increase verbosity.
-q, --quiet Print less information.
--disable-title Forcefully disable setting the terminal title.
Useful if the terminal title setting code is
causing issues, e.g. when running in a script.
-V, --version Show the version and exit.
-h, --help Show this help message and exit.
Capturer arguments:
Any arguments passed after a double dash ('--') will be passed directly to
the capture program: 'grim' in the case of screenshots, or 'wf-recorder' in
the case of recordings.
Examples:
Toggle recording current monitor `hyprcap rec monitor:active`
Screenshot a window (interactive) `hyprcap shot window`
Toggle recording a specific region `hyprcap rec region:100,100,400x300`
Stop an ongoing recording `hyprcap rec-stop`
Fall back to monitor capture when selection is cancelled
`hyprcap shot region || hyprcap shot monitor:active`
```
## Configuration
You can add the various modes as keybindings in your Hyprland config like so:
```ini
# ~/.config/hypr/hyprland.conf
...
# Screenshot a region
bind = $MOD SHIFT, S, exec, hyprcap shot region -z -c -n
# Screenshot current window
bind = $MOD SHIFT ALT, S, exec, hyprcap shot window:active -z -c -n
# Screenshot with interactive selection
bind = $MOD SHIFT CTRL, S, exec, hyprcap shot -z -c -n
# Toggle recording a region
bind = $MOD SHIFT, R, exec, hyprcap rec region -c -n
# Toggle recording current window
bind = $MOD SHIFT ALT, R, exec, hyprcap rec window:active -c -n
# Toggle recording with interactive selection
bind = $MOD SHIFT CTRL, R, exec, hyprcap rec -c -n
```
### Save location
You can save the captures by using the `--write` (`-w`) option. The `--out-dir`
(`-o`) and `--filename` (`-f`) options can be used to specify the output
directory and filename, respectively. By default, captures are saved in the
`$XDG_PICTURES_DIR/Screenshots` directory for screenshots and
`$XDG_VIDEOS_DIR/Captures` for recordings. If those XDG directory variables
are not set, the defaults are `~/Pictures/Screenshots` and
`~/Videos/Captures`, respectively.
> [!Note]
>
> The current capture is saved in the `$XDG_CACHE_DIR/hyprcap` dir for internal
> use.
## Contributing
Contributions are welcome! You can help by:
- Reporting bugs and issues on the [GitHub
repository](https://github.com/alonso-herreros/hyprcap/issues)
- Suggesting new features or improvements
- Submitting pull requests with fixes or new features
- Improving the documentation
- Testing the utility and providing feedback
## Credit
This project is based on [Gustash's
Hyprshot](https://github.com/Gustash/Hyprshot)
[aur-shield]: https://img.shields.io/aur/version/hyprcap?label=hyprcap&logo=arch+linux
[aur-link]: https://aur.archlinux.org/packages/hyprcap
[aur-git-shield]: https://img.shields.io/aur/version/hyprcap-git?label=hyprcap-git&logo=arch+linux
[aur-git-link]: https://aur.archlinux.org/packages/hyprcap-git
[release-shield]: https://img.shields.io/github/v/release/alonso-herreros/hyprcap?color=green&logo=github
[release-link]: https://github.com/alonso-herreros/hyprcap/releases/latest
[fuzzel]: https://codeberg.org/dnkl/fuzzel