Skip to content
🎬 Cross-platform hotkey short video capture for games
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
capsulerun Remove dependency on wstr, closes #62 Apr 18, 2019
docs Add Hyper Ultra Astronautics to list of tested games Feb 24, 2017
libcapsule get rid of ctor, cf. #62 Apr 18, 2019
release Add linux-opengl-ld test Apr 18, 2019
wincap Implement capsulerun for linux Apr 14, 2019
.gitignore Add linux-opengl-dlopen test Apr 16, 2019
.gitlab-ci.yml remove cache Apr 17, 2019
.gitmodules Don't link libcapsule against ffmpeg, drop PolyHook, migrate build sc… Aug 25, 2016
Cargo.toml Add debug symbols to release build.. and strip them after testing. Apr 17, 2019
LICENSE Re-license as GPLv2 (overdue, forced to), make README more useful Feb 14, 2017
Makefile Fix windows runner Apr 15, 2019


capsule augments any game so that pressing a key records a video+audio clip. Those clips can be easily shared later, see this tweet for example.

It's being developed mainly for integration with the app, but is designed as a separate pair of projects:

libcapsule is responsible for detecting which video & audio APIs a game uses, and intercepting calls to them so that it may capture video and audio frames.

capsulerun is responsible for launching the game, injecting libcapsule, establishing a connection to it, receiving video and audio frames, encoding, and muxing them.

See Build instructions if you know enough to give it a shot :)

Design goals

  • Easy to use - no configuration, hit a key = record (think FRAPS)
  • Fast - should slow down games as little as possible
  • Quality recordings - high FPS, preserve colorspace when possible
  • Desktop audio - all captured gameplay should come with audio
  • Easy sharing - output should be immediately useful (H264/AAC)


Things that are out of scope (ie. that capsule will not officially support):

  • Compositing (more than one video source, etc.)
  • Live-streaming
  • Any platforms that aren't Linux, macOS, or Windows (especially mobile, BSDs, etc.)
  • Long videos - haven't settled on a maximum yet but "a few minutes"
  • Hooking into existing processes - capsulerun must be used to launch game



  • System
    • capsulerun launches child, relays stdout/stderr, injects 32-bit & 64-bit processes properly
    • capsulerun handles child quitting unexpectedly, relays exit code
    • capsulerun & libcapsule communicate via a pair of fifos/named pipes, send frames via shared memory
    • capsulerun has 'headless' mode where it doesn't launch a child, acts as just an encoder (HTML5 games, etc.)
  • Video
    • encoder outputs variable fps h264 video, aac audio, in an mp4 container


  • Control
    • X11 recording hotkey support (hardcoded to F9)
  • Video
    • OpenGL capture
    • Vulkan capture
  • Audio
    • ALSA: Intercepts ALSA API calls, only F32LE supported so far
    • PulseAudio: Captures monitor of default output device


  • Control
    • Cocoa recording hotkey support (hardcoded to F9)
  • Video
    • OpenGL capture
    • Vulkan capture
  • Audio
    • CoreAudio: Intercepts API calls, only F32LE supported so far


  • Control
    • Win32 recording hotkey support (hardcoded to F9)
  • Video
    • Direct3D 9 capture
    • Direct3D 10 capture
    • Direct3D 11 capture (with GPU color conversion & dummy overlay)
    • Direct3D 12 capture
    • Vulkan capture
  • Audio
    • Wasapi: Intercepts API calls, only F32LE supported so far
    • Wasapi fallback: captures default loopback device

Build instructions

This project is being ported to Go & Rust. These instructions are OUTDATED.

capsule is a (set of) CMake projects, which handles things like:

  • Download some dependencies
  • Generating Makefiles, MSVC project files, etc.
  • Doing 32/64-bit tests
  • Bundling required libraries with the final executable

Like typical CMake projects, capsule should be built in a subfolder, never directly in the source tree, as you'll see in platform-specific instructions

Building on Linux

Notes: some distributions ship libav, most distributions ship outdated versions of ffmpeg, save yourself some trouble and build x264 and ffmpeg 3.2+ yourself into a prefix. You can then pass it to cmake with -DCAPSULE_DEPS_PREFIX=/path/to/prefix

64-bit and 32-bit versions are built separately. Example of 64-bit build:

cd /path/to/capsule
mkdir build64
cd build64
cmake ..
make install -j4

capsulerun usage:

/path/to/capsule/build64/dist/capsulerun -- path/to/some/game.x86_64

If nothing's happening, the game isn't using OpenGL, you've got the wrong capsule architecture (64-bit for a 32-bit game for example), or there's something capsule doesn't support yet.

NB: Launcher scripts may give you a bit of trouble at the moment, as capsulerun will establish a connection with the shell and not the game, which will fail. This will be addressed later.

Building on macOS

Pretty much the same as Linux, except you don't need to compile x264 & ffmpeg yourself, a stripped-down home-cooked universal build will be downloaded by cmake.

The resulting capsulerun & libcapsule are universal, which means there's no separate 32-bit/64-bit build processes and they should work with every app, no matter what their architecture.

Example build:

cd /path/to/capsule
mkdir build
cd build
cmake ..
make install -j4

capsulerun supports launching .app bundles and invididual executables. Example usage:

/path/to/capsule/build/dist/capsulerun -- path/to/some/

Building on Windows

Important notes:

  • Microsoft Visual C++ (MSVC) is needed, 2015 is what we're using internally.
  • CMake shipped with msys2 won't cut it, you need a Windows release of CMake (which includes the Visual Studio project generators):

You probably won't get anywhere with an MSVC older than 2015.

From the Visual C++ 2015 Native Build Tools Command Prompt, run:

cd C:\path\to\capsule
mkdir build32
cd build32
cmake -G "Visual Studio 14 2015" ..

To compile, run this from the build32 folder:

msbuild INSTALL.vcxproj

(You can use /maxcpucount:n to speed up the build process, since capsule is broken down in a few projects - where n is the maximum number of CPUs you want to use)

To build a 64-bit version, add Win64 to the generator name (the -G parameter).

C:\path\to\capsule\build32\dist\capsulerun.exe -- some_game.exe

NB: Some games with launchers (for example UE4 games) may give you a bit of trouble at the moment, as capsulerun will establish a connection with the launcher and not the game, which will fail. This will be addressed later.


capsule is released under the GPL v2 license, see the LICENSE file.

It uses the following libraries:

Some of its code is derived from the following projects:

Special thanks to:

You can’t perform that action at this time.