Merge in-app yt-dlp: verified working end to end, Termux no longer needed

1 files changed, 19 insertions, 3 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 50e1fcb..d6160d3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -86,6 +86,22 @@ claims three separate times across these repos.
   title+date. An episode that loses its identity loses its playback position.
 - **Retention is auto-delete-once-played** with a grace period, so a mis-tap doesn't destroy an
   episode you were still listening to.
-- **YouTube never touches this app.** Audio arrives via podkit running in Termux on the phone,
-  writing to a local folder Listen imports. No extractor code here, nothing to break when Google
-  ships a change.
+- **YouTube audio is yt-dlp, embedded.** Chaquopy runs an in-process CPython with real yt-dlp;
+  see `youtube/YouTubeAudio.kt` and `src/main/python/ytaudio.py`. No Termux, no podkit, no
+  server round trip.
+  - **Pin the Python version.** Chaquopy defaults to 3.8, which yt-dlp no longer supports, so
+    pip silently resolves the last 3.8-compatible release (2024.10.22) and YouTube extraction
+    fails while the build succeeds. `YouTubeAudioTest` fails on a pre-2025 yt-dlp for exactly
+    this reason.
+  - **Audio-only, always.** Separate audio and video streams need ffmpeg to merge, which is the
+    documented failure mode for yt-dlp on Android. A single pre-muxed audio stream has nothing
+    to merge and needs no ffmpeg.
+  - **No proof-of-origin tokens.** Obtaining one means running Google's attestation script in a
+    WebView, which this app does not do. It works without one from an ordinary phone connection.
+  - **Known risk:** yt-dlp has deprecated YouTube extraction without a JavaScript runtime and
+    warns that some formats may be missing. There is no deno/node on Android. If yt-dlp makes a
+    JS runtime mandatory, this breaks and the fallback is bundling a JS engine it accepts.
+
+- **Gradle is pinned to 8.14.3, not 9.x**, because Chaquopy 16.1.0 calls `org.gradle.util.
+  VersionNumber`, removed in Gradle 9. Chaquopy 17 moved to AGP 9.x; going there means bumping
+  AGP, Gradle and Chaquopy together. This is the one deliberate divergence from FeeDreader.