animate

README

Golang FFMPEG Animation Package

This package creates an image that can be drawn on, and provides an EmitFrame() method to pipe the image to FFMPEG, and a Close() method to finish the animation.

The process of actually drawing frames of animation is left as an exercise for the reader.

The extension of the destination file determines the encoding format and parameters:

• .gif: Creates a looping indexed GIF animation.

  Generating an optimal palette would require buffering the entire animation, so instead a fixed general purpose palette is used.

• .png/.apng: Creates a looping animated PNG image. Lossless and supports transparency.

  This is the only supported format that is both completely lossless and supports transparency.

• .mp4: Creates an MP4 video using the libx264rgb codec with the ultrafast preset. Should be lossless, but doesn't support transparency.

  The file will be quite large, and probably isn't something you'd want to distribute directly.

• .mkv: Identical to MP4, except with a Matroska container.

• .webp: Creates a looping WEBP animation. The RGB->YUV conversion is lossy, but is otherwise lossless and supports transparency.

• .webm: Creates a WEBM video. The RGB->YUV conversion is lossy, but is otherwise lossless and supports transparency.

Installation

go get smariot.com/animate

Documentation

You can find the documentation at https://pkg.go.dev/smariot.com/animate.

Demo

The cmd/demo directory contains a simple program to demonstrate this package by generating the following image:

Documentation

Index

• type Animation
  • func New(r image.Rectangle, rate float64, out string) (*Animation, error)
  • func (a *Animation) Close() error
  • func (a *Animation) Elapsed() time.Duration
  • func (a *Animation) EmitFrame() error
  • func (a *Animation) Frame() int

Types

type Animation

type Animation struct {
	image.NRGBA
	// contains filtered or unexported fields
}

Animation implements the [draw.Image] interface; you can draw to it and then invoke [EmitFrame].

That said, some implementations might be optimized for known image types, in which case, passing a pointer to the [NRGBA] field might be more efficient.

func New

func New(r image.Rectangle, rate float64, out string) (*Animation, error)

New begins a new animation at the given size and frame rate, to be written to the specified output file.

The output filename must have one of the following extensions: - .gif (lossy, uses a default fixed palette) - .png / .apng (lossless) - .mp4 (lossless RGB, doesn't support transparency) - .mkv (lossless RGB, doesn't support transparency) - .webp (lossy YUV colorspace conversion, alpha supported) - .webm (lossy YUV colorspace conversion, alpha supported)

Note that the output file won't be created immediately, the animation will be written to a temporary file and then renamed by the [Close] method if no errors are encountered.

func (*Animation) Close

func (a *Animation) Close() error

Close finishes writing the animation, and cleans up any resources.

func (*Animation) Elapsed

func (a *Animation) Elapsed() time.Duration

Elapsed returns the timestamp for the current frame, with first frame having a timestamp of 0.

func (*Animation) EmitFrame

func (a *Animation) EmitFrame() error

EmitFrame writes the image as it presently appears as a frame to the animation.

If this is successful, then the frame counter is advanced. The frame buffer isn't cleared.

func (*Animation) Frame

func (a *Animation) Frame() int

Frame returns the current frame number, with the first frame being 0.