feat(cc608): add timecc608 -sc for self-contained segment captions

Flipping each caption on its cue's first frame is frame-accurate but makes a caption span the segment boundary, which costs a client that starts, seeks or joins mid-stream its first cue period. Make that trade selectable per stream: timecc608_CC1-eng-sc keeps a cue's build and flip inside the cue's own frames, so every segment is independently decodable, at the price of the caption appearing ~0.5 s into the second its clock names (measured: flips at frames 15 and 45 for cue boundaries 0 and 30 at 30 fps). The default is unchanged.

The grammar is now <channel>-<lang>[-sc]. A trailing sc is only the flag when a language precedes it, so CC1-sc stays the Sardinian tag, CC1-sc-sc is that language self-contained, and CC1-eng-xx remains the language eng-xx; only a tag whose final subtag is literally sc cannot be expressed.

cc608UnitFrames takes a cc608FlipMode and keeps the fresh-encoder-per-cue rebuild in both modes rather than delegating to go-608's generate.BuildUnitCues + WithFlipAtCueStart: BuildUnitCues shares one encoder across a unit's cues, so cues after the first are diffs, and a receiver joining mid-unit would flip a diff and see one row of a two-row caption.

/urlgen documents the option and its trade-off; the field already accepted it since it validates through CreateCC608Config.

Author: tobbee

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Optional `-sc` field on `timecc608` (e.g. `timecc608_CC1-eng-sc`) keeps every CTA-608 caption inside the
+  segment that carries it, so segments stay independently decodable for a client that starts, seeks or joins
+  mid-stream. In exchange each caption appears ~0.5 s into the second its clock names, which is the behaviour
+  from before the flip-on-cue-start fix below.
+
 ### Changed
 
 - mp4ff dependency bumped to v0.55.0 and go-608 to v0.7.0

README.md

