Repository Public
1<!--2Author: Simon-Pierre Boucher — contact@spboucher.ai3File: README.md4-->5<div align="center">67<img src="docs/brand/logo.svg" alt="SP Music logo" width="560">89<br><br>1011<img src="docs/brand/icon.png" alt="SP Music icon" width="112" height="112">1213# SP Music pour macOS1415**Lecteur musical natif — Swift 6, SwiftUI, AppKit, AVAudioEngine — de la bibliothèque privée servie par music.spboucher.ai : lecture en continu depuis le cluster, téléchargement vérifié et lecture hors ligne sans aucune requête.**1617**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1819[](https://music.spboucher.ai)202122232425262728293031323334353637[](https://git.spboucher.ai/sp-music-macos/commits)38[](https://git.spboucher.ai/sp-music-macos/commits)39[](https://git.spboucher.ai/sp-music-macos/insights)40[](https://git.spboucher.ai/sp-music-macos)41[](https://git.spboucher.ai/sp-music-macos/insights)42[](https://git.spboucher.ai/sp-music-macos)43[](https://git.spboucher.ai/sp-music-macos/branches)44[](https://git.spboucher.ai/sp-music-macos/tags)45[](https://git.spboucher.ai/sp-music-macos)46474849505152535455565758596061</div>6263---6465## Sommaire6667- [Vue d'ensemble](#-vue-densemble)68- [Fonctionnalités](#-fonctionnalités)69- [Architecture](#-architecture)70- [Pile technique](#-pile-technique)71- [Organisation du dépôt](#-organisation-du-dépôt)72- [Construire et tester](#-construire-et-tester)73- [Configuration](#-configuration)74- [Écrans](#-écrans)75- [Backend et API](#-backend-et-api)76- [Données locales](#-données-locales)77- [Connexion](#-connexion)78- [Sécurité et vie privée](#-sécurité-et-vie-privée)79- [Tests](#-tests)80- [Publier](#-publier)81- [Pièges connus](#-pièges-connus)82- [Non vérifié et limites](#-non-vérifié-et-limites)83- [Documentation](#-documentation)84- [Auteur](#-auteur)85- [Licence](#-licence)8687---8889## 🎯 Vue d'ensemble9091SP Music pour macOS est le lecteur **natif** de la bibliothèque privée servie par92[music.spboucher.ai](https://music.spboucher.ai) sur le cluster MacLustr. Deux modes complémentaires :9394- **lecture en continu** depuis le cluster (fichiers originaux, jamais transcodés pour l'app) ;95- **téléchargement et lecture hors ligne** : albums, listes ou bibliothèque entière copiés sur le Mac, lisibles sans96 aucune connexion.9798Aucun WebView, aucun HTML : l'interface, le moteur audio, les téléchargements et la bibliothèque locale sont du code99natif. Bundle `ai.spboucher.spmusic`, macOS 14 ou plus récent, universel (Apple Silicon et Intel), signé Developer ID,100runtime durci.101102### Famille SP Music103104| Dépôt | Plateforme | Rôle |105|---|---|---|106| [sp-music](https://git.spboucher.ai/sp-music) | Web · PWA | Serveur : site, API `/api/v1`, worker d'import, diffusion audio, paroles |107| **[sp-music-macos](https://git.spboucher.ai/sp-music-macos)** (ce dépôt) | macOS | Client natif : copie locale du catalogue, lecture en continu et hors ligne |108| [sp-music-ios](https://git.spboucher.ai/sp-music-ios) | iOS · iPadOS | Client natif : même API, paquet séparé |109110## ✨ Fonctionnalités111112État détaillé, fonction par fonction (Testé / Vu / Écrit / Absent) : [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md).113114| Domaine | Ce que fait l'app |115|---|---|116| Bibliothèque | accueil (écoutés récemment, ajouts récents, hors ligne, listes), albums en grille avec 4 tris, fiches album et artiste, liste des titres |117| Recherche | locale, FTS5, accents ignorés, préfixes — fonctionne hors ligne |118| Favoris et listes | titres et albums favoris ; listes créées, renommées, complétées, ordonnées, supprimées — modifiables hors ligne, conflits sans écrasement |119| Lecture en continu | par plages d'octets dans un fichier creux, cache vérifié par SHA-256 et réutilisé |120| FLAC | recherche par plage d'octets exacte à l'échantillon (`FLACIndex`, `FLACSliceSource`) |121| Enchaînement | deux platines : piste suivante démarrée à l'échantillon exact (sans blanc) ou en fondu à puissance constante |122| Traitements | égaliseur 10 bandes, normalisation BS.1770 à −14 LUFS, « mode direct » qui les désactive d'un bloc, adaptation de la fréquence du périphérique |123| Téléchargements | titre, album, liste, bibliothèque entière ; file persistante, reprise à l'octet, SHA-256, pause / reprise / annulation, limite de téléchargements simultanés |124| Hors ligne | collections « gardées hors ligne », lecture sans aucune requête, détection de la perte et du retour du cluster |125| Paroles | synchronisées ligne à ligne, clic pour se déplacer, cache hors ligne |126| Intégration macOS | touches multimédias, widget « À l'écoute », menu du Dock, mini-lecteur, notifications, ouverture de fichiers audio locaux |127| Administration | import (fichiers, dossiers, ZIP) par morceaux, doublons, remplacement, édition d'album, pochette, suppression, santé du serveur |128| Stockage | dossier de bibliothèque déplaçable (disque externe possible), garde des suppressions |129130**Choix assumés**131132- **Pas de bac à sable** : la bibliothèque vit dans un dossier choisi (`~/Music`, disque externe) et doit rester133 lisible par d'autres lecteurs. Runtime durci sans exception.134- **Pas de « bit-perfect » annoncé** : le chemin passe par le mélangeur 32 bits flottants de Core Audio ; l'app décrit135 ce qu'elle fait sans prétendre connaître ce que reçoit le périphérique.136- **Pas de mise à jour automatique.**137138## 🏗 Architecture139140```mermaid141flowchart TB142 UI["SwiftUI · App · Features · Components"] --> AM["AppModel"]143 AM --> PC["PlaybackController"]144 PC --> AE["AudioEngine"]145 AE --> AV["AVAudioEngine"] --> OUT["Sortie Core Audio"]146 PC -->|ResolvedSource| LS["LibrarySession"]147 LS -->|"ByteSource : LocalFileSource · ProgressiveHTTPSource · FLACSliceSource"| AE148 subgraph CORE["SPMusicCore (paquet SwiftPM, aucune interface)"]149 LS --> ST["LibraryStore<br/>SQLite · FTS5"]150 LS --> SM["StorageManager + PathGuard"]151 LS --> DM["DownloadManager<br/>reprise par plage · SHA-256"]152 LS --> SY["SyncEngine"]153 LS --> AR["ArtworkStore"]154 LS --> API["APIClient + Connectivity"]155 end156 API -->|HTTPS| SRV["music.spboucher.ai<br/>/api/v1"]157 DM -->|"Range + If-Range"| SRV158```159160### Règles tenues161162- **Le moteur audio ne connaît ni les titres ni le réseau** : il reçoit des sources d'octets et des jetons.163- **Le moteur de téléchargement ne connaît pas le moteur audio** ; il réutilise seulement un fichier complet du cache164 de lecture.165- **La bibliothèque locale n'a jamais besoin du serveur** : ouvrir une session, lister, chercher et lire un titre166 téléchargé ne font aucune requête (prouvé par un test qui compte les connexions).167- **Rien n'est supprimé hors d'un dossier marqué par l'app**, liens symboliques résolus.168169### Lecture170171- Deux platines (lecteur → mélangeur) alimentent un pré-mélangeur, l'égaliseur, puis le mélangeur principal. La piste172 suivante est préparée sur l'autre platine et démarrée à l'échantillon exact où la courante se termine (pas de173 blanc), ou plus tôt avec une rampe à puissance constante (fondu).174- Chaque platine décode sur sa propre file : une source qui attend le réseau ne bloque jamais les commandes.175- Les rappels du lecteur AVFoundation ne prennent jamais le verrou du moteur sur un fil audio (cause de deux176 interblocages trouvés par les tests).177- **Lecture en continu** : `ProgressiveHTTPSource` écrit dans un fichier creux par requêtes de plage ; le décodeur lit178 ce qui est arrivé. Un saut demande les octets de la destination. Fichier complet → vérifié par SHA-256 → marqué,179 réutilisable.180- **FLAC** : Core Audio se déplace dans un FLAC en le relisant depuis le début (mesuré, avec ou sans table de181 recherche). `FLACIndex` trouve une frontière de trame juste avant la cible (SEEKTABLE, sinon synchro de trame validée182 par CRC-8 et par la trame suivante) et `FLACSliceSource` présente « en-tête + audio à partir de là » au décodeur.183 Exact à l'échantillon.184- **Fidélité** : aucun transcodage ; égaliseur, normalisation et fondu désactivables d'un bloc (« mode direct ») ;185 option pour régler la fréquence du périphérique sur celle du titre.186187### Synchronisation188189```mermaid190sequenceDiagram191 autonumber192 participant App as SyncEngine193 participant API as music.spboucher.ai194 App->>API: opérations locales en attente, dans l'ordre195 App->>API: GET library/sync?since=<dernière révision>196 API-->>App: artistes, albums, titres modifiés + pierres tombales197 App->>API: GET library/sync/me198 API-->>App: listes, favoris, état de lecture199 App->>API: historique d'écoute (POST puis GET)200 App->>App: met en file les téléchargements des collections gardées hors ligne201```202203Une passe : (1) envoyer les opérations locales, dans l'ordre ; (2) tirer le catalogue depuis la dernière révision vue204(tout, si demandé, si plus de 24 h, ou si les compteurs divergent) ; (3) tirer listes et favoris du compte, sauf si des205opérations attendent encore ; (4) historique dans les deux sens ; (5) mettre en file les téléchargements des206collections « gardées hors ligne ». Aucun fichier audio n'est transféré par une synchronisation.207208Conflit de liste (modifiée ici hors ligne et ailleurs) : aucune version n'est écrasée ; celle du Mac est enregistrée à209côté sous « … (copie de ce Mac) » et l'utilisateur est prévenu.210211### Téléchargements212213Octets dans `<bibliothèque>/.spmusic/partial/<titre>.<asset>.part` ; reprise par `Range` + `If-Range` sur214l'identifiant de l'asset ; taille puis SHA-256 vérifiés avant un déplacement atomique vers le nom lisible. L'état est215en base : une fermeture ou un plantage ne perd rien. Un fichier remplacé sur le cluster est retéléchargé ; un titre216supprimé du cluster mais téléchargé ici est conservé et signalé.217218## 🧱 Pile technique219220| Couche | Technologie | Version | Rôle |221|---|---|---|---|222| Langage | Swift (`swift-tools-version` 6.0, mode de langage 6) | 6.0 | concurrence stricte `complete`, isolation par défaut `MainActor` dans l'app |223| Interface | SwiftUI + AppKit | macOS 14+ | fenêtres, barre latérale, lecteur, réglages |224| Audio | AVAudioEngine · Core Audio | système | décodage, deux platines, égaliseur, mélangeur |225| Persistance | SQLite (bibliothèque système `sqlite3`) + FTS5 | système | bibliothèque locale, recherche |226| Réseau | URLSession (`APIClient`, `HTTPByteStream`) | système | JSON, plages d'octets |227| Authentification | AuthenticationServices · Trousseau | système | clé d'accès, session |228| Système | MediaPlayer, notifications | système | « À l'écoute », touches multimédias |229| Paquet | SwiftPM `SPMusicCore` (bibliothèque) + `spmusic-cli` (point d'entrée provisoire) | — | cœur sans interface, testable seul |230| Projet | XcodeGen (`project.yml`) | — | `SPMusic.xcodeproj` n'est pas versionné |231| Distribution | Developer ID · `notarytool` · DMG | — | signature, notarisation, agrafage |232233Aucune dépendance tierce : `Package.swift` ne déclare aucun paquet externe.234235## 🗂 Organisation du dépôt236237```238Package.swift paquet SwiftPM « SPMusicCore » (aucune interface) + tests239project.yml définition XcodeGen de l'app (SPMusic.xcodeproj n'est pas versionné)240Core/ 24 fichiers — le cœur241├── Audio/ AudioEngine, AudioDecoder, AudioQueue, AudioOutputManager, ByteSource, FLACSeeker, LoudnessAnalyzer, PlaybackController242├── Networking/ APIClient, AdminAPI, Connectivity, HTTPByteStream243├── Authentication/ AuthService244├── Downloads/ DownloadManager245├── Offline/ LibrarySession, StorageManager246├── Persistence/ LibraryStore, SQLite247├── Synchronization/ SyncEngine, WireModels248├── Metadata/ ArtworkStore, Models249└── Security/ Keychain, PathGuard250App/ point d'entrée, AppDelegate, AppEnvironment, AppSettings, intégrations macOS (Notifier, NowPlayingBridge, PasskeySignIn)251Features/ Home · Library · Albums · Artists · Playlists · Search · NowPlaying · Downloads · Settings · Administration · Welcome252Components/ AlbumCard · TrackRow · PlayerBar · ArtworkView · SidebarView · Common253Resources/ Info.plist, droits (Release et Debug), catalogue d'assets, icône254Tests/CoreTests/ 42 tests + proxy de pannes (FaultProxy), fixtures, support du backend de test255Tools/spmusic-cli/ point d'entrée en ligne de commande (provisoire)256Scripts/ build, tests, backend de test, release, notarisation, en-têtes d'auteur257docs/ ARCHITECTURE.md · FEATURE_MATRIX.md · TEST_REPORT.md · brand/258```259260| Dossier | Fichiers Swift | Lignes |261|---|---|---|262| `Core/` | 24 | 4 638 |263| `Features/` | 11 | 1 715 |264| `Tests/` | 10 | 1 412 |265| `App/` | 7 | 1 131 |266| `Components/` | 6 | 686 |267| `Tools/` | 1 | 4 |268| **Total** | **61** | **9 622** |269270## 🚀 Construire et tester271272Le projet Xcode est généré par XcodeGen depuis `project.yml`.273274```bash275Scripts/build.sh # génère le projet et construit l'app Debug276Scripts/backend-dev.sh start # vrai backend de test local (clone de sp-music.git dans ~/dev/sp-music-testbed, PostgreSQL, ffmpeg)277Scripts/t.sh # tous les tests du cœur ; Scripts/t.sh <filtre> [secondes]278Scripts/run-dev.sh --shot /tmp/x.png -- -SPMusicRoute albums # lance le build Debug sur le backend de test, muet, et capture la fenêtre279Scripts/make-icon.sh # régénère l'icône depuis le SVG280Scripts/check-headers.sh # en-têtes d'auteur281```282283<details>284<summary><b>Tous les scripts</b></summary>285286| Script | Rôle |287|---|---|288| `Scripts/build.sh` | génère le projet Xcode et construit l'app Debug (erreurs seulement sur la console) |289| `Scripts/t.sh [filtre] [secondes] [lignes]` | `swift test` avec filtre et limite de temps, n'affiche que les verdicts |290| `Scripts/backend-dev.sh start\|stop` | vrai backend SP Music local pour les tests fonctionnels : code du cluster, base PostgreSQL propre, stockage propre, vrai ffmpeg, vrai worker (port 8695 par défaut) |291| `Scripts/dev-session.sh` | affiche un jeton de session du backend **de test**, obtenu par les vraies routes d'association d'appareil ; ne touche jamais la production |292| `Scripts/run-dev.sh [--shot out.png] [--wait s] [--keep] [--fresh] [--no-server] [-- args…]` | lance le build Debug sur le backend de test, avec ses propres dossiers, muet, et capture sa fenêtre |293| `Scripts/window-shot.swift` | capture de la fenêtre de l'app |294| `Scripts/make-icon.sh` | rend le SVG de l'icône dans le catalogue d'assets (toutes les tailles macOS) |295| `Scripts/add-headers.py` · `Scripts/check-headers.sh` | ajoute / vérifie l'en-tête d'auteur (Author / File / Description) |296| `Scripts/asc.py` | client minimal de l'API App Store Connect (clé existante) |297| `Scripts/provision.py` | identifiant d'app, Associated Domains, profil Developer ID — idempotent |298| `Scripts/release.sh` | archive Release signée → `dist/SP Music.app` |299| `Scripts/verify-release.sh [app]` | signature, runtime durci, droits, profil, pas de moteur web, pas de droit de débogage, pas de secret |300| `Scripts/notarize.sh` | notarisation, agrafage, DMG signé + notarisé |301302</details>303304## ⚙️ Configuration305306**Build** (`project.yml`)307308| Réglage | Valeur |309|---|---|310| `MARKETING_VERSION` · `CURRENT_PROJECT_VERSION` | `1.0.0` · `1` |311| `SWIFT_VERSION` · `SWIFT_STRICT_CONCURRENCY` | `6.0` · `complete` |312| Cible de déploiement | macOS 14.0 |313| Identifiant Release · Debug | `ai.spboucher.spmusic` · `ai.spboucher.spmusic.debug` |314| Signature Release | manuelle, `Developer ID Application`, profil « SP Music Developer ID », `--timestamp` |315| Signature Debug | locale, sans profil ni droit restreint (pas d'Associated Domains) ; identifiant distinct pour qu'une copie de développement ne masque jamais l'app installée pour les clés d'accès |316| `ENABLE_HARDENED_RUNTIME` | `YES` |317| Langue de développement | `fr` |318319**Variables d'environnement des tests et scripts** (noms seulement)320321| Variable | Rôle |322|---|---|323| `SPMUSIC_TEST_URL` · `SPMUSIC_TEST_PORT` · `SPMUSIC_TEST_DB` | backend de test |324| `SPMUSIC_TESTBED` · `SPMUSIC_TEST_SCRIPT` | emplacement du clone de test et de son script |325| `SPMUSIC_REAL_FLAC` | fichier FLAC réel pour le test de recherche par plage (sinon ignoré) |326| `SPMUSIC_PROD_URL` · `SPMUSIC_PROD_TOKEN` | test de fumée en lecture seule contre la production (sinon ignoré) |327| `NOTARY_PROFILE` | profil trousseau de `notarytool` (défaut : `MacLustr-Notarize`) |328329**Arguments de lancement** (développement et tests fonctionnels, build Debug)330331| Argument | Effet |332|---|---|333| `-SPMusicServer <url>` | serveur |334| `-SPMusicDataDir <dossier>` · `-SPMusicLibraryRoot <dossier>` | dossiers de données et de bibliothèque |335| `-SPMusicDevToken <jeton>` | session de développement |336| `-SPMusicRoute albums\|artists\|tracks\|downloads\|admin\|album:<id>\|nowplaying` | écran d'ouverture |337| `-SPMusicPlay <titre>` · `-SPMusicSeek <secondes>` · `-SPMusicShowNowPlaying` | lecture automatique |338| `-SPMusicDownloadAlbum <album>` | téléchargement automatique |339340## 🖥 Écrans341342| Écran | Dossier | État (v1.0.0) |343|---|---|---|344| Bienvenue / connexion | `Features/Welcome` | Vu |345| Accueil | `Features/Home` | Vu |346| Albums et fiche album | `Features/Albums` | Vu |347| Artistes et fiche artiste | `Features/Artists` | Écrit (liste testée côté base) |348| Titres | `Features/Library` | Écrit (requêtes testées) |349| Listes de lecture | `Features/Playlists` | données Testées, écran Écrit |350| Recherche | `Features/Search` | recherche Testée, écran Écrit |351| Lecture en cours | `Features/NowPlaying` | Vu |352| Téléchargements | `Features/Downloads` | Vu |353| Réglages | `Features/Settings` | Écrit |354| Administration | `Features/Administration` | API Testée, écran Écrit |355356Légende ([`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md)) — **Testé** : couvert par un test automatisé réel ·357**Vu** : constaté dans l'app lancée · **Écrit** : implémenté, compilé, jamais exercé.358359## 🔌 Backend et API360361Les ajouts côté serveur (synchronisation incrémentale, association d'appareil, historique, fichier362`apple-app-site-association`) sont dans le dépôt [sp-music](https://git.spboucher.ai/sp-music) (migration363`003_native_clients.sql`, `docs/ARCHITECTURE.md` § Clients natifs). Le site web n'est pas modifié dans son364comportement.365366| Route du serveur | Usage dans l'app |367|---|---|368| `GET /api/v1/library/sync?since=<rev>` | catalogue incrémental et pierres tombales |369| `GET /api/v1/library/sync/me` | listes, favoris, état de lecture |370| `GET` · `POST /api/v1/library/history` | historique d'écoute dans les deux sens |371| `PATCH playlists/:id` · `PUT playlists/:id/order` (`baseUpdatedAt`) | détection des conflits de liste (`409`) |372| `POST /api/v1/auth/device/{start,poll}` | association avec le navigateur |373| `GET /api/v1/stream/<id>` (`Range`) | lecture en continu et téléchargement |374| `GET /api/v1/art/<id>` | pochettes |375| `/api/v1/admin/*` | import, édition d'album, santé (`AdminAPI.swift`) |376377## 💾 Données locales378379- **Musique téléchargée** : `~/Music/SP Music/<compte>/<Artiste>/<Album (année)>/01 Titre.flac` (dossier modifiable380 dans Réglages › Stockage, disque externe possible). Ce sont les originaux du cluster, vérifiés par SHA-256, lisibles381 par n'importe quel lecteur. Un fichier `.spmusic/library.json` marque le dossier ; l'app ne supprime jamais rien en382 dehors.383- **Base locale, pochettes, cache de lecture** : `~/Library/Application Support/SP Music/Accounts/<serveur>_<compte>/`.384- **Session** : dans le trousseau. Se déconnecter n'efface pas la musique téléchargée.385386## 🔑 Connexion3873881. **Clé d'accès** (AuthenticationServices) : même vérification serveur que le navigateur. Demande le droit389 `com.apple.developer.associated-domains` (profil Developer ID) et l'app installée dans `/Applications`.3902. **Association avec le navigateur** : l'app affiche un code, un navigateur déjà connecté l'approuve sur391 `https://music.spboucher.ai/appareil`, l'app reçoit sa propre session (révocable dans « Compte » sur le site).392393## 🔐 Sécurité et vie privée394395- Session dans le trousseau (`Core/Security/Keychain.swift`) ; droit `webcredentials:music.spboucher.ai` pour les clés396 d'accès.397- `PathGuard` : aucune suppression hors d'un dossier marqué par l'app (`..`, liens symboliques, marqueur).398- Chaque fichier téléchargé est vérifié (taille puis SHA-256) avant installation ; un fichier corrompu n'est jamais399 installé.400- Runtime durci sans exception ; App Transport Security limité au réseau local (`NSAllowsLocalNetworking`) pour le401 backend de test.402- Une session révoquée laisse la musique locale lisible.403- `Scripts/verify-release.sh` vérifie l'absence de moteur web, de droit de débogage et de secret dans le bundle.404- Aucun certificat n'est créé par les scripts ; aucun identifiant n'est affiché.405406## ✅ Tests407408Rapport complet : [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) — v1.0.0 (1), 18 novembre 2026 : **42 tests409automatisés, 40 réussis, 2 ignorés** (fichier FLAC réel absent ; fumée production sans jeton), en 17 s, 10 exécutions410consécutives sans échec.411412| Fichier | Tests | Portée |413|---|---|---|414| `ClusterTests.swift` | 11 | association d'appareil, synchronisation, téléchargements, modifications hors ligne |415| `StreamingAndOfflineTests.swift` | 8 | lecture en continu, hors ligne sans connexion, stockage |416| `UnitTests.swift` | 8 | cœur sans réseau |417| `AudioTests.swift` | 7 | formats, moteur, enchaînement sans blanc, mesure du niveau |418| `FLACSeekTests.swift` | 4 | recherche FLAC par plage |419| `AdminTests.swift` | 3 | import, édition, santé, 403 pour un auditeur |420| `ProductionSmokeTests.swift` | 1 | fumée en lecture seule contre la production |421| **Total** | **42** | |422423Les tests d'intégration parlent à un **vrai** serveur (le code du cluster, sa base, son worker) à travers un proxy TCP424qui produit de vraies pannes (coupure, lenteur, corruption). Ils sont ignorés quand le backend de test ne tourne pas.425Le test de fumée contre la production est en lecture seule et ne tourne que si on lui fournit une session426(`SPMUSIC_PROD_URL`, `SPMUSIC_PROD_TOKEN`).427428<details>429<summary><b>Ce qui est vérifié, par domaine</b></summary>430431| Domaine | Vérifié |432|---|---|433| Formats | FLAC 16 et 24 bits, ALAC, WAV, AIFF, MP3, AAC : ouverts, décodés (fréquence du signal mesurée), déplacement exact ; faux fichier refusé |434| Moteur | lecture, pause, déplacement, volume, gain de normalisation et mode direct, enchaînement **sans blanc** (signal continu ± 20 ms sur 4 s), enchaînement 44,1 → 96 kHz |435| Recherche FLAC par plage | exacte à l'échantillon sur 4 positions + fin de fichier, moins du quart du fichier lu, avec et sans SEEKTABLE |436| Connexion | association d'appareil réelle, jeton inconnu refusé, session révoquée détectée |437| Synchronisation | première synchro complète, suivantes vides, renommage, suppressions, historique dans les deux sens |438| Téléchargements | album complet vérifié SHA-256 ; coupure à 3 Mo → reprise **à l'octet exact** ; fermeture de l'app → reprise au relancement ; octet corrompu → jamais installé |439| Hors ligne | serveur coupé : parcourir, chercher, lire deux titres enchaînés avec **0 connexion** |440| Lecture en continu | son avant l'arrivée du fichier, saut loin devant par requête de plage, copie complète vérifiée ; coupure courte surmontée seule |441| Modifications hors ligne | liste créée, complétée, renommée, favoris → envoyés au retour ; conflit → deux versions conservées + avis |442| Stockage | déplacement de la bibliothèque, dossier occupé refusé, disque débranché sans perte ; garde des chemins |443| Administration | import par morceaux d'un vrai fichier, doublon reconnu, édition d'album, pochette, santé, suppression |444| Mesure du niveau | écart ≤ 0,3 LU avec `ffmpeg ebur128` sur bruit rose et sinus |445| Grande bibliothèque | 72 000 titres synchronisés en 1,6 s ; 6 000 albums listés en 21 ms ; recherche en 11 ms |446447</details>448449**Bogues trouvés par les tests et corrigés** : en-tête `User-Agent` non ASCII quand le nom du Mac contient un accent ;450deux interblocages du moteur audio ; index de recherche en O(n²) à la première synchronisation ; garde des chemins451contournable par un lien symbolique vers un fichier inexistant ; relecture complète d'un FLAC pour s'y déplacer ;452plantage au premier « À l'écoute » ; fiches album, artiste et liste restées vides.453454## 📦 Publier455456```bash457python3 Scripts/provision.py # identifiant d'app + Associated Domains + profil Developer ID (clé App Store Connect existante ; idempotent)458Scripts/release.sh # archive Release signée → dist/SP Music.app459Scripts/verify-release.sh # signature, droits, natif seulement, pas de secret460Scripts/notarize.sh # notarisation Apple (profil trousseau « MacLustr-Notarize »), agrafage, DMG signé + notarisé + SHA-256461```462463Aucun certificat n'est créé par ces scripts ; aucun identifiant n'est affiché.464465État de la v1.0.0 (tag `v1.0.0`, d'après `docs/TEST_REPORT.md`) : archive Release universelle (arm64 + x86_64),466signature Developer ID, runtime durci, profil avec Associated Domains ; notarisation **Accepted** pour l'app et pour467le DMG, tickets agrafés ; `spctl` : « Notarized Developer ID ».468469## 🩺 Pièges connus470471| Piège | Remède dans le code |472|---|---|473| Core Audio relit tout un FLAC pour s'y déplacer, même avec SEEKTABLE | `FLACIndex` + `FLACSliceSource` (`Core/Audio/FLACSeeker.swift`) |474| Rappel du lecteur AVFoundation attendant le verrou du moteur → interblocage | les rappels ne prennent jamais le verrou ; reconnexion d'une platine hors verrou |475| Rappels MediaPlayer appelés hors du fil principal (plantage au premier « À l'écoute ») | corrigé dans `App/Integration/NowPlayingBridge.swift` |476| En-tête `User-Agent` non ASCII (nom du Mac avec accent ou apostrophe typographique) | nom ramené en ASCII |477| Index FTS5 en O(n²) à la première grande synchronisation | index par `rowid` de la piste |478| Lien symbolique vers un fichier qui n'existe pas encore | `PathGuard` résout l'ancêtre existant |479| Fiche restée vide (tâche attachée à un conteneur vide) | corrigé dans les vues de fiche |480| Clé d'accès indisponible en Debug | normal : le build Debug n'a pas le droit Associated Domains ; utiliser l'association avec le navigateur ou `Scripts/dev-session.sh` |481482## ⚠️ Non vérifié et limites483484Repris de [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) et de [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md) :485486- **Connexion par clé d'accès dans l'app** : le droit, le profil et le fichier d'association sont en place, l'échange487 n'a jamais eu lieu.488- **Aucune écoute humaine** : tout a joué volume à zéro ou en rendu hors ligne.489- Fondu enchaîné, égaliseur, adaptation de la fréquence du périphérique, changement ou débranchement de sortie,490 veille : écrits, jamais exercés.491- Touches multimédias, widget « À l'écoute », menu du Dock, mini-lecteur, raccourcis configurables, ouverture de492 fichiers, glisser-déposer, notifications : écrits, jamais exercés.493- Écrans d'administration, de réglages, artistes, titres, favoris, historique, liste de lecture, recherche :494 compilés ; leurs données et leurs API sont testées, les écrans n'ont pas été parcourus.495- Téléchargement de toute la bibliothèque réelle ; Ogg, Opus, DSD (aucun titre) ; paroles réelles dans la vue.496- Autre Mac, tranche Intel, macOS 14 à 26, VoiceOver, profilage Instruments.497- **Absent de cette version** : interface en anglais (français seulement), thème d'accent, édition titre par titre et498 réordonnancement d'un album, gestion des comptes, journal d'audit et correction des paroles (à faire sur le site).499500## 📚 Documentation501502- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — couches, règles tenues, lecture, synchronisation, téléchargements503- [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md) — parité avec le site et état par fonction504- [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) — ce qui a tourné, bogues corrigés, non vérifié505506## 👤 Auteur507508<div align="center">509<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>510511**Simon-Pierre Boucher** — conception, développement, exploitation<br>512[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai513514</div>515516## 📄 Licence517518Le dépôt ne contient pas de fichier de licence. Tous droits réservés © 2026 Simon-Pierre Boucher.519