ffmpeg

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 13, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package ffmpeg drives the ffmpeg and ffprobe processes that turn a source into a clip, a GIF, a still, or a preview.

Index

Constants

View Source 
const (

	// Height720p is the smallest height still called 720p.
	Height720p = 720
	// Height1080p is the smallest height still called 1080p.
	Height1080p = 1080
	// Height2160p is the smallest height called 4K.
	Height2160p = 2160
)

Variables

View Source 
var (
	// ErrCopyUnavailable reports a clip whose source has no seek point that
	// starts a copy on the keyframe it was planned from.
	ErrCopyUnavailable = errors.New("no seek starts a copy on the keyframe")
	// ErrCopyMismatch reports a copy whose length is not the one planned,
	// so it did not start on the planned keyframe.
	ErrCopyMismatch = errors.New("the copy's length is not the one planned")
	// ErrCopyUnclean reports a copy whose first frames do not decode cleanly,
	// such as one starting on an open GOP keyframe whose leading frames refer
	// to pictures before the cut.
	ErrCopyUnclean = errors.New("the copy does not decode cleanly")
)
View Source 
var (
	// ErrTimeout reports an ffmpeg run that was stopped at its deadline.
	ErrTimeout = errors.New("ffmpeg ran past its time limit")

	// ErrNotStarted reports an ffmpeg that could not be started at all, such
	// as a binary missing from the configured path.
	ErrNotStarted = errors.New("ffmpeg could not be started")
)
View Source 
var (
	// ErrNoOutputPath reports a render asked to write to no path.
	ErrNoOutputPath = errors.New("no output path")

	// ErrEmptyOutput reports a render that finished without writing anything,
	// or without writing a file at all.
	ErrEmptyOutput = errors.New("ffmpeg wrote an empty file")
)

Functions

func ChannelLayoutName 

func ChannelLayoutName(channels int) string

ChannelLayoutName names common speaker layouts.

Parameters:

  • channels: Audio channel count on the source.

Returns:

  • name: The layout's display name, or empty when the count is unknown.

func DynamicRangeLabel 

func DynamicRangeLabel(transfer string) string

DynamicRangeLabel names a color transfer for display.

Parameters:

  • transfer: ffprobe color_transfer of the source.

Returns:

  • label: The transfer's display name, or empty when it is not HDR.

func IsHDRSource 

func IsHDRSource(transfer string) bool

IsHDRSource reports whether a source carries an HDR transfer.

Parameters:

  • transfer: ffprobe color_transfer of the source.

Returns:

  • hdr: True when the source is PQ or HLG.

func PreviewDuration 

func PreviewDuration(duration time.Duration) time.Duration

PreviewDuration caps a preview window so encodes stay cheap.

Parameters:

  • duration: Requested clip duration.

Returns:

  • capped: The window that will actually be encoded.

func SourceQuality 

func SourceQuality(info probe.Info) string

SourceQuality is a short label for what a source's video is.

Parameters:

  • info: Probed information for the source.

Returns:

  • label: The resolution and dynamic range, or empty when neither is known.

func SourceResolutionLabel 

func SourceResolutionLabel(height int) string

SourceResolutionLabel classifies a source height the way a viewer would name it.

Parameters:

  • height: Video height in pixels.

Returns:

  • label: The class name, or empty when the height is unknown.

func SweepStaged added in v0.4.0 

func SweepStaged(cutoff time.Time, dirs ...string) int

SweepStaged removes the staging files and GIF palettes a render left behind.

It looks in each directory for what an interrupted process leaves there. Only files last written before cutoff are removed. ffmpeg keeps writing a staging file while it renders, so a file another process sharing the directory is still rendering is left alone. A missing directory is skipped.

Parameters:

  • cutoff: Files written at or after this time are kept.
  • dirs: Directories renders write to.

Returns:

  • removed: How many files were removed.

Types

type CopyPlan added in v0.4.0 

type CopyPlan struct {
	// HEVC reports that the copied video is HEVC, which an MP4 tags hvc1.
	HEVC bool
	// CopyAudio reports that the audio track is copied too, rather than
	// encoded the way an encoded clip's audio is.
	CopyAudio bool
}

CopyPlan is how a video clip is copied from its source.

func CopyFits added in v0.4.0 

