ffmpeg

README

Simple Go FFMPEG Wrapper for Camera Streams

Capture short video clips from camera stream URLs (RTSP and HTTP(S)).

Provides a simple interface to set FFMPEG options and save or stream captured video.

Lots of other libraries out there do ffmpeg and rtsp things, but I couldn't find any that fit this simple task of "get a video snippet from a camera."

• GODOC

Notes

• SaveVideo/SaveVideoContext write to files and return ffmpeg output text.
• GetVideo/GetVideoContext return an io.ReadCloser stream.
• Input URL scheme is respected:
  • RTSP URLs use -rtsp_transport tcp.
  • Non-RTSP URLs do not include RTSP-only options.
• Output container differs by destination:
  • file output: mov
  • stream output ("-"): fragmented MP4 flags for pipe-safe output
• Errors include a tail of ffmpeg stderr when available for better diagnostics.

Example

package main

import (
	"log"

	"golift.io/ffmpeg"
)

func main() {

	/*
	 * Example non-transcode direct-save from securityspy.
	 */

	securitypsy := "https://user:pass@127.0.0.1:8001/++video?cameraNum=1"
	output := "/tmp/securitypsy_captured_file.mov"

	c := &ffmpeg.Config{
		FFMPEG: "/usr/local/bin/ffmpeg",
		Copy:   true, // do not transcode
		Audio:  true, // retain audio stream
		Time:   10,   // 10 seconds
	}

	encode := ffmpeg.Get(c)
	cmd, out, err := encode.SaveVideo(securitypsy, output, "SecuritySpyVideoTitle")

	log.Println("Command Used:", cmd)
	log.Println("Command Output:", out)

	if err != nil {
		log.Fatalln(err)
	}

	log.Println("Saved file from", securitypsy, "to", output)

	/*
	 * Example transcode from a Dahua IP camera.
	 */

	dahua := "rtsp://admin:password@192.168.1.12/live"
	output = "/tmp/dahua_captured_file.m4v"

	f := ffmpeg.Get(&ffmpeg.Config{
		Audio:  true, // retain audio stream
		Time:   10,   // 10 seconds
		Width:  1920,
		Height: 1080,
		CRF:    23,
		Level:  "4.0",
		Rate:   5,
		Prof:   "baseline",
	})

	cmd, out, err = f.SaveVideo(dahua, output, "DahuaVideoTitle")

	log.Println("Command Used:", cmd)
	log.Println("Command Output:", out)

	if err != nil {
		log.Fatalln(err)
	}

	log.Println("Saved file from", dahua, "to", output)
}

Documentation

Overview

Package ffmpeg captures video from RTSP streams, like IP cameras.

Provides a simple interface to set FFMPEG options and capture video from an RTSP source.

Example (Dahua)

Example transcode from a Dahua IP camera.

{ //nolint:testableexamples // it's an example.
	dahua := "rtsp://admin:password@192.168.1.12/live" //nolint:gosec // it's an example.
	output := "/tmp/dahua_captured_file.m4v"
	encode := Get(&Config{
		Audio:  true, // retain audio stream
		Time:   10,   // 10 seconds
		Width:  1920,
		Height: 1080,
		CRF:    23,
		Level:  "4.0",
		Rate:   5,
		Prof:   "baseline", // or main or high
	})

	cmd, out, err := encode.SaveVideo(dahua, output, "DahuaVideoTitle")

	log.Println("Command Used:", cmd)
	log.Println("Command Output:", out)

	if err != nil {
		log.Fatalln(err)
	}

	log.Println("Saved file from", dahua, "to", output)
}

Example (SecuritySpy)

Example non-transcode direct-save from securityspy.

{ //nolint:testableexamples // it's an example.
	securitypsy := "rtsp://user:pass@127.0.0.1:8000/++stream?cameraNum=1" //nolint:gosec // it's an example.
	output := "/tmp/securitypsy_captured_file.mov"
	config := &Config{
		FFMPEG: "/usr/local/bin/ffmpeg",
		Copy:   true, // do not transcode
		Audio:  true, // retain audio stream
		Time:   10,   // 10 seconds
	}
	encode := Get(config)
	cmd, out, err := encode.SaveVideo(securitypsy, output, "SecuritySpyVideoTitle")

	log.Println("Command Used:", cmd)
	log.Println("Command Output:", out)

	if err != nil {
		log.Fatalln(err)
	}

	log.Println("Saved file from", securitypsy, "to", output)
}

Index

• Variables
• type Config
• type Encoder
  • func Get(config *Config) *Encoder
  • func (e *Encoder) Config() Config
  • func (e *Encoder) GetVideo(input, title string) (string, io.ReadCloser, error)
  • func (e *Encoder) GetVideoContext(ctx context.Context, input, title string) (string, io.ReadCloser, error)
  • func (e *Encoder) SaveVideo(input, output, title string) (cmdStr, outputStr string, err error)
  • func (e *Encoder) SaveVideoContext(ctx context.Context, input, output, title string) (cmdStr, outputStr string, err error)
  • func (e *Encoder) SetAudio(audio string) bool
  • func (e *Encoder) SetCRF(crf string) int
  • func (e *Encoder) SetHeight(height string) int
  • func (e *Encoder) SetLevel(level string) string
  • func (e *Encoder) SetProfile(profile string) string
  • func (e *Encoder) SetRate(rate string) int
  • func (e *Encoder) SetSize(size string) int64
  • func (e *Encoder) SetTime(seconds string) int
  • func (e *Encoder) SetWidth(width string) int

