~ knotless Search/
↑↓ move↵ open⇧↵ all results

geesawra.industries/hydraulophone

An unofficial YouTube Music app for iPhone, iPad, and Mac.

0
0
main
302 lines · 14.3 KB Raw History

Hydraulophone agent guide

Project intent

Hydraulophone is a native SwiftUI YouTube Music-compatible client for iPhone, iPad, and Mac. It is a greenfield project and will be developed primarily by agents from the command line, not interactively in Xcode.

The iOS app supports both iPhone and iPad, and the shared app also builds for Mac Catalyst. Keep these as one feature implementation with platform-appropriate navigation and system behavior. Do not add Apple TV, watchOS, visionOS, Android, or a server component unless the owner explicitly changes this scope.

The initial product direction is:

  • Swift and SwiftUI for the app.
  • Native Apple frameworks first.
  • A small, testable networking and domain layer rather than networking code in SwiftUI views.
  • A real end-to-end vertical slice over broad placeholder UI.
  • One SwiftUI app implementation with iOS and Mac Catalyst destinations; iPhone, iPad, and Mac must not drift into separate feature implementations.

This file is the default engineering contract for all agents. More specific AGENTS.md files may add rules for their directory.

Reference implementation and protocol boundary

Use TeamAuraMusic/AuraMusic to learn the YouTube Music/InnerTube request shapes, response conventions, client profiles, playback behavior, and failure modes. Useful reference areas include:

  • innertube: transport, client context, request bodies, response models, continuations, and page parsing.
  • InnerTube.kt: request construction, headers, login signing, retries, and endpoint boundaries.
  • YouTube.kt: domain-facing operations and parsing.
  • YTPlayerUtils.kt: playback URL and format handling.

AuraMusic is a reference, not a runtime dependency. Do not port Kotlin mechanically, copy large sections of source, or assume its current behavior is an official YouTube API contract. InnerTube is undocumented and changes without notice. When relying on a behavior, record the AuraMusic source URL and the source commit in a protocol note or ADR.

Hydraulophone will be GPL-3.0 licensed, consistent with the AuraMusic reference. A clean-room Swift reimplementation based on observed protocol behavior is still preferred over a mechanical Kotlin port, but implementation code may be adapted when its GPL-3.0 provenance is preserved. Retain required copyright and license notices, and document adapted code and its source commit.

Hydraulophone is not affiliated with YouTube or Google. Do not describe it as official, and do not add claims that imply endorsement. Avoid collecting, storing, or transmitting more user data than the feature requires.

Architecture rules

Keep these boundaries explicit:

SwiftUI views
    -> feature state / view models
        -> domain services
            -> InnerTube transport and decoding
            -> playback service
            -> persistence / credentials
  • SwiftUI views render state and send user intents. They must not construct URLRequests, parse JSON, or own long-lived playback/network tasks.
  • Keep transport DTOs separate from stable domain models. InnerTube responses are large, polymorphic, and prone to adding or removing fields.
  • Put protocol-specific code behind small interfaces so fixture-based tests do not need the network.
  • Prefer Swift structured concurrency. Use async/await, cancellation, and Sendable value types. Use actors for mutable session, cache, and playback state where appropriate; do not mark the entire application @MainActor just to avoid designing isolation.
  • UI-facing state belongs on the main actor. Heavy decoding, persistence, and network work must not block it.
  • Use typed errors with enough context for recovery and a useful user-facing message. Do not turn every failure into an empty list or silently retry forever.
  • Prefer the Observation framework and simple dependency injection when the deployment target supports them. Do not introduce a large architecture framework without a concrete benefit.
  • Prefer URLSession, Codable, AVFoundation, MediaPlayer, Keychain Services, and other system APIs before adding a package dependency.

The minimum deployment target, bundle identifier, signing setup, and project generation tool are not decided yet. The first setup change must choose and document them. Project configuration must be reproducible from checked-in files; do not require an agent to click through Xcode project settings.

