ArchiveWave

Interest-based audio discovery over the Internet Archive — iOS and Android.

Pick what you want to hear and it plays: drama, lectures, live concerts, historic broadcasts, with a player built to the standard people expect from Pocket Casts or Apple Music.

We host nothing. Every recording streams directly from archive.org through their public APIs, and every item links back to its page there. ArchiveWave is an independent application, not affiliated with or endorsed by the Internet Archive.

---

What makes it different

Things that exist only because the catalogue is an archive:

• On this day — exact month and day matched across every year in the catalogue. A radio drama that went out on this date in 1948 is a recommendation nothing else in the category can make.
• Machine transcripts — synced to playback and searchable inside a three-hour recording.
• Rising this week — from the search index's rolling download counters, so trending works with no user base of our own.
• Per-item rights — read from licenseurl, rights and possible-copyright-status, so the app states the Archive's own position rather than our guess.
• Audio quality as a choice — every derivative with its real bitrate and file size.
• Subjects and creators — tappable, turning any item into a doorway to the rest of the archive.

And three properties of the build itself:

• A taxonomy that lives in data. Kind → area → source → item, with source queries held as strings. Adding content is a data change.
• An interest model that explains itself. Two numbers and an addition, shown as bars, with "why this?" reading out the arithmetic.
• Failure handling that names causes. Rate-limited, offline, Archive-not-answering, empty and stale are five distinguishable states, never one generic error.

---

Repository layout

CLAUDE.md               operating constitution + Autonomous Execution Directive
AUTONOMY.md             execution authority — GREEN / YELLOW / RED
PRODUCT-PLAN.md         Phase 0 → v1.0 → v2.5, with launch plan
PROJECT-STATE.md        live state — read this first
DESIGN-AND-ROADMAP.md   the original design audit this build was made against

claude/agents/          13 agent definitions, versioned
.claude/agents/         the installed copies that actually load
claude/README.md        how the two stay in sync

archivewave-mobile/     the app
  App.js                state, playback wiring, navigation
  src/core.js           taxonomy, Archive client, curation primitives, storage
  src/curation.js       editorial layer — collections, ranking, home rows
  src/audio/            rntp.js (ship) · expoaudio.js (test) · service.js
  src/net.js            request governor, cache, reachability
  src/screens.js        Interests, Dial, Search, Browse, Library
  src/screens2.js       Home, Now Playing, Queue, Detail, Settings, Transcript
  store/                submission material, legal pages, generated graphics
  REVIEW-FIXES.md       what was built against the Archive app's own reviews
  STORE-SUBMISSION.md   submission walkthrough
  SETUP-WINDOWS.md      running it from a Windows PC

src/core.js stays platform-free — no DOM, no React Native imports beyond AsyncStorage — so a web build and the mobile build run identical rules and cannot drift.

---

Running it

See archivewave-mobile/README.md for the full instructions, and archivewave-mobile/SETUP-WINDOWS.md if you are on Windows.

Quick test, no native build — set ENGINE = "expo" in src/config.js:

cd archivewave-mobile
npm install
npx expo install --fix
npx expo start

Scan the QR code with Expo Go. Everything works except what needs native code: the lock screen is minimal and there is no car integration.

The real thing — leave ENGINE = "rntp", the default:

npm install
npx expo run:ios      # or: npx expo run:android

This is the shipping configuration. react-native-track-player drives an OS-level queue, so the lock screen, notification controls, headphone buttons, audio focus and car head units work, and playback survives suspension.

---

Status

Pre-launch. Phase A is built and Phase B is largely built. What stands between this and the App Store is mostly not code — see PRODUCT-PLAN.md for the full picture and PROJECT-STATE.md for current state.

The known blockers, honestly:

• 55 source identifiers were written from memory and have never been checked against live Archive data. Some will return nothing or noise. Verifying them is the highest-value work available on this project.
• Placeholders remain — com.example.archivewave, example.com legal URLs, you@example.com in the User-Agent.
• The legal pages are drafted but unpublished, and no DMCA agent is registered.
• No counsel read on the shipping collections. The rights position in archivewave-mobile/store/content-rights-position.md is our reasoning, not an opinion.
• The Internet Archive letter is written and unsent.
• Google Play requires 12 testers for 14 continuous days before production access. That is the longest pole in the schedule and it has not started.

Nothing here is a rights clearance. Before shipping to either store, get a rights opinion on the collections you intend to include and contact the Internet Archive about request volume, caching and attribution. Both stores will ask what rights you have to the content.

---

Working on this

This repository is set up for autonomous agent work. If you are an agent:

1. Read PROJECT-STATE.md first, and verify its top claims against the code
2. CLAUDE.md defines what the product is and the execution posture
3. AUTONOMY.md defines what needs approval — only RED stops work
4. Update PROJECT-STATE.md as part of finishing work

Two rules worth stating up front:

Playback changes require verification on physical iOS and Android hardware. A simulator does not reproduce audio focus, headphone disconnect, Bluetooth behaviour, or lock-screen controls. Work that cannot be verified is marked unverified rather than reported as done.

We are a guest on donation-funded infrastructure. Requests are spaced and backed off deliberately. Do not raise concurrency or bypass the governor to make a screen feel faster.

---

Licence

The application code's licence is the owner's decision and is not yet set.

The audio is not ours. It belongs to whoever holds rights in each recording, and ArchiveWave's position on that is documented in archivewave-mobile/store/content-rights-position.md.