tvheadend: audio/video start alignment confirmed; 107 is no longer a demo

Five runs per encoder with the rewritten 108 close the problem outright.
Offset between the first audio packet and the first picture, negative meaning
the picture comes first:

    step                  SOFTWARE        VAAPI          QSV
                          med / worst     med / worst    med / worst
    none                   534 / 534      1391 / 1391    1368 / 1368
    107 alone              130 / 226       356 / 1052       85 / 110
    107 + 108 (flag)       280 / 295       304 /  385       53 /  93
    107 + 108 (pts)        -11 /   -5       -9 /    0      -18 /   -2

Fifteen measurements in the last row, every one at or below zero: no run left
with audio ahead of the picture. The DEMONSTRATION label comes off 107 -- the
remedy is settled and the numbers back each step of it.

Adds 106-108-av-start-HOWTO.txt, recording how the three patches divide the
problem and why none substitutes for another: 106 acts on a frame entering the
encoder, 107 and 108 on packets leaving for the client. Without 106 the first
picture lands one frame later and the other two discard 3003 ticks more audio
than they need to.

The flag-based row is kept deliberately. That version of 108 removed the VAAPI
worst case and did nothing for software, because a flag set by the first
picture lets through audio arriving behind it stamped earlier -- one software
recording shows VIDEO at pts 572 ms written first, then six audio packets
stamped 277 to 384 ms. The timestamp comparison is the point, and 107 already
had it right.

Chain applies with zero rejects from a pristine tarball.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QEH1b4ASNYSrZFQnEeroj8

Author: th0ma7

cross/tvheadend/patches/106-108-av-start-HOWTO.txt

@@ -0,0 +1,68 @@
+=============================================================================
+ Audio/video start alignment -- 106, 107 and 108 together
+=============================================================================
+
+Symptom: a transcoded stream begins with sound over a blank or frozen picture,
+half a second to a second and a half of it, on every encoder path.
+
+Cause, measured rather than assumed. The video decoder cannot produce anything
+until the source delivers an MPEG-2 sequence header, which is where width and
+height come from; timing the logs, only 23 to 87 ms separate the filter graph
+being configured from the first frame leaving it, so essentially the whole wait
+is that. The audio encoder meanwhile runs from the first moment. Two things
+then let its output reach the client ahead of any picture:
+
+  - globalheaders releases its hold queue as soon as headers are complete, and
+    that queue holds several hundred ms of audio with no picture beside it;
+  - after the release gh_passthru forwards everything unfiltered, and the audio
+    encoder lags the video one on the delivery clock while stamping its output
+    with the original stream times -- so audio arrives *after* the first picture
+    carrying a pts *before* it.
+
+Each patch closes one part, and none of them substitutes for another:
+
+  106  video.c        recovers the first frame's timestamp from its dts so the
+                      monotonicity guard stops discarding it. Without it the
+                      first picture is one frame later, which is 3003 ticks
+                      more audio for 107 and 108 to discard.
+  107  globalheaders  drops audio stamped before the first picture when the
+                      hold queue is released.
+  108  globalheaders  keeps that same timestamp test running past the release,
+                      so late-arriving early-stamped audio is caught too.
+
+Offset between the first audio packet and the first picture, measured by
+recording the stream with curl and reading the Matroska blocks. Negative means
+the picture comes first, which is what a viewer wants:
+
+    step                  SOFTWARE        VAAPI          QSV
+                          med / worst     med / worst    med / worst
+    none                   534 / 534      1391 / 1391    1368 / 1368
+    107 alone              130 / 226       356 / 1052       85 / 110
+    107 + 108 (flag)       280 / 295       304 /  385       53 /  93
+    107 + 108 (pts)        -11 /   -5       -9 /    0      -18 /   -2
+
+Five runs per encoder in the final row, fifteen measurements, every one of them
+at or below zero -- no run left with audio ahead of the picture.
+
+The middle row is kept because it is instructive. That version of 108 gated on
+"have we delivered a picture yet" instead of comparing timestamps. It removed
+the VAAPI worst case, 1052 down to 385 ms, and did nothing at all for software,
+because a flag is set by the first picture and then lets through the audio that
+arrives behind it stamped earlier. Reading one software recording in file write
+order shows it plainly:
+
+    VIDEO  pts  572 ms     <- delivered first
+    audio  pts  277 ms
+    audio  pts  298 ms      ... six of them, all stamped ahead of that picture
+
+The timestamp comparison is the whole point, and 107 already had it right.
+
+Cost: the leading audio is discarded, up to about 1.4 s of sound the source did
+provide. Holding it instead does not work -- holding does not alter timestamps,
+so a later release still stamps it ahead of the first picture and the player
+still shows a blank frame. Making that work would mean shifting audio
+timestamps forward, which desynchronises sound from picture. Discarding is the
+only variant that closes the gap without touching synchronisation.
+
+None of this is introduced by PR #2117: video.c's guard and globalheaders.c are
+both identical in master (45cbe4adb).

cross/tvheadend/patches/106-video-recover-first-frame-pts.patch

@@ -55,6 +55,12 @@ joins the stream. A VAAPI run that joined on a P frame produced no untimed
 frame at all -- the decoder had no reference and discarded everything until the
 next key frame, by which point timestamps were sound again.
 
+Still worth carrying alongside 107 and 108, which close the audio/video
+start-up gap downstream in globalheaders.c. They do not overlap: this one acts
+on a frame entering the encoder, they act on packets leaving for the client.
+Without it the first picture lands one frame later, so 107 and 108 discard
+3003 ticks more audio than they need to. See 106-108-av-start-HOWTO.txt.
+
 Not introduced by PR #2117: the guard is identical in master (45cbe4adb).
 
 Left alone deliberately: self->pts is seeded to 0 by the calloc of TVHContext,

cross/tvheadend/patches/107-globalheaders-align-av-start.patch

@@ -1,9 +1,5 @@
 Start the audio and video tracks together on a transcoded stream.
 
-DEMONSTRATION PATCH -- the mechanism is measured, the remedy is one of two
-possible ones and is offered for discussion rather than as a settled fix. See
-the trade-off at the end.
-
 Recording the output of three profiles with curl and reading the Matroska
 blocks directly shows the audio track beginning well before the first picture:
 
@@ -54,7 +50,20 @@ the release and the first picture still slips out ahead of it. Patch 108
 extends the same filter past the release and closes that second window; the two
 are meant to be measured separately.
 
-The trade-off, and why this is a demonstration. Discarding leading audio means
+Final measurement, five runs per encoder, offset between the first audio packet
+and the first picture (negative = picture first, which is what a viewer wants):
+
+    step                  SOFTWARE        VAAPI          QSV
+                          med / worst     med / worst    med / worst
+    none                   534 / 534      1391 / 1391    1368 / 1368
+    107 alone              130 / 226       356 / 1052       85 / 110
+    107 + 108 (flag)       280 / 295       304 /  385       53 /  93
+    107 + 108 (pts)        -11 /   -5       -9 /    0      -18 /   -2
+
+Fifteen measurements in the final row, every one at or below zero. See
+106-108-av-start-HOWTO.txt for how the three patches divide the problem.
+
+The trade-off. Discarding leading audio means
 the stream starts at the first picture and loses up to ~1.4 s of sound that the
 source did provide. The alternative is to hold the audio instead of dropping
 it, so nothing is lost but start-up latency grows by the same amount. Which is

cross/tvheadend/patches/108-globalheaders-align-av-passthru.patch

@@ -41,9 +41,18 @@ gh_first_video_pts is seeded to PTS_UNSET at creation -- calloc would leave it
 at 0, a legitimate timestamp -- and reset in gh_flush(), which is the one place
 every stop and restart path goes through.
 
-Untested at runtime. Same measurement as before: record with curl, compare the
-first audio and first video timestamps, several runs per profile since the
-spread between runs is wide.
+Final measurement, five runs per encoder, offset between the first audio packet
+and the first picture (negative = picture first, which is what a viewer wants):
+
+    step                  SOFTWARE        VAAPI          QSV
+                          med / worst     med / worst    med / worst
+    none                   534 / 534      1391 / 1391    1368 / 1368
+    107 alone              130 / 226       356 / 1052       85 / 110
+    107 + 108 (flag)       280 / 295       304 /  385       53 /  93
+    107 + 108 (pts)        -11 /   -5       -9 /    0      -18 /   -2
+
+Fifteen measurements in the final row, every one at or below zero. See
+106-108-av-start-HOWTO.txt for how the three patches divide the problem.
 
 Not introduced by PR #2117: globalheaders.c is untouched by it.