buttery generates continuous GIF loops.
$ buttery homer.gifSee buttery -help for more options.
https://github.com/mcandre/buttery/releases
$ go install github.com/mcandre/buttery/cmd/buttery@latesthttps://pkg.go.dev/github.com/mcandre/buttery
BSD-2-Clause
(None)
For more information on developing buttery itself, see DEVELOPMENT.md.
buttery -check <GIF> can act as a linter for basic GIF file format integrity. In the event of a corrupt GIF file, the program emits a brief message and exits non-zero.
buttery -getFrames <GIF> reports the frame count. This is useful for planning edits, particularly towards the far end of the original animation sequence.
The -stitch Mirror option is the primary loop smoothing transition, and the default transition setting.
Mirror twists the GIF timeline around like a Mobius strip, so that it arrives naturally back at the start. This is useful for smoothing GIF's that present misaligned images at the extreme ends of the loop.
We can diagram logically how Mirror works, by examining its effect on the frame sequence. With the notation:
real frame sequence (successive sequence repeated during infinite loop playback...)
1 2 3 (1 2 3 ...)
Each restart of the loop has a jarring visual jump from frame 3 to its successor frame 1.
1 2 3 2 (1 2 3 2 ...)
Of course, running the buttery editor yourself is the best way to appreciate how it works.
By mirroring the sequence backward in time, we remove the biggest visual jump. The overall visual effect is that of a sailor rowing back and forth in place. The Mirror transition often dramatically improves the smoothness of a GIF loop.
However, some motion may still appear awkward with mirroring, such as sharp, quick motions towards the extreme ends of the loop, or motions that appear to defy physical entropy. For this reason, we provide alternative transitions and other editing tools, described below.
The transision settings -stitch FlipH or -stitch FlipV disguise jarring misalignment, by reflecting the frames horizontally or vertically.
With the notation:
R: An original "right" frameL: A frame reflected horizontally "leftward"U: A original "upright" frameD: A frame reflected vertically "downward"
FlipH:
R R R (R R R ...)
FlipV:
U U U (U U U ...)
FlipH:
R R R L L L (R R R L L L ...)
FlipV:
U U U D D D (U U U D D D ...)
The FlipH/FlipV transitions are snappy, with an effect like rebounding a tennis ball across a net.
The -stitch Shuffle transition setting randomizes the frame sequence.
1 2 3 4 5 6
Example ordering:
6 3 1 4 2 5
Naturally, the more unique frames available, the more opportunity for unique random orderings.
This transition tends to artificially accelerate the perceived animation speed.
This transition hides a single jarring misalignment, in the noise of a completely random, spastic animation.
The -stitch None transition setting applies no particular transition at all between animation cycles. In art, sometimes less is more.
Animation smoothing takes a long time. We recommend pre-cutting your source assets to the desired subsequence. Every frame removed from the input GIF makes the buttery editing process faster.
Often, animations appear to accelerate when frame are removed. This is not always a bad thing; sometimes a fast animation helps to smooth over more subtle details.
The -trimStart <n> / -trimEnd <n> options drop n frames from the start and/or end of the original sequence. Zero indicates no trimming.
For brevity, we will now assume the None transition and elide the successive sequence repetitions.
1 2 3 4 5
With -trimStart 1:
2 3 4 5
With -trimEnd 1:
1 2 3 4
With -trimStart 1 and -trimEnd 1:
2 3 4
For convenience, we provide a similar option -trimEdges <n>. This drops n frames from both sides of the original sequence. Zero indicates no trimming.
1 2 3 4 5
With -trimEdges 1:
2 3 4
The -window <n> option truncates the original sequence to a fixed frame count. This is helpful for cutting down long animations. Zero indicates no truncation.
1 2 3 4 5
With -window 3:
1 2 3
With -window 3 and -trimStart 1:
2 3 4
The -cutInterval <n> option removes every nth frame from the original sequence.
This can mitigate some oscillation, such as lighting fluctuations from fans.
1 2 3 4 5 6 7 8
With -cutInterval 2:
1 3 5 7
This can also artificially accelerate the perceived speed of the animation. Useful when want to accelerate an animation already scaled down to 2cs per frame.
The -shift <offset> option performs a circular, leftward shift on the original sequence. This is useful for fine tuning how the GIF's very first cycle presents, before entering successive loops.
Zero is the neutral shift. A negative offset indicates rightward shift.
1 2 3
With -shift 1:
2 3 1
With -shift -1:
3 1 2
The -scaleDelay <factor> option adjusts animation speed, by multiplying each frame delay by the given factor.
1 = 1.0 is the neutral, and default factor.
Negative values reverse the original sequence.
We can diagram this in terms of the frame delays, expressed in centiseconds. That is, 4cs indicates 4 centisec = 4/100 sec between advancing to the next frame.
4cs 6cs 8cs
With -scaleDelay 2:
8cs 12cs 16cs
With -scaleDelay 0.5:
2cs 3cs 4cs
With -scaleDelay -1:
8cs 6cs 4cs
For compatibility with a wide range of GIF viewers, the resulting delay is upheld to a lower bound of 2cs.
The -loopCount <n> option configures the low-level GIF loop counter setting. According to the GIF standard:
-1indicates loop exactly once.0indicates infinite, endless looping (default).nindicates n replays after the first play = 1 + n total iterations.
1 2 3
With -loopCount 0:
1 2 3 (1 2 3 ...)
- ffmpeg edits and converts videos
- gifenc.sh converts numerous video formats to animated GIF's
- ImageMagick converts between multimedia formats, including GIF and WEBP
- mkvtools edits MKV videos
- VLC plays numerous multimedia formats
- webm supports audio in animation loops
🧈