Xcapture - the command-line window recorder
Xcapture is a command-line driven X11 window recorder, outputting a
raw video stream on standard out for processing by other tools.
If you're looking for a scriptable tool that just provides you with
raw video and want to edit it in your favourite video editor or
process it with ffmpeg, this may be the tool for you.
If you're looking for an all-in-one solution that does encoding and
overlays and effects for you, you may want to look into
SimpleScreenRecorder or OBS instead.
Installation
go get -u honnef.co/go/xcapture
Usage
Usage of xcapture:
-cfr
Use a constant frame rate
-fps uint
FPS (default 30)
-size string
Canvas size in the format WxH in pixels. Defaults to the initial size of the captured window
-win int
Window ID
Xcapture expects at least the -win option to specify the window to
capture. The window ID may be obtained by tools such as xwininfo or
xdotool. To select a window for recording by clicking on it, you could
use the following:
xcapture -win $(xdotool selectwindow)
The -fps option controls the frame rate of the capture. In VFR
(variable frame rate) mode, this sets the upper limit. In CFR
(constant frame rate) mode, it sets the fixed frame rate. See
Variable frame rate for more details on VFR
and CFR. CFR mode can be enabled with the -cfr option.
The -size option sets the video size. By default, xcapture uses the
initial size of the captured window. The -size option can be useful
if you want to compose a small window on a larger video, especially if
you expect to enlarge the window at some point.
Window resizing
When you resize the captured window, xcapture can't change the video
size. Instead, it will either render a portion of the window if it's
larger than the canvas, or draw the window in its original size on a
black background if it's smaller than the canvas.
Output format
Xcapture will emit a Matroska stream containing uncompressed RGBA images.
Depending on your resolution and frame rate, this may produce a large
amount of data. For example, 1920x1080 at 60 FPS would produce nearly
500 MB per second (2073600 pixels at 4 byte each, 60 times a second).
The output format is meant as an intermediate format, to be processed
and transcoded after recording.
Depending on your available CPU power, storage capacity and bandwidth,
and workflows, you can process this data in a number of ways.
If you have very large, very fast storage (high-end SSDs or NVMe
storage), you can save the file directly:
xcapture [args] > output.mkv
Alternatively, you can compress the output with lz4 before storing it:
xcapture [args], lz4 > output.mkv.lz4
On a modern mid-range CPU, this should be able to compress 1080p30 on
the fly using a single CPU core. A test capture of 30 FPS game footage
achieved a compression rate of 4:1.
If you have more CPU to spare, you could also transcode the stream to
H.264 on the fly, either lossy or lossless. To record the file in
H.264 lossless with the x264 codec, you can use something like the
following:
xcapture [args], ffmpeg -i pipe:0 -c:v libx264 -qp 0 -preset ultrafast -f matroska output.mkv
Testing it on the same recording as before, this achieved a
compression rate of 19:1 while still being able to maintain 30 FPS.
More complex setups are possible. For example, you could compress the
video with lz4, send it over a fast network to another machine, and
have that machine transcode the file in lossless H.264 and store it.
Finally, to test xcapture without storing any data, you can pipe it
into a media player such as ffplay:
xcapture [args], ffplay -loglevel quiet -
Variable frame rate
By default, xcapture emits a video with a variable frame rate, where
new frames are only written if the screen content changed (or at least
once every second). This can reduce CPU load and I/O, and allows for
much higher maximum frame rates if content is mostly static but
sometimes updates rapidly. In this mode, the -fps flag sets the
maximum frame rate. For example, -fps 60 may write new frames
anywhere between once and 60 times a second.
VFR has some downsides, however: Not all software may support it
fully, and streaming a live capture may appear jerky. For example, mpv
will not update the progress bar while displaying a frame. You can use
the -cfr flag to force a constant frame rate if necessary.
Converting VFR to CFR with ffmpeg
If you've recorded your screen in VFR mode but want to convert the
video to CFR, you can use ffmpeg's -vsync and -r options.
For example, given a VFR recording screen.mkv with a maximum frame
rate of 30 fps, you can convert it to CFR at 30 fps with the following
command:
ffmpeg -i screen.mkv -vsync cfr -r 30 screen_cfr.mkv
(Note that we're not specifying any codec, so ffmpeg will default to
lossy H.264. Extend the command as necessary).
Status output
Xcapture prints detailed status information during recording, looking
like this:
3600 frames, 0 dup, started recording 2m0.033503072s ago
capture latency min/max/avg: 1.57ms/6.29ms/3.22ms±0.47ms (100 %ile: 6.29ms)
write latency min/max/avg: 0.00ms/4.19ms/1.21ms±0.32ms (100 %ile: 4.19ms)
render loop min/max/avg: 0.00ms/4.72ms/1.29ms±0.29ms (100 %ile: 4.72ms)
Last slowdown: never (0 total)
The first line prints the number of frames written so far, how many
frames had to be duplicated (as opposed to captured from the screen)
and how long ago the recording began. In VFR mode, it's perfectly fine
to see a large number of duplicates. That simply means that the screen
didn't update.
In CFR mode, however, it means that we couldn't capture the window
contents fast enough and had to emit a duplicate frame in order to
maintain a constant frame rate. Seeing a large number of dups in CFR
mode is bad and is caused by a too slow CPU. A small number of dups
can occur during window resizing or moving.
The next three lines display various timing related information about
the screen capture process, the video output and the render loop,
which fetches screen captures and sends them out for writing. Each
line displays the following information: The minimum, maximum and
average (the arithmetic mean) time spent per one iteration, the
standard deviation of the average, and the percentile of loop
iterations that weren't too slow to keep up with the targeted frame
rate.
The final line shows the last time that we were too slow and couldn't
keep up with the frame rate.
Let's consider the following example, in which we were capturing 60
FPS CFR and sending it into ffmpeg:
2220 frames, 8 dup, started recording 37.016802689s ago
capture latency min/max/avg: 1.57ms/29.36ms/3.36ms±1.46ms (99.21875 %ile: 9.44ms)
write latency min/max/avg: 0.00ms/24.12ms/4.58ms±0.64ms (99.951171875 %ile: 13.11ms)
render loop min/max/avg: 0.00ms/24.12ms/4.61ms±0.72ms (99.90234375 %ile: 15.20ms)
Last slowdown: 36.929765031s ago (2 total)
It shows that we've recorded 2220 frames in 37 seconds, of which 8
were duplicated. 99.21875% of frames could be captured in time,
needing at most 9.44ms. 0.78125% of frames couldn't be captured in
time, and at worst we needed 29.36ms to capture a frame. This
corresponds with the number of duplicated frames.
Similarly, ~99.95% of all frames could be written in time. The
remaining ~0.04% were too slow, most likely because ffmpeg couldn't
keep up. And even in the 99.95% of cases, we came dangerously close to
16.6ms (the duration of one frame at 60 FPS); the average, however,
was 4.58ms with very little variance. Together with the final line,
which indicates that the last time we fell behind was right at the
beginning of the recording, we can deduce that ffmpeg was slow to
start but otherwise fast enough at processing our frames.
THe render loop shows similar statistics to the write loop, which
makes sense, as its runtime is largely dictated by how long it took to
write a frame.
Overall, the output shows us that, aside from a hiccup at the
beginning, we can record at our targeted frame rate without issues.
In contrast, the following example shows much worse performance, to
the point that the recorded video will be largely useless:
2875 frames, 18 dup, started recording 31.989022993s ago
capture latency min/max/avg: 2.62ms/24.12ms/4.41ms±1.09ms (99.21875 %ile: 8.91ms)
write latency min/max/avg: 0.00ms/18.87ms/8.10ms±0.92ms (96.875 %ile: 10.49ms)
render loop min/max/avg: 0.00ms/25.69ms/8.25ms±1.56ms (96.875 %ile: 11.01ms)
Last slowdown: 3.421969078s ago (81 total)
Over 3% of our frames couldn't be written fast enough, and we've
already had 81 slowdowns in 32 seconds, the last slowdown having
occured 3.4 seconds ago, so not near the start of the recording. We
don't seem able to record at the targeted frame rate.
Codecs
When recording video, an important choice is that of the codec and its
settings. This document will not attempt to recommend either. Instead,
it will list possible factors that will restrict the set of suitable
choices.
Essentially, these are the variables that will determine your options:
- Resolution of the captured window
- Frame rate of the capture
- The kind of captured content (terminal window, fast paced game play,
or anything in between) - Lossless or lossy encoding
- Available disk space for the recording (alternatively, the length of
the recording) - Write and seek speeds of the storage
- Available CPU that can be used on encoding, without impacting the
captured content
These variables can be divided into two categories: requirements and
available resources. Higher requirements will necessitate higher
resources, while fewer resources should cause you to readjust your
requirements.
It is possible to trade disk space and speed for CPU and vice versa,
but only to a certain degree. It is also possible, and usually
necessary, to trade one requirement for another. Recording high
resolutions at low frame rates and vice versa poses relatively little
issues, while recording at high resolution and high frame rates can
quickly exceed your resources.
For example, storing high-paced game footage at 1920x1080, 60 FPS and
lossless will require a tremendous amount of fast disk space, or a
tremendous amount of CPU, or a high amount of both.
Storing a 300x300 terminal window that only updates at a rate of 5
FPS, however, is virtually free and achievable with any codec on
almost any system.
While it is impossible to point at one specific combination of codec
and options and to say "This is the best choice", we'll try our best
to list some of the most viable choices. You are, however, encouraged
to do your own research if you expect the highest possible quality out
of your recordings.
On the lossless front – the preferred way of storing content that has
to be edited - viable options are HuffYUV, Ut Video, and to a degree
H.264 (with a QP of 0 and preferably the RGB color space). Depending
on the resolution and frame rate, storing the raw output might also be
an option. On Windows, MagicYUV and Lagarith might also be of
interest. FFmpeg on Linux, however, does not provide encoders for
these.
On the lossy front – handy for quick screencasts or capturing funny
moments – H.264 with the best settings that your CPU is capable of is
your best bet.