Files
filebrowser/backend/internal/transcoding/engine.go
T

515 lines
18 KiB
Go

package transcoding
import (
"context"
"fmt"
"os"
"strings"
"github.com/gtsteffaniak/go-ffmpeg/capabilities"
"github.com/gtsteffaniak/go-ffmpeg/encode"
"github.com/gtsteffaniak/go-logger/logger"
"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
"github.com/gtsteffaniak/filebrowser/backend/pkg/settings"
)
// maxCopySegmentDurationSec caps remux/video-copy segment length; sparse keyframe
// indexes otherwise plan multi-minute #EXTINF values and MSE-hostile fMP4.
func maxCopySegmentDurationSec(segmentSec float64) float64 {
cap := segmentSec * 3
if cap < 12 {
cap = 12
}
return cap
}
func vodMaxSegmentDuration(list ffmpeg.VODSegmentList) float64 {
var max float64
for _, d := range list.Durations {
if d > max {
max = d
}
}
return max
}
// MediaEngine adapts the ffmpeg service for HLS transcoding.
type MediaEngine struct{}
// VODJob is a running ffmpeg HLS VOD encode.
type VODJob interface {
Cancel()
Wait() error
// Running reports whether ffmpeg is still active (non-blocking).
Running() bool
// VTDecodeUnreliable reports sustained VideoToolbox hardware decode failures
// in ffmpeg stderr — a signal to restart the job with software decode.
VTDecodeUnreliable() bool
}
// Engine performs probe/plan/start operations for tests and production.
type Engine interface {
Available() bool
BuildPlan(ctx context.Context, realPath string, profile Profile) (hlsPlan, error)
StartVODJob(ctx context.Context, realPath, outputDir string, plan hlsPlan, startIndex int, session *ffmpeg.HLSVODSession) (VODJob, error)
}
func NewMediaEngine() *MediaEngine {
return &MediaEngine{}
}
var _ Engine = (*MediaEngine)(nil)
func (e *MediaEngine) Available() bool {
return ffmpeg.Enabled() && settings.TranscodeEnabled()
}
func (e *MediaEngine) ProbeFile(ctx context.Context, path string) (ffmpeg.StreamInfo, error) {
svc := ffmpeg.Get()
if svc == nil {
return ffmpeg.StreamInfo{}, ErrUnavailable
}
return svc.ProbeMediaStream(ctx, path)
}
func (e *MediaEngine) BuildPlan(ctx context.Context, realPath string, profile Profile) (plan hlsPlan, err error) {
info, err := e.ProbeFile(ctx, realPath)
if err != nil {
return plan, err
}
if !info.HasVideo && !info.HasAudio {
return plan, ErrUnsupportedMedia
}
stat, statErr := os.Stat(realPath)
if statErr != nil {
return plan, statErr
}
pipeline := ffmpeg.HLSPipelineOptions{
MaxHeight: maxHeightForProfile(profile),
}
mustTranscode := profileForcesVideoTranscode(profile) ||
profileRequiresBitrateTranscode(profile, info) ||
(pipeline.MaxHeight > 0 && info.Height > pipeline.MaxHeight)
pipeline.ForceVideoTranscode = mustTranscode
buildIn := ffmpeg.BuildHLSSegmentBuildInput(info, pipeline)
defaults := ffmpeg.DefaultOnDemandHLSDefaults()
svc := ffmpeg.Get()
if svc == nil {
return plan, ErrUnavailable
}
params, err := svc.BuildHLSSegmentParams(ctx, realPath, buildIn, true)
if err != nil {
return plan, err
}
// No audio stream to carry — keep it out of the ffmpeg args and reflect it
// in the cache fingerprint instead of relying on the optional -map probe.
params.OmitAudio = !info.HasAudio
plan.info = info
plan.params = params
plan.profileMode = string(profile)
plan.maxHeight = maxHeightForProfile(profile)
plan.avgBitrateKbps = avgBitrateForProfile(profile)
plan.remux = params.Remux
plan.videoCopy = params.VideoCopy
plan.needsTranscode = mustTranscode || (!plan.remux && !plan.videoCopy)
if plan.needsTranscode {
plan.setTranscodeProfiles(ctx, svc, realPath, profile)
} else {
plan.encoderName = "copy"
}
var keyframes []float64
// copyImpossible is set when the keyframe timeline cannot support stream
// copy: either the pre-flight window already contains a gap past the copy
// cap, or the probe itself failed. Both cases fail safe toward transcode,
// since a copy plan with multi-minute #EXTINF values is unplayable.
copyImpossible := false
plan.segmentSec = defaults.SegmentDurationSec
if plan.remux || plan.videoCopy {
rawKeyframes, kfErr := probeKeyframesCached(ctx, svc, realPath, stat.Size(), stat.ModTime().UnixNano(), plan.segmentSec, true)
if kfErr != nil {
copyImpossible = true
logger.Warningf("transcode: keyframe probe failed on %s (%v) — forcing video transcode for HLS", realPath, kfErr)
} else if len(rawKeyframes) == 0 {
// Pre-flight (or a keyframe-free stream) proved copy impossible
// without paying for the full-file demux.
copyImpossible = true
} else {
keyframes, _ = ffmpeg.PrepareHLSMediaTimeline(rawKeyframes, info.Duration, info.StartTime)
}
}
plan.buildTimeline(keyframes)
if plan.mediaDurationSec <= 0 {
return plan, ErrUnsupportedMedia
}
if (plan.remux || plan.videoCopy) && (copyImpossible || vodMaxSegmentDuration(plan.vodList) > maxCopySegmentDurationSec(plan.segmentSec)) {
logger.Infof(
"transcode: longest keyframe segment %.1fs exceeds %.1fs cap on %s — forcing video transcode for HLS",
vodMaxSegmentDuration(plan.vodList),
maxCopySegmentDurationSec(plan.segmentSec),
realPath,
)
pipeline.ForceVideoTranscode = true
buildIn = ffmpeg.BuildHLSSegmentBuildInput(info, pipeline)
params, err = svc.BuildHLSSegmentParams(ctx, realPath, buildIn, true)
if err != nil {
return plan, err
}
params.OmitAudio = !info.HasAudio
plan.params = params
plan.remux = params.Remux
plan.videoCopy = params.VideoCopy
plan.needsTranscode = true
plan.setTranscodeProfiles(ctx, svc, realPath, profile)
plan.buildTimeline(nil)
}
cacheID := ffmpeg.HLSCacheIdentity{
SourcePath: realPath,
FileSize: stat.Size(),
FileModTime: stat.ModTime().UnixNano(),
Profile: plan.profileMode,
MaxResolution: plan.maxHeight,
MaxBitrate: plan.avgBitrateKbps,
SegmentDurationSec: plan.segmentSec,
Params: params,
}
// Generations produced before the publisher model serve corrupt or
// unverifiable timelines, so the cache namespace is versioned.
plan.cacheFingerprint = "vod-" + ffmpeg.HLSCacheFingerprint(cacheID)
return plan, nil
}
// setTranscodeProfiles resolves the encode/decode profiles for a transcode plan.
func (plan *hlsPlan) setTranscodeProfiles(ctx context.Context, svc *ffmpeg.Service, realPath string, profile Profile) {
plan.encodeProfile = encodeProfileForMode(plan.info, profile)
plan.decodeProfile = ffmpeg.HLSDecodeProfileForOnDemand(plan.info)
if !settings.HardwareAccelerationEnabled() {
plan.decodeProfile.ForceSoftware = true
}
if sel, err := svc.ResolveVideoEncoder(plan.encodeProfile); err == nil {
plan.encoderName = sel.Encoder
plan.accelName = string(sel.Accel)
}
logEncoderChoice(realPath, profile, plan.encodeProfile, plan.encoderName, plan.accelName, svc)
// Hardware encoder limit checks need output height AND frame rate;
// OutputHeight comes from DefaultHLSVideoProfile, fps from the probe.
if fps, ferr := svc.ProbeVideoFPS(ctx, realPath); ferr == nil && fps > 0 {
plan.encodeProfile.FrameRate = fps
}
}
// buildTimeline plans the VOD segment list, media duration and playlist body
// from the probed info and the (already prepared) keyframes; nil keyframes
// select the fixed transcode grid.
func (plan *hlsPlan) buildTimeline(keyframes []float64) {
info := plan.info
plan.keyframes = keyframes
_, plan.mediaDurationSec = ffmpeg.PrepareHLSMediaTimeline(nil, info.Duration, info.StartTime)
// Duration and keyframes are already on the 0-based media timeline; passing
// the container start_time again would shift every boundary by it.
plan.vodList = ffmpeg.BuildVODSegmentList(plan.mediaDurationSec, plan.segmentSec, 0, keyframes)
if n := plan.vodList.Count(); n > 0 {
last := n - 1
plan.mediaDurationSec = plan.vodList.Starts[last] + plan.vodList.Durations[last]
}
plan.playlistBody = ffmpeg.BuildVODPlaylist(plan.vodList, ffmpeg.DefaultVODPlaylistOptions())
}
func (e *MediaEngine) StartVODJob(ctx context.Context, realPath, outputDir string, plan hlsPlan, startIndex int, session *ffmpeg.HLSVODSession) (VODJob, error) {
svc := ffmpeg.Get()
if svc == nil {
return nil, ErrUnavailable
}
opts := ffmpeg.HLSVODJobOptions{
Input: ffmpeg.InputSource{
URL: realPath,
StreamType: ffmpeg.StreamFile,
},
OutputDir: outputDir,
StartIndex: startIndex,
StartSec: vodPlaylistStartSec(plan, startIndex),
SegmentSec: plan.segmentSec,
InputStartTimeSec: plan.info.StartTime,
KeyframeSeekTimes: plan.keyframes,
Decode: plan.decodeProfile,
Profile: plan.encodeProfile,
MaxHeight: plan.maxHeight,
Remux: plan.remux,
VideoCopy: plan.videoCopy,
GOP: plan.params.GOP,
InputVideoCodec: plan.info.VideoCodec,
OmitAudio: plan.params.OmitAudio,
Throttle: settings.TranscodeThrottleConfig(),
ClearSegmentsFromIndex: plan.vodClearFromIndex,
Session: session,
}
if planUsesExplicitCopy(plan) {
// Explicit-cut copy jobs align restarts to the synthetic playlist grid
// via -f segment -segment_times and the live .ffmpeg-vod-segments.csv.
opts.SegmentList = &plan.vodList
opts.StopIndex = copyJobStopIndex(startIndex, plan.vodList.Count())
}
job, err := svc.StartHLSVODSegmentJob(ctx, opts)
if err != nil {
return nil, err
}
return job, nil
}
// copyLookaheadSegments bounds how far a stream-copy job runs ahead of where it
// started. Copy jobs are I/O-bound and otherwise race to EOF, writing the whole
// file into the cache regardless of the playhead. A bounded job ends cleanly,
// the producer parks, and the next segment request relaunches it.
const copyLookaheadSegments = 15
// copyJobStopIndex returns the segment index a copy job should stop before, or
// 0 (unbounded) when the window already covers the rest of the file.
func copyJobStopIndex(startIndex, count int) int {
stop := startIndex + copyLookaheadSegments
if stop >= count {
return 0
}
return stop
}
type hlsPlan struct {
info ffmpeg.StreamInfo
params ffmpeg.HLSSegmentParams
profileMode string
maxHeight int
avgBitrateKbps int
remux bool
videoCopy bool
needsTranscode bool
encodeProfile encode.VideoProfile
decodeProfile ffmpeg.VideoDecodeProfile
encoderName string
accelName string
keyframes []float64
segmentSec float64
mediaDurationSec float64
cacheFingerprint string
vodList ffmpeg.VODSegmentList
playlistBody string
vodClearFromIndex bool
}
// maxHeightForProfile returns the configured output height cap for a profile.
// Zero means "keep the source resolution".
func maxHeightForProfile(profile Profile) int {
cfg, ok := settings.TranscodeProfileConfig(string(profile))
if !ok {
return 0
}
return cfg.MaxResolution
}
func avgBitrateForProfile(profile Profile) int {
cfg, ok := settings.TranscodeProfileConfig(string(profile))
if !ok {
return 0
}
return cfg.AvgBitrateKbps
}
// profileForcesVideoTranscode reports whether the profile always re-encodes.
// Quality preserves the source whenever stream copy is possible; the smaller
// profiles always transcode so output is normalized h264 video plus AAC stereo
// audio at a bounded bitrate, regardless of how the source was encoded.
func profileForcesVideoTranscode(profile Profile) bool {
return profile != ProfileQuality
}
// profileRequiresBitrateTranscode reports whether the profile pins a bitrate cap
// below the source. Stream copy would silently ignore the cap, so a full video
// re-encode is required to honor the profile.
func profileRequiresBitrateTranscode(profile Profile, info ffmpeg.StreamInfo) bool {
cfg, ok := settings.TranscodeProfileConfig(string(profile))
if !ok || cfg.AvgBitrateKbps <= 0 {
return false
}
return info.VideoBitrate <= 0 || info.VideoBitrate/1000 > cfg.AvgBitrateKbps
}
func encodeProfileForMode(info ffmpeg.StreamInfo, profile Profile) encode.VideoProfile {
cfg, _ := settings.TranscodeProfileConfig(string(profile))
maxHeight := cfg.MaxResolution
// The scale filter can only cap the height, never upscale, so a cap above the
// source resolution must not be used to pick a higher bitrate rung.
if maxHeight <= 0 || (info.Height > 0 && info.Height < maxHeight) {
maxHeight = info.Height
}
base := ffmpeg.DefaultHLSVideoProfile(maxHeight)
switch profile {
case ProfileDataSaver:
base.Quality = encode.PresetVeryfast
case ProfileBalanced:
base.Quality = encode.PresetFast
default:
base.Quality = encode.PresetMedium
}
base.Bitrate = transcodeBitrateConfig(cfg, info, maxHeight)
accel, encoder := preferredEncoderSelection(profile)
base.Accel = accel
base.Encoder = encoder
return base
}
// logEncoderChoice records which encoder a plan will actually use. A software
// encoder chosen despite available hardware is the single most confusing
// transcode outcome (the job is orders of magnitude slower), so that case is
// logged at info with the reason; a normal hardware/copy choice stays at debug.
func logEncoderChoice(realPath string, profile Profile, p encode.VideoProfile, encoderName, accelName string, svc *ffmpeg.Service) {
requested := settings.TranscodeEncoderBackend(string(profile))
software := accelName == "" || accelName == string(capabilities.AccelNone) || accelName == "copy"
if software {
if requested != "" && requested != "auto" && requested != "cpu" {
logger.Warningf("transcode: encoder backend %q is unavailable for profile %s; falling back to automatic selection (%s)", requested, profile, realPath)
} else if hardwareEncodeAvailable(svc.Capabilities()) {
logger.Infof("transcode: using software encoder %q (%s) for profile=%s though hardware encode is available; check the configured accel device and encoder backend (%s)",
encoderName, requestedLabel(requested), profile, realPath)
} else {
logger.Infof("transcode: using software encoder %q for profile=%s (no hardware encoder available) (%s)", encoderName, profile, realPath)
}
return
}
logger.Infof("transcode: using encoder %q (accel=%s) for profile=%s (%s)", encoderName, accelName, profile, realPath)
}
func requestedLabel(requested string) string {
if requested == "" {
return "auto"
}
return requested
}
// hardwareEncodeAvailable reports whether any detected hardware path can encode
// h264 — the codec every transcode profile outputs.
func hardwareEncodeAvailable(caps *capabilities.Capabilities) bool {
if caps == nil {
return false
}
for _, accel := range []capabilities.AccelType{
capabilities.AccelNVENC,
capabilities.AccelAMF,
capabilities.AccelQSV,
capabilities.AccelVAAPI,
capabilities.AccelD3D12,
capabilities.AccelVideoToolbox,
} {
if caps.CodecEncodeAvailable(capabilities.CodecH264, accel) {
return true
}
}
return false
}
// preferredEncoderSelection resolves the configured encoder backend for a profile:
// preset override, then the transcode-level default, then auto. "cpu" forces
// software; legacy accel names (vaapi, nvenc, …) select that backend; an
// explicit ffmpeg encoder name pins the encoder. Unavailable choices degrade to
// auto instead of failing jobs.
func preferredEncoderSelection(profile Profile) (capabilities.AccelType, string) {
// Hardware detection runs once at startup; the admin toggle is applied here,
// per transcode, so changing it takes effect immediately without re-probing.
if !settings.HardwareAccelerationEnabled() {
return capabilities.AccelNone, ""
}
backend := settings.TranscodeEncoderBackend(string(profile))
switch backend {
case "", "auto":
return "", ""
case "cpu":
return capabilities.AccelNone, ""
default:
if accel, ok := legacyAccelBackend(backend); ok {
caps := ffmpeg.Get().Capabilities()
if caps == nil || !caps.CodecEncodeAvailable(capabilities.CodecH264, accel) {
return "", ""
}
return accel, ""
}
caps := ffmpeg.Get().Capabilities()
if caps == nil {
return "", ""
}
for _, opt := range caps.EncodeOptions {
if opt.Codec != capabilities.CodecH264 || !opt.Available || opt.Encoder != backend {
continue
}
if opt.Accel == "" || opt.Accel == capabilities.AccelNone {
return capabilities.AccelNone, backend
}
return opt.Accel, backend
}
return "", ""
}
}
func legacyAccelBackend(backend string) (capabilities.AccelType, bool) {
switch backend {
case "nvenc", "amf", "qsv", "vaapi", "d3d12", "videotoolbox":
return capabilities.AccelType(backend), true
default:
return "", false
}
}
// transcodeBitrateConfig resolves the target bitrate: explicit config wins, then the
// source bitrate when no downscale is applied, then a resolution-derived default.
func transcodeBitrateConfig(cfg settings.TranscodeProfile, info ffmpeg.StreamInfo, maxHeight int) encode.BitrateConfig {
if cfg.AvgBitrateKbps > 0 {
kbps := cfg.AvgBitrateKbps
// The cap is a ceiling: -b:v is a target average, so a source already
// below it would be inflated to the profile value. Floor at the source.
if src := info.VideoBitrate / 1000; src > 0 && src < kbps {
kbps = src
}
return bitrateFromKbps(kbps)
}
if info.VideoBitrate > 0 && (maxHeight <= 0 || info.Height <= maxHeight) {
return bitrateFromKbps(info.VideoBitrate / 1000)
}
return ffmpeg.DefaultHLSVideoProfile(maxHeight).Bitrate
}
func bitrateFromKbps(kbps int) encode.BitrateConfig {
if kbps < 1 {
kbps = 1
}
return encode.BitrateConfig{
Target: fmt.Sprintf("%dk", kbps),
Min: fmt.Sprintf("%dk", kbps/2),
Max: fmt.Sprintf("%dk", kbps*3/2),
BufSize: fmt.Sprintf("%dk", kbps*2),
}
}
func userTranscodeLimit(uMax int) int {
if uMax < 1 {
return 1
}
return uMax
}
func normalizeClientID(id string) string {
id = strings.TrimSpace(id)
if id == "" {
return "default"
}
if len(id) > 128 {
return id[:128]
}
return id
}