# 🎧 Noxely

> Un serveur cherche, guette les radios et enregistre. Le téléphone ne fait que récupérer les
> fichiers prêts — et garde sa batterie.

[![Platform](https://img.shields.io/badge/Plateforme-Android%208.0%2B-3DDC84?logo=android&logoColor=white)](https://developer.android.com)
[![Kotlin](https://img.shields.io/badge/Kotlin-2.1.0-7F52FF?logo=kotlin&logoColor=white)](https://kotlinlang.org)
[![Compose](https://img.shields.io/badge/Jetpack%20Compose-Material%203-4285F4?logo=jetpackcompose&logoColor=white)](https://developer.android.com/jetpack/compose)
[![Media3](https://img.shields.io/badge/Media3-1.11.1-FF6F00?logo=googleplay&logoColor=white)](https://developer.android.com/media/media3)
[![Version](https://img.shields.io/badge/Version-2.1.0-6B4EFF)](VERSION)
[![Licence](https://img.shields.io/badge/Licence-GPL%20v3-3FD8C0)](LICENSE)
[![Hors ligne](https://img.shields.io/badge/Hors%20ligne-100%25-3FD8C0)](#-comment-ça-marche)

Noxely est un lecteur audio et vidéo pensé pour les trajets, les tunnels, les avions et les
forfaits épuisés. On choisit ce qu'on emporte, l'application le télécharge, et tout reste lisible
sans la moindre connexion.

---

## 📸 Aperçu

| Bibliothèque | Lecture | Hors ligne | Catalogues libres |
|:---:|:---:|:---:|:---:|
| ![Bibliothèque](docs/screenshots/bibliotheque.png) | ![Lecture](docs/screenshots/lecture.png) | ![Hors ligne](docs/screenshots/hors-ligne.png) | ![Catalogue](docs/screenshots/catalogue.png) |

---

## 🏗️ Architecture

```
        SERVEUR  (Python / FastAPI, sur votre machine)
        ├── cherche dans les catalogues libres
        ├── guette les morceaux sur les radios
        ├── enregistre les directs, titrage ICY compris
        └── tient les fichiers prêts
                     │  HTTP + jeton
                     ▼
        MOBILE  (Android / Compose)
        └── demande ce qui est neuf, télécharge, lit
            Wi-Fi non facturé · batterie suffisante · toutes les 6 h
```

Tout ce qui écoutait en continu a migré sur le serveur. Le téléphone dort entre deux
synchronisations : c'est là qu'est l'économie.

## ✨ Ce que fait le serveur

| | |
|---|---|
| 🔎 **Recherche** | Internet Archive, Underground (netlabels + Free Music Archive), LibriVox, Wikimedia Commons |
| 🧾 **Choix piste par piste** | Un album affiche ses pistes avec leur taille avant d'être mis en file |
| 📡 **Guet multi-stations** | Nommez un morceau : les stations les plus écoutées sont balayées jusqu'à le trouver |
| 📻 **Enregistrement** | Capture du direct, nommée d'après le titre annoncé par la station |
| ⏳ **File de téléchargement** | Reprise après échec, état visible |
| 🖥️ **Interface web** | Tout se pilote depuis un navigateur, sans toucher au téléphone |

## 📱 Ce que fait le mobile

| | |
|---|---|
| 🔄 **Synchronisation sobre** | Toutes les 6 h, en Wi-Fi non facturé et batterie suffisante |
| 📱 **Appairage** | Un bouton côté serveur, un bouton côté téléphone : aucun jeton à recopier |
| 🎵 **Lecture** | Audio et vidéo, arrière-plan, casque, écran verrouillé, ±15 s, stop |
| 📚 **Bibliothèque** | Médias reçus du serveur et contenu déjà présent sur l'appareil |
| 📋 **Playlists** | Listes nommées, appui long pour y ajouter un titre |
| 🖼️ **Pochettes** | Cherchées automatiquement pour les titres qui n'en ont pas |
| ℹ️ **À propos et mises à jour** | Version, garanties, journal, et suivi des releases du dépôt |

---

## 📦 Sources interrogées par le serveur

| Source | État | Détail |
|---|:---:|---|
| 📱 Appareil | ✅ | Musique et vidéos déjà sur le téléphone (côté mobile) |
| 🔗 Lien direct | ✅ | URL `http(s)` vers un fichier audio ou vidéo |
| 📻 Podcast RSS | ✅ | Flux standard avec `<enclosure>` |
| 🏛️ Internet Archive | ✅ | Domaine public / Creative Commons |
| 📚 LibriVox | ✅ | Livres audio du domaine public, filtrables par langue |
| 🎼 Wikimedia Commons | ✅ | Enregistrements classiques et archives sonores libres |
| 📻 Radio | ✅ | Annuaire Radio Browser, direct et enregistrement (flux HLS exclus) |
| 🎧 Underground | ✅ | Netlabels et Free Music Archive : ~94 000 morceaux d'artistes indépendants |

### 🔎 Catalogues évalués puis écartés

| Candidat | Pourquoi non |
|---|---|
| **Openverse** | A cessé de servir l'accès anonyme : **401 sur huit requêtes sur huit**, et jusqu'à 21 s de latence quand il répondait encore. Exige désormais une inscription. |
| **ccMixter** | La recherche fonctionne, mais les fichiers ne sont servis qu'avec un en-tête `Referer` — que Media3 ne permet pas de poser par téléchargement. |
| **Radio Browser** | Flux radio continus : rien à mettre en cache. |

### ⚖️ Ce que Noxely ne fait pas — et pourquoi

| Service | Pourquoi |
|---|---|
| 🎵 **Spotify** | Le SDK ne donne aucun accès au flux audio. Le hors-ligne n'existe que dans l'application Spotify. Un podcast également diffusé en RSS public reste ajoutable. |
| ▶️ **YouTube** | Les conditions d'utilisation interdisent d'extraire ou de stocker les flux. Le hors-ligne passe par YouTube Premium. |
| ☁️ **Google Drive / Photos** | Techniquement faisable pour vos propres fichiers, mais cela exige un identifiant OAuth Google lié à votre compte développeur, volontairement non embarqué ici. |

C'est un choix assumé : l'application ne contourne rien, elle travaille avec les sources qui
autorisent la copie locale.

---

## 🧭 Comment ça marche

```
Source  ──►  Bibliothèque  ──►  [ Garder ]  ──►  Cache Media3  ──►  Lecture hors ligne
                                                      │
                                             reprise auto (WorkManager)
```

Trois propriétaires de données, aucun doublon :

- **MediaStore** possède le contenu local — on le relit, on ne le recopie pas ;
- **`imported.json`** possède les seules références distantes ajoutées à la main ;
- **l'index Media3** possède l'état du cache — taille, progression, complétude.

Le cache utilise un `NoOpCacheEvictor` : il contient **exactement** ce que vous avez demandé à
garder, et rien n'en est effacé sans votre geste. La lecture lit ce cache mais n'y écrit jamais,
pour qu'une écoute en ligne ne le fasse pas gonfler à votre insu.

---

## 🚀 Démarrage

### Prérequis

- ☕ JDK 17
- 🤖 Android SDK avec la plateforme **36** et les build-tools 36
- 📱 Un appareil ou un émulateur en **Android 8.0 (API 26)** ou plus

### Construire

```bash
make build          # APK de debug
make install        # installe sur l'appareil connecté
make run            # installe et lance
make lint           # analyse Android Lint
make release        # APK de release (signé si keystore.properties existe)
make publish        # release Gitea : tag + notes + APK signé
make publish-dry    # simulation, sans rien envoyer
make deploy         # release puis publish
```

`make help` liste toutes les cibles, groupées par catégorie.

Sans `make`, les commandes Gradle équivalentes fonctionnent :

```bash
./gradlew assembleDebug
./gradlew installDebug
```

L'APK se trouve dans `app/build/outputs/apk/debug/app-debug.apk`.

### Signer une version de publication

Créez un `keystore.properties` à la racine — il est ignoré par git :

```properties
storeFile=cachette.jks
storePassword=...
keyAlias=cachette
keyPassword=...
```

### 📤 Publier une version

`make publish` crée le tag, la release Gitea et y attache l'APK **signé**. La cible est
idempotente : relancée sur une version déjà publiée, elle réutilise la release et remplace l'asset.
`make publish-dry` répète l'opération à blanc.

La publication délègue à `gitea_release.sh` de **BorisSkill**, qui déduit l'hôte, le propriétaire
et le dépôt du remote `origin` — il n'y a donc aucun nom de dépôt à configurer ici. Le chemin du
script est surchargeable : `make publish GITEA_RELEASE=/chemin/gitea_release.sh`.

Prérequis :

| Élément | Rôle |
|---|---|
| `VERSION` | Source unique de la version — `versionCode` en est déduit (`1.0.0` → `10000`) |
| `CHANGELOG.md` | La section `## [x.y.z]` devient le corps des notes de release |
| `keystore.properties` | Signature — sans lui l'APK est `-unsigned` et refusé à la publication |
| Dépôt git | Un `origin` configuré : le tag `vx.y.z` y est poussé |

Le jeton Gitea est résolu dans l'ordre : `$GITEA_TOKEN`, `.gitea-token` à la racine du dépôt,
`~/.config/gitea/token`, puis repli sur `~/.git-credentials`. Aucun secret n'est stocké dans ce
dépôt.

Pour monter de version, éditez `VERSION` et ajoutez la section correspondante au `CHANGELOG.md` :
Gradle, le tag git et les notes de release suivront seuls.

---

## 🔐 Permissions et vie privée

| Permission | Pourquoi |
|---|---|
| `READ_MEDIA_AUDIO` / `READ_MEDIA_VIDEO` | Lister la musique et les vidéos de l'appareil |
| `INTERNET` | Télécharger ce que vous avez choisi de garder |
| `POST_NOTIFICATIONS` | Commandes de lecture et progression des téléchargements |
| `FOREGROUND_SERVICE_*` | Continuer la lecture et les téléchargements écran éteint |
| `REQUEST_INSTALL_PACKAGES` | Proposer l'installation d'une mise à jour téléchargée |

Aucune donnée ne quitte l'appareil : pas de compte, pas de télémétrie, pas de sauvegarde cloud
(`dataExtractionRules` exclut explicitement le contenu mis en cache). Les seules connexions
sortantes sont celles des URL que vous ajoutez et des catalogues que vous interrogez.

> ⚠️ `usesCleartextTraffic` est activé pour permettre l'usage d'un serveur média auto-hébergé en
> `http://` sur le réseau local. C'est un compromis assumé ; préférez `https` dès que possible.

---

> ⚠️ **Changement de nom en 1.6.0.** L'application s'appelait Cachette et son identifiant était
> `fr.tuxgyver.cachette`. Android traite le nouvel identifiant `fr.tuxgyver.noxely` comme une
> application distincte : une installation en 1.5.0 ne se met pas à jour toute seule, il faut la
> désinstaller puis installer Noxely. Les enregistrements déjà rangés dans `Music/Cachette`
> survivent — ils sont dans le stockage partagé — et restent lisibles par tout lecteur.

---

## 📼 Où vont les enregistrements

À partir d'Android 10, dans `Music/Noxely/`, déclarés dans MediaStore : ils sont donc visibles
de tous les lecteurs de l'appareil et survivent à la désinstallation. En deçà, ils restent dans le
dossier privé de l'application, MediaStore y réclamant une permission de stockage dont Noxely n'a
pas besoin par ailleurs.

Le nom du fichier porte le titre du morceau — et pas seulement la colonne `TITLE` : en publiant le
fichier, MediaStore le relit et réécrit ce champ à partir du nom. Le scan local, lui, ignore
`Music/Noxely` pour ne pas afficher deux fois ce que la bibliothèque connaît déjà.

Chaque enregistrement se supprime individuellement depuis l'écran **Hors ligne** : fichier, entrée
MediaStore et référence en bibliothèque partent ensemble. « Tout libérer » ne les touche pas.

---

## 🆕 Mises à jour

Noxely étant distribuée hors magasin, elle surveille elle-même les releases du dépôt.

```
Release publiée  ──►  vérification quotidienne (WorkManager, Wi-Fi)
                            │
                            ├─ version plus récente ? ──► téléchargement de l'APK
                            │                                    │
                            └─ sinon : rien                      ▼
                                                        notification « prête à installer »
                                                                  │
                                                        installation = geste utilisateur
```

L'installation reste un geste explicite : Android l'impose à toute application hors magasin.
L'écran **Sources** porte la même vérification à la demande, et affiche la version installée.

Le dépôt étant privé, la lecture des releases demande un jeton. Il est lu depuis
`update-token.properties` (ignoré par git) et injecté dans `BuildConfig` à la compilation :

```properties
giteaUpdateToken=…
```

> ⚠️ Un jeton embarqué dans un APK est extractible. Celui-ci est volontairement limité à la portée
> `read:repository` et révocable depuis Gitea. Il donne un accès en lecture aux dépôts du compte —
> ne pas lui accorder davantage.

---

## 🗂️ Structure

```
app/src/main/java/fr/tuxgyver/cachette/
├── NoxelyApp.kt            Application + conteneur de dépendances (assemblé à la main)
├── MainActivity.kt
├── model/                  MediaEntry, MediaKind, SourceKind
├── library/                MediaStore, persistance des imports, bibliothèque unifiée
├── sources/                Import URL et RSS, catalogues Internet Archive et LibriVox
├── offline/                Cache Media3, gestionnaire et service de téléchargement
├── playback/               MediaSessionService, ExoPlayer, contrôleur d'interface
├── radio/                  Annuaire des stations, service d'enregistrement du direct
├── update/                 Vérification des releases, téléchargement, notification
└── ui/                     Compose — thème, bibliothèque, hors ligne, playlists, sources,
                            parcours des catalogues, choix des pistes, lecteur
```

---

## 🧪 État de vérification

Validé sur émulateur Pixel (Android 17, API 37) :

- ✅ Scan MediaStore audio et vidéo, vignettes comprises
- ✅ Lecture avec session média système et position qui progresse
- ✅ Import d'un flux RSS et de ses épisodes
- ✅ Téléchargement d'un épisode jusqu'à l'état « disponible hors connexion »
- ✅ Recherche Internet Archive, résolution du fichier et mise en cache
- ✅ Android Lint sans erreur

---

## 📄 Licence

**GNU General Public License v3.0** — le texte intégral est dans [LICENSE](LICENSE).

Copyright © 2026 Johnny (tuxgyver)

Noxely est un logiciel libre : vous pouvez le redistribuer et le modifier selon les termes de la
GPL v3, telle que publiée par la Free Software Foundation, au choix dans sa version 3 ou dans une
version ultérieure.

Il est distribué dans l'espoir d'être utile, mais **sans aucune garantie**, sans même la garantie
implicite de qualité marchande ou d'adéquation à un usage particulier. Voir la licence pour le
détail.

Ce choix engage aussi celui qui redistribue : toute version modifiée diffusée doit l'être sous la
même licence, code source compris.