Skip to content
Andrew Caudwell edited this page Oct 13, 2022 · 10 revisions

How to record videos of Gource

Video Capture Software

By far the easiest way to record a video of Gource is using a third party video capture program. The only downside of this approach is you will have less control over the final encoding quality of the video and you may need to manually start and stop recording.

I recommend these programs:

Raw Video Output and Encoding

You can capture raw video from Gource using the -o (aka --output-ppm-stream) option. This creates an uncompressed sequence of screenshots in PPM format which can then be processed by a video encoder (such as ffmpeg) to produce a video.

You can also adjust the output frame rate with -r (aka --output-framerate). Note you will need to adjust the frame rate used by the encoder (eg ffmpeg -r) to match, unless you are going for a speed-up timelapse or slow motion effect.

Make sure you keep the window of Gource entirely visible while recording. If you minimize or partially obscure the window, your video card may decide not draw the output consistently and you will get artifacts in your recording. You may like to use the -f option to run in full-screen mode to stop this happening.

You may want to record your video in widescreen as that is the trend for online video now days. You can record in 720p by adding -1280x720 to the command line.

Also check out the Controls section of the wiki for steps to customize the look of Gource for your videos.

Linux / Mac

FFmpeg using x264 codec

The below command lines will create a video at 60fps using the x264 codec in an mp4 container.

This assumes you have recent version of ffmpeg with libx264 support. Some distributions like Ubuntu do not enable libx264 support by default in ffmpeg (See this thread for various ways to enable libx264 support on Ubuntu). Consult guides for your distribution if this is the case.

In one command (raw video piped directly into ffmpeg):

gource -1280x720 -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.mp4

As two commands:

gource -1280x720 -o gource.ppm
ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i gource.ppm -vcodec libx264 -preset medium -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.mp4

You can increase the -crf value to trade quality (1) for a smaller output file size (17). Note that the quality of the 'bloom' is quite sensitive to compression. Also you can change the -preset to trade off fast encoding (ultrafast) vs smaller the output file size (veryslow), or something in between (medium). See the FFmpeg H.264 wiki for more details.

This one has the advantage of keeping the raw video file (gource.ppm) so you can go back and tweak the encoding parameters if you don't like the output quality or need a different video format without recording the video again. The disadvantage is that this raw uncompressed video and you can expect it to use up 100gs of gigs, so keep that in mind!

The file extension 'avi' can be changed to 'mp4' or 'mkv' to get ffmpeg to use a different container format for the video. 'avi' is typically discouraged for long videos as there is a 2GB file limit associated with that format.

Note: ffmpeg seems to be a constantly moving target, so you may find you need slightly different arguments with your version. There is a good guide to using x264 with ffmpeg here.

FFmpeg using WebM codec

A good alternative codec to x264 is WebM. Below is a very basic command line example of using ffmpeg to produce a Gource WebM video:

gource -1280x720 -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libvpx -b 10000K gource.webm

Windows

Here is an example command-line using the built in PPM frame capture support and ffmpeg to generate a video:

gource -1280x720 -o gource.ppm C:\\path\\to\\code\\repository
C:\\ffmpeg\\bin\\ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i gource.ppm -vcodec libx264 -preset medium -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.x264.avi

You can increase the -crf value to trade quality (1) for a smaller output file size (17). Note that the quality of the 'bloom' is quite sensitive to compression. Also you can change the -preset to trade off fast encoding (ultrafast) vs smaller the output file size (veryslow), or something in between (medium). See the FFmpeg H.264 wiki for more details.

The file extension 'avi' can be changed to 'mp4' or 'mkv' to get ffmpeg to use a different container format for the video. 'avi' is typically discouraged for long videos as there is a 2GB file limit associated with that format.

You can get an ffmpeg build for Windows from here.

Note: ffmpeg seems to be a constantly moving target, so you may find you need slightly different arguments with your version. There is a good guide to using x264 with ffmpeg here.

Videos

Video showing off the new Bloom effect:

A collage of different open source software projects displayed using Gource:

Examples

Various videos of projects created with Gource.

Minecraft

Torchlight II

Koha Library System

Homebrew

Git