InnerTube protocol rules

Treat the following as implementation facts to isolate and test, not as guaranteed permanent API:

  • Requests use a client profile containing client name, client version, locale, and, when available, visitor data. The client context is part of the request body.
  • Common requests include YouTube client metadata headers and an appropriate origin/referer. Centralize those headers in the transport layer and keep client profiles configurable rather than scattering literals across features.
  • Core operations generally include search, browse, player, next/queue, suggestions, and account/library mutations. Add an operation only when a product feature needs it.
  • Continuation tokens are opaque. Store and pass them unchanged; never parse them into an app-level ID or manufacture them from assumptions.
  • Decode defensively: tolerate unknown fields, missing optional renderers, and response layout variants. A missing field should produce a typed absence, not a crash.
  • Keep a sanitized fixture for every supported response shape. Fixtures must not contain cookies, authorization headers, personal account data, or unnecessarily large media payloads.
  • Search filter parameters and other opaque encoded values must be treated as protocol data. Keep encoding/combination logic in one tested adapter.
  • Do not log request bodies, cookies, authorization values, visitor data, raw stream URLs, or full account responses.

Authentication

Authentication is required for all user-facing browsing and playback. The app shell must finish restoring an authenticated session, or keep the user on a non-dismissible sign-in screen; do not expose anonymous catalog or playback paths through the product UI. Keep protocol-level guest support isolated for bounded diagnostics and testing. Treat web session cookies and derived authorization values as credentials:

  • Store credentials only in the Keychain, never in UserDefaults, source, fixtures, crash reports, or normal logs.
  • Keep login/session management separate from anonymous requests.
  • Model expiry and sign-out explicitly. Clear all related Keychain data on sign-out.
  • Do not invent a credential collection flow. Use a reviewed system/browser authentication approach and document its security and platform constraints before implementing it.
  • If a protocol request uses a derived session signature, compute it in one tested component and redact its inputs from diagnostics.

Playback

The player endpoint can return expiring adaptive formats, separate audio and video streams, client-specific restrictions, and playback metadata needed by YouTube. Do not persist direct media URLs as durable IDs and do not assume an URL will remain valid after a session.

  • Keep stream selection policy separate from response decoding. Prefer an audio-only format suitable for AVPlayer, and make codec/container choices explicit.
  • Refresh expired or rejected stream URLs through the player flow rather than retrying the same URL indefinitely.
  • Handle cancellation, interruptions, route changes, network loss, and background/foreground transitions as normal states.
  • Use AVAudioSession, Now Playing metadata, and MPRemoteCommandCenter only in the playback layer.
  • Validate background playback on a physical iPhone. Simulator playback is useful for UI and unit tests but is not evidence that audio session behavior works on hardware.
  • Do not add downloads/offline storage, transcoding, equalization, or casting until each has a clear product requirement and a reviewed design.

Networking and resilience

  • Configure request and resource timeouts deliberately.
  • Retry only transient transport failures and rate-limited responses where a bounded retry is appropriate. Do not retry malformed responses, auth failures, most client errors, or cancelled tasks.
  • Use cancellation-aware exponential backoff with a small attempt limit.
  • Avoid concurrent duplicate requests for the same resource when an actor or task-sharing mechanism can make this deterministic.
  • Respect server responses and avoid polling loops that create unnecessary traffic.
  • Make cache policy explicit. Do not cache credentials or expiring media URLs as if they were permanent data.
  • Surface offline and degraded-network states distinctly from an empty result.

Swift and UI conventions

  • Use clear feature-oriented names and small files. Follow the existing formatter/linter configuration once one is added.
  • Avoid force unwraps and try! in production code. If an invariant truly cannot fail, encode it in the type or explain and test the invariant.
  • Do not use Task.detached without a documented isolation and cancellation reason.
  • Keep previews and sample data deterministic and offline.
  • Design loading, empty, error, retry, and partial-content states before calling a screen complete.
  • Support Dynamic Type, VoiceOver labels, sufficient contrast, reduced motion, and usable touch targets from the first real screen.
  • Do not hard-code layout for one simulator size.
  • Never put protocol secrets or real account data in previews or screenshots.

