SPB Git

Repository Public

13 entries at the root
History

Latest commit docs: legendary README — icon, logo, live spbgit badges, author a0f54ba

NameLast commitUpdated
App SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
Components SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
Core SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
Design SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
docs docs: legendary README — icon, logo, live spbgit badges, author
Features SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
Resources SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
Scripts SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
Tests SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
UITests SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
.gitignore SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
project.yml SP Music for iOS and iPadOS 1.0.0: native player with streaming and verified offline downloads
README.md docs: legendary README — icon, logo, live spbgit badges, author
README.md View source
SP Music logo



SP Music icon

# 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

music.spboucher.ai version plateforme TestFlight licence author

Swift concurrence SwiftUI AVQueuePlayer SQLite URLSession SwiftPM XcodeGen passkeys CarPlay dépendances WebView

commits last commit activity language languages size branches tags clones

fichiers Swift lignes Swift cœur écrans tests unitaires tests d'intégration tests d'interface captures

bundle App Store Connect signature cible appareils


# Sommaire


# 🎯 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/).

Accueil sur iPhone Fiche album sur iPhone Lecteur sur iPhone Téléchargements sur iPhone
Connexion et iPad
Connexion sur iPhone

Barre de lecture sur iPad

File d'attente sur 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 ; URLSession d'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 : NavigationSplitView avec 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

text
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

bash
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_VERSION dans project.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 par Scripts/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

  1. Le rang dans la file disparaissait des informations « En lecture » à l'arrivée de la pochette.
  2. Le lecteur plein écran débordait de l'écran (l'image de fond imposait sa largeur).
  3. Sur iPad, la ligne « Téléchargements » de la barre latérale ne se sélectionnait pas.
  4. En-tête d'album illisible sur iPad en portrait ; barre de lecture iPad invisible.

# 📦 Publication TestFlight

bash
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ée
  • docs/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.

Clone sp-music-ios

Anonymous clone and fetch. Pushing requires the owner's personal access token.

Snapshot of main

Files main
Menu

Theme