SPB Git

Repository Public

ARCHITECTURE.md 4.3 KB

# Architecture

text
SwiftUI (App, Features, Components) ── AppModel ──┐
                                                  ▼
                 PlaybackController ── AudioEngine ── AVAudioEngine ── sortie Core Audio
                        │                  ▲
                        │ ResolvedSource   │ ByteSource : LocalFileSource | ProgressiveHTTPSource (+ FLACSliceSource)
                        ▼                  │
                 LibrarySession ───────────┘
                  ├─ LibraryStore (SQLite, FTS5)      tout ce que l'interface affiche, sans réseau
                  ├─ StorageManager + PathGuard       fichiers sur disque, seules suppressions autorisées
                  ├─ DownloadManager                  file persistante, reprise par plage, SHA-256
                  ├─ SyncEngine                       opérations locales → cluster, deltas cluster → local
                  ├─ ArtworkStore                     pochettes sur disque
                  └─ APIClient + Connectivity         JSON, session, état du réseau

# Règles tenues

  • Le moteur audio ne connaît ni les titres ni le réseau : il reçoit des sources d'octets et des jetons.
  • Le moteur de téléchargement ne connaît pas le moteur audio ; il réutilise seulement un fichier complet du cache de lecture.
  • La bibliothèque locale n'a jamais besoin du serveur : ouvrir une session, lister, chercher et lire un titre téléchargé ne font aucune requête (prouvé par un test qui compte les connexions).
  • Rien n'est supprimé hors d'un dossier marqué par l'app, liens symboliques résolus.

# Lecture

  • Deux platines (lecteur → mélangeur) alimentent un pré-mélangeur, l'égaliseur, puis le mélangeur principal. La piste suivante est préparée sur l'autre platine et démarrée à l'échantillon exact où la courante se termine (pas de blanc), ou plus tôt avec une rampe à puissance constante (fondu).
  • Chaque platine décode sur sa propre file : une source qui attend le réseau ne bloque jamais les commandes.
  • Les rappels du lecteur AVFoundation ne prennent jamais le verrou du moteur sur un fil audio (cause de deux interblocages trouvés par les tests).
  • Lecture en continu : ProgressiveHTTPSource écrit dans un fichier creux par requêtes de plage ; le décodeur lit ce qui est arrivé. Un saut demande les octets de la destination. Fichier complet → vérifié par SHA-256 → marqué, réutilisable.
  • FLAC : Core Audio se déplace dans un FLAC en le relisant depuis le début (mesuré, avec ou sans table de recherche). FLACIndex trouve une frontière de trame juste avant la cible (SEEKTABLE, sinon synchro de trame validée par CRC-8 et par la trame suivante) et FLACSliceSource présente « en-tête + audio à partir de là » au décodeur. Exact à l'échantillon.
  • Fidélité : aucun transcodage ; égaliseur, normalisation et fondu désactivables d'un bloc (« mode direct ») ; option pour régler la fréquence du périphérique sur celle du titre. L'app n'annonce pas de lecture « bit-perfect ».

# Synchronisation

Une passe : (1) envoyer les opérations locales, dans l'ordre ; (2) tirer le catalogue depuis la dernière révision vue (tout, si demandé, si plus de 24 h, ou si les compteurs divergent) ; (3) tirer listes et favoris du compte, sauf si des opérations attendent encore ; (4) historique dans les deux sens ; (5) mettre en file les téléchargements des collections « gardées hors ligne ». Aucun fichier audio n'est transféré par une synchronisation.

Conflit de liste (modifiée ici hors ligne et ailleurs) : aucune version n'est écrasée ; celle du Mac est enregistrée à côté sous « … (copie de ce Mac) » et l'utilisateur est prévenu.

# Téléchargements

Octets dans <bibliothèque>/.spmusic/partial/<titre>.<asset>.part ; reprise par Range + If-Range sur l'identifiant de l'asset ; taille puis SHA-256 vérifiés avant un déplacement atomique vers le nom lisible. L'état est en base : une fermeture ou un plantage ne perd rien. Un fichier remplacé sur le cluster est retéléchargé ; un titre supprimé du cluster mais téléchargé ici est conservé et signalé.

Files main
Menu

Theme