My Gource video production pipeline
Tags: gource
Published: 2021-04-28 23:24:59

I really love [Gource](https://gource.io) 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](https://gource.io).
* Download and install [ffmpeg](https://ffmpeg.org/download.html).
* Create a separate directory for your Gource project

# Step 1 - Generating the PPM file
The goal of this step is to generate a [PPM](https://fr.wikipedia.org/wiki/Portable_pixmap) 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 named `fOobOrg.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 a `caption.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 {% link https://dev.to/voieducode/a-great-starter-project-a-config-file-generator-for-gource-4oih %}.