func CopyFits(
	info probe.Info,
	preset clip.QualityPreset,
	rect crop.CropRect,
	audioIndex int,
) (plan CopyPlan, fits bool)

CopyFits reports whether a video clip can be copied from its source.

A copy keeps the source's video as it is, so the source must already be what an encode with the preset would produce. That means no crop, no wider than the preset allows, and in the codec and pixel format the encode would pick. Those are 8-bit 4:2:0 H.264 for SDR, and 10-bit 4:2:0 HEVC for an HDR source the preset keeps HDR for. A Dolby Vision source is never copied.

Parameters:

  • info: The probed source.
  • preset: The clip's encode settings.
  • rect: The black-bar crop detected for the clip.
  • audioIndex: The clip's audio track.

Returns:

  • plan: How to copy the clip.
  • fits: False when the clip has to be encoded.

type ExecFFmpeg 

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

ExecFFmpeg runs the ffmpeg and ffprobe binaries.

func NewExecFFmpeg 

func NewExecFFmpeg(ffmpegPath, ffprobePath string) *ExecFFmpeg

NewExecFFmpeg creates a new FFmpeg executor whose deadline scales with the length of each clip.

Parameters:

  • ffmpegPath: Path to the ffmpeg binary.
  • ffprobePath: Path to the ffprobe binary.

Returns:

  • exec: The executor.

func (*ExecFFmpeg) CopyClip added in v0.4.0 

func (execFFmpeg *ExecFFmpeg) CopyClip(
	ctx context.Context,
	input, output string,
	keyframe, end time.Duration,
	preset clip.QualityPreset,
	audioIndex int,
	plan CopyPlan,
) error

CopyClip copies a clip segment from its source without encoding its video.

The copy starts on keyframe and ends at end. Where a seek lands depends on the demuxer, so the seek point is searched for first, and the copy's length is checked before it is published. The audio is copied or encoded as plan says. Like an encode, the file is written to a staging file and published only once it is complete.

Parameters:

  • ctx: Cancellation and deadline for the copy.
  • input: Source media path.
  • output: Destination mp4 path.
  • keyframe: The keyframe the copy starts on, from ExecFFmpeg.KeyframeBefore.
  • end: Where the clip ends in the source.
  • preset: The clip's encode settings, for the audio bitrate.
  • audioIndex: Audio stream index on the source.
  • plan: How to copy the clip, from CopyFits.

Returns:

func (*ExecFFmpeg) DetectCrop 

func (execFFmpeg *ExecFFmpeg) DetectCrop(
	ctx context.Context,
	input string,
	start, duration time.Duration,
) (crop.CropRect, error)

DetectCrop samples the source with cropdetect and returns a crop rectangle.

Parameters:

  • ctx: Cancellation and deadline for the pass.
  • input: Source media path.
  • start: Seek offset into the source.
  • duration: Length of the clip.

Returns:

  • rect: The detected crop rectangle, or a zero value when there are no bars.
  • err: Non-nil only when the pass failed and produced no usable output.

func (*ExecFFmpeg) ExtractClip 

func (execFFmpeg *ExecFFmpeg) ExtractClip(
	ctx context.Context,
	input, output string,
	start, duration time.Duration,
	preset clip.QualityPreset,
	audioIndex int,
	rect crop.CropRect,
) error

ExtractClip encodes a clip segment, with x265 when it keeps HDR and x264 otherwise.

Parameters:

  • ctx: Cancellation and deadline for the encode.
  • input: Source media path.
  • output: Destination mp4 path.
  • start: Seek offset into the source.
  • duration: Length of the clip.
  • preset: Encode quality, including whether HDR is kept.
  • audioIndex: Audio stream index on the source.
  • rect: Optional black-bar crop.

Returns:

  • err: Non-nil when the clip could not be encoded.

func (*ExecFFmpeg) ExtractGIF 

func (execFFmpeg *ExecFFmpeg) ExtractGIF(
	ctx context.Context,
	input, output string,
	start, duration time.Duration,
	width, fps int,
	rect crop.CropRect,
) error

ExtractGIF extracts a GIF from a video using the palettegen/paletteuse pair.

