Documentation
¶
Overview ¶
Package ffmpeg locates and drives the bundled FFmpeg binaries.
Index ¶
- Variables
- func CheckExpertArgs(args []string) error
- func Command(ctx context.Context, path string, args ...string) *exec.Cmd
- func ConcatInputArgs(list string) []string
- func DeviceArgs(family string) []string
- func FileInput(path string) []string
- func FlattenFilter(mode string, width, height int) string
- func InContainer() bool
- func OwnGroups() []int
- func ParseRate(s string) int64
- func PartsInput(dir, name string, parts []string) ([]string, error)
- func RedactArgs(args []string) string
- func Run(ctx context.Context, path string, args []string, attrs ...any) ([]byte, *logging.Tail, error)
- func RunLow(cmd *exec.Cmd) error
- func SplitArgs(s string) []string
- func StreamThreads(height int) (decode, encode int)
- func SubfileURL(e dvd.FileExtent) string
- func ToneMapChain(rng string) string
- func ToneMapTo(rng string, maxHeight int) string
- func ValidPreset(v string) bool
- func ValidRate(v string) bool
- func WriteConcat(dir, name string, segs []Segment, streamIDs ...int) (string, error)
- type Format
- type GPUDevice
- type HWEncoder
- type HWStatus
- type Plan
- type Probe
- type Quality
- type Segment
- type Stream
- func (s *Stream) Depth() int
- func (s *Stream) DisplaySize() (w, h int)
- func (s *Stream) DolbyVision() (profile, compat int, ok bool)
- func (s *Stream) DynamicRange() string
- func (s *Stream) FrameRates() (avg, nominal float64)
- func (s *Stream) IsInterlaced() bool
- func (s *Stream) Range() string
- func (s *Stream) StereoMode(path string) string
- type Tools
- func (t *Tools) CanDecode(name string) bool
- func (t *Tools) HardwareStatus() (list []HWStatus, done bool)
- func (t *Tools) HasDemuxer(name string) bool
- func (t *Tools) HasFilter(name string) bool
- func (t *Tools) ImageThumb(ctx context.Context, path string, orientation, width, shrink int, out string) error
- func (t *Tools) KeyframeNear(ctx context.Context, path string, videoIndex int, sec float64) (float64, bool)
- func (t *Tools) MeasureDuration(ctx context.Context, path string) float64
- func (t *Tools) Plan(q Quality) Plan
- func (t *Tools) Poster(ctx context.Context, inputArgs []string, atSec float64, width int, out string) error
- func (t *Tools) ProbeFile(ctx context.Context, path string) (*Probe, error)
- func (t *Tools) ProbeHardware(ctx context.Context)
- func (t *Tools) ProbeInput(ctx context.Context, input []string) (*Probe, error)
- func (t *Tools) StartHardwareProbe()
- func (t *Tools) Still(ctx context.Context, inputArgs []string, atSec float64, width int, out string) error
- func (t *Tools) ToneMapFilter(rng string) string
Constants ¶
This section is empty.
Variables ¶
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.
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 ¶
CheckExpertArgs says whether the expert fields' options are allowed: pairs of an option from the list above and a plain value.
func Command ¶
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 ¶
ConcatInputArgs are the ffmpeg input flags for an ffconcat list of subfiles.
func DeviceArgs ¶
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 ¶
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 ¶
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 ParseRate ¶
ParseRate reads a bitrate such as "8M", "1500k" or "2000000" as bits per second (0 = not a rate).
func PartsInput ¶
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 ¶
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 ¶
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 ¶
SplitArgs splits an option string like a shell would (spaces separate, single or double quotes group). Used for the expert ffmpeg options.
func StreamThreads ¶
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 ¶
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 ¶
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 ¶
ValidPreset reports whether v is a libx264 preset.
func WriteConcat ¶
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 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.
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) SeekMargin ¶
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) Video ¶
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 ¶
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 ¶
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.
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) DisplaySize ¶
DisplaySize is the picture's size as shown: phones store upright video as a sideways frame with a rotation to apply.
func (*Stream) DolbyVision ¶
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 ¶
DynamicRange names what the range alone doesn't say, for the player's information.
func (*Stream) FrameRates ¶
FrameRates reads the stream's average and nominal rates. Either is 0 when not known.
func (*Stream) IsInterlaced ¶
IsInterlaced: the stream says its fields are stored one after the other.
func (*Stream) Range ¶
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 ¶
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 ¶
Tools holds resolved binary paths and encoder capabilities.
func Locate ¶
Locate finds ffmpeg/ffprobe: explicit paths, then beside the executable (bin/, ffmpeg/), then PATH.
func (*Tools) CanDecode ¶
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 ¶
HardwareStatus reports every known hardware encoder (testing still in progress shows as Tested=false).
func (*Tools) HasDemuxer ¶
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 ¶
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 ¶
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) 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) ProbeHardware ¶
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 ¶
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 ¶
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).