ffmpeg

package
v0.8.0-alpha Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package ffmpeg locates and drives the bundled FFmpeg binaries.

Index

Constants

This section is empty.

Variables

View Source
var HWEncoders = []HWEncoder{
	{"h264_nvenc", "NVIDIA NVENC", "nvidia"},
	{"h264_qsv", "Intel Quick Sync", "intel"},
	{"h264_videotoolbox", "Apple VideoToolbox", "apple"},
	{"h264_amf", "AMD AMF (VCE/VCN)", "amd"},
	{"h264_vaapi", "VAAPI (Linux: Intel/AMD)", "vaapi"},
}

HWEncoders in default preference order.

View Source
var VideoToolboxQuality = runtime.GOARCH == "arm64"

VideoToolboxQuality says VideoToolbox takes a constant quality (-q:v). FFmpeg allows that on Apple silicon only: an Intel Mac's FFmpeg refuses to open the encoder with it ("-q:v qscale not available for encoder. Use -b:v bitrate instead."), so there it's given a bitrate. The server and the FFmpeg it uses are built for the same chip. A variable, for the tests.

Functions

func CheckExpertArgs

func CheckExpertArgs(args []string) error

CheckExpertArgs says whether the expert fields' options are allowed: pairs of an option from the list above and a plain value.

func Command

func Command(ctx context.Context, path string, args ...string) *exec.Cmd

Command prepares an ffmpeg/ffprobe process. On Windows it never opens a console window (the server often runs without one, from the tray).

func ConcatInputArgs

func ConcatInputArgs(list string) []string

ConcatInputArgs are the ffmpeg input flags for an ffconcat list of subfiles.

func DeviceArgs

func DeviceArgs(family string) []string

DeviceArgs are the input options that give a hardware encoder family (vaapi, qsv) the device found for it, nil for one that needs none.

func FileInput

func FileInput(path string) []string

FileInput opens a file from a library as input. Only local file reading is allowed, and only as a real media format (see libraryFormats): a downloaded "video" that is really a playlist must not make the server fetch addresses on the network, or read other files.

func FlattenFilter

func FlattenFilter(mode string, width, height int) string

FlattenFilter keeps the left eye of a 3D picture. A half-width pair is stretched back to its proper shape; a full-width one is simply cut in two.

func InContainer

func InContainer() bool

InContainer says whether the server runs in a container (the image sets WMS_DOCKER=1; Docker and Podman leave a file at the root too).

func OwnGroups

func OwnGroups() []int

OwnGroups are the process's group IDs, its main one first.

func ParseRate

func ParseRate(s string) int64

ParseRate reads a bitrate such as "8M", "1500k" or "2000000" as bits per second (0 = not a rate).

func PartsInput

func PartsInput(dir, name string, parts []string) ([]string, error)

PartsInput opens the files of a split film as one input. Only files can be read, and the list is written here from names that were checked. Each part is held to the formats a file from a library may be, and the list format has to be among them for this one to open, so a part whose bytes are a list is stopped by looking, as a disc's cells are.

func RedactArgs

func RedactArgs(args []string) string

RedactArgs is a command line for the log, without the headers and logins a stream's input options can carry.

func Run

func Run(ctx context.Context, path string, args []string, attrs ...any) ([]byte, *logging.Tail, error)

Run runs a short FFmpeg or ffprobe job and waits for it, returning its output and what it said. It leaves a record of how the job ended, tied to the session in ctx (see logging.WithSession); attrs say what it was for.

func RunLow

func RunLow(cmd *exec.Cmd) error

RunLow starts another program the way background FFmpeg jobs are started, at a lower priority so it has the processor only when nothing else wants it, and waits for it. For the helper programs an owner installs (a stem separator), which can run for minutes.

func SplitArgs

func SplitArgs(s string) []string

SplitArgs splits an option string like a shell would (spaces separate, single or double quotes group). Used for the expert ffmpeg options.

func StreamThreads

func StreamThreads(height int) (decode, encode int)

