torrentclaw/unarr
1
0
Fork 0
Code Issues Pull requests Projects Releases 4 Packages Wiki Activity Actions

feat(stream): burn bitmap (PGS/DVB) subtitles into the video via overlay

Browse source 
Bitmap subs can't be served as WebVTT, so the user picks one and the daemon
re-encodes with it overlaid. HLSSessionConfig.BurnSubtitleIndex (*int, nil=no
burn) flows into the cache key + a -filter_complex graph:
  [0✌️0]<vchain>[base];[0:s:N][base]scale2ref[sub][base2];[base2][sub]overlay[vout]
Overlay after the tonemap (SDR subs keep brightness); scale2ref fits the PGS
canvas to the output. Invalid/text/out-of-range index -> clean-encode fallback.
IsTextSubtitle now includes "text" (parity with the web classifier).
This commit is contained in:
Deivid Soto 2026-06-01 09:51:27 +02:00
parent 8207d1d2a9
commit 665ec0a34f
9 changed files with 196 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

20
internal/agent/types.go
View file

@ -398,18 +398,26 @@ type LibraryDeleteRequest struct {
// HLS registry; source bytes come from FilePath (or, when only InfoHash is
// set, from a download_task on disk).
type StreamSession struct {
SessionID string `json:"sessionId"`
FilePath string `json:"filePath,omitempty"`
InfoHash string `json:"infoHash,omitempty"`
TaskID string `json:"taskId,omitempty"`
FileName string `json:"fileName,omitempty"`
FileSize int64 `json:"fileSize,omitempty"`
SessionID string `json:"sessionId"`
FilePath string `json:"filePath,omitempty"`
InfoHash string `json:"infoHash,omitempty"`
TaskID string `json:"taskId,omitempty"`
FileName string `json:"fileName,omitempty"`
FileSize int64 `json:"fileSize,omitempty"`
// Quality target the daemon should aim for when transcoding. One of
// "2160p" | "1080p" | "720p" | "480p" | "original" | "" (defer to config).
Quality string `json:"quality,omitempty"`
// AudioIndex selects the source audio track (-map 0:a:N). -1 means
// "use the default/first track".
AudioIndex int `json:"audioIndex,omitempty"`
// BurnSubtitleIndex, when set, is the 0-based subtitle stream index
// (-map 0:s:N) of a BITMAP subtitle (PGS/DVB) to burn into the video. Text
// subtitles are served as separate WebVTT tracks and never burned. A pointer
// (not int) so absent/null = "no burn": the zero value 0 is a valid track
// index, so an int sentinel would silently burn track 0 when the field is
// omitted. Forces a full video re-encode (the overlay can't ride a copy
// path), so the web only sends it when the user picks a bitmap sub.
BurnSubtitleIndex *int `json:"burnSubtitleIndex,omitempty"`
// PlayMethod is how the daemon should serve this session:
// "" — default (HLS transcode); also what legacy servers send.
// "direct" — the source is already browser-native (the web decided this

32
internal/cmd/daemon.go
View file

@ -669,14 +669,15 @@ func runDaemonStart() error {
}
hlsCtx, hlsCancel := context.WithCancel(ctx)
startHLSPlayback(engine.HLSSessionConfig{
SessionID: sess.SessionID,
SourceURL: sess.DirectURL,
CacheID: sess.InfoHash,
FileName: sess.FileName,
Quality: sess.Quality,
AudioIndex: sess.AudioIndex,
Transcode: tcRuntime,
Cache: hlsCache,
SessionID: sess.SessionID,
SourceURL: sess.DirectURL,
CacheID: sess.InfoHash,
FileName: sess.FileName,
Quality: sess.Quality,
AudioIndex: sess.AudioIndex,
BurnSubtitleIndex: sess.BurnSubtitleIndex,
Transcode: tcRuntime,
Cache: hlsCache,
// 2c: refresh the debrid link if it expires mid-transcode; the
// auto-restart supervisor calls this before relaunching ffmpeg.
RefreshURL: func(rctx context.Context) (string, error) {
@ -788,13 +789,14 @@ func runDaemonStart() error {
// that absorbs the gap until the playlist registers.
hlsCtx, hlsCancel := context.WithCancel(ctx)
startHLSPlayback(engine.HLSSessionConfig{
SessionID: sess.SessionID,
SourcePath: filePath,
FileName: sess.FileName,
Quality: sess.Quality,
AudioIndex: sess.AudioIndex,
Transcode: tcRuntime,
Cache: hlsCache,
SessionID: sess.SessionID,
SourcePath: filePath,
FileName: sess.FileName,
Quality: sess.Quality,
AudioIndex: sess.AudioIndex,
BurnSubtitleIndex: sess.BurnSubtitleIndex,
Transcode: tcRuntime,
Cache: hlsCache,
}, hlsCtx, hlsCancel)
}

84
internal/engine/hls.go
View file

@ -151,7 +151,15 @@ type HLSSessionConfig struct {
FileName string
Quality string // "2160p"|"1080p"|"720p"|"480p"|"original"|""
AudioIndex int // 0-based ffmpeg audio stream selection (-map 0:a:N). -1 = default.
Transcode TranscodeRuntime
// BurnSubtitleIndex burns a BITMAP subtitle (PGS/DVB) at this 0-based
// subtitle stream index into the video. nil = no burn (text subs are served
// as separate WebVTT). A pointer (not int) so the zero value 0 — a valid
// stream index — can't be mistaken for a burn request when a caller leaves
// the field unset. Part of the cache key so a burned encode never collides
// with the clean one. Forces the video re-encode the HLS path already does
// to also composite the subtitle overlay.
BurnSubtitleIndex *int
Transcode TranscodeRuntime
// Cache is an optional persistent segment cache keyed by (source, quality,
// audio). When set, completed encodes are kept across sessions so re-plays
// of the same file at the same quality skip ffmpeg entirely. nil disables
@ -169,6 +177,15 @@ func (cfg HLSSessionConfig) sourceRef() string {
return cfg.SourcePath
}
// burnSubtitleIndexOrNone resolves the optional burn-in subtitle pointer to the
// int sentinel the cache key and filtergraph use: nil → -1 ("no burn").
func (cfg HLSSessionConfig) burnSubtitleIndexOrNone() int {
if cfg.BurnSubtitleIndex == nil {
return -1
}
return *cfg.BurnSubtitleIndex
}
// logName is a short, log-friendly source label. For local files it's the base
// name; for a URL source (no SourcePath) it prefers FileName over the raw URL
// (which would leak a query-string token into the logs).
@ -383,9 +400,9 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
// Debrid URL sessions key by CacheID (info_hash) so re-plays hit cache
// despite the URL changing each resolution; local files key by path.
if cfg.CacheID != "" {
cacheKey = cfg.Cache.KeyForID(cfg.CacheID, cfg.Quality, cfg.AudioIndex)
cacheKey = cfg.Cache.KeyForID(cfg.CacheID, cfg.Quality, cfg.AudioIndex, cfg.burnSubtitleIndexOrNone())
} else {
cacheKey = cfg.Cache.KeyFor(cfg.SourcePath, cfg.Quality, cfg.AudioIndex)
cacheKey = cfg.Cache.KeyFor(cfg.SourcePath, cfg.Quality, cfg.AudioIndex, cfg.burnSubtitleIndexOrNone())
}
// Integrity gate: HasComplete just stats the marker. If init.mp4 or
// the last segment vanished (external rm, partial-disk failure), we
@ -1217,8 +1234,31 @@ func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir strin
args = append(args, "-output_ts_offset", strconv.FormatFloat(startSec, 'f', 3, 64))
}
// Map video + selected audio. Always use first video stream.
args = append(args, "-map", "0:v:0")
// Burn a bitmap subtitle (PGS/DVB) into the video when requested. Validate
// the index points at a real bitmap track in range — text subs are served as
// separate WebVTT and never burned, and a stale/out-of-range index falls
// back to a clean encode rather than failing the session.
burnIdx := -1
if reqBurn := cfg.burnSubtitleIndexOrNone(); reqBurn >= 0 {
if reqBurn < len(probe.SubtitleTracks) &&
!probe.SubtitleTracks[reqBurn].IsTextSubtitle() {
burnIdx = reqBurn
} else {
log.Printf("[hls %s] burn subtitle %d ignored — not a bitmap track in range",
shortHLSID(cfg.SessionID), reqBurn)
}
}
// Map video + selected audio. With burn-in the video comes from the
// filter_complex graph ([vout], built below); otherwise map the source video
// stream directly. ffmpeg resolves the [vout] label from -filter_complex
// regardless of argv order, so mapping it here (before audio) keeps video as
// output stream 0.
if burnIdx >= 0 {
args = append(args, "-map", "[vout]")
} else {
args = append(args, "-map", "0:v:0")
}
audioIdx := cfg.AudioIndex
if audioIdx < 0 {
audioIdx = 0
@ -1362,19 +1402,37 @@ func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir strin
if probe.HDR != "" && cfg.Transcode.TonemapHDR {
tonemap = hdrTonemapChain
}
var filterChain string
// Core video chain (scale + optional tonemap + pixel format + color metadata),
// WITHOUT the optional hwUploadTail — that has to run last, after any subtitle
// overlay, so it's appended separately below.
var vchain string
if maxH > 0 && probe.Height > maxH {
filterChain = fmt.Sprintf(
"scale=-2:%d:force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2,%sformat=%s%s%s",
maxH, tonemap, pixFormat, colorTail, hwUploadTail,
vchain = fmt.Sprintf(
"scale=-2:%d:force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2,%sformat=%s%s",
maxH, tonemap, pixFormat, colorTail,
)
} else {
filterChain = fmt.Sprintf(
"scale=trunc(iw/2)*2:trunc(ih/2)*2,%sformat=%s%s%s",
tonemap, pixFormat, colorTail, hwUploadTail,
vchain = fmt.Sprintf(
"scale=trunc(iw/2)*2:trunc(ih/2)*2,%sformat=%s%s",
tonemap, pixFormat, colorTail,
)
}
args = append(args, "-vf", filterChain)
if burnIdx >= 0 {
// Burn-in: process the video to its final size + SDR colorspace FIRST,
// then composite the subtitle. Overlaying SDR PGS/DVB graphics onto a
// still-HDR (PQ) frame and tonemapping afterwards would crush the
// subtitle brightness, so the overlay must come after the tonemap. The
// subtitle canvas is scaled to the processed frame via scale2ref so a
// PGS/DVB stream authored at any resolution lines up. hwUploadTail
// (VAAPI) runs last, on the composited frame.
filterComplex := fmt.Sprintf(
"[0:v:0]%s[base];[0:s:%d][base]scale2ref[sub][base2];[base2][sub]overlay%s[vout]",
vchain, burnIdx, hwUploadTail,
)
args = append(args, "-filter_complex", filterComplex)
} else {
args = append(args, "-vf", vchain+hwUploadTail)
}
// Audio: AAC stereo 48 kHz — broadest browser compatibility.
audioBitrate := cfg.Transcode.AudioBitrate

8
internal/engine/hls_cache.go
View file

@ -153,12 +153,12 @@ func (c *HLSCache) ReleaseWriter(key string) {
// KeyFor derives a stable cache key for (source, quality, audioIndex). Using
// the absolute source path means renaming a file invalidates the cache, which
// is correct — segment content is tied to the encoded source.
func (c *HLSCache) KeyFor(sourcePath, quality string, audioIndex int) string {
func (c *HLSCache) KeyFor(sourcePath, quality string, audioIndex, burnSubtitleIndex int) string {
abs, err := filepath.Abs(sourcePath)
if err != nil {
abs = sourcePath
}
h := sha256.Sum256([]byte(fmt.Sprintf("%s|%s|%d", abs, quality, audioIndex)))
h := sha256.Sum256([]byte(fmt.Sprintf("%s|%s|%d|%d", abs, quality, audioIndex, burnSubtitleIndex)))
return hex.EncodeToString(h[:8]) // 16 hex chars — collision-safe enough for per-host cache
}
@ -167,8 +167,8 @@ func (c *HLSCache) KeyFor(sourcePath, quality string, audioIndex int) string {
// the debrid direct URL is re-resolved per play and would never cache-hit, so
// we key by the torrent info_hash — the same content always maps to the same
// key across plays. NOT run through filepath.Abs (an id/URL is not a path).
func (c *HLSCache) KeyForID(id, quality string, audioIndex int) string {
h := sha256.Sum256([]byte(fmt.Sprintf("%s|%s|%d", id, quality, audioIndex)))
func (c *HLSCache) KeyForID(id, quality string, audioIndex, burnSubtitleIndex int) string {
h := sha256.Sum256([]byte(fmt.Sprintf("%s|%s|%d|%d", id, quality, audioIndex, burnSubtitleIndex)))
return hex.EncodeToString(h[:8])
}

2
internal/engine/hls_cache_smoke_test.go
View file

@ -98,7 +98,7 @@ func TestHLSCacheSmoke(t *testing.T) {
encodeDur := time.Since(t0)
t.Logf("session 1: MISS completed in %s", encodeDur.Round(time.Millisecond))
key := cache.KeyFor(source, "720p", 0)
key := cache.KeyFor(source, "720p", 0, -1)
if !cache.HasComplete(key) {
t.Fatalf("cache.HasComplete(%s) is false after successful encode", key)
}

13
internal/engine/hls_cache_test.go
View file

@ -21,18 +21,21 @@ func newTestCache(t *testing.T, sizeGB int) *HLSCache {
func TestKeyForStable(t *testing.T) {
c := newTestCache(t, 1)
k1 := c.KeyFor("/a/b/movie.mkv", "1080p", 0)
k2 := c.KeyFor("/a/b/movie.mkv", "1080p", 0)
k1 := c.KeyFor("/a/b/movie.mkv", "1080p", 0, -1)
k2 := c.KeyFor("/a/b/movie.mkv", "1080p", 0, -1)
if k1 != k2 {
t.Fatalf("expected stable keys, got %q vs %q", k1, k2)
}
if c.KeyFor("/a/b/movie.mkv", "720p", 0) == k1 {
if c.KeyFor("/a/b/movie.mkv", "720p", 0, -1) == k1 {
t.Fatal("quality should change key")
}
if c.KeyFor("/a/b/movie.mkv", "1080p", 1) == k1 {
if c.KeyFor("/a/b/movie.mkv", "1080p", 1, -1) == k1 {
t.Fatal("audio index should change key")
}
if c.KeyFor("/x/y/other.mkv", "1080p", 0) == k1 {
if c.KeyFor("/a/b/movie.mkv", "1080p", 0, 2) == k1 {
t.Fatal("burn subtitle index should change key")
}
if c.KeyFor("/x/y/other.mkv", "1080p", 0, -1) == k1 {
t.Fatal("path should change key")
}
}

74
internal/engine/hls_url_args_test.go
View file

@ -111,12 +111,80 @@ func TestHLSSourceRefAndCacheID(t *testing.T) {
c := &HLSCache{root: "/tmp/cache"}
// Same CacheID + quality + audio → same key regardless of the (volatile) URL.
k1 := c.KeyForID("hash1", "720p", -1)
k2 := c.KeyForID("hash1", "720p", -1)
k1 := c.KeyForID("hash1", "720p", -1, -1)
k2 := c.KeyForID("hash1", "720p", -1, -1)
if k1 != k2 {
t.Errorf("KeyForID not stable: %q != %q", k1, k2)
}
if c.KeyForID("hash2", "720p", -1) == k1 {
if c.KeyForID("hash2", "720p", -1, -1) == k1 {
t.Error("KeyForID collision across distinct ids")
}
}
// Burn-in: a bitmap subtitle index routes the video through -filter_complex with
// scale2ref + overlay and maps [vout]; a nil / text / out-of-range index keeps
// the plain -vf path (text subs are served as WebVTT, never burned).
func TestBuildHLSFFmpegArgsBurnSubtitle(t *testing.T) {
idx := func(n int) *int { return &n }
base := func() HLSSessionConfig {
return HLSSessionConfig{
SessionID: "burn",
SourcePath: "/tmp/movie.mkv",
Quality: "1080p",
Transcode: TranscodeRuntime{
FFmpegPath: "/usr/bin/ffmpeg",
FFprobePath: "/usr/bin/ffprobe",
HWAccel: HWAccelNone,
},
}
}
probe := &StreamProbe{
Width: 1920, Height: 1080, DurationSec: 100,
SubtitleTracks: []ProbeSubtitleTrack{
{Index: 0, Codec: "subrip"}, // text → not burnable
{Index: 1, Codec: "hdmv_pgs_subtitle"}, // bitmap → burnable
},
}
t.Run("nil = clean -vf path", func(t *testing.T) {
got := strings.Join(buildHLSFFmpegArgsAt(base(), probe, "/tmp/d", 0, 0), " ")
if strings.Contains(got, "-filter_complex") || strings.Contains(got, "overlay") {
t.Errorf("no-burn argv must not overlay: %s", got)
}
if !strings.Contains(got, "-map 0:v:0") || !strings.Contains(got, "-vf") {
t.Errorf("no-burn argv must -map 0:v:0 with -vf: %s", got)
}
})
t.Run("bitmap index burns via filter_complex", func(t *testing.T) {
cfg := base()
cfg.BurnSubtitleIndex = idx(1)
got := strings.Join(buildHLSFFmpegArgsAt(cfg, probe, "/tmp/d", 0, 0), " ")
for _, want := range []string{"-filter_complex", "[0:s:1]", "scale2ref", "overlay", "-map [vout]"} {
if !strings.Contains(got, want) {
t.Errorf("burn argv missing %q: %s", want, got)
}
}
if strings.Contains(got, "-map 0:v:0") {
t.Errorf("burn argv must map [vout], not 0:v:0: %s", got)
}
})
t.Run("text index is ignored (served as WebVTT)", func(t *testing.T) {
cfg := base()
cfg.BurnSubtitleIndex = idx(0) // subrip → not a bitmap track
got := strings.Join(buildHLSFFmpegArgsAt(cfg, probe, "/tmp/d", 0, 0), " ")
if strings.Contains(got, "overlay") || strings.Contains(got, "-filter_complex") {
t.Errorf("text-sub burn must fall back to clean encode: %s", got)
}
})
t.Run("out-of-range index is ignored", func(t *testing.T) {
cfg := base()
cfg.BurnSubtitleIndex = idx(9)
got := strings.Join(buildHLSFFmpegArgsAt(cfg, probe, "/tmp/d", 0, 0), " ")
if strings.Contains(got, "overlay") {
t.Errorf("out-of-range burn must fall back to clean encode: %s", got)
}
})
}

2
internal/engine/probe.go
View file

@ -61,7 +61,7 @@ type ProbeSubtitleTrack struct {
// without re-rendering. Bitmap subs (PGS, DVB) need burn-in.
func (s ProbeSubtitleTrack) IsTextSubtitle() bool {
switch s.Codec {
case "subrip", "srt", "ass", "ssa", "webvtt", "mov_text":
case "subrip", "srt", "ass", "ssa", "webvtt", "mov_text", "text":
return true
}
return false