https://github.com/gmbeard/shadow-cast
GPU accelerated screen and audio recording for Linux
https://github.com/gmbeard/shadow-cast
Last synced: 16 days ago
JSON representation
GPU accelerated screen and audio recording for Linux
- Host: GitHub
- URL: https://github.com/gmbeard/shadow-cast
- Owner: gmbeard
- License: gpl-2.0
- Created: 2023-11-04T15:04:51.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-09T22:18:27.000Z (about 1 year ago)
- Last Synced: 2025-02-09T23:23:25.519Z (about 1 year ago)
- Language: C++
- Homepage:
- Size: 1.89 MB
- Stars: 42
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-repositories - gmbeard/shadow-cast - GPU accelerated screen and audio recording for Linux (C++)
README
## Shadow Cast - GPU accelerated screen and audio recording
*Shadow Cast* is a low-latency, low-overhead, GPU accelerated screen & audio capture utility.
Typical screen capture utilities copy the framebuffer data between host and GPU memory when encoding, causing significant load on the host CPU. This can affect both the running applications and the quality of the resulting media. *Shadow Cast* captures and encodes the framebuffer directly on the GPU with very little or no performance penalty to running applications. This makes *Shadow Cast* ideal for capturing gameplay footage, even in the most hardware intensive games. [See how it performs](doc/performance.md).
- [Example](#example---cyberpunk-2077)
- [Usage](#usage)
- [Requirements](#requirements)
- [Building from source](#building-from-source)
- [Installing](#installing)
- [Alternative projects](#some-alternative-projects)
- [FAQ](doc/faq.md)
#### Example - Cyberpunk 2077
[](https://www.youtube.com/watch?v=frXGxrdgTLY)
More examples can be found in [this YouTube playlist](https://www.youtube.com/watch?v=cczxo_S7tV8&list=PLnsSpqzSlJMKbVEuUbIfMhdgcoPpG-FoQ)
### Usage
You can start a capture session using...
```
$ shadow-cast [ ]
```
The resulting media/container type is determined by the extension of ``, e.g. `.mp4` or `.mkv`.
If no `OPTIONS` are specified then *Shadow Cast* will pick some sensible defaults for the audio/video encoders and sample/frame rates, but these can be changed by specifying the following `OPTIONS` on the command line...
| Option | Description |
|--------- |------------ |
| `-A ` | Audio encoder. All options available to `ffmpeg` should work here. Defaults to `libopus` |
| `-V ` | Video encoder. Available options are `h264_nvenc` and `hevc_nvenc`. defaults to `hevc_nvenc` |
| `-f ` | Capture FPS. values from `20` to `70` are accepted. defaults to `60` |
| `-s ` | Audio sample rate. Defaults to `48000` (_NOTE: Some encoders will only support certain sample rates. Shadow Cast will display an error if your chosen sample rate isn't supported_) |
Ctrl+C / SIGINT will stop the capture session and finalize the output media.
### Requirements
- FFMpeg (libav)
- NVIDIA GPU, supporting NVENC and NvFBC
- Pipewire
- X11 or Wayland
### Building from source
In order to build *Shadow Cast* you will need a C++20 compiler, plus the following libraries' headers/libs installed...
- ffmpeg / libav
- X11
- Pipewire
- Wayland (wayland-client, wayland-egl, wayland-devel)
- libdrm
- libglvnd
These can usually be obtained through your Linux distribution's package manager using the `-devel` packages of each.
After obtaining the source, change to the project's directory and run the following commands...
```
$ mkdir ./build
$ cd ./build
$ cmake ..
$ cmake --build .
```
_TIP: You may be able to speed up the_ `cmake --build .` _step by appending_ ` -- -j$(nproc)`
### Installing
Following the steps to build, above, you can install the built binary using...
```
$ sudo ./install-helper.sh
```
#### Installing to a Different Location
By default, *Shadow Cast* will be installed to `/usr/local/bin`. If you wish to install to a different location, run the following command _before_ running the above install step...
```
$ cmake -DCMAKE_INSTALL_PREFIX= ..
```
... replacing `` with your custom install path (E.g. `$HOME/.local`, `/opt`, etc.)
This will install the binary to `/bin/shadow-cast`. Once installed, you must ensure that `/bin` is in your `$PATH`.
### Some Alternative Projects
#### [gpu-screen-recorder](https://git.dec05eba.com/gpu-screen-recorder/about/)
*Shadow Cast* takes most of its inspiration from this project and it has been a very helpful reference. It seems to be the only other alternative that offers the same (if not better) performance and ease-of-use characteristics. *gpu-screen-recorder* offers AMD and Intel support in addition to NVIDIA.
#### [ffmpeg command-line utility](https://ffmpeg.org/)
This is the utility I used for capture prior to creating *Shadow Cast*. You can capture an X display using the `ffmpeg -f x11grab ...` command. In my experience, the performance when capturing gameplay footage is pretty terrible, and the resulting media will often contain lots of frame drops / tearing ([Example of `x11grab` vs *Shadow Cast* on YouTube](https://www.youtube.com/watch?v=ogFdvVON4z0)).
#### [OBS Studio](https://obsproject.com/)
Admittedly, I've never used this software. I'm aware that it is very popular for capturing / streaming but I don't really consider it to align with my use-cases. I much prefer a simple / small utility, where it is quick to setup a capture.