StreamThreads is how many threads the decoder and libx264 get for a stream someone is watching, whose picture comes out this many lines high (0 when that isn't known, which is taken as 1080 or less). 0 leaves it to FFmpeg.

FFmpeg starts a decoding thread for each processor thread and libx264 one and a half, and each of them holds pictures of its own. On a 20-thread machine a 1080p conversion held 1.1 GB that way and 530 MB with eight threads, for the same processor time and still five times faster than real time; a 4K one held 3.9 GB, and 2.5 GB with sixteen. On a machine with eight processor threads or fewer, FFmpeg's own choice is about this anyway, and speed matters more there.

func SubfileURL

func SubfileURL(e dvd.FileExtent) string

SubfileURL builds a subfile protocol URL for one extent.

func ToneMapChain

func ToneMapChain(rng string) string

ToneMapChain is the chain itself: linear light, a Hable curve, then BT.709. The frames are told first what they are, because a file may only say so in its container, and without that zscale stops with "no path between colorspaces". They're told afterwards as well, so the encoder marks what comes out as an ordinary picture.

func ToneMapTo

func ToneMapTo(rng string, maxHeight int) string

ToneMapTo is that chain, bringing the picture down to at most maxHeight lines (0 = as it is) on the way into linear light, so the rest of it works on the smaller picture. Mapping works in floating point on every pixel: a 4K film shown at 1080p was mapped at its full size and then shrunk, which took 69 processor seconds for 10 seconds of it, and 43 this way.

func ValidPreset

func ValidPreset(v string) bool

ValidPreset reports whether v is a libx264 preset.

func ValidRate

func ValidRate(v string) bool

ValidRate reports whether v is empty or a bitrate like 8M or 192k.

func WriteConcat

func WriteConcat(dir, name string, segs []Segment, streamIDs ...int) (string, error)

WriteConcat writes an ffconcat list for the segments into dir and returns the list path. Multi-extent segments get a concatf side file.

streamIDs, when given, pin the output streams to these MPEG-PS stream ids (in this order). Without them the concat demuxer pairs streams by position, and DVD VOBs do not list their streams in a stable order: an interleaved cell may announce subtitles before audio, which then silently swaps the audio track for a subtitle stream for the length of that cell.

Types

type Format

type Format struct {
	Filename   string            `json:"filename"`
	FormatName string            `json:"format_name"`
	Duration   string            `json:"duration"`
	StartTime  string            `json:"start_time"`
	Size       string            `json:"size"`
	BitRate    string            `json:"bit_rate"`
	Tags       map[string]string `json:"tags"`
}

type GPUDevice

type GPUDevice struct {
	Path    string `json:"path"`              // /dev/dri/renderD128, /dev/nvidia0, /dev/dxg
	Vendor  string `json:"vendor,omitempty"`  // intel | amd | nvidia | other, when the system says
	Driver  string `json:"driver,omitempty"`  // the kernel's driver: i915, xe, amdgpu, nvidia
	Group   int    `json:"group"`             // the group ID that owns it, -1 when unknown
	Mode    string `json:"mode,omitempty"`    // its permissions, such as 0660
	Usable  bool   `json:"usable"`            // the server opened it
	Problem string `json:"problem,omitempty"` // why it can't be used, in plain words
	Fix     string `json:"fix,omitempty"`     // what to do about it
}

GPUDevice is a graphics device the server can see, and whether it may use it. Hardware encoders fail in ways FFmpeg doesn't explain ("No VA display found"), so the server looks at the device itself: a container that can't open the render node is the usual reason, and the fix is one line of the compose file.

func FindGPUs

func FindGPUs() []GPUDevice

FindGPUs lists the graphics devices in /dev and whether the server can open each: render nodes for VA-API and Quick Sync, NVIDIA's nodes, and WSL's /dev/dxg. Opening one is a few system calls, no process.

func GPUs

func GPUs() []GPUDevice

GPUs are the graphics devices found by the last hardware test.

type HWEncoder

type HWEncoder struct {
	Name   string `json:"name"`   // ffmpeg encoder name
	Label  string `json:"label"`  // shown in the UI
	Vendor string `json:"vendor"` // nvidia | intel | amd | apple | vaapi
}

HWEncoder describes a hardware H.264 encoder WittyMediaServer can use.

type HWStatus

type HWStatus struct {
	HWEncoder
	Compiled bool   `json:"compiled"`
	Tested   bool   `json:"tested"`
	Working  bool   `json:"working"`
	Error    string `json:"error,omitempty"`  // the end of FFmpeg's message
	Reason   string `json:"reason,omitempty"` // why it can't be used, in plain words
	Device   string `json:"device,omitempty"` // the device it uses or was tried on
}

HWStatus says whether an encoder is compiled into ffmpeg and actually works on this machine (ffmpeg lists encoders it was built with even when the GPU or driver is missing, so each one is test-encoded).

type Plan

type Plan struct {
	Name      string   // ffmpeg encoder
	Args      []string // encoder options
	PixFmt    string   // software pixel format fed to the encoder
	InputArgs []string // options placed before -i (device setup)
	Upload    string   // filter appended after format= (hwupload for VAAPI)
}

Plan is everything needed to run one encoder.

type Probe

type Probe struct {
	Streams  []Stream `json:"streams"`
	Format   Format   `json:"format"`
	Chapters []struct {
		Start string            `json:"start_time"`
		End   string            `json:"end_time"`
		Tags  map[string]string `json:"tags"`
	} `json:"chapters"`
}

func (*Probe) Audio

func (p *Probe) Audio() []Stream

func (*Probe) Duration

func (p *Probe) Duration() float64

func (*Probe) SeekMargin

func (p *Probe) SeekMargin() float64

SeekMargin is how far ahead of a start to begin reading this file, for hls.Spec.SeekMargin: transport and program streams have no index to seek by.

func (*Probe) Subtitles

func (p *Probe) Subtitles() []Stream

func (*Probe) Video

func (p *Probe) Video() *Stream

Video is the file's picture: its first video stream that really is one. A file may also carry cover art, stored as a one-frame video stream, ahead of it.

func (*Probe) VideoIndex

func (p *Probe) VideoIndex() int

VideoIndex is the number among the file's video streams (v:N) of the one Video returns. Picking "the first video stream" would pick the cover art of some files.

func (*Probe) VideoStreams

func (p *Probe) VideoStreams() []Stream

VideoStreams lists the streams that are pictures, without cover art.

type Quality

type Quality struct {
	// HW lists the hardware encoders the admin enabled; the first one that
	// works on this machine is used, else libx264.
	HW        []string
	Preset    string // libx264 preset (ultrafast … slow); "" = veryfast
	CRF       int    // constant quality (lower = better); 0 = 21. Mapped onto each hardware encoder's scale.
	MaxRate   string // e.g. "8M": cap the bitrate (helps remote/slow networks)
	AudioRate string // e.g. "192k"; "" = 192k stereo / 384k surround
	// CapRate is a hard limit on the video bitrate, e.g. "4M" (see WithCap).
	// Every encoder is told in the way it really obeys, and expert options
	// can't lift it.
	CapRate string
	// Expert mode: replaces the encoder options (after -c:v) entirely, and
	// extra output options appended before the HLS muxer options.
	VideoArgs  []string
	OutputArgs []string
}

Quality is the transcode quality profile chosen in Settings.

func (Quality) WithCap

func (q Quality) WithCap(total string) Quality

WithCap applies a total bitrate limit (video and sound together, e.g. "4M") to a profile: sound stays within it, the video gets the rest, and a lower limit chosen in Settings still counts.

type Segment

type Segment struct {
	Extents  []dvd.FileExtent
	Duration float64 // seconds, 0 = unknown
	// Lead is how long before its first picture a segment's earliest packet
	// lies (seconds): usually sound, stored ahead of its picture, up to a
	// quarter of a second on a DVD, a different amount in every segment. The
	// concat demuxer puts a segment on the timeline by that earliest packet, so
	// without this the picture lands late by that much, and each join repeats
	// or drops frames and sound. (The demuxer's inpoint would say the same thing
	// directly, but it seeks to get there, and that can land a whole group of
	// pictures in.)
	Lead float64
	// Outpoint is the time on the segment's own clock (seconds) to stop reading at,
	// when its bytes run on further than it needs; 0 reads them all. FFmpeg stops at
	// the first packet of any stream that is decoded at this time or later, so it
	// doesn't end a segment on a chosen frame.
	Outpoint float64
}

Segment is one playable run of bytes with a known duration.

type Stream

type Stream struct {
	Index       int               `json:"index"`
	ID          string            `json:"id"`
	CodecType   string            `json:"codec_type"`
	CodecName   string            `json:"codec_name"`
	PixFmt      string            `json:"pix_fmt"`
	Width       int               `json:"width"`
	Height      int               `json:"height"`
	Channels    int               `json:"channels"`
	SampleRate  string            `json:"sample_rate"`
	FieldOrder  string            `json:"field_order"`
	SAR         string            `json:"sample_aspect_ratio"`
	DAR         string            `json:"display_aspect_ratio"`
	Tags        map[string]string `json:"tags"`
	Disposition map[string]int    `json:"disposition"`
	Duration    string            `json:"duration"`
	// For playback decisions.
	Profile       string           `json:"profile"`
	Level         int              `json:"level"`
	ColorTransfer string           `json:"color_transfer"`
	BitRate       string           `json:"bit_rate"`
	BitsPerSample string           `json:"bits_per_raw_sample"`
	CodecTag      string           `json:"codec_tag_string"`
	SideData      []map[string]any `json:"side_data_list"`
	// Frame rates as fractions, and whether captions are carried inside the picture.
	RFrameRate     string `json:"r_frame_rate"`
	AvgFrameRate   string `json:"avg_frame_rate"`
	ClosedCaptions int    `json:"closed_captions"`
}

func (*Stream) Depth

func (s *Stream) Depth() int

Depth is the bits per colour sample.

func (*Stream) DisplaySize

func (s *Stream) DisplaySize() (w, h int)

DisplaySize is the picture's size as shown: phones store upright video as a sideways frame with a rotation to apply.

func (*Stream) DolbyVision

func (s *Stream) DolbyVision() (profile, compat int, ok bool)

DolbyVision finds the stream's Dolby Vision record: its profile and the kind of base layer other players can show. ok is false for a stream without one.

func (*Stream) DynamicRange

func (s *Stream) DynamicRange() string

DynamicRange names what the range alone doesn't say, for the player's information.

func (*Stream) FrameRates

func (s *Stream) FrameRates() (avg, nominal float64)

FrameRates reads the stream's average and nominal rates. Either is 0 when not known.

func (*Stream) IsInterlaced

func (s *Stream) IsInterlaced() bool

IsInterlaced: the stream says its fields are stored one after the other.

func (*Stream) Range

func (s *Stream) Range() string

Range classes the picture: sdr, hdr10 (PQ), hlg or dv5. Dolby Vision with a base layer other players can show counts as that base layer; profile 5 has none (its colours come out wrong without a Dolby Vision decoder).

func (*Stream) StereoMode

func (s *Stream) StereoMode(path string) string

StereoMode finds a 3D picture stored in one frame, from what the file says or the way such files are named: sbs (side by side), tab (one above the other), or "".

type Tools

type Tools struct {
	FFmpeg   string
	FFprobe  string
	Encoders map[string]bool
	Version  string
}

Tools holds resolved binary paths and encoder capabilities.

func Locate

func Locate(ffmpegPath, ffprobePath string) (*Tools, error)

Locate finds ffmpeg/ffprobe: explicit paths, then beside the executable (bin/, ffmpeg/), then PATH.

func (*Tools) CanDecode

func (t *Tools) CanDecode(name string) bool

CanDecode says whether this FFmpeg has a decoder by this name. Builds differ: AC-4, for one, is in none we ship today. When it can't be found out, the answer is yes, and FFmpeg itself has the last word.

func (*Tools) HardwareStatus

func (t *Tools) HardwareStatus() (list []HWStatus, done bool)

HardwareStatus reports every known hardware encoder (testing still in progress shows as Tested=false).

func (*Tools) HasDemuxer

func (t *Tools) HasDemuxer(name string) bool

HasDemuxer says whether this FFmpeg can read an input of this name, found by asking it once it has answered. An FFmpeg that can't be asked has none, for now.

func (*Tools) HasFilter

func (t *Tools) HasFilter(name string) bool

HasFilter says whether this FFmpeg has a video filter, found by asking `ffmpeg -filters` once it has answered. A machine too busy to answer in time hasn't said it has none: remembering that would leave HDR flat and dim until the next restart.

func (*Tools) ImageThumb

func (t *Tools) ImageThumb(ctx context.Context, path string, orientation, width, shrink int, out string) error

ImageThumb makes a JPEG of a picture, at most width pixels along its longer side, upright according to its EXIF orientation (1 to 8; 0 means as stored). shrink halves a JPEG that many times while decoding (0 to 3). Rotation is always done here rather than by FFmpeg, whose handling differs by version.

func (*Tools) KeyframeNear

func (t *Tools) KeyframeNear(ctx context.Context, path string, videoIndex int, sec float64) (float64, bool)

KeyframeNear finds where a copy that starts at this time really starts: the first keyframe FFmpeg reaches after seeking there. No keyframe found says so.

func (*Tools) MeasureDuration

func (t *Tools) MeasureDuration(ctx context.Context, path string) float64

MeasureDuration reads a file through without decoding it, for what doesn't say how long it is: a bare stream with no container. 0 means it couldn't be found out.

func (*Tools) Plan

func (t *Tools) Plan(q Quality) Plan

Plan picks the encoder for a quality profile.

func (*Tools) Poster

func (t *Tools) Poster(ctx context.Context, inputArgs []string, atSec float64, width int, out string) error

Poster makes a title's picture from about atSec into it: the keyframe before that point, read on one thread. A title's picture doesn't need the exact frame, and going straight to a keyframe takes a tenth of the work and a third of the memory of decoding up to the moment on every core (measured on a 7 GB film: 110 ms and 77 MB against 2560 ms and 219 MB). If that finds nothing, it's Still.

func (*Tools) ProbeFile

func (t *Tools) ProbeFile(ctx context.Context, path string) (*Probe, error)

ProbeFile runs ffprobe on a regular media file.

func (*Tools) ProbeHardware

func (t *Tools) ProbeHardware(ctx context.Context)

ProbeHardware looks at the graphics devices, then test-encodes a few frames with every compiled hardware encoder that could work with them.

func (*Tools) ProbeInput

func (t *Tools) ProbeInput(ctx context.Context, input []string) (*Probe, error)

ProbeInput runs ffprobe on input options built by the caller (a TV stream).

func (*Tools) StartHardwareProbe

func (t *Tools) StartHardwareProbe()

StartHardwareProbe test-encodes in the background, once. It starts with the server only if hardware encoding is switched on, else when Settings first asks: on a small machine every test is a process that starts up, looks for a device and fails.

func (*Tools) Still

func (t *Tools) Still(ctx context.Context, inputArgs []string, atSec float64, width int, out string) error

Still grabs one frame as JPEG/PNG (by extension of out). inputArgs is everything up to and including -i; atSec seeks (input-side) when > 0.

func (*Tools) ToneMapFilter

func (t *Tools) ToneMapFilter(rng string) string

ToneMapFilter is the filter chain that turns HDR (BT.2020 PQ or HLG) video into SDR BT.709 for displays and encoders that cannot show HDR. rng says which it is, as Stream.Range does. Empty when this FFmpeg lacks the filters, in which case the picture plays unmapped (flat and dim, but watchable).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL