fix(apple): minimize cold stream guidance prefix

docs/operations/jellyfin-music-surface-v12.md

@@ -118,7 +118,7 @@ release is available.
 
 For an uncached `apple-download` track, Allstarr opens the compatible sidecar's
 `api/stream/{id}` response with `ResponseHeadersRead`. The sidecar first emits a
-metadata-free ID3v2.4 padding tag accepted by the supported FLAC readers, then
+empty 10-byte ID3v2.4 tag accepted by the supported FLAC readers, then
 streams FFmpeg's FLAC stdout after Apple fetch/decryption. This opens the response
 for clients with short prefix deadlines without inserting audio, changing
 duration, resampling, or routing to another provider. The gateway returns FLAC,

sidecars/apple-gateway/README.md

@@ -18,7 +18,7 @@ both on Allstarr's private network. Do not expose the gateway or wrapper login e
 - `GET /api/song/{songId}`
 - `GET /api/download/{songId}?quality=...` — complete managed FLAC artifact
 - `GET /api/stream/{songId}?quality=...` — progressive FLAC with an immediate,
-  metadata-free ID3v2 padding prelude while Apple fetch/decryption completes
+  empty 10-byte ID3v2 prelude while Apple fetch/decryption completes
 - `HEAD /api/stream/{songId}?quality=...` — FLAC type/disposition only; no media preparation
 - `POST /api/jobs/download` for supported Apple catalog or library URLs
 - `GET /api/jobs/download/{jobId}`

sidecars/apple-gateway/apple_gateway/app.py

@@ -39,17 +39,7 @@ CAPABILITIES = (
 )
 PREPARED_CACHE_TTL_SECONDS = 6 * 60 * 60
 PREPARED_CACHE_MAX_TRACKS = 32
-FLAC_GUIDANCE_PADDING_BYTES = 64 * 1024
-
-
-def _id3_padding_tag(payload_size: int) -> bytes:
-    if not 0 <= payload_size <= 0x0FFFFFFF:
-        raise ValueError("ID3 payload size is outside the synchsafe range")
-    size = bytes((payload_size >> shift) & 0x7F for shift in (21, 14, 7, 0))
-    return b"ID3\x04\x00\x00" + size + bytes(payload_size)
-
-
-FLAC_GUIDANCE_PREFIX = _id3_padding_tag(FLAC_GUIDANCE_PADDING_BYTES)
+FLAC_GUIDANCE_PREFIX = b"ID3\x04\x00\x00\x00\x00\x00\x00"
 
 
 def _version(distribution: str) -> str:
@@ -345,8 +335,8 @@ def create_app(
     @application.get("/api/stream/{song_id}")
     async def stream_song(song_id: str, quality: str = "alac-16-44") -> StreamingResponse:
         async def content() -> AsyncIterator[bytes]:
-            # ID3v2 tags may precede FLAC. A padding-only tag opens the response
-            # immediately while Apple prepares the real, otherwise unchanged audio.
+            # Open the response while Apple prepares the unchanged audio. Keep the
+            # empty tag short: clients may count its bytes when seeking the cached file.
             yield FLAC_GUIDANCE_PREFIX
             source = await prepare_song(song_id, quality, "aac-web")
             async for chunk in process_runner.stream_flac(source):

sidecars/apple-gateway/tests/test_gateway.py

@@ -14,7 +14,6 @@ from fastapi.responses import StreamingResponse
 
 from apple_gateway.app import (
     API_VERSION,
-    FLAC_GUIDANCE_PADDING_BYTES,
     FLAC_GUIDANCE_PREFIX,
     create_app,
 )
@@ -283,16 +282,9 @@ async def test_song_stream_opens_before_preparing_configured_quality(settings: S
     assert runner.calls[-1][1] == "alac"
 
 
-def test_flac_guidance_prefix_is_a_metadata_free_id3v24_padding_tag():
-    assert FLAC_GUIDANCE_PREFIX[:6] == b"ID3\x04\x00\x00"
-    encoded_size = FLAC_GUIDANCE_PREFIX[6:10]
-    assert all(byte < 0x80 for byte in encoded_size)
-    decoded_size = sum(
-        byte << shift for byte, shift in zip(encoded_size, (21, 14, 7, 0))
-    )
-    assert decoded_size == FLAC_GUIDANCE_PADDING_BYTES
-    assert len(FLAC_GUIDANCE_PREFIX) == 10 + FLAC_GUIDANCE_PADDING_BYTES
-    assert not any(FLAC_GUIDANCE_PREFIX[10:])
+def test_flac_guidance_prefix_is_an_empty_id3v24_tag():
+    assert FLAC_GUIDANCE_PREFIX == b"ID3\x04\x00\x00\x00\x00\x00\x00"
+    assert len(FLAC_GUIDANCE_PREFIX) == 10
 
 
 @pytest.mark.asyncio