Parameters:

  • ctx: Cancellation and deadline for the encode.
  • input: Source media path.
  • output: Destination GIF path.
  • start: Seek offset into the source.
  • duration: Length of the GIF window.
  • width: Output width in pixels, or 0 for the default.
  • fps: Output frames per second, or 0 for the default.
  • rect: Optional black-bar crop.

An HDR source is always tone mapped to SDR before the palette is built, because a GIF cannot carry HDR and its untouched pixels would look washed out.

Returns:

  • err: Non-nil when either pass failed.

func (*ExecFFmpeg) ExtractPreview 

func (execFFmpeg *ExecFFmpeg) ExtractPreview(
	ctx context.Context,
	input, output string,
	start, duration time.Duration,
	audioIndex int,
	rect crop.CropRect,
	preset clip.QualityPreset,
) error

ExtractPreview writes a short, downscaled preview segment, encoded like the clip it previews.

Parameters:

  • ctx: Cancellation and deadline for the encode.
  • input: Source media path.
  • output: Destination mp4 path.
  • start: Seek offset into the source.
  • duration: Requested window, capped by PreviewDuration.
  • audioIndex: Audio stream index on the source.
  • rect: Optional black-bar crop.
  • preset: Encode options; only PreserveHDR and MaxWidth are read. A narrower source keeps its width, and a zero MaxWidth caps at 1080p.

Returns:

  • err: Non-nil when the preview could not be encoded.

func (*ExecFFmpeg) ExtractScreenshot 

func (execFFmpeg *ExecFFmpeg) ExtractScreenshot(
	ctx context.Context,
	input, output string,
	timestamp time.Duration,
	rect crop.CropRect,
) error

ExtractScreenshot extracts a screenshot from a video.

Parameters:

  • ctx: Cancellation and deadline for the encode.
  • input: Source media path.
  • output: Destination image path.
  • timestamp: Offset into the source to grab the frame from.
  • rect: Optional black-bar crop.

An HDR source is always tone mapped to SDR, because a JPEG cannot carry HDR and its untouched pixels would look washed out.

Returns:

  • err: Non-nil when the still could not be written.

func (*ExecFFmpeg) KeyframeBefore added in v0.4.0 

func (execFFmpeg *ExecFFmpeg) KeyframeBefore(
	ctx context.Context,
	path string,
	at, window time.Duration,
) (keyframe time.Duration, found bool, err error)

KeyframeBefore finds the last keyframe at or before a time in a source.

Parameters:

  • ctx: Cancellation and deadline for the read.
  • path: Source media path.
  • at: The time the keyframe may not be after.
  • window: How far before at the keyframe may be.

Returns:

  • keyframe: The keyframe's time, rounded up to the millisecond.
  • found: False when no keyframe lies in the window.
  • err: Non-nil when the source cannot be read.

func (*ExecFFmpeg) Probe 

func (execFFmpeg *ExecFFmpeg) Probe(ctx context.Context, path string) (probe.Info, error)

Probe probes a media file for information.

Parameters:

  • ctx: Cancellation and deadline for the probe.
  • path: Media file path.

Returns:

  • info: The probed media information.
  • err: Non-nil when the file cannot be probed.

func (*ExecFFmpeg) WithTimeout added in v0.4.0 

func (execFFmpeg *ExecFFmpeg) WithTimeout(timeout time.Duration) *ExecFFmpeg

WithTimeout returns a copy of the executor that gives every run the same deadline.

Parameters:

  • timeout: The deadline for each run, or zero or less to scale it with the clip.

Returns:

  • exec: The configured copy.

Source Files

View all Source files

Directories

Path Synopsis
Package crop parses ffmpeg cropdetect rectangles.
 Package crop parses ffmpeg cropdetect rectangles.
Package ffmpegtest provides fake ffmpeg and ffprobe binaries for tests.
 Package ffmpegtest provides fake ffmpeg and ffprobe binaries for tests.
Package probe reads what a source file actually is, using ffprobe.
 Package probe reads what a source file actually is, using ffprobe.
Package progress reports ffmpeg encode completion from stderr.
 Package progress reports ffmpeg encode completion from stderr.
Package tonemap builds the ffmpeg filter chain that maps an HDR source down to Rec.709 so a browser renders it the way it was graded.
 Package tonemap builds the ffmpeg filter chain that maps an HDR source down to Rec.709 so a browser renders it the way it was graded.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.