I really love Gource and over the years I have refined a simple pipeline to generate some cool feel-good visualisations for the codebases I have involved been with. Here is my formula:
git repo + gource config + user pics dir + captions + logo
=> gource PPM file
run ffmpeg script
=> gource video
add music audio file
=> final VIDEO
Prerequisites
- Download and install the latest Gource binaries.
- Download and install ffmpeg.
- Create a separate directory for your Gource project
Step 1 - Generating the PPM file
The goal of this step is to generate a PPM file, which is a simple of picture dump of all the frames generated by Gource.
This section describes all the parts that are necessary to create that file:
- Git repository you wish to visualise
- Custom user pictures
- Custom logo
- Caption file
- Gource config file to use as follows:
gource --load-config <gource.config file path>
Git repo
- Clone the repository you want to visualise
- From the repo directory run the command
git shortlog -sne
to generate a list of all the users involved in the repo and save that list in a file
User pictures and logo
- If you want to use custom pictures for users, create a separate
users
folder in your project folder. - Using the list generated in the step above download all the corresponding pictures, ensuring that they are named exactly like in than list, using exactly the same casing i.e. if the user is called
fOobOrg
, the picture must be namedfOobOrg.eee
where "eee" is whatever extension (png,jpg, gif, bmp etc.) - Source a logo and save it in your project folder - try to get a transparent background as it will look better.
Caption file
I usually invest a lot of time in producing a meaningful caption file as it helps people get some context around all the pyrotechnics. My recommendation is to use the repository log messages as a starting point.
- Pre-populate a caption file by running the command
git log --pretty="%at|%as %s"
in the repo working directory and saving its output to acaption.txt
file in your project folder. This will generate a good starting point for introducing custom captions. Here is an example caption output:
1471530982|2016-08-18 Fix Unused Default Values Issue (#31)
1471117298|2016-08-13 release 0.6.1.9
...
- Edit the caption file as you see fit, use an online Date to UNIX timestamp converter tool to generate the required timestamp. Make sure your captions is properly sorted in a chronological order.
Gource config file
Gource has many options but I have settled on a few that produce just the right amount of details for my purpose.
I usually try to create 2 videos:
- a short one that uses the overview
camera-mode
option, - and a longer one with more details and the tracking
camera-mode
.
I find that 3-4 minutes maximum is a good length for the short video to keep people engaged as it corresponds to the average duration of soundtracks.
[display]
viewport=1920x1080
[gource]
key=true
start-date=<DATE yyyy-mm-dd>
seconds-per-day=1.25
user-image-dir=<PATH>
colour-images=false
multi-sampling=1
camera-mode=overview
filename-time=2.0
title=<TITLE>
user-scale=1.50
user-font-size=18
stop-at-time=<TIME IS SECONDS>
hide=mouse,progress
highlight-users=1
highlight-all-users=1
path=<REPOSITORY PATH>
output-framerate=60
caption-file=<CAPTION FILE>
caption-size=22
caption-duration=6
logo=<LOGO PATH>
Step 2 - Generating the intermediary video
To generate the intermediary video I use ffmpeg to process the PPM file as follows:
ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i <gource.ppm path> -vcodec libx264 -preset medium -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 <gource.x264.mp4 output path>
Ensure that the frame rate matches the output-framerate
option you have used to generate the PPM file.
Step 3 - Producing the final video
To produce the final video, I merge the generated video with an audio file using ffmpeg:
ffmpeg -i video.mp4 -i <audio file path> -c:v copy -c:a aac output.mp4
I usually do not do any further editing or titling as it is not worth the effort.
Next steps
It takes a bit of work to produce a Gource video so there is an opportunity to streamline the process. One way to do this could be to create a helper tool as I describe in my post
.
Top comments (0)