@@ -33,7 +33,7 @@ There is a corresponding setting for `wvtt` (segmented WebVTT) subtitles using `
 For in-band closed captions, `/timecc608_CC1-eng` injects a CTA-608 (CEA-608) caption
 into the AVC/HEVC video itself, showing a ticking UTC clock and the segment number on
 channel CC1, and advertises it with a CEA-608 `Accessibility` descriptor. The value is
-`<channel>-<lang>` (only `CC1` is supported so far). It cannot be combined with encryption
+`<channel>-<lang>[-sc]` (only `CC1` is supported so far). It cannot be combined with encryption
 and is rejected for assets that already carry captions.
 
 Each caption is displayed over exactly the interval its text names. A pop-on caption is
@@ -58,6 +58,14 @@ ahead of the `EOC` to clear the state would erase the build that is about to be
 A player should reset its 608 decoder state on a seek or other discontinuity — which is
 what turns the stale case into the blank one — exactly as it resets any other decoder.
 
+Appending `-sc` (`/timecc608_CC1-eng-sc`) switches this trade the other way: a cue's build
+and its flip both ride the cue's own frames, so every caption stays inside the segment that
+carries it and no segment depends on its neighbour. A client can then start, seek or join
+anywhere and see a complete caption immediately. The cost is latency — the flip can only
+follow its own build, so each caption appears ~0.5 s into the second its clock names and
+remains up into the next one. Use the default for frame-accurate timing, `-sc` to test a
+player against captions that are decodable segment by segment.
+
 The new `livesim2` software is written in Go instead of Python and designed to handle
 content in a more flexible and versatile way. It is intended to be very easy to install and deploy locally
 since it is compiled into a single binary that serves the content via a built-in

cmd/livesim2/app/cc608.go

@@ -22,29 +22,61 @@ type CC608Config struct {
 	// Lang is the RFC-5646 language code used both for the caption content locale
 	// and for the value of the MPD Accessibility descriptor.
 	Lang string `json:"Lang"`
+	// SelfContained keeps every caption inside the segment that carries it: a cue's
+	// pop-on build and its EOC flip both ride the cue's own frames, so no segment
+	// depends on its neighbour. The flip then lands ~build-pairs frames into the cue
+	// (0.6-0.75 s of a one-second cue), so the caption lags the interval its text
+	// names. The default (false) flips each caption on its cue's first frame instead,
+	// which is frame-accurate but makes a caption span the segment boundary.
+	SelfContained bool `json:"SelfContained,omitempty"`
 }
 
+// cc608SelfContainedToken is the optional trailing field of the timecc608 value that
+// asks for self-contained segments.
+const cc608SelfContainedToken = "sc"
+
 // cc608LangRegexp is a light RFC-5646 check: a 2-3 letter primary subtag followed by
 // optional hyphen-separated subtags (e.g. eng, swe, en-US, zh-Hans).
 var cc608LangRegexp = regexp.MustCompile(`^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$`)
 
 // CreateCC608Config parses the value of a "timecc608" URL option.
 //
-// Grammar: <channel>-<lang>, e.g. CC1-eng.
+// Grammar: <channel>-<lang>[-sc], e.g. CC1-eng or CC1-eng-sc.
 //   - channel: CEA-608 channel; only CC1 is supported in the first milestone.
 //   - lang:    RFC-5646 language code (caption locale + MPD Accessibility value).
+//   - sc:      optional; keep captions self-contained per segment (see
+//     CC608Config.SelfContained). Omitted, captions flip on their cue's first frame.
+//
+// Since a language tag may itself carry hyphenated subtags (en-US, zh-Hans), the "sc"
+// field is only recognized as such when the value has three or more fields; the lang is
+// everything between the channel and it. "CC1-sc" is therefore the language "sc"
+// (Sardinian), and "CC1-sc-sc" is that language with self-contained segments. The one
+// tag this cannot express is a language whose final subtag is literally "sc".
 func CreateCC608Config(val string) (*CC608Config, error) {
-	channel, lang, ok := strings.Cut(val, "-")
+	channel, rest, ok := strings.Cut(val, "-")
 	if !ok {
-		return nil, fmt.Errorf("timecc608 must be <channel>-<lang>, got %q", val)
+		return nil, fmt.Errorf("timecc608 must be <channel>-<lang>[-sc], got %q", val)
 	}
 	if channel != "CC1" {
 		return nil, fmt.Errorf("timecc608 channel %q not supported (only CC1)", channel)
 	}
+	lang := rest
+	selfContained := false
+	if pre, last, hasMore := cutLast(rest, "-"); hasMore && last == cc608SelfContainedToken {
+		lang, selfContained = pre, true
+	}
 	if !cc608LangRegexp.MatchString(lang) {
 		return nil, fmt.Errorf("timecc608 language %q is not a valid RFC-5646 code", lang)
 	}
-	return &CC608Config{Channel: channel, Lang: lang}, nil
+	return &CC608Config{Channel: channel, Lang: lang, SelfContained: selfContained}, nil
+}
+
+// cutLast splits s around the last instance of sep, like strings.Cut around the first.
+func cutLast(s, sep string) (before, after string, found bool) {
+	if i := strings.LastIndex(s, sep); i >= 0 {
+		return s[:i], s[i+len(sep):], true
+	}
+	return s, "", false
 }
 
 // ParseCC608Config parses a "timecc608" option value, accumulating any error.

cmd/livesim2/app/cc608_inject.go

@@ -85,17 +85,36 @@ func cc608PairCount(toks []cta608.Token) int {
 	})) / 2
 }
 
+// cc608FlipMode selects where a cue's pop-on flip lands relative to the cue it names.
+type cc608FlipMode int
+
+const (
+	// cc608FlipAtCueStart puts each EOC on its cue's first frame, transmitting the
+	// build over the preceding frames. Frame-accurate, but captions span unit
+	// boundaries. This is the default.
+	cc608FlipAtCueStart cc608FlipMode = iota
+	// cc608SelfContained keeps a cue's build and flip inside the cue's own frames, so
+	// no unit depends on its neighbour. The flip lands ~build-pairs frames into the
+	// cue, i.e. the caption lags the interval its text names.
+	cc608SelfContained
+)
+
 // cc608UnitFrames builds the per-frame CTA-608 schedule for one unit (one fragment)
 // of nFrames frames starting at unitStartMS.
 //
 // A pop-on caption occupies two transmissions: a build (RCL + ENM + rows) written
 // into non-displayed memory, and an EOC that flips it on screen. Both drain at one
-// 608 pair per frame, so where the build is placed decides when the caption
-// appears. go-608's generate.BuildUnitCues starts the build at its cue's first
-// frame, which puts the flip ~pairs frames *into* the cue — ~0.5-0.75s of a
-// one-second cue — so the caption became visible well after the time it displays.
+// 608 pair per frame, so where the build is placed decides when the caption appears.
+//
+// With mode cc608SelfContained, both ride the cue's own frames: the build drains from
+// the cue's first frame and the flip follows it, which puts the flip ~pairs frames
+// *into* the cue — 0.6-0.75s of a one-second cue — so the caption is visible well
+// after the time its text names. Nothing crosses a unit boundary, so every segment
+// decodes standalone and a client that starts, seeks or joins anywhere sees a correct
+// (if late) caption. nextContent is unused in this mode.
 //
-// Here each cue's EOC rides its cue's first frame and its build drains over the
+// With the default cc608FlipAtCueStart, each cue's EOC rides its cue's first frame
+// and its build drains over the
 // frames immediately before it, so the flip coincides with the cue boundary and the
 // caption is shown exactly over the interval its text names. The consequence is that
 // a cue's build lives in the preceding cue's frames: the first cue's build belongs to
@@ -110,12 +129,15 @@ func cc608PairCount(toks []cta608.Token) int {
 // case into the blank one — and not something the server can paper over, since an ENM
 // ahead of the EOC would erase the build about to be flipped.
 //
-// Each cue is encoded with a fresh cta608.Encoder so its build is always a complete
-// rebuild. That keeps every EOC paired with a build that fully describes its screen,
-// which is what makes independently generated, on-demand units line up: the build in
-// unit N's tail and the flip at unit N+1's first frame are produced by separate
-// calls and must agree without sharing encoder state.
-func cc608UnitFrames(fps float64, nFrames int, unitStartMS int64, content, nextContent generate.CueContentFunc) ([]schedule.Frame, error) {
+// In both modes each cue is encoded with a fresh cta608.Encoder so its build is always
+// a complete rebuild rather than a diff against the previous cue. That keeps every EOC
+// paired with a build that fully describes its screen, which is what makes
+// independently generated, on-demand units line up: the build in unit N's tail and the
+// flip at unit N+1's first frame are produced by separate calls and must agree without
+// sharing encoder state. It is also what lets a receiver joining mid-unit get a whole
+// caption rather than one row of one.
+func cc608UnitFrames(fps float64, nFrames int, unitStartMS int64, content, nextContent generate.CueContentFunc,
+	mode cc608FlipMode) ([]schedule.Frame, error) {
 	if nFrames <= 0 {
 		return nil, fmt.Errorf("cc608: nFrames must be > 0, got %d", nFrames)
 	}
@@ -130,6 +152,36 @@ func cc608UnitFrames(fps float64, nFrames int, unitStartMS int64, content, nextC
 	// boundary(k) is the first unit-relative frame of cue k; boundary(n) == nFrames.
 	boundary := func(k int) int { return int(math.Round(float64(k) * float64(nFrames) / float64(n))) }
 
+	// cueTokens encodes cue k from a clean encoder, split into the build and the EOC
+	// that flips it. Pushes drain in push order (the scheduler is a FIFO gated by
+	// eligibility time), so a build pushed before its EOC keeps the byte stream ordered.
+	cueTokens := func(cue generate.UnitCue) (build, eoc []cta608.Token) {
+		var enc cta608.Encoder
+		return cc608SplitEOC(enc.Apply(cta608.CaptionBlock{Lines: cue.Lines, Mode: cta608.PopOn}))
+	}
+
+	sched := schedule.NewScheduler(fps, schedule.WithDoubling(cta608.DoublingOff))
+	if mode == cc608SelfContained {
+		for k := 0; k < n; k++ {
+			start, end := boundary(k), boundary(k+1)
+			build, eoc := cueTokens(content(k, wallAt(start)))
+			// Build and EOC are both eligible at the cue's first frame and drain one pair
+			// per frame, so the flip lands at start+pairs. Require it to leave at least
+			// one frame of display before the next cue takes the screen.
+			if pairs := cc608PairCount(build) + cc608PairCount(eoc); start+pairs >= end {
+				return nil, fmt.Errorf("cc608: cue %d needs %d frames to build and flip but its slice is only "+
+					"%d frames at %g fps; shorten the lines or lower the update rate", k, pairs, end-start, fps)
+			}
+			if len(build) > 0 {
+				sched.Push(schedule.TimedTokens{TimeMS: wallAt(start), Field: 1, Tokens: build})
+			}
+			if len(eoc) > 0 {
+				sched.Push(schedule.TimedTokens{TimeMS: wallAt(start), Field: 1, Tokens: eoc})
+			}
+		}
+		return cc608CollectFrames(sched, nFrames, wallAt), nil
+	}
+
 	// Cue k flips at boundary(k). The extra entry at nFrames is the next unit's first
 	// cue: its build drains this unit's tail, its EOC belongs to the next unit.
 	type flip struct {
@@ -142,11 +194,9 @@ func cc608UnitFrames(fps float64, nFrames int, unitStartMS int64, content, nextC
 	}
 	flips = append(flips, flip{nFrames, nextContent(0, wallAt(nFrames))})
 
-	sched := schedule.NewScheduler(fps, schedule.WithDoubling(cta608.DoublingOff))
 	prevFlip := -1 // last frame already claimed by a flip
 	for i, f := range flips {
-		var enc cta608.Encoder
-		build, eoc := cc608SplitEOC(enc.Apply(cta608.CaptionBlock{Lines: f.cue.Lines, Mode: cta608.PopOn}))
+		build, eoc := cueTokens(f.cue)
 		buildStart := f.frame - cc608PairCount(build)
 		// The first cue flips at frame 0, so its build was transmitted by the previous
 		// unit and there is nothing to place here. Every other build must fit between
@@ -158,22 +208,23 @@ func cc608UnitFrames(fps float64, nFrames int, unitStartMS int64, content, nextC
 				return nil, fmt.Errorf("cc608: cue flipping at frame %d needs %d frames of build but only %d are free "+
 					"at %g fps; shorten the lines or lower the update rate", f.frame, f.frame-buildStart, free, fps)
 			}
-			// Pushes drain in push order (the scheduler is a FIFO gated by eligibility
-			// time), so pushing the build before its EOC keeps the byte stream ordered
-			// and lands the flip on f.frame exactly.
 			sched.Push(schedule.TimedTokens{TimeMS: wallAt(buildStart), Field: 1, Tokens: build})
 		}
 		if f.frame < nFrames && len(eoc) > 0 {
 			sched.Push(schedule.TimedTokens{TimeMS: wallAt(f.frame), Field: 1, Tokens: eoc})
 		}
 		prevFlip = f.frame
 	}
+	return cc608CollectFrames(sched, nFrames, wallAt), nil
+}
 
+// cc608CollectFrames drains the scheduler into one entry per unit frame.
+func cc608CollectFrames(sched *schedule.Scheduler, nFrames int, wallAt func(int) int64) []schedule.Frame {
 	frames := make([]schedule.Frame, nFrames)
 	for i := range frames {
 		frames[i] = sched.Frame(wallAt(i))
 	}
-	return frames, nil
+	return frames
 }
 
 // injectCC608 splices in-band CTA-608 caption SEI into a unit's video samples in
@@ -182,21 +233,23 @@ func cc608UnitFrames(fps float64, nFrames int, unitStartMS int64, content, nextC
 // SEI NALU before the first VCL NALU of each sample, updating Data and Size. samples
 // are the video track's FullSamples in decode order; fps and unitStartMS give the
 // caption timing; segNr is this unit's segment number and nextSegNr the segment
-// number of the unit that follows (the same segment for a non-final fragment).
+// number of the unit that follows (the same segment for a non-final fragment); mode
+// selects where each cue flips (nextSegNr is unused for cc608SelfContained).
 //
 // The schedule is presentation-ordered but samples arrive in decode order. Since
 // receivers reassemble cc_data by presentation time (PTS) — dash.js, hls.js and
 // Shaka all sort caption pairs by PTS — the k-th caption frame must ride the k-th
 // sample in *presentation* order. With B-frames (decode order != presentation order)
 // a naive frames[i]->samples[i] mapping permutes the CEA-608 byte stream and garbles
 // the caption.
-func injectCC608(samples []mp4.FullSample, fps float64, unitStartMS int64, segNr, nextSegNr uint32, codec carriage.Codec) error {
+func injectCC608(samples []mp4.FullSample, fps float64, unitStartMS int64, segNr, nextSegNr uint32,
+	codec carriage.Codec, mode cc608FlipMode) error {
 	if len(samples) == 0 {
 		return nil
 	}
 	// cc608UnitFrames validates the frame rate and returns an error (never panics)
 	// if it is out of the CEA-608 range.
-	frames, err := cc608UnitFrames(fps, len(samples), unitStartMS, cc608CueContent(segNr), cc608CueContent(nextSegNr))
+	frames, err := cc608UnitFrames(fps, len(samples), unitStartMS, cc608CueContent(segNr), cc608CueContent(nextSegNr), mode)
 	if err != nil {
 		return fmt.Errorf("cc608 build cues: %w", err)
 	}
@@ -275,11 +328,12 @@ func isVCLNalu(nalu []byte, codec carriage.Codec) bool {
 // change, the moof size is unchanged and trun.DataOffset / mdat.StartPos stay
 // valid (mirroring the tfdt-shift bookkeeping in genLiveSegment).
 //
-// Each fragment is one caption unit. Because a cue's build is transmitted ahead of
-// its flip (see cc608UnitFrames), a fragment also carries the build for the first
-// cue of whatever follows it: the next fragment of this segment, or — for the last
+// Each fragment is one caption unit. In the default mode a cue's build is transmitted
+// ahead of its flip (see cc608UnitFrames), so a fragment also carries the build for the
+// first cue of whatever follows it: the next fragment of this segment, or — for the last
 // fragment — the first cue of the next segment, which is why the next unit's segment
-// number is passed down.
+// number is passed down. With timecc608's "-sc" (CC608Config.SelfContained) each unit
+// keeps its captions to itself and the next number goes unused.
 func applyCC608(seg *mp4.MediaSegment, meta segMeta, cfg *ResponseConfig) error {
 	rep := meta.rep
 	codec, ok := cc608CodecFor(rep.Codecs)
@@ -289,6 +343,10 @@ func applyCC608(seg *mp4.MediaSegment, meta segMeta, cfg *ResponseConfig) error
 	if rep.initSeg == nil || rep.initSeg.Moov == nil || rep.initSeg.Moov.Mvex == nil {
 		return fmt.Errorf("cc608: missing init/trex for representation %q", rep.ID)
 	}
+	mode := cc608FlipAtCueStart
+	if cfg.CC608 != nil && cfg.CC608.SelfContained {
+		mode = cc608SelfContained
+	}
 	trex := rep.initSeg.Moov.Mvex.Trex
 	for i, frag := range seg.Fragments {
 		samples, err := frag.GetFullSamples(trex)
@@ -310,7 +368,7 @@ func applyCC608(seg *mp4.MediaSegment, meta segMeta, cfg *ResponseConfig) error
 		if i == len(seg.Fragments)-1 {
 			nextSegNr = meta.newNr + 1
 		}
-		if err := injectCC608(samples, fps, unitStartMS, meta.newNr, nextSegNr, codec); err != nil {
+		if err := injectCC608(samples, fps, unitStartMS, meta.newNr, nextSegNr, codec, mode); err != nil {
 			return err
 		}
 		if err := writeBackCC608Samples(frag, samples); err != nil {