Examples

• Package (Dahua)
• Package (SecuritySpy)

Variables

var (
	DefaultFrameRate   = 5
	MinimumFrameRate   = 1
	MaximumFrameRate   = 60
	DefaultFrameHeight = 720
	DefaultFrameWidth  = 1280
	MinimumFrameSize   = 100
	MaximumFrameSize   = 5000
	DefaultEncodeCRF   = 21
	MinimumEncodeCRF   = 16
	MaximumEncodeCRF   = 30
	DefaultCaptureTime = 15
	MaximumCaptureTime = 1200             // 10 minute max.
	DefaultCaptureSize = int64(2500000)   // 2.5MB default (roughly 5-10 seconds)
	MaximumCaptureSize = int64(104857600) // 100MB max.
	DefaultFFmpegPath  = "/usr/local/bin/ffmpeg"
	DefaultProfile     = "main"
	DefaultLevel       = "3.0"
)

Default, Maximum and Minimum Values for encoder configuration. Change these if your needs differ.

var (
	ErrInvalidOutput = errors.New("output path is not valid")
	ErrInvalidInput  = errors.New("input path is not valid")
)

Custom errors that this library outputs. The library also outputs errors created elsewhere.

Types

type Config

type Config struct {
	Copy   bool   // Copy original stream, rather than transcode.
	Audio  bool   // include audio?
	Width  int    // 1920
	Height int    // 1080
	CRF    int    // 24
	Time   int    // 15 (seconds)
	Rate   int    // framerate (5-20)
	Size   int64  // max file size (always goes over). use 2000000 for 2.5MB
	FFMPEG string // "/usr/local/bin/ffmpeg"
	Level  string // 3.0, 3.1 ..
	Prof   string // main, high, baseline
}

Config defines how ffmpeg shall transcode a stream. If Copy is true, these options are ignored: profile, level, width, height, crf and frame rate.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder is the struct returned by this library. Contains all the bound methods.

func Get

func Get(config *Config) *Encoder

Get an encoder interface.

func (*Encoder) Config

func (e *Encoder) Config() Config

Config returns the current values in the encoder.

func (*Encoder) GetVideo

func (e *Encoder) GetVideo(input, title string) (string, io.ReadCloser, error)

GetVideo retreives video from an input and returns an io.ReadCloser to consume the output. Input must be an RTSP URL. Title is encoded into the video as the "movie title." Returns command used for diagnostics, io.ReadCloser and error or nil. This will automatically create a context timeout based on the requested capture length. For full timeout control, use GetVideoContext(). If you want to control the context, use GetVideoContext().

func (*Encoder) GetVideoContext

func (e *Encoder) GetVideoContext(ctx context.Context, input, title string) (string, io.ReadCloser, error)

GetVideoContext retreives video from an input and returns an io.ReadCloser to consume the output. Input must be an RTSP URL. Title is encoded into the video as the "movie title." Returns command used for diagnostics, io.ReadCloser and error or nil. Use the context to add a timeout value (max run duration) to the ffmpeg command.

func (*Encoder) SaveVideo

func (e *Encoder) SaveVideo(input, output, title string) (cmdStr, outputStr string, err error)

SaveVideo saves a video snippet to a file. Input must be an RTSP URL and output must be a file path. It will be overwritten. Returns command used for diagnostics, command output and error or nil. This will automatically create a context timeout based on the requested capture length. For full timeout control, use SaveVideoContext(). If you want to control the context, use SaveVideoContext().

func (*Encoder) SaveVideoContext

func (e *Encoder) SaveVideoContext(
	ctx context.Context, input, output, title string,
) (cmdStr, outputStr string, err error)

SaveVideoContext saves a video snippet to a file using a provided context. Input must be an RTSP URL and output must be a file path. It will be overwritten. Returns command used for diagnostics, command output and error or nil. Use the context to add a timeout value (max run duration) to the ffmpeg command.

func (*Encoder) SetAudio

func (e *Encoder) SetAudio(audio string) bool

SetAudio turns audio on or off based on a string value. This can also be passed into Get() as a boolean.

func (*Encoder) SetCRF

func (e *Encoder) SetCRF(crf string) int

SetCRF sets the h264 transcode CRF value from a string. This can also be passed into Get() as an int.

func (*Encoder) SetHeight

func (e *Encoder) SetHeight(height string) int

SetHeight sets the transcode frame width from a string. This can also be passed into Get() as an int.

func (*Encoder) SetLevel

func (e *Encoder) SetLevel(level string) string

SetLevel sets the h264 transcode level. This can also be passed into Get().

func (*Encoder) SetProfile

func (e *Encoder) SetProfile(profile string) string

SetProfile sets the h264 transcode profile. This can also be passed into Get().

func (*Encoder) SetRate

func (e *Encoder) SetRate(rate string) int

SetRate sets the transcode framerate from a string. This can also be passed into Get() as an int.

func (*Encoder) SetSize

func (e *Encoder) SetSize(size string) int64

SetSize sets the maximum transcode file size as a string. This can also be passed into Get() as an int64.

func (*Encoder) SetTime

func (e *Encoder) SetTime(seconds string) int

SetTime sets the maximum transcode duration from a string representing seconds. This can also be passed into Get() as an int.

func (*Encoder) SetWidth

func (e *Encoder) SetWidth(width string) int

SetWidth sets the transcode frame width from a string. This can also be passed into Get() as an int.