geesawra.industries/hydraulophone
An unofficial YouTube Music app for iPhone, iPad, and Mac.
Session handoff
Latest work — 2026-09-24
The owner approved the softened Watermark app icon: a lavender droplet with
three sound-bar cutouts on the existing violet palette. The production resource
and compiler setting now select Resources/AppIcon-Watermark-Smooth.icon.
Scripts/render-app-icon regenerates its six native iOS 27 appearances; earlier
concepts remain preserved as inactive artwork. See the
icon design and validation.
Strict lint and the full simulator/device builds passed. The update installed
and launched with offline fixtures on the iPhone 18 Pro simulator, and installed
on the physical iPhone 17 Pro Max. The phone was locked, so its automatic launch
was denied and its Home Screen appearance was not visually verified. Formal
test suites remain paused. No commit was requested.
Native CarPlay audio integration is implemented in CarPlaySceneDelegate.swift.
It shares the iPhone AppModel, authentication, queue and playback controller;
Home, Library collections, Downloads and Up Next route through existing
services. CPSearchTemplate was removed because Apple reserves it for
navigation apps. Now Playing exposes repeat/shuffle and the queue. Offline Only
limits CarPlay to completed downloads and the queue. Browse work is cancelled or
discarded across account changes and scene disconnects. The iOS 27 Now Playing
publisher now treats an active CarPlay scene as active for its system-primary
request.
Simulator and device signing both include the CarPlay audio entitlement by
default. just carplay-simulator builds and launches the app; use Device Hub's
Help-menu search for “CarPlay” to locate the connection command for the selected
iPhone simulator (the old Simulator app's I/O > External Displays menu does not
apply). Physical-device installation requires Apple's approved profile. No
phone installation or CarPlay display runtime validation was performed. Formal tests remain paused;
docs/test-briefs/carplay.md records the deferred acceptance cases. See
docs/adr/0009-carplay-audio.md. No commit was
requested.
Home now fetches all available continuation pages when the Home view loads,
automatically resumes an interrupted fetch on return, and retries from the
failed continuation without discarding content already shown. CarPlay Home
shows its first page immediately, then appends continuation pages in the
background. Its More row still pages long local lists; duplicate and empty
continuations terminate safely. Coverage expectations are recorded in the
active-work and CarPlay acceptance briefs; no tests were run.
Normalize Volume is enabled by default for native Opus and AAC. Loudness travels with streams, caches and downloads; older local assets get one background metadata refresh when online. Perceptual loudness takes priority because live High and Standard responses use different relative-loudness baselines. See normalization and queue preparation for design, source provenance, validation and deferred regression briefs.
On unmetered connections with cache enabled, the next High track is prepared
after three seconds and fully cached; Standard caches its successor after the
current cache fill. High remains gapless. The public JNN key is now bundled
with attribution for ordinary home-screen launches as well as Just installs.
just lint and the bounded just simulator-smoke-listening-quality passed;
no formal test suites were run. Hardware listening confirmation remains open.
The owner authorized phone installs again in the morning. just device-install
built, installed and launched this work; simulator validation is the current
playback evidence. Formal test implementation remains paused.
Earlier today, Library kept its heading across loading and content states, and
Home personal mix playlists gained support for received browse IDs and
watch-playlist endpoints. The personal-mix canary found My Supermix and loaded
its first page and continuation. That work is committed as e1923c0.
Earlier work — 2026-09-24
Track context menus now share Play Next, Add to Queue, Go to Artist/Album and download actions across Home, song rows, downloads and Up Next. Artist pages open natively, and Library artist rows are navigable. Optional browse references preserve received IDs/params across queues and downloads; unavailable links are disabled. Offline navigation opens saved albums only. See track navigation and the UI test brief.
just lint, simulator builds and just simulator-smoke-track-actions passed.
The read-only live diagnostic followed a search artist link to seven catalog
sections and an album with eight tracks. Direct long-press/back gestures remain
unverified because Device Hub automation timed out. No formal suites or phone
deployments were run.
See the overnight handoff for startup caching,
downloads, Offline Only, listening controls and simulator acceptance. Formal
test implementation remains paused; deferred cases are in test-briefs/.
The sections below describe earlier checkpoints and may include superseded playback paths.
Current work — 2026-09-23
- The owner requires sign-in for the whole product. The root waits for restore, then presents required sign-in until a complete authenticated session is installed. Sign-out cannot reveal guest catalog or playback.
- Home lost the greeting and filter-chip strip; reaching the Home list's
pagination sentinel now requests the next continuation automatically and
keeps Retry after an error. Playlists retain their existing Library layout;
Library now has Songs, Playlists, Albums, and Artists categories using the
AuraMusic browse IDs recorded in
protocol/catalog-pagination.md. - Playback metadata now keeps album artwork, artist, and album visible in Now Playing and the mini player; collection rows include track positions. Audio quality is selected only from Settings.
- High is now selectable in Settings for an authenticated session even when runtime proof configuration is absent. That lets a simulator run expose the resolver's missing-proof error directly; it does not silently select Standard. Sign-in and network policy remain enforced.
- Production High requests use authenticated WEB_REMIX, discover the player
script timestamp, and make one aligned player request with the same session
and proof pair. This timestamp use is a Hydraulophone adaptation: pinned
AuraMusic omits it in the audio path, while the observed unaligned stream
returned 403 and the aligned stream passed. High selects the highest valid
Opus candidate, including approximately 135 kb/s if that is the best Opus
returned; no 200 kb/s cutoff or AAC/Opus bitrate comparison remains. One
proof/player/alignment attempt follows a media 403. In the latest production
canaries, High resolved and played Opus at 326,575 b/s, reported matching
duration, passed pause/resume and High→Standard→High switching, and advanced
after both 65% and 90% seeks. WebKit already had both seek targets buffered,
so unbuffered seeking remains unverified. The public JNN client key is now
vendored with attribution under
Config/; it is not an account credential. - The local cipher adapter now decodes the outer
signatureCipherenvelope once and replaces only transformed signature/nquery fields, preserving other URL bytes. It rejectssp=nbecause that would collide with thenchallenge parameter. The aligned production canary resolved and played its ciphered stream, exercising this path without adding formal tests. - A GPT-6 review found the earlier smoke could count playback after an
unobserved stall/reload and could accept a recovery seek as the requested
seek. The diagnostic now pins the playback request and seek generations,
checks clock advancement through the sustained window, and rejects proof
generators whose effective expiry has passed or expires during minting.
The current source passes
just lintandgit diff --check.just simulator-smoke-highbuilt and launched successfully after recovering the CoreSimulatorService connection. No formal tests were added or run. - Test implementation and test targets are paused at the owner's request.
Proposed cases are saved in
test-briefs/2026-09-23-active-work.md. - Validation:
just lint,git diff --check, and the High iOS Simulator build pass. The first aligned production canary passed initial progress, pause/resume, High→Standard→High switching, and 65%/90% seek progress. Two early-seek runs found both far targets were already buffered at assignment; they report random access as inconclusive, not as a playback failure. The canary checks track/quality/codec continuity and WebKit buffering at the exactcurrentTimeassignment. No formal tests were run. - A fresh Standard regression smoke at 16:13 passed after the stricter
request-generation and sustained-clock checks: 690.226-second AAC HLS,
pause/resume, and unbuffered 65%/90% seeks. The ignored diagnostic log is
.build/simulator-smoke.log. - A byte-for-byte audit of nine reference files against AuraMusic commit
185a77d31733047de06cbec619d40731755a0ec1found two High proof-lifecycle differences. Hydraulophone now mints the visitor-bound token once per live generator and applies AuraMusic's ten-minute margin to GenerateIT expiry. These are protocol-fidelity fixes, not proven causes of the observed 403. Do not claim either is the 403 root cause without a canary result. - The local High WEB decipher fallback is intentional Hydraulophone behavior; AuraMusic does not use its slow decipher fallback for the primary WEB_REMIX audio path. Hydraulophone's immediate one-time retry after a media 403 also differs from AuraMusic's client fallback behavior and remains an unvalidated resilience policy.
- The owner's latest screenshot note asks to remove the left chip now that
quality lives in Settings.
HomeViewcurrently defines only the trailing account toolbar item, and Settings is the only quality control in source. The attached temporary image was unavailable on disk, so compare against the live screen if the chip is still visible there. - Continue High only if requested: the user's listening on the live simulator
already confirms audible playback and seek-bar movement. Do not keep
triggering audible smoke seeks without a fresh need. If pursuing stronger
transport evidence, add a same-stream bounded far-range diagnostic; WebKit's
built-in buffer currently fills both seek targets before the early canary
checks. Keep formal tests paused. Proposed cases remain in
test-briefs/2026-09-23-active-work.md.
Mini-player layout follow-up
The mini-player was inset outside TabView, covering the floating tab bar.
It now uses the native bottom accessory on iOS 26+, with a per-tab safe-area
inset on earlier iOS versions. The native accessory supplies its own material.
The iOS 27 simulated-iPhone regression verified non-overlapping frames,
tappable navigation across all four tabs, and opening/closing Now Playing.
Strict lint and the simulator build passed. Only iOS 27 is installed here, so
the earlier-iOS fallback is compiled but not runtime-validated.
Overnight continuation — read this first
The owner authorized continued work, a primary-repository commit, a new Home,
catalog pagination/caching/refresh, and initial quality Settings. Playback was
checkpointed as 5f28772, then fast-forwarded into the primary checkout's
main. Do not restore the older direct-AAC prototype described in the archived
record below.
Current feature implementation:
- Home is the first tab: native shelves and filter chips, with playable song cards and typed playlist/album navigation. Albums use their raw browse IDs.
- Search, library playlists, playlist tracks, album tracks, and Home use an optional paginated service capability. Old array APIs remain first-page wrappers. Player/authentication operations are not paginated.
- Opaque continuation handling includes one in-flight page, deduplication, repeated-token termination, error/retry footers, and content-preserving pull-to-refresh.
CachedMusicServicewraps production catalog access: memory-only first-page cache, 64-entry LRU, bounded TTLs, independently cancellable shared requests, and session/resource generations. Playback URLs and credentials bypass it.- AppModel gates catalog views during account transitions; sign-out immediately hides private pages, then waits for underlying session/cache invalidation before permitting anonymous loads.
- Settings and Now Playing share persisted non-secret quality preferences. Standard remains fixed HLS AAC (~128 kb/s). High Opus remains experimental and unavailable without sign-in and runtime proof configuration. Expensive networks require an explicit High opt-in; Low Data Mode and unknown network state use Standard while retaining the preference. Adaptive Auto is not implemented or mislabeled as Standard.
- A rejected High stream remains a visible error, not an undisclosed downgrade. Select Standard to recover. Fresh High streams still intermittently return HTTP 403 despite successful proof creation and timestamp alignment.
Final integrated checks on 2026-09-23:
- Strict source/test lint passed.
- Core package: 76 Swift Testing tests plus 6 XCTest tests passed.
- Hosted Core/app/offline UI at 00:42 on iPhone 18 Pro / iOS 27: 159 tests / 165 executions, no failures or skips. This includes five UI checks for Home shelves/refresh/paging, collection navigation, Search/Library, quality availability, and a network preference surviving relaunch.
- Release Core build passed. Offline Home was installed, launched, and visually inspected on the simulated iPhone.
- A fresh Standard HLS regression at 00:05 passed: 1.421 s first progress, 0.852 s next-track progress, unbuffered 65%/90% seeks and pause/resume.
- The bounded live catalog diagnostic passed at 00:36: anonymous Home
14 + 14 items, authenticated Home 41 + 59, search 17, library
11, playlist tracks 100 + 7, and one album-detail track. Search and
library advertised no continuation in this response; their continuation
variants are covered offline. Guest Home requires stable visitor context,
just like guest playback. See the catalog protocol note for the observed
layouts and
just simulator-smoke-catalog. - Independent reviews led to fixes for overlapping cache session transitions, last-waiter cancellation, scoped continuation variants, unique Home page identities, private collection navigation reset, and refresh/queue isolation.
- The existing synchronous
AVAudioSessionactivation warning still appears in hosted playback tests. It was not the startup bottleneck measured in this session. No physical-device/background acceptance was attempted.
Remaining product follow-ups: make High Opus repeatably available before promoting it beyond experimental; design a genuine adaptive Auto option; validate background/route/interruptions on hardware only when the owner lifts the simulator-only restriction. Do not describe these as completed.
See catalog protocol, cache policy, and ADR 0002.
Priority #1 resumed after this checkpoint. See the player performance investigation for subsequent baseline evidence, implementation, and acceptance results. The shutdown record below describes the original checkpoint, not the resumed work.
Resumed status — working native HLS
- The root request gap was missing visitor context. The restored session had no
visitor value; the pinned Aura
sw.js_databootstrap supplies one anonymously. Guest profiles receive visitor context but no Cookie/Authorization/delegation. - VISIONOS now returns working direct streams and an HLS manifest. Normal playback prepares visitor context and prefers a validated audio-only HLS rendition through native AVPlayer.
- Simulator evidence at 18:32: first progress 1.657 s, next track 1.234 s, matching 370.48-second duration, and actual progress after both 65% and 90% seeks where the target was not buffered before seeking.
- HLS audio format
234(approximately 128 kb/s AAC-LC) is now preferred over233(approximately 48 kb/s HE-AAC). This is not official-app 256 kb/s High quality. The owner wants that higher-quality path too, alongside HLS, and separate fixed-quality and adaptive Auto choices. - Scrubbing now previews locally, commits on release, and holds the latest seek target against stale native time callbacks. The owner confirmed “scrubbing works great” in the simulator.
- Higher-resolution artwork and authenticated ~256 kb/s access are active follow-ups. Artwork now selects the largest declared variant and requests display-scaled pixels with fallback. Its simulator build is installed.
- The speculative normal-audio signature-timestamp change was stopped: pinned Aura's ordinary audio flow does not send it. A separate authenticated High experiment uses the matching script timestamp intentionally.
- At 21:20, High Opus (~272 kb/s advertised peak) passed proof-assisted far-range access and actual WebKit decoding/playback/seeking. Native player-control integration is in progress; the playback seek targets in that run were buffered. See the investigation record for exact limits and runtime proof configuration. AVPlayer HLS remains the working Standard path.
- The owner restricts runtime validation to the simulated iPhone and asked agents to stop writing tests during experimentation. Subsequent validation uses the simulator app; no physical-device acceptance is claimed.
- Checkpoint validation at 23:24: strict lint passed; the existing Core suite passed (54 Swift Testing tests plus 6 XCTest tests); hosted Core/app passed 114 tests / 120 executions, no failures or skips. Existing service fixtures were adjusted for prepared visitor context and pinned guest-first ordering; no new speculative tests were added.
- Latest High controller and standalone probes again received HTTP 403 before engine installation. High is labelled experimental and requires proof configuration; do not claim repeatable High acceptance. Standard's final live regression passed at ~1.468 seconds with unbuffered far seeks and pause/resume.
Archived original shutdown record — superseded above
The owner stopped this session and requested a checkpoint in the primary repository. This is an iPhone-only SwiftUI prototype, not a completed release. Read this document before relying on earlier completion claims.
Implemented in this checkout:
- Reproducible XcodeGen project (
project.yml, XcodeGen 2.46.0), iOS 17 minimum. - Keychain-backed YouTube Music web-session capture and restoration.
- Ephemeral WebKit/network cookie handling and scoped legacy-store cleanup.
- Anonymous search, authenticated playlist browsing, and first-page track lists.
- Native AAC playback using AVPlayer with an AVAssetResourceLoader/URLSession bridge, queue controls, pause/resume, seeking, and redacted diagnostics.
- Purple native UI, mini/full player, and an always-visible scrub bar that is disabled until seeking is available.
- Offline fixtures/tests and opt-in simulator smoke commands.
Verified evidence and important limits
- Strict lint and 34 Core tests passed at 15:23 local.
- The hosted simulator suite passed 70 tests / 74 executions at 15:23, with no failures or skips. One parameterized test accounts for the extra executions.
- Final shutdown validation at 15:49 passed strict lint, 34 Core tests, and 71 hosted tests / 75 executions, with no failures or skips.
- Live simulator checks restored a real session, returned 17 search results, 11 playlists, and 100 tracks from the selected playlist.
- The extended run at 14:06–14:07 demonstrated 30 seconds of playback, pause/resume, a relative seek, and next-track playback.
- The relative seek used AVPlayer's reported duration. It did not prove seeking into an unbuffered part of the complete track. The owner subsequently reported that seeking is limited to the downloaded section.
- No full-song, physical-iPhone, background-audio, interruption, or route-change acceptance has been established. Only an iPhone 18 Pro / iOS 27 simulator was available.
- The final diagnostic edits were compiled and included in the 15:49 hosted tests. No new live-stream acceptance was claimed for those logging changes. Simulator tests still emit a warning about synchronous audio-session activation on the main thread; startup tracing measured that activation at only 6–23 ms in the observed runs.
Open issues — next priorities
Slow startup and full-track random access
Startup is approximately ten seconds on the tested simulator. At 15:11:
- Stream resolved: 641 ms.
- Asset installed: 644 ms.
- Initial 2-byte content-info response: 55 ms.
- First 512 KiB response: 100 ms.
- AVPlayer item ready: 10,058 ms.
- First verified playback progress: 10,374 ms.
The loader trace had an all-to-end request for 5,998,431 bytes but recorded only two 512 KiB ranges before the request closed. The earlier diagnostic did not distinguish cancellation from failure correctly. New bounded debug timelines record terminal outcome, safe error category, HTTP status, range offsets, and query-key-presence booleans without exposing URLs or credentials. Use those to establish the cause; do not assume the file was fully downloaded.
A 64 KiB initial-read experiment did not improve readiness and produced a
failed run. It was reverted to the known 512 KiB policy. Do not repeat that
experiment without new evidence. Do not fake EOF, report a partial response's
Content-Length as the whole asset length, or set
isEntireLengthAvailableOnDemand to true for this network-backed loader.
The Android reference uses independently reopenable Media3 DataSpecs and HTTP Range requests, not a requirement to download all earlier bytes before seeking. Its normal playback chain is:
DefaultMediaSourceFactory -> ResolvingDataSource -> CacheDataSource -> OkHttpDataSource.
Pinned source:
AuraMusic MusicService.kt.
Its offline range= query handling must not be confused with playback.
Also do not mechanically copy DataSpec.subrange(dataSpec.position, ...):
that API's offset is relative, whereas AVFoundation supplies absolute offsets.
Next acceptance check:
- Obtain authoritative duration from selected format
approxDurationMs, falling back tovideoDetails.lengthSeconds. - Compare it with AVPlayer's partially parsed duration; do not mask a transport or demux failure merely by changing the slider's maximum.
- While an offset-zero request is active or cancelled, seek to 65% and 90% of the full track.
- Observe independent far-offset HTTP requests and actual playback progress afterward, without fetching all preceding ranges first.
- Verify cancelling the old request does not cancel the seek request.
Relevant files: StreamingResourceLoader.swift, PlaybackController.swift,
PlaybackSupport.swift, NowPlayingView.swift, and LiveSmokeDiagnostics.swift.
Approved deciphering follow-up — not integrated
The owner explicitly approved narrow reuse/adaptation of alexeichhorn/YouTubeKit 0.4.9. No other third-party library is approved; provide links and obtain permission before adding one.
The package's solver API is internal. The intended approach was to adapt its
JavaScriptCore signature and n solver rather than replace our working
transport/authentication stack. Preserve MIT, Meriyah ISC, Astring MIT, and
yt-dlp/ejs Unlicense notices. Never enable remote extraction services.
The unfinished isolated assignment had draft PlayerDeciphering.swift and
PlayerStreamCipher.swift files and an error-model edit, but no verified
integrated result. Those drafts are not part of this checkpoint.
If the previous Delta history is available, inspect
the deciphering child thread
for recovery; do not treat the draft as tested code.
Current playback still cannot resolve cipher-only formats or supply PO tokens. Observed WEB_REMIX responses contained two ciphered AAC formats. Tested responses supplied no HLS manifest. Deciphering does not itself implement a PO-token provider.
Protocol decisions to preserve
- Library browse ID is
FEmusic_liked_playlists; playlist views useVL<id>. - Preserve raw DATASYNC_ID. Do not send it as
onBehalfOfUser. - Use only explicit
DELEGATED_SESSION_IDfor delegated-account context. Raw DATASYNC caused HTTP 500; omission with unchanged cookies/visitor data made browsing work. - Default requests use pinned Aura WEB_REMIX configuration without mandatory homepage scraping; the previous homepage bootstrap hit a consent redirect.
- Respect profile login capability. Guest player requests must not receive Cookie, Authorization, or delegated-account context.
- Never log/persist credentials, raw media URLs, account responses, or real account fixtures. Credentials stay in Keychain.
- Native playback is AAC/MP4; arbitrary WebM/Opus is not treated as playable.
- Media transport uses only approved profile headers and strict HTTPS URL/ redirect validation, including rejection of URL-embedded credentials.
Commands
just check
just simulator-test
just simulator
just simulator-offline
just simulator-logs
just simulator-logs-recent
Opt-in live checks, using an existing authorized simulator Keychain session:
just simulator-smoke
just simulator-smoke-extended
just simulator-smoke-high
For a bounded hosted test run without automatic diagnostic collection:
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild test \
-project Hydraulophone.xcodeproj -scheme Hydraulophone \
-destination 'platform=iOS Simulator,name=iPhone 18 Pro,OS=27.0' \
-derivedDataPath .build/ios-simulator -parallel-testing-enabled NO \
-collect-test-diagnostics never \
-only-testing:HydraulophoneCoreTests -only-testing:HydraulophoneAppTests \
CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=YES CODE_SIGNING_ALLOWED=YES \
CODE_SIGN_STYLE=Manual DEVELOPMENT_TEAM=
Run just generate first in a fresh checkout. Generated Xcode projects,
build output, test results, and logs are ignored and are not the source of truth.
Current status
Implementation resumed on 2026-09-23. Proposed checks remain briefs only; wait for explicit approval before adding test code or running the formal test targets. The authenticated High canary built and played timestamp-aligned Opus at 326,575 b/s, with matching duration, pause/resume, quality switching, and progress after both far seeks. The seeks were buffered at assignment, so the canary leaves unbuffered random access open. No physical-device/background validation is claimed.