SP Music — iOS et iPadOS
Lecteur natif de la bibliothèque musicale privée hébergée sur MacLustr (music.spboucher.ai) : Swift 6 et SwiftUI, sans aucune vue web — diffusion depuis le cluster et lecture hors ligne de la musique téléchargée.
Author: Simon-Pierre Boucher
Sommaire
- Vue d'ensemble
- Captures
- Fonctionnalités
- Architecture
- Pile technique
- Organisation du dépôt
- Commandes
- Configuration
- Écrans
- API utilisée
- Parité avec le site
- Sécurité et vie privée
- Tests
- Publication TestFlight
- Blocages et limites — à lire
- Documentation
- Auteur
- Licence
🎯 Vue d'ensemble
Lecteur natif de la bibliothèque musicale privée hébergée sur MacLustr (music.spboucher.ai). Swift 6 et SwiftUI,
sans aucune vue web : diffusion depuis le cluster et lecture hors ligne de la musique téléchargée.
| Identifiant | ai.spboucher.spmusic.ios |
| Version | 1.0.0 (1) — envoyée sur TestFlight le 2026-11-17 (App Store Connect n° 6836172581) |
| Cible | iOS / iPadOS 26.1 et plus, iPhone et iPad |
| Serveur | API « clients natifs » de Music SP (dépôt sp-music, branche main) |
Famille SP Music
| Dépôt | Plateforme | Rôle |
|---|---|---|
| sp-music | Web · PWA | Serveur : site, API /api/v1, worker d'import, diffusion audio, paroles |
| sp-music-macos | macOS | Client natif (AVAudioEngine), paquet séparé |
| sp-music-ios (ce dépôt) | iOS · iPadOS | Client natif : diffusion, téléchargement, lecture hors ligne |
L'application n'ajoute rien au backend : elle réutilise l'API des clients natifs du dépôt sp-music.
📸 Captures
Captures produites par les tests d'interface sur simulateur (docs/captures/).
Connexion et iPad
✨ Fonctionnalités
- Bibliothèque : albums, artistes, titres, listes de lecture, favoris, récemment écoutés, musique téléchargée ; recherche instantanée sur la copie locale (donc aussi en mode avion).
- Lecture :
AVQueuePlayer, fichiers originaux décodés par iOS (FLAC 16/24 bits, ALAC, AAC, MP3, WAV, AIFF), piste suivante préparée à l'avance, file d'attente, aléatoire, répétition, paroles synchronisées. - Hors ligne : téléchargement d'un titre, d'un album, d'une liste ou de toute la bibliothèque ;
URLSessiond'arrière-plan ; reprise ; chaque fichier est vérifié (taille + SHA-256 de l'original) avant d'être déclaré disponible ; un fichier partagé par plusieurs albums ou listes n'est stocké qu'une fois et n'est supprimé que lorsque plus rien ne le réclame. - Système : lecture en arrière-plan, écran verrouillé / Centre de contrôle / Dynamic Island par les commandes
standard (
MPNowPlayingInfoCenter,MPRemoteCommandCenter), AirPods et Bluetooth, sélecteur de sortie AirPlay, interruptions (appels), CarPlay (code livré, voir Blocages). - Synchronisation : incrémentale (révisions + suppressions), favoris et écoutes mis en file hors ligne puis envoyés au retour du réseau, reprise de la file de lecture entre appareils.
- Connexion : clé d'accès du site (Face ID / Touch ID), association depuis un appareil déjà connecté, lien d'inscription, code de récupération ; session dans le trousseau ; verrouillage biométrique optionnel.
- iPad :
NavigationSplitViewavec barre latérale, barre de lecture pleine largeur, lecteur plein écran à deux colonnes, raccourcis clavier (menu « Lecture », ⌘F, ⌘1–⌘5), glisser-déposer de titres vers les listes.
🏗 Architecture
flowchart TB
subgraph APP["Application SwiftUI"]
UI["Features · Components"] --> ENV["AppEnvironment<br/>état partagé"]
CP["CarPlaySceneDelegate"] --> ENV
end
subgraph CORE["SPMusicCore (paquet Swift, iOS + macOS, aucune dépendance)"]
AUD["Audio<br/>AudioPlayer · PlaybackQueue · SourceResolver<br/>AudioSessionManager · NowPlayingCenter"]
API["API<br/>APIClient · Endpoints"]
AUTH["Authentication<br/>AuthService · Passkeys"]
DB["Persistence<br/>Database · SQLite"]
SYNC["Synchronization<br/>SyncEngine"]
DL["Downloads<br/>DownloadManager"]
OFF["Offline<br/>OfflineFiles"]
SEC["Security · Settings"]
end
ENV --> AUD
ENV --> SYNC
ENV --> DL
ENV --> AUTH
AUD --> OFF
AUD --> API
SYNC --> API
SYNC --> DB
DL --> OFF
DL --> DB
AUTH --> API
AUTH --> SEC
API -->|HTTPS| SRV["music.spboucher.ai<br/>/api/v1"]
DL -->|"URLSession d'arrière-plan"| SRV
Téléchargement vérifié
sequenceDiagram
autonumber
participant U as Utilisateur
participant DM as DownloadManager
participant S as music.spboucher.ai
participant F as OfflineFiles
U->>DM: télécharger un album
DM->>DM: ignore les fichiers déjà présents (comptage des références)
DM->>S: GET /api/v1/stream/<id> (session d'arrière-plan, reprise)
S-->>DM: octets de l'original
DM->>DM: vérifie la taille puis le SHA-256 annoncé par la synchronisation
alt intégrité conforme
DM->>F: fichier déclaré disponible
else échec
DM->>DM: fichier refusé, nouvel essai
end
F-->>U: lecture sans réseau
🧱 Pile technique
| Couche | Technologie | Version | Rôle |
|---|---|---|---|
| Langage | Swift (SWIFT_VERSION 6.0 ; swift-tools-version 6.2 pour le paquet) |
6 | concurrence stricte complete |
| Interface | SwiftUI | iOS 26.1+ | iPhone et iPad (TARGETED_DEVICE_FAMILY 1,2) |
| Audio | AVFoundation (AVQueuePlayer), MediaPlayer |
système | lecture, « En lecture », commandes distantes |
| Persistance | SQLite | système | copie locale du catalogue, files d'attente hors ligne |
| Réseau | URLSession (dont session d'arrière-plan) | système | API JSON, transferts |
| Authentification | AuthenticationServices · Trousseau | système | clé d'accès, session |
| Voiture | CarPlay | système | scène livrée, droit à obtenir |
| Paquet | SPMusicCore — plateformes iOS 26.1 et macOS 15 |
— | cœur testable sur le Mac par swift test |
| Projet | XcodeGen (project.yml) |
— | le projet Xcode n'est pas versionné |
| Outils constatés | Xcode 27.2, SDK iOS 27.2, simulateurs iOS 26.5 | — | d'après docs/AUDIT.md |
🗂 Organisation du dépôt
App/ point d'entrée, état partagé (AppEnvironment), pochettes, scène CarPlay
Features/ écrans : Accueil, Bibliothèque, Albums, Listes, Recherche, Lecteur, Téléchargements, Réglages, Compte
Components/ mini-lecteur, rangées, pochettes, bouton de téléchargement, commandes système, thème
Core/ paquet Swift SPMusicCore (iOS + macOS) : API, authentification, base SQLite, synchronisation,
téléchargements, fichiers hors ligne, moteur audio — sans aucune dépendance externe
Resources/ Info.plist (+ Info-Debug.plist), droits, catalogue d'images (icône claire / sombre / teintée)
Design/ sources vectorielles de l'icône (icon.svg, icon-dark.svg, icon-tinted.svg)
Tests/ tests d'intégration sur simulateur ; Core/Tests : tests unitaires ; UITests : tests d'interface
Scripts/ backend de test, suites de tests, essai production, archive et envoi TestFlight
docs/ AUDIT.md (existant + matrice de parité), TESTS.md (ce qui a été réellement exécuté), captures, brand/| Dossier | Fichiers Swift | Lignes |
|---|---|---|
Core/Sources |
17 | 3 202 |
Features/ |
10 | 1 763 |
Components/ |
6 | 567 |
Core/Tests |
2 | 516 |
App/ |
4 | 509 |
Tests/ |
2 | 362 |
UITests/ |
1 | 121 |
Total (avec Core/Package.swift) |
43 | 7 062 |
Le projet Xcode est généré : xcodegen generate (il n'est pas versionné).
🚀 Commandes
Scripts/test.sh core # 21 tests unitaires du cœur, sur le Mac
Scripts/test-server.sh up # backend jetable sur m5ma:8692 (bibliothèque synthétique) + tunnel + identifiants
Scripts/test.sh app # 12 tests d'intégration sur simulateur (HTTP réel, audio réel)
Scripts/test.sh ui [iPad] # tests d'interface, captures dans build/shots/
Scripts/prod-smoke.sh # essai en lecture seule contre la production (compte temporaire, supprimé à la fin)
Scripts/release.sh archive|export|validate|upload # archive Release → IPA de distribution → TestFlight| Script | Détail |
|---|---|
Scripts/test.sh core |
tests unitaires de SPMusicCore sur le Mac, sans réseau |
Scripts/test.sh app [iPad] |
tests d'intégration sur simulateur contre le backend jetable |
Scripts/test.sh ui [iPad] |
tests d'interface (même backend) ; captures dans build/shots/ |
Scripts/test-server.sh up |
clone ou rafraîchit le backend, base neuve, bibliothèque synthétique (ondes sinusoïdales, tous les conteneurs pris en charge), démarrage sur m5ma:8692, tunnel SSH vers localhost:8692, identifiants de test écrits hors du dépôt |
Scripts/prod-smoke.sh |
crée un compte auditeur temporaire, exécute Tests/AppTests/ProductionSmokeTests.swift, puis supprime le compte quoi qu'il arrive |
Scripts/release.sh archive |
archive Release pour appareils → build/SPMusic.xcarchive |
Scripts/release.sh export |
IPA signé pour la distribution (profil App Store Connect, certificat géré par Apple) → dist/ |
Scripts/release.sh validate |
validation App Store Connect de l'IPA (n'envoie rien) |
Scripts/release.sh upload |
envoi vers App Store Connect / TestFlight |
⚙️ Configuration
Réglage (project.yml) |
Valeur |
|---|---|
MARKETING_VERSION · CURRENT_PROJECT_VERSION |
1.0.0 · 1 |
SWIFT_VERSION · SWIFT_STRICT_CONCURRENCY |
6.0 · complete |
| Cible de déploiement | iOS 26.1 |
| Identifiants | app ai.spboucher.spmusic.ios, tests .tests, tests d'interface .uitests |
| Signature | automatique |
| Droits (appareil) | Resources/SPMusic.entitlements — webcredentials:music.spboucher.ai |
| Droits (simulateur) | Resources/SPMusic-CarPlay.entitlements — pour exécuter les écrans CarPlay |
| Debug | Resources/Info-Debug.plist : backend de test joint par http://localhost:8692 à travers un tunnel SSH |
| Mac Catalyst · « Conçu pour iPad » sur Mac · visionOS | désactivés |
| Mode d'arrière-plan | audio |
- Avant chaque envoi : incrémenter
CURRENT_PROJECT_VERSIONdansproject.yml. - La clé de l'API App Store Connect est lue dans
~/.config/spmusic-ios/asc.env; rien de secret n'est dans le dépôt. SPMUSIC_BACKEND_REF: branche du backend clonée parScripts/test-server.sh.
📱 Écrans
| Écran | Fichier |
|---|---|
| Racine (onglets iPhone, barre latérale iPad) | Features/Root/RootView.swift |
| Accueil | Features/Home/HomeView.swift |
| Bibliothèque | Features/Library/LibraryView.swift |
| Fiche album | Features/Albums/AlbumDetailView.swift |
| Listes de lecture | Features/Playlists/PlaylistViews.swift |
| Recherche | Features/Search/SearchView.swift |
| Lecteur | Features/NowPlaying/NowPlayingView.swift |
| Téléchargements | Features/Downloads/DownloadsView.swift |
| Réglages | Features/Settings/SettingsView.swift |
| Compte et connexion | Features/Account/AccountViews.swift |
| CarPlay | App/CarPlay/CarPlaySceneDelegate.swift |
🔌 API utilisée
Client : Core/Sources/SPMusicCore/API/ (APIClient.swift, Endpoints.swift). Serveur :
sp-music.
| Domaine | Appels |
|---|---|
| Synchronisation | catalogue incrémental (library/sync?since=), données du compte (library/sync/me) |
| Paroles | paroles d'un titre |
| Favoris | activer / désactiver un favori (titre ou album) |
| Listes | créer, renommer, supprimer, ajouter des titres, ordonner |
| Lecture | enregistrer l'état de lecture ; demander un rendu de compatibilité et suivre son état |
| Historique | envoyer et lire les écoutes |
| Compte | clés d'accès (lister, supprimer), sessions (lister, révoquer), déconnexion |
| Connexion | clé d'accès, code de récupération, association d'appareil (démarrer, interroger) |
| Médias | diffusion GET /api/v1/stream/<id>[?v=compat] (Range → 206), pochettes |
🔁 Parité avec le site
Tableau établi lors de l'audit du 2026-11-17 (docs/AUDIT.md).
| Fonction | Web | iOS / iPadOS |
|---|---|---|
| Parcourir albums, artistes, titres | oui | oui |
| Recherche | serveur | locale, hors ligne comprise |
| Listes de lecture (créer, renommer, ordonner, supprimer) | oui | oui (en ligne) |
| Favoris | oui | oui, mis en file hors ligne |
| Diffusion de l'original, repli AAC | oui | oui |
| File d'attente, aléatoire, répétition | oui | oui (mêmes règles) |
| Reprise de la file entre appareils | oui | oui |
| Paroles synchronisées | mot à mot | ligne à ligne |
| Commandes système (écran verrouillé, casque) | Media Session | oui, natives |
| Téléchargement et lecture hors ligne | non | oui |
| Historique d'écoute | non | oui (envoyé au serveur) |
| Connexion par clé d'accès | oui | oui (native) |
| Association d'appareil par code | page d'approbation | oui |
| Administration (import, édition des tags, comptes) | oui | non — reste sur le site |
| CarPlay | — | code livré, droit Apple à obtenir |
| Égaliseur, fondu, normalisation | non | non |
🔐 Sécurité et vie privée
- Session dans le trousseau ; verrouillage biométrique optionnel de l'application (Face ID).
- Clé d'accès du site par le droit Associated Domains (
webcredentials:music.spboucher.ai) ; le serveur publie le fichier d'association pour cet identifiant. - Chaque fichier téléchargé est vérifié (taille + SHA-256 de l'original) avant d'être déclaré disponible ; un transfert refusé (401) n'est jamais pris pour de l'audio.
- L'essai en production est en lecture seule, avec un compte auditeur temporaire supprimé à la fin.
- Rien de secret n'est dans le dépôt : clé App Store Connect et identifiants de test sont lus hors du dépôt.
- Les tests n'utilisent qu'une bibliothèque synthétique (ondes sinusoïdales) : aucun enregistrement commercial.
✅ Tests
Détail : docs/TESTS.md — ce qui a été réellement exécuté le 2026-11-17. Aucun résultat n'est
simulé ; ce qui n'a pas pu être exécuté est listé comme tel.
| Suite | Commande | Résultat rapporté |
|---|---|---|
| Unitaires du cœur | Scripts/test.sh core |
21 / 21 |
| Intégration sur simulateur | Scripts/test.sh app |
12 / 12 |
| Interface iPhone | Scripts/test.sh ui |
2 / 2 |
| Interface iPad | Scripts/test.sh ui iPad |
2 / 2 |
| Essai production | Scripts/prod-smoke.sh |
2 / 2 |
Fonctions de test dans le dépôt : CoreTests.swift 21, IntegrationTests.swift 10, ProductionSmokeTests.swift 2,
SPMusicUITests.swift 2.
Moyens : simulateurs dédiés « SPMusic iPhone » (iPhone 17 Pro) et « SPMusic iPad » (iPad Pro 11" M5), iOS 26.5 ; backend jetable (le vrai serveur Music SP, dans son propre clone, sa propre base et son propre port) avec une bibliothèque synthétique couvrant FLAC 16/44,1, FLAC 24/48, FLAC 24/96, MP3 320, AAC 256, ALAC, WAV, AIFF, plus un fichier de 40 Mo. Aucun iPhone ni iPad réel n'était branché au Mac.
Liste du cahier des charges, test par test
| Test demandé | État | Comment |
|---|---|---|
| Connexion au cluster | exécuté | Session réelle, production comprise (TLS, passerelle). |
| Streaming | exécuté | 8 formats lus depuis le flux et décodés par iOS ; en production, un FLAC 24/48 de 32 Mo avec saut profond (requête Range). |
| Téléchargement d'un titre | exécuté | Y compris en production, SHA-256 identique à celui du serveur. |
| Téléchargement d'un album | exécuté | 6 titres, chacun vérifié octet pour octet ; aussi par l'interface. |
| Téléchargement d'une playlist | exécuté | Ordre de la liste conservé ; fichiers déjà présents non retéléchargés. |
| Lecture en mode avion | exécuté par équivalent | Pile sans réseau, sans session, serveur à une adresse morte : lecture, piste suivante, enchaînement automatique, répétition, aléatoire, recherche. |
| Lecture avec écran verrouillé | non exécuté | Demande un appareil. Le mode d'arrière-plan audio est déclaré. |
| Lecture en arrière-plan | non exécuté | Idem. |
| Commandes AirPods | non exécuté | Demande un appareil. Vérifié : commandes enregistrées et informations « En lecture » publiées. |
| Changement de sortie audio | réaction vérifiée | Notification « sortie disparue » envoyée à la main : la lecture se met en pause. |
| Interruption par appel / reprise | réaction vérifiée | Notifications d'interruption envoyées à la main : la lecture reprend. |
| Synchronisation | exécuté | Complète puis incrémentale ; production : 875 titres en 0,2 s. |
| Reconnexion réseau | exécuté (unitaire) | Favori et écoute faits hors ligne, envoyés une seule fois au retour. |
| Gestion des téléchargements | exécuté | Pause puis reprise d'un fichier de 40 Mo, échec d'intégrité refusé puis réessayé, fichier disparu retéléchargé. |
| Gestion du stockage | exécuté | Comptage des références (album + liste), suppression, rapport d'espace. |
| Face ID | non exécuté | Demande un appareil. |
| Passkeys | non exécuté de bout en bout | Vérifié : format WebAuthn des réponses, fichier d'association publié, droit Associated Domains dans le binaire signé. |
| Association d'appareil par code | exécuté | Code affiché, approbation, session propre à l'appareil, code inutilisable ensuite. |
| Connexion par code de récupération | exécuté | Par l'API et par l'interface. |
| Navigation iPhone | exécuté | Parcours complet par l'interface, 16 captures relues. |
| Navigation iPad | exécuté | Même parcours, barre latérale, lecteur plein écran. |
| Qualité audio | exécuté | Rendu AAC existant et rendu préparé à la demande ; libellés de format vérifiés. |
| CarPlay | non exécuté | Droit Apple non accordé. |
Défauts trouvés par les tests et corrigés
- Le rang dans la file disparaissait des informations « En lecture » à l'arrivée de la pochette.
- Le lecteur plein écran débordait de l'écran (l'image de fond imposait sa largeur).
- Sur iPad, la ligne « Téléchargements » de la barre latérale ne se sélectionnait pas.
- En-tête d'album illisible sur iPad en portrait ; barre de lecture iPad invisible.
📦 Publication TestFlight
Scripts/release.sh archive # build/SPMusic.xcarchive
Scripts/release.sh export # IPA de distribution dans dist/
Scripts/release.sh validate # validation App Store Connect
Scripts/release.sh upload # envoi TestFlight| Étape (1.0.0, build 1) | État |
|---|---|
| Build simulateur | fait |
| Archive Release pour appareil, signée | faite |
| IPA signé pour la distribution (profil App Store, certificat géré par Apple) | fait — 3,1 Mo |
| Validation App Store Connect | « VERIFY SUCCEEDED with no errors » |
| Envoi TestFlight | « UPLOAD SUCCEEDED with no errors », 1.0.0 (1) |
| Installation sur un iPhone réel | à faire par le propriétaire (TestFlight) |
Il n'y a pas de certificat « Apple Distribution » local : la signature de distribution est faite par le certificat géré par Apple, via la clé de l'API App Store Connect. L'identifiant d'app (avec la capacité Associated Domains) et les profils ont été créés automatiquement lors de l'archive.
⚠️ Blocages et limites — à lire
Voir docs/TESTS.md pour le détail. En bref :
- Aucun appareil réel n'était branché : tout a été exécuté sur simulateur (iPhone 17 Pro et iPad Pro 11", iOS 26.5). Restent à vérifier sur iPhone : clé d'accès avec Face ID, AirPods, écran verrouillé, appel entrant, transferts en arrière-plan app suspendue, mode avion réel.
- CarPlay : le code est livré, mais Apple doit accorder le droit
com.apple.developer.carplay-audio(demande à faire sur developer.apple.com/contact/carplay). Le build TestFlight est signé sans ce droit ; la scène CarPlay ne s'y connecte donc pas. Non testé. - Égaliseur, fondu enchaîné, normalisation : non livrés (optionnels au cahier des charges). Ils imposent de traiter le signal dans l'app.
- Interface en français uniquement.
- Les modifications de listes de lecture demandent une connexion (refus explicite hors ligne) ; favoris et écoutes, eux, sont mis en file.
- Administration (import, édition des tags, comptes) : reste sur le site.
📚 Documentation
docs/AUDIT.md— audit de l'existant, matrice de parité, configuration Apple constatéedocs/TESTS.md— ce qui a été réellement exécuté, défauts corrigés, distribution
👤 Auteur
Simon-Pierre Boucher — conception, développement, exploitation
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 Licence
Le dépôt ne contient pas de fichier de licence. Tous droits réservés © 2026 Simon-Pierre Boucher.