Github GiFs crash course

github_gifs.md

Guide to Github GiFs

Constraints

1. Max 100 MB File size allowed in commit check in. Max 10 MB if you use drag and drop on web.
2. Anything above 50MB takes eons to load. You need to shrink file size as much as you can.
3. MP4/MOV file support is limited to web drag and drop only thus limiting to 10 MB size. It also adds an ugly player frame with controls. Gifs are much prettier.

Pipeline

1. Screen capture to MP4 format using ShareX
2. Use Openshot to remove dead space in recording, add transitions etc. (See Tip 6 at bottom for a super hack)
3. Use FFMpeg to convert MP4 to a GIF.
4. Use Gifsicle to further reduce size if possible.

Golden Rule

It is far less error prone and size efficient to stitch smaller quick cuts together than trying to capture entire demo in 1 long cut. You can stitch files using lossless cut.

Commands

ShareX

1. Shift + PrtScr to Start Screen Capture.
2. Pick one
    - Press 1 to capture Monitor 1, 2 for Monitor 2. 
    - Hover and click on Window to capture window.
    - Draw a rectangle to capture a region anywhere.

Openshot

Export video from openshot at High quality preset but at 1 Mbps bit rate at max. Bit rate can be adjusted in advanced section of export dialogue box. This is enough for Gif creation even for 1080p videos.

If reqired, you can reduce size of Openshot rendered video by reducing bit rate even more before converting it to GiF.

ffmpeg -i openshot_rendered.mp4 -c:v libx264 -b:v 600k -profile:v baseline -c:a copy input.mp4

FFMpeg

1. Generate color palette png

  ffmpeg -i input.mp4 -vf "fps=10,scale=-1:720:flags=lanczos,palettegen=stats_mode=diff" -y palette.png

2. Use palette.png to create gif

  ffmpeg -i input.mp4 -i palette.png -lavfi "fps=10,scale=-1:720:flags=lanczos [x]; [x][1:v] paletteuse=dither=bayer:bayer_scale=3" -y output.gif

Gifsicle

gifsicle --optimize=3 --lossy=15 -o final.gif output.gif

Gif in Github Readme

Add the following tag in your Markdown to render Gif.

![my_demo_title](./path-to-file-in-repo/my_demo.gif)

Large Files in GitHub

[WARNING: DESTRUCTIVE ADVICE!! DON"T FOLLOW IF YOU DON'T KNOW WHAT YOU ARE DOING]

1. Large Gifs in git history make the git repo grow huge. So do as many iterations as you can before committing the file to repo. You can't keep doing trials by pushing the file to remote each time.
2. Don't work on anything else until your large file is ready. It is easier to force push to remove large file from repo if nothing else of importance has changed.
3. If you have pushed large file multiple times to repo. Reset Head to the commit before all large check ins and force push to reset your history.
4. Once you have removed all commits referring to Large File and force pushed to remote. run the following to clear your local git repo

rm -rf .git/refs/original/
git reflog expire --expire=now --all
git fsck --full --unreachable
git repack -A -d
git gc --aggressive --prune=now 

5. Github will clear the remote reflog after 30 days. Until then your deleted files will still be recoverable.

Tips

1. Adjust Gif resolution in ffmpeg by changing scale=width:height. Change either width or height, set the other to -1 to maintain aspect ratio.
2. If you care about static background more than what is changing in your demo. remove stats_mode=diff from palette generation in ffmpeg.
3. Gifsicle will not always reduce size further without using --lossy=15 param. And it can kill quality heavily. So use only if necessary. Do not increase the value above 15-25 as the returns on size compression become diminishing above that. Quality reduces massively while size barely reduces by 1-2 MBs.
4. Best way to reduce size is to reduce number of things that change between frames.
   • Make your background static.
   • Remove as many un-necessary items from screen as possible.
   • Use a blank Black background, and use black heavily to reduce size / color space required.
5. Don't add any heading for your demo gif in Github Readme. This makes the readme look clean and consistent while the gif is still loading.
6. If your demo is long but has distinct parts. Create a split screen 2x2 grid which can play 4 distinct parts simultaneously using OpenShot. This will make your video duration 1/4th of original, reducing your gif size tremendously.