geesawra.industries/hydraulophone
An unofficial YouTube Music app for iPhone, iPad, and Mac.
Player performance investigation — 2026-09-22
This follows priority #1 in SESSION-HANDOFF.md. Startup speed and full-track random access are separate acceptance requirements. Changing the scrubber maximum alone is not a transport or demux fix.
Latest investigation after native Opus/gapless: High startup latency. A fresh simulator trace reproduced 2.94-second startup; repeated watch-page/script work cost about 0.93 seconds. It includes pinned AuraMusic and current Metrolist/InnerTubeX comparisons. Prewarm/preparation reuse and a dedicated public-JS HTTP disk cache now reduce the observed simulator sample to 1.69 seconds first selection and 0.57 seconds warm return. A process restart reused cached script bytes. These are individual simulator samples; the new implementation is not yet validated on the phone. Encoded track caching and downloads are described in ADR 0007.
Current High update — 2026-09-23
The owner prefers Opus even around 135 kb/s over a numerically higher AAC
format. Production High therefore selects the highest valid Opus candidate and
does not apply the old 200 kb/s cutoff. The pinned AuraMusic audio request omits
signatureTimestamp, but the live authenticated WEB_REMIX stream that passed
media ranges and WebKit playback required it. Production now fetches the player
script and makes a second authenticated, timestamp-aligned request with the
same session and proof pair before resolving the ciphered Opus URL.
Evidence before this production change: aligned WEB_REMIX Opus at 272,202 b/s returned HTTP 206 at 0%, 65%, and 90%. A standalone WebKit probe reported the full 370.4935-second duration, advanced after both 65% and 90% seeks, and completed a short playback interval. The earlier unaligned production request returned HTTP 403 on both its original and refreshed proof attempts.
The first production canary then resolved authenticated aligned Opus at 326,575
b/s through the shared controller and passed first progress, pause/resume, and
High→Standard→High switching. A second canary moved the 65%/90% seeks directly
after initial progress; both seeks advanced but both targets were already
buffered. The canary correctly calls this inconclusive for unbuffered seeking.
It does not show a playback failure. Same-stream far-range probes in the
production resolver would provide stronger seek evidence without relying on
WebKit's buffering window. No formal tests have been added or run; proposed
checks remain in docs/test-briefs/2026-09-23-active-work.md.
On a physical iPhone on 2026-09-23, two consecutive High song selections took 4.698 s and 3.443 s to first verified progress. The first spent 3.687 s in stream resolution: proof 0.428 s, initial player response 0.432 s, player script fetch 1.050 s, aligned response 0.287 s, local decipher 1.196 s, and media probe 0.294 s. The second still fetched the player script (1.345 s), while the prepared decipherer reused its code (0.069 s). This establishes repeated script discovery as a latency cost; it does not implicate the Opus bitrate or explain the blank iOS media card.
A ten-minute in-memory player-script/timestamp cache was tried on-device to skip the first player response and script fetch after a successful probe. The owner reported no perceptible startup improvement and less reliable playback. The cache was reverted. Keep the proven timestamp-aligned request and bounded 403 recovery until a faster sequence passes sustained device playback as well as timing checks. Metrolist's stream URL cache proposal addresses expired URL reuse; it is a recovery reference, not evidence for skipping the player-script discovery in this iPhone flow.
Working simulator path
At 18:15, header-presence diagnostics established that the restored Keychain
session had no visitor value. Simply propagating its optional field had
therefore not exercised visitor parity. The missing step was Aura's anonymous
https://music.youtube.com/sw.js_data bootstrap.
At 18:18, that bootstrap succeeded and guest VISIONOS changed from UNPLAYABLE to OK. Opus byte ranges at zero, 65%, and 90% all returned matching HTTP 206 responses. Cookie and Authorization remained absent on guest requests.
At 18:19, native AAC through the existing loader read the complete file and started in 2.591 seconds, but AVPlayer's duration was roughly double the metadata duration. This justified testing a different native container path, not merely widening the slider.
At 18:32, the audio-only HLS path demonstrated:
| Check | Result |
|---|---|
| First verified playback progress | 1.657 seconds |
| Next-track verified progress | 1.234 seconds |
| Playlist and AVPlayer duration | 370.480 seconds, matching |
| Seek to 65% | Target unbuffered beforehand; playback advanced afterward |
| Seek to 90% | Target unbuffered beforehand; playback advanced afterward |
| Sustained playback, pause/resume, next | Passed the app diagnostic |
The ordinary app now prepares visitor context only for playback (not mandatory search/library startup) and prefers audio-only HLS. See visitor context and native HLS. The owner subsequently confirmed the scrubber's drag/release behavior after the stale-clock fix.
At 00:05 on 2026-09-23, after adding the catalog cache, Home and shared quality
preferences, the same simulated-iPhone extended check passed again:
1.421 s first verified progress, 0.852 s next-track progress, matching
370.493/370.480-second authoritative/parsed durations, actual progress after
unbuffered 65% and 90% seeks, and pause/resume. The selected HLS rendition was
again 234 at 128,000 advertised bits/second. The app was terminated afterward.
The manifest exposed audio groups 233 and 234 without explicit BANDWIDTH.
Selection initially chose 233; it now prefers 234 (~128 kb/s AAC-LC)
over 233 (~48 kb/s HE-AAC). This is a fixed available quality, not a claim
of parity with the official app's ~256 kb/s High setting. That higher-quality
request remains a separate, active investigation.
Everything below is historical diagnosis; the earlier “not an improvement” statements describe the failed decipher-first checkpoint, not current HLS.
High-quality Opus evidence
The authenticated WEB response advertises ~265 kb/s AAC and ~272 kb/s Opus. A timestamp-aligned, tokenless Opus URL passed all three range probes at 20:35, but a fresh resolution at 21:04 returned 403. That single tokenless success is not a reliable production strategy.
At 21:20 the approved local proof flow completed both native YouTube proof requests with HTTP 200 and minted the visitor/video-bound pair. With those tokens and the matching player-script timestamp, High Opus passed byte-zero, 65%, and 90% range checks. A separate native-WebKit audio experiment then demonstrated:
- actual playback with 370.4935-second duration;
- advancing playback after both 65% and 90% seeks;
- a successful short sustained run.
Those playback targets were already buffered; this run is not proof of unbuffered WebKit seeking. The earlier HTTP probes independently establish far-range access. AVPlayer reports no native WebM/Opus support on this simulator, while WebKit reports support and actually decoded the stream. No GStreamer/VLC/FFmpeg dependency was added.
The Opus backend is integrated into the shared player controls. HLS remains the Standard/default path. The owner permits simulator validation, and background/physical-device behavior of the WebKit Opus backend remains unverified.
The later shared-controls check and a matching standalone probe both received HTTP 403 again before engine installation, despite successful proof generation. Both one-byte and two-byte offset-zero reads were rejected, ruling out that probe-size difference. High is therefore explicitly experimental: the earlier successful decode does not establish repeatable availability or complete shared-controls acceptance. The bounded comparison hook was removed.
The subsequent Standard regression passed: ~1.468-second first progress, matching duration, unbuffered 65%/90% seek progress, and pause/resume. Review fixes also cover pause during a WebM seek, Play intent during a quality switch, fresh refresh budgets on quality changes, and independent cancellation of coalesced proof consumers.
On 2026-09-23 at 16:01, just simulator-smoke-extended passed on the iPhone
18 Pro / iOS 27 simulator after adding exact-time seek evidence. Standard AAC
HLS played with authoritative/parsed durations of 690.226/690.200 seconds,
pause/resume passed, and both 65% and 90% seeks advanced from targets reported
unbuffered immediately before the native seek assignment. This confirms the
existing Standard path still works with the revised smoke instrumentation.
Current validation: a DEBUG-only High foreground canary is available as
just simulator-smoke-high. It checks track and quality identity, Opus codec
and bitrate, sustained clock advancement, pause/resume, quality switching, and
65%/90% seek progress. WebKit's buffered state is sampled inside the JavaScript
seek operation immediately before currentTime is assigned. Already-buffered
targets are reported as inconclusive, not accepted as random-access evidence.
On 2026-09-23, the proof-backed High canary ran once with the public JNN client
key extracted transiently from the pinned AuraMusic source. Both proof
exchanges succeeded. The first media URL returned HTTP 403; the resolver
invalidated proof and fetched one fresh player response and proof pair, whose
media URL also returned HTTP 403. The canary stopped before WebKit playback,
so it does not establish candidate decoding or seek behavior. Test targets
remain paused; proposed cases are in
docs/test-briefs/2026-09-23-active-work.md.
Proof configuration is supplied transiently through the simulator process
environment (HYDRAULOPHONE_PUBLIC_JNN_KEY, via the host's SIMCTL_CHILD_
prefix). just simulator and just simulator-smoke-high load the public key
from the pinned AuraMusic source after verifying the source file digest; an
explicit SIMCTL_CHILD_HYDRAULOPHONE_PUBLIC_JNN_KEY override is also accepted.
It is public protocol configuration, not a developer's personal API key. No
key literal, obfuscated key fragments, proof token, or attestation body is
stored in source or logs. The general YouTube web API key was not a substitute
for this proof-specific configuration.
Baseline before this change
Two bounded live simulator runs used the existing authorized Keychain session. Only redacted Hydraulophone diagnostics were collected; no credentials, media URLs, or account responses were saved as fixtures.
At 15:55, the existing extended smoke failed after sustained playback and pause/resume, when its relative seek triggered a player failure. Refresh exhausted the remaining playable profiles. Initial readiness took 10,282 ms; first verified progress took 10,598 ms.
At 15:56–15:57, debug-level collection distinguished normal cancellation from the range failure:
| Event | Observed result |
|---|---|
| Stream resolved | 726 ms after selection; direct AAC from IOS/21.03.3 |
| Asset installed | 732 ms after selection |
| Content-info read | HTTP 206; bytes 0–1; total asset length 5,998,431 bytes |
| Initial all-to-end read | HTTP 206 for 0–524,287 and 524,288–1,048,575 |
| Initial read terminal state | AVPlayer cancelled it at 313 ms after loader creation |
| Independent later read | Requested absolute offset 1,130,496; HTTP 403 at 371 ms; no bytes returned |
| Item ready | 10,189 ms after selection |
| First verified progress | 10,504 ms after selection |
The media URL had no range, n, or pot query keys; values were not logged.
The basic smoke still reported success because two seconds of initial progress
does not demonstrate full-track access. This trace does not establish why
the server rejected the later range.
Bounded follow-up experiments
These used freshly resolved streams and ephemeral loaders before AVPlayer was installed, separating server rejection from AVPlayer cancellation.
| Time | Experiment | Result |
|---|---|---|
| 16:18 | Original headers vs explicit Accept-Encoding: identity; each tested 2 bytes and 512 KiB at offsets 0 and 1,130,496 | Both variants returned 206 at zero and 403 at the later offset. Eight requests total. |
| 16:20–16:21 | Diagnostic-only query-addressed ranges, checked separately with absolute and slice-relative HTTP offsets | Offset zero exposed a two-byte subresource, not the whole asset. The far absolute request returned 416; the correctly slice-relative request still returned 403. No query-range policy was adopted. |
| 16:26 | The lower-bitrate direct AAC format, original vs identity encoding | Two-byte zero probes succeeded with total length 2,261,464; both far probes and initial 512 KiB probes returned 403. No lower-quality selection policy was adopted. |
The last run's terminal log collection was interrupted by a conversation message; its bounded results were recovered from the same simulator process's redacted subsystem log, not by repeating requests.
All temporary probe APIs, query mutations, and alternate-format flags were removed. These experiments establish that cancellation, byte-range size, and the tested encoding-header difference do not explain the failing later read. They do not establish whether the server requires a PO token or another client capability.
The owner then authorized proceeding with the handoff's deciphering follow-up, including vendoring the pinned YouTubeKit source and exposing only the needed solver. That work preserves the existing transport/authentication stack and does not enable remote extraction services. Successful deciphering alone will not count as streaming-performance acceptance.
Duration safeguards checkpoint
At 16:36, strict lint, 39 Core tests, and 83 hosted tests / 87 executions passed with zero failures or skips. This checkpoint predates deciphering.
The normal, unmodified-range extended smoke at 16:37 reported:
- authoritative selected-format duration: 370.493 seconds;
- AVPlayer parsed duration: 440.338 seconds;
- readiness: 9,913 ms; first verified progress: 10,230 ms;
- the same two initial 512 KiB responses followed by HTTP 403.
An incompletely parsed duration can therefore be an overestimate, not
only a shortened duration. The smoke failed explicitly with
duration_mismatch; it did not run or claim the 65%/90% seeks. Full
timeline consistency is a prerequisite for those acceptance checks.
Authoritative metadata is kept separate from AVPlayer's duration. Normal UI and remote full-track seeking are disabled on a substantial mismatch, with an explanatory player message; changing metadata alone does not make the scrubber actionable. Restart-at-zero remains available.
Local deciphering checkpoint
The actual pinned YouTubeKit parser-based solver is now bundled (Meriyah, Astring, and yt-ejs, with verified blob hashes and complete licenses). Synthetic IIFE fixtures exercise the real parser/generator, both challenges, and reuse of prepared player code. Those tests also passed inside the iOS Core framework on the simulator, verifying resource packaging.
The 17:14 live run successfully fetched the current player script and locally deciphered both WEB_REMIX AAC formats, but both resulting media probes failed. The 17:18 run repeated that check after making probe headers identical to playback's five approved media headers; both probes returned HTTP 403. No credentials were added to either media or script requests.
The resolver fell back to the same IOS source and the same partial-range failure. First verified progress was 12,358 ms at 17:18, versus roughly 10,500 ms in the original baseline. Thus this checkpoint is not a performance improvement: the failed new candidate adds work before the old fallback. Signature-timestamp alignment with the fetched script is the next reference parity check. A PO-token requirement remains a possibility, not an established diagnosis.
Review also found and corrected a false-positive seek-evidence path: each seek now has an upper event boundary at the next seek marker, so a 90% request cannot satisfy the 65% check. This regression test passed on the simulator.
Known solver limitation: byte/challenge/cache sizes are bounded, and execution is off the main actor with no native network/filesystem bridge. However, JavaScriptCore does not provide a public Swift execution-interruption or heap limit here. Cancellation checks cannot interrupt a running JavaScript loop. This is an outstanding availability-hardening concern, not a credential-leak finding, and must not be described as a hard execution timeout.
Required acceptance
- Carry selected-format
approxDurationMs, falling back tovideoDetails.lengthSeconds, separately from AVPlayer's parsed duration. - Seek to 65% and 90% of that full duration and observe actual progress near each target, not only a seek callback or slider update.
- Establish independent far-offset HTTP reads before all preceding ranges have been fetched, while the initial request is active or cancelled.
- Establish that cancelling an old loading request does not cancel a new one.
- Compare startup timings before and after any transport change.
Preserve the known 512 KiB range policy unless new evidence warrants a change. Do not fake EOF, report partial response length as asset length, or declare the entire network resource available on demand. The handoff's reverted 64 KiB experiment is not being repeated.
Reference checks
The pinned AuraMusic playback path uses independent 512 KiB HTTP ranges and
the unmodified resolved media URL. Its offline downloader's range= query
is not part of this playback path. Relevant sources at commit
185a77d31733047de06cbec619d40731755a0ec1:
- Playback DataSpec and range cap.
- Five media-profile headers.
- Byte-zero validation with those headers.
Aura pins Media3 1.10.1. Its
OkHttpDataSource request construction
explicitly sets Accept-Encoding: identity for byte-range requests.
Hydraulophone's baseline does not set this explicitly. This is a candidate
for a single-variable comparison, not proof of a wire-level difference or
an explanation of the HTTP 403: URLSession can synthesize headers.
No reference source supports adding credentials to media requests or treating byte-zero probe success as proof of full-track random access. No reference implementation code or new runtime dependency was added for this investigation.
Validation environment
Xcode 27, iPhone 18 Pro / iOS 27 simulator. The unmodified hosted Core/app suite passed again at 15:59. The owner explicitly restricted this investigation to the simulated iPhone. No physical-device validation is being performed or claimed; no signing material or project signing changes have been added.
Native Opus migration, 2026-09-23
The native High simulator diagnostic passed on a 690.241-second stereo Opus stream. Stream resolution took 2.804 seconds; native packet reading, decoding, and preparation added 236 ms; first verified render progress was at 3.319 seconds. A later switch back to High resolved in 1.592 seconds, prepared native output in 92 ms, restored the seek position, and verified progress at 1.997 seconds. Both 65% and 90% seeks were unbuffered and produced progress near the target; pause/resume and switching to Standard also passed without a retry.
Those are simulator measurements. On the iPhone, first verified progress was 3.716 seconds cold, then 2.504, 2.731, and 2.491 seconds for subsequent selections. Native readiness added 109–280 ms after resolution. The owner confirmed the faster start and a working Lock Screen card. The engine removes WebKit output startup while retaining the existing InnerTube resolution sequence; long background/route/interruption validation remains outstanding.