ffmpeg-go

Install the ffmpeg-go package using Go modules:

go get -u github.com/u2takey/ffmpeg-go

Prerequisite: Install FFmpeg ffmpeg-go is a pure-Go wrapper and does not install the FFmpeg binary itself. You must install FFmpeg on your system and ensure it is available in your $PATH.

You can verify the installation by running:

ffmpeg

If you see ffmpeg: command not found, you must install it via your OS package manager (e.g., brew install ffmpeg on macOS or sudo apt install ffmpeg on Ubuntu).

The library builds a Directed Acyclic Graph (DAG) of media processing.

1. Nodes (*Node) represent operations (inputs, filters, or outputs).
2. Streams (*Stream) represent the connections between nodes. A node's streamSpec defines which streams it expects as inputs.
3. Selectors and Labels: When connecting nodes, you use Label and Selector to specify which exact track (e.g., video vs audio) is being passed from one node to another.

To retrieve a specific stream from a node, use the Get(a string) method. The string format a can be a simple label (e.g., "v") or a label with a selector separated by a colon (e.g., "v:0").

The ffmpeg-go library uses a graph-based model to represent complex FFmpeg command chains.

• Graph: The top-level structure representing the entire execution plan. It contains a list of Nodes and global GraphOptions.
• GraphNode: Represents a single unit of work (like an input, a filter, or an output) within the graph. It defines which input streams it consumes, which output streams it produces, and the specific Args and KwArgs required for that step.
• GraphOptions: Configuration for the execution of the graph, such as Timeout and OverWriteOutput.

You can control the resource usage of an FFmpeg process using .RunWithResource(cpuLimit, memLimit). This allows you to restrict the amount of CPU cores or memory the process can consume.

e := ComplexFilterExample("./sample_data/in1.mp4", "./sample_data/overlay.png", "./sample_data/out2.mp4")
err := e.RunWithResource(0.1, 0.5)
if err != nil {
	assert.Nil(t, err)
}

You can extract a specific frame from a video and pipe it to an io.Reader (like a buffer) by using the select filter to pick the frame number and setting the output format to image2 with vcodec as mjpeg.

func ExampleReadFrameAsJpeg(inFileName string, frameNum int) io.Reader {
	buf := bytes.NewBuffer(nil)
	err := ffmpeg.Input(inFileName).
		Filter("select", ffmpeg.Args{fmt.Sprintf("gte(n,%d)", frameNum)}).
		Output("pipe:", ffmpeg.KwArgs{"vframes": 1, "format": "image2", "vcodec": "mjpeg"}).
		WithOutput(buf, os.Stdout).
		Run()
	if err != nil {
		panic(err)
	}
	return buf
}

To overlay an image onto a video, use the ffmpeg.Filter function. You can scale the overlay image first using .Filter("scale", ...) and then apply the overlay filter to the stream set. Use ffmpeg.KwArgs to enable the overlay at specific timestamps (e.g., enable: gte(t,1)).

// show watermark with size 64:-1 in the top left corner after seconds 1
overlay := ffmpeg.Input("./sample_data/overlay.png").Filter("scale", ffmpeg.Args{"64:-1"})
err := ffmpeg.Filter(
    []*ffmpeg.Stream{
        ffmpeg.Input("./sample_data/in1.mp4"),
        overlay,
    }, "overlay", ffmpeg.Args{"10:10"}, ffmpeg.KwArgs{"enable": "gte(t,1)"}).
    Output("./sample_data/out1.mp4").OverWriteOutput().ErrorToStdOut().Run()

Use ffmpeg.Input and ffmpeg.Output combined with ffmpeg.KwArgs to specify codec changes. For example, to transcode an MP4 file to H.265 (libx265), pass the codec option in KwArgs.

err := ffmpeg.Input("./sample_data/in1.mp4").
		Output("./sample_data/out1.mp4", ffmpeg.KwArgs{"c:v": "libx265"}).
		OverWriteOutput().ErrorToStdOut().Run()

To extract a specific segment of a video, use the ss (start time) and t (duration) parameters within ffmpeg.KwArgs in both the Input and Output calls.

err := ffmpeg.Input("./sample_data/in1.mp4", ffmpeg.KwArgs{"ss": 1}).
    Output("./sample_data/out1.mp4", ffmpeg.KwArgs{"t": 1}).OverWriteOutput().Run()

To track progress, use ffmpeg.Probe to get the total duration of the file. Then, use .GlobalArgs("-progress", "unix://...") to instruct FFmpeg to write progress data to a Unix socket.

func ExampleShowProgress(inFileName, outFileName string) {
	a, err := ffmpeg.Probe(inFileName)
	if err != nil {
		panic(err)
	}
	totalDuration := gjson.Get(a, "format.duration").Float()

	err = ffmpeg.Input(inFileName).
		Output(outFileName, ffmpeg.KwArgs{"c:v": "libx264", "preset": "veryslow"}).
		GlobalArgs("-progress", "unix://"+TempSock(totalDuration)).
		OverWriteOutput().
		Run()
	if err != nil {
		panic(err)
	}
}

To create multiple different versions of a video (e.g., different resolutions or bitrates) from a single source, use .Split() on the input stream. This creates multiple identical streams that can be processed independently. Use ffmpeg.MergeOutputs to execute all output commands in a single run.

// get multiple output with different size/bitrate
input := ffmpeg.Input("./sample_data/in1.mp4").Split()
out1 := input.Get("0").Filter("scale", ffmpeg.Args{"1920:-1"}).
	Output("./sample_data/1920.mp4", ffmpeg.KwArgs{"b:v": "5000k"})
out2 := input.Get("1").Filter("scale", ffmpeg.Args{"1280:-1"}).
	Output("./sample_data/1280.mp4", ffmpeg.KwArgs{"b:v": "2800k"})

err := ffmpeg.MergeOutputs(out1, out2).OverWriteOutput().ErrorToStdOut().Run()

The DrawBox method draws a colored rectangle on the video stream.

• x, y, w, h: The rectangle dimensions and position.
• color: The color string (e.g., "red").
• thickness: The thickness of the border. If 0, it is omitted from the arguments.
• kwargs: Additional FFmpeg drawbox parameters.

Returns a *Stream.