Tests and fixtures

Every protocol or stateful feature should have tests at the lowest practical layer:

  • Unit-test request construction, client context, header policy, stream selection, continuation handling, search parameter encoding, and error mapping.
  • Decode sanitized JSON fixtures for success, missing optional sections, continuation pages, authentication failures, rate limits, and malformed responses.
  • Test view models with injected fake services and controllable clocks/tasks.
  • Test playback state transitions without requiring a live YouTube request.
  • Add an integration test only when it can be opt-in and cannot expose credentials or make an uncontrolled volume of requests.
  • Never make the default test suite depend on a live InnerTube endpoint.

When behavior depends on a changing external response, capture the smallest sanitized fixture and explain its source and date in a nearby README or protocol note.

Command-line workflow

Agents should do all normal work with command-line tools. Do not require a human to open Xcode to generate files, change build settings, or run tests. Use the checked-in project-generation command, if the project adopts one, and xcodebuild/swift as the canonical build tools.

Normal build recipes create Hydraulophone.xcodeproj only when it is absent. After editing project.yml, explicitly run just generate or just regenerate to update an existing project; do not regenerate it on every build.

Before making a change:

  1. Read this file and any more specific instruction file.
  2. Inspect the current project structure and existing scripts.
  3. Identify the smallest vertical slice and its acceptance check.
  4. Check whether the behavior is protocol-sensitive, security-sensitive, or device-only; plan the corresponding test.

After making a change:

  1. Run focused unit tests first.
  2. Run formatting/linting checks that exist in the repository.
  3. Build/test the iOS scheme for an available simulator destination.
  4. When the change affects signing, audio sessions, background behavior, Keychain, networking, or device-only APIs, validate on a physical iPhone or iPad if one is available. If it is unavailable, say so explicitly in the handoff.
  5. Review git diff, generated files, logs, and staged/untracked files for secrets or accidental project targets.

Typical commands after the project exists (adjust names and destinations to the checked-in configuration):

swift --version
xcodebuild -version
xcodebuild -list -project Hydraulophone.xcodeproj
xcodebuild test \
  -scheme Hydraulophone \
  -destination 'platform=iOS Simulator,name=<available iPhone>'
xcodebuild build \
  -scheme Hydraulophone \
  -destination 'platform=iOS Simulator,name=<available iPhone>'
xcodebuild build \
  -scheme Hydraulophone \
  -destination 'generic/platform=macOS,variant=Mac Catalyst'

Use xcodebuild -showdestinations -scheme Hydraulophone to discover valid destinations instead of guessing an installed simulator. Device builds require the developer's local signing identity and must never commit provisioning profiles or certificates.

Documentation and handoff

Record consequential decisions in docs/adr/ once that directory exists. Protocol notes should include:

  • the AuraMusic source URL and commit consulted;
  • the observed request/response behavior;
  • what is an intentional Hydraulophone choice rather than a protocol fact;
  • known breakage risks and how to update the adapter;
  • privacy, licensing, or authentication implications.

An agent handoff must state what changed, what was tested, what could not be tested, and any follow-up risk. Keep TODOs actionable and tied to a feature or decision; do not leave vague placeholders such as “finish API later”.

Definition of done

A change is complete only when:

  • the requested behavior works through the intended UI or API boundary;
  • protocol, session, and playback concerns remain in their layers;
  • failure, cancellation, and empty states are handled;
  • tests cover the new behavior without requiring live credentials, unless the owner explicitly defers tests and the handoff records that deferral;
  • iPhone/iPad simulator and Mac Catalyst build evidence is recorded;
  • physical-device validation is recorded when relevant;
  • no secrets, personal data, or accidental extra Apple targets were added;
  • the relevant docs, ADR, fixture provenance, and license notices are updated.