🎵 AIME - AI Music Enabler - Version 4.7.0

Application web moderne pour tracker et analyser l'historique d'écoute musicale depuis Last.fm, avec enrichissement automatique via Spotify, Discogs et IA.

🚀 Développement

Développé avec Vibe Coding en utilisant VS Code et GitHub Copilot

Cette application a été entièrement développée en exploitant les capacités d'assistance par IA de GitHub Copilot dans VS Code, démontrant la puissance du "Vibe Coding" - une approche de développement fluide et productive basée sur la collaboration homme-IA.

🏗️ Architecture

Frontend: React 18 + TypeScript + Material-UI
Backend: FastAPI + Python 3.10+
Base de données: SQLite / PostgreSQL
APIs Intégrées:
- Last.fm: Agrégation multi-sources (PlexAmp, Quobuz, Apple Music, etc.)
- Spotify: URLs, images, métadonnées tracks, lecture directe
- Apple Music: Liens directs, recherche intelligente, lecture directe ✨ v4.7
- Discogs: Collection, vinyl records
- EurIA (Infomaniak AI): Descriptions automatiques

📖 Documentation d'Architecture Détaillée

Pour une compréhension complète de l'architecture, consulter les documents dans le dossier /docs:

Document	Contenu
ARCHITECTURE-INDEX.md	🗺️ Guide de navigation (COMMENCER ICI)
ARCHITECTURE-GUI-AND-APIS.md	🎨 Interface graphique + tous les API externes détaillés
ARCHITECTURE-DIAGRAMS.md	🎨 Diagrammes Mermaid des flux et dépendances
CODE-ORGANIZATION-SUMMARY.md	🔧 Refactoring plan et organisation du code
AI-PROMPTS.md	🤖 Catalogue complet des prompts EurIA

👉 Pour les développeurs: Commencez par ARCHITECTURE-INDEX.md pour naviguer efficacement

🐳 Docker — Prêt pour le déploiement

Cette application est empaquetée et prête pour un déploiement via Docker Compose. Vous trouverez un script d'automatisation et une checklist dans le dossier deploy/ :

deploy/deploy.sh — script SSH pour cloner, builder et démarrer l'application sur un serveur distant.
deploy/aime.service — unité systemd pour démarrer le stack via docker compose.
deploy/Caddyfile — exemple de configuration Caddy (remplacez example.com).

Voir deploy/FINAL-README.md pour la checklist complète et les commandes.

🚦 Développement & Release — Workflow Sûr

Maintenant que l'application tourne en production via Docker, vous pouvez développer de nouvelles fonctionnalités sans risquer de casser la production. Voici le workflow recommandé :

Résumé du Workflow

Développer en branche (feature/*) — modifiez le code librement.
Tester localement : docker compose build && docker compose up.
Merger vers main quand ok.
Tagger et publier une version (v4.8.0).
Déployer en production avec un tag immuable (pas latest).
Rollback rapide : revenir à la version antérieure en 1 commande si problème.

Points Clés

Isolement : Votre code en développement ne touche pas la production.
Immuabilité : Les images Docker taggées (v4.8.0) ne changent jamais — reproductibilité garantie.
Sécurité : Secret et configs restent hors du dépôt (deploy/deploy.sh --copy-secrets).
Contrôle : Vous décidez quand et comment déployer — pas d'automatisation cachée.

Commandes Rapides

# Développer une feature
git checkout -b feature/my-new-feature
# ... modifiez le code ...
docker compose build && docker compose up
# ... testez ...

# Merger et relâcher
git checkout main && git merge feature/my-new-feature
git tag -a v4.8.0 -m "Release v4.8.0"
git push origin main --tags

# Publier les images
docker compose build --no-cache
docker tag aime-backend:latest mon-username/aime-backend:v4.8.0
docker tag aime-frontend:latest mon-username/aime-frontend:v4.8.0
docker push mon-username/aime-backend:v4.8.0
docker push mon-username/aime-frontend:v4.8.0

# Déployer en production
./deploy/deploy.sh --host user@prod-server --copy-secrets

📖 Pour toutes les étapes détaillées : consultez deploy/FINAL-README.md.

📋 Fonctionnalités

✅ Implémentées

Tracking Temps Réel - Multi-Source
- Surveillance automatique Last.fm toutes les 2 minutes (agrège données de multiples sources)

Support des sources : PlexAmp, Quobuz, et autres services compatibles Last.fm
Détection nouveaux tracks écoutés en temps réel
Enrichissement métadonnées (images artistes/albums de Spotify, Last.fm, Discogs)
Génération automatique descriptions IA

Gestion Collection Discogs
- Import collection depuis Discogs API
- Synchronisation manuelle
- Visualisation avec pochettes

2b. ✨ Découverte par IA - Créer Collections

Génération automatique de collections basées sur des requêtes en langage naturel
Recherche intelligente d'albums via EurIA
Création de playlists thématiques personnalisées
Suggestions d'albums basées sur le contexte musicale
Aperçu visuel: Affichage automatique des 5 premières couvertures d'albums de chaque collection

Journal d'Écoute
- Liste chronologique inversée
- Marquage favoris
- Affichage images multiples (artiste, album Spotify, album Last.fm)
- Info IA expandable
Timeline Horaire
- Visualisation par heure et par jour
- Vue d'ensemble des écoutes
Gestion des Trackers

Configuration Last.fm
Suivi automatique des écoutes
✨ Auto-restart : Le tracker redémarre automatiquement après un redémarrage serveur

Scheduler et Exports Automatiques ✨ v4.5 - Auto-Start Garanti
- 🎋 Génération quotidienne de haikus pour 5 albums aléatoires (6h00)
- 📝 Export automatique de la collection en Markdown (8h00)
- 📊 Export automatique de la collection en JSON (10h00)
- 📖 Génération automatique de 10 magazines chaque jour à 3h00
- 🗑️ Gestion automatique des fichiers (garde les 5 derniers de chaque type)
- ⚙️ Configuration modifiable des limites de fichiers
- 🛡️ Auto-Start Garanti : Le scheduler redémarre automatiquement même si non marqué actif en DB
- ✨ Formats scheduler identiques à l'API (haiku, json, markdown)
  - Tables des matières avec liens internes
  - Métadonnées complètes (images, résumés IA, labels)
  - Source unique pour tous les exports (cohérence garantie)
📖 Magazine Éditorial ✨ NOUVEAU v4.5 (5 février 2026)
- Format Éditorial : 5 pages scrollables avec contenu aléatoire
- Page 1 - Artiste Aléatoire : Présentation complète + albums + haïku IA
- Page 2 - Album du Jour : Album spotlight + description IA longue (2000+ caractères)
- Page 3 - Haïkus : 3 albums aléatoires + haïkus générés EurIA
- Page 4 - Timeline : Récapitulatif écoutes récentes + statistiques
- Page 5 - Playlist Thème : Thème aléatoire + albums + description créative
- Auto-Refresh : Nouvelle édition automatique toutes les 15 minutes
- Navigation Fluide : Scroll souris, boutons, pagination
- 🎨 Portraits d'Artistes : Boutons "Portrait" sur chaque artiste avec génération IA en streaming
- 📊 Scroll Indicator : Affichage "Page n sur x" pendant le scrolling
- 🎲 Éditions Multiples : 10 magazines générés automatiquement chaque jour à 3h
- Design Moderne : Glassmorphism avec couleurs variables et layouts aléatoires
- Responsive : Desktop, Tablet, Mobile optimisés
🎭 Portrait d'Artiste ✨ NOUVEAU v4.5
- Génération IA Streaming : Texte généré progressivement par EurIA
- Format Markdown : Support complet avec titres, listes, emphases
- Accessible Partout : Boutons "Portrait" sur tous les artistes du magazine
- Interface Modal : Affichage élégant avec image d'artiste
- Temps Réel : Voir le texte se construire phrase par phrase
API REST Complète

Endpoints pour collection, historique, playlists, services, magazines
Documentation Swagger auto-générée
Validation Pydantic

🚧 En Développement

Timeline horaire par jour
Génération playlists (7 algorithmes)
Analytics et statistiques avancées
Export playlists (M3U, JSON, CSV)

🚀 Installation

Prérequis

Python 3.10-3.13 (⚠️ Python 3.14 nécessite SQLAlchemy dev - voir TROUBLESHOOTING)
Node.js 18+
Git

🎧 Scrobbling Apple Music (Last.fm)

Pour scrobbler vos écoutes Apple Music sur Last.fm, plusieurs solutions recommandées :

Sur iOS : Last.fm (app officielle) — Application officielle de Last.fm pour iOS, permettant de scrobbler vos écoutes et de suivre votre historique musical en temps réel.
Sur iOS : Marvis Pro — Application puissante permettant de scrobbler automatiquement vos lectures Apple Music vers Last.fm.
Sur iOS : QuietScrob - Last.fm Scrobbler — Alternative légère et discrète pour scrobbler automatiquement vos écoutes vers Last.fm avec une interface minimaliste.
Sur Mac OS X : NepTunes for Last.fm — Utilitaire léger pour scrobbler Apple Music (et d'autres lecteurs) directement sur votre Mac.

Ces outils permettent d'assurer que toutes vos écoutes Apple Music sont bien prises en compte dans l'historique Last.fm, et donc agrégées dans AIME.

Installation Rapide

# Cloner le repository
cd "/Users/patrickostertag/Documents/DataForIA/AIME - AI Music Enabler"

# Donner les permissions d'exécution aux scripts
chmod +x scripts/*.sh

# Exécuter l'installation
./scripts/setup.sh

cd backend

# Créer environnement virtuel
python3 -m venv .venv
source .venv/bin/activate

# Installer dépendances
pip install -r requirements.txt

# Initialiser base de données
python3 -c "from app.database import init_db; init_db()"

Frontend

cd frontend

# Installer dépendances
npm install

🎯 Démarrage

Mode Développement

# Démarrer backend + frontend
./scripts/start-dev.sh

Ou manuellement:

# Terminal 1 - Backend
cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2 - Frontend
cd frontend
npm run dev

URLs

Frontend: http://localhost:5173
API: http://localhost:8000
Documentation API: http://localhost:8000/docs

Accès depuis un autre ordinateur du réseau local

Backend : lancer Uvicorn en écoutant toutes les interfaces

cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Si vous utilisez Docker Compose, les ports 8000 et 80 sont déjà exposés sur l'hôte.

CORS : autoriser le poste distant dans config/.env

CORS_ORIGINS=http://localhost:5173,http://192.168.1.X:5173,http://192.168.1.X

Frontend : pointer l'URL API vers l'hôte et autoriser l'écoute réseau

cd frontend
cp .env.example .env
# dans .env -> VITE_API_URL=http://192.168.1.X:8000/api/v1
npm install
npm run dev

Accès : depuis le poste distant, ouvrez http://192.168.1.X:5173 (ou le port 80 si vous utilisez Docker).
Checklist rapide

VITE_API_URL pointe bien vers l'IP de l'hôte (pas localhost) côté frontend
CORS_ORIGINS inclut l'origine du frontend (IP:port) côté backend
Le fichier data/musique.db est bien monté/accessible (Docker: volume ./data)

📁 Structure du Projet

music-tracker/
├── backend/                 # API FastAPI
│   ├── app/
│   │   ├── api/v1/         # Routes API
│   │   ├── models/         # Modèles SQLAlchemy
│   │   ├── schemas/        # Schémas Pydantic
│   │   ├── services/       # Services (Spotify, Last.fm, etc.)
│   │   └── main.py         # Point d'entrée
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/               # Application React
│   ├── src/
│   │   ├── pages/         # Pages principales
│   │   ├── components/    # Composants réutilisables
│   │   ├── api/           # Client API
│   │   └── types/         # Types TypeScript
│   ├── package.json
│   └── Dockerfile
├── config/                 # Configuration
│   ├── app.json           # Config application
│   └── secrets.json       # API keys (GITIGNORE)
├── data/                   # Données
│   └── musique.db         # Base SQLite
├── scripts/               # Scripts utilitaires
│   ├── setup.sh
│   └── start-dev.sh
├── docker-compose.yml
└── README.md

🔧 Configuration

Les API keys sont déjà configurées dans config/secrets.json:

Last.fm: Tracking d'écoute
Spotify: Images artistes/albums
Discogs: Collection musicale
EurIA: Génération descriptions IA

🐳 Docker

🔗 Adhérences entre Docker et l’hôte

Voici comment les containers interagissent avec le système hôte (volumes, ports, variables, réseau) :

Ports exposés

Container	Host	Usage
backend:8000	8000	API FastAPI
frontend:80	80	Web HTTP

Volumes montés (partage de fichiers/dossiers)

Backend :

Host                    →  Container
./data                  →  /app/data
./config                →  /app/config
./backend               →  /app/backend
/etc/localtime          →  /etc/localtime (ro)
/etc/timezone           →  /etc/timezone (ro)

Init-DB :

Host                    →  Container
./data                  →  /app/data
./config                →  /app/config
/etc/localtime          →  /etc/localtime (ro)
/etc/timezone           →  /etc/timezone (ro)

Frontend :

Host                    →  Container
/etc/localtime          →  /etc/localtime (ro)
/etc/timezone           →  /etc/timezone (ro)

Variables d’environnement synchronisées

TZ=Europe/Paris : timezone identique à l’hôte
PYTHONUNBUFFERED=1 : logs Python immédiats
ENVIRONMENT=production, PROJECT_ROOT=/app

Réseau

Réseau bridge music-tracker-network (172.20.0.0/16)
Communication interne entre containers
Backend attend que Frontend soit prêt (depends_on + healthcheck)

Résumé : Les dossiers ./data, ./config et le code source ./backend sont partagés en temps réel. Les modifications locales sont visibles instantanément dans le container.

# Construire et lancer avec Docker Compose
docker-compose up -d

# Arrêter
docker-compose down

📚 Documentation API

Endpoints principaux:

Collection

GET /api/v1/collection/albums - Liste albums avec pagination
GET /api/v1/collection/albums/{id} - Détail album
POST /api/v1/collection/albums - Créer album
PUT /api/v1/collection/albums/{id} - Modifier album
DELETE /api/v1/collection/albums/{id} - Supprimer album

Historique

GET /api/v1/history/tracks - Journal chronologique
GET /api/v1/history/timeline - Timeline horaire
GET /api/v1/history/stats - Statistiques
POST /api/v1/history/tracks/{id}/love - Marquer favori

Playlists

GET /api/v1/playlists - Liste playlists
POST /api/v1/playlists/generate - Générer playlist
GET /api/v1/playlists/{id} - Détail playlist
GET /api/v1/playlists/{id}/export - Exporter playlist

Services

GET /api/v1/services/tracker/status - Statut tracker Last.fm
POST /api/v1/services/tracker/start - Démarrer tracker Last.fm
POST /api/v1/services/tracker/stop - Arrêter tracker Last.fm
POST /api/v1/services/discogs/sync - Synchroniser Discogs
POST /api/v1/services/ai/generate-info - Générer info IA

Magazine ✨ NOUVEAU

GET /api/v1/magazines/generate - Générer nouveau magazine éditorial
POST /api/v1/magazines/regenerate - Alias pour générer nouveau magazine

Scheduler (Tâches Automatiques)

GET /api/v1/services/scheduler/config - Configuration scheduler + max_files_per_type
PATCH /api/v1/services/scheduler/config - Mettre à jour max_files_per_type
POST /api/v1/services/scheduler/start - Démarrer scheduler
POST /api/v1/services/scheduler/stop - Arrêter scheduler
POST /api/v1/services/scheduler/trigger/{task_name} - Déclencher tâche manuel
- generate_haiku_scheduled - Générer haikus
- export_collection_markdown - Export Markdown
- export_collection_json - Export JSON

Documentation complète: http://localhost:8000/docs

📅 Tâches Automatiques (Scheduler)

Le scheduler exécute automatiquement trois tâches quotidiennes:

🎋 Génération de Haikus (6h00)

POST /api/v1/services/scheduler/trigger/generate_haiku_scheduled

Sélectionne 5 albums aléatoires
Génère un haiku IA pour chaque
Export en fichier Markdown horodaté
Format: generate-haiku-YYYYMMDD-HHMMSS.md

📝 Export Markdown (8h00)

POST /api/v1/services/scheduler/trigger/export_collection_markdown

Exporte la collection complète
Groupée par artiste
Inclut année et support
Format: export-markdown-YYYYMMDD-HHMMSS.md

📊 Export JSON (10h00)

POST /api/v1/services/scheduler/trigger/export_collection_json

Exporte la collection complète
Format JSON avec métadonnées
Inclut ID, titre, année, support, artistes, nombre de tracks
Format: export-json-YYYYMMDD-HHMMSS.json

⚙️ Configuration Fichiers

PATCH /api/v1/services/scheduler/config?max_files_per_type=5

Modifiable dans les Settings de l'application
Valeur par défaut: 5 fichiers par type
Les anciens fichiers sont automatiquement supprimés
Les logs affichent les suppressions (🗑️)

Stockage: Tous les fichiers générés dans le répertoire Scheduled Output/

🧪 Tests

# Backend
cd backend
pytest tests/ -v --cov=app

# Frontend
cd frontend
npm run test

📚 Documentation

Guide de Démarrage Rapide - Point de départ (COMMENCER ICI)
Documentation Complète - Guide complet avec index
Architecture Complète - Architecture système détaillée
Schéma Base de Données - Modèle relationnel (Mermaid)
Catalogue Prompts IA - 🤖 Tous les prompts EurIA utilisés
Architecture Détaillée - Détails techniques complets
API REST - Documentation endpoints
Nouvelles Fonctionnalités - Version 4.0.0

Documentation des Fonctionnalités

Tracker Last.fm - Configuration et import
Journal/Timeline - Vue chronologique
Scheduler et Exports - Tâches automatiques et configuration
Magazine Éditorial - Guide complet du Magazine (10 pages)
Magazine - Guide d'Utilisation - Guide de démarrage (15 pages)
Magazine - Implémentation - Architecture technique (12 pages)
Magazine - Améliorations - Roadmap et idées futures (20 pages)
Magazine - Prompts EurIA - Catalogue des prompts IA (18 pages)
Magazine - Testing - Guide de test complet (16 pages)
Magazine - Vue Visuelle - Mockups et designs (14 pages)

🔧 Dépannage

Si vous rencontrez des problèmes lors de l'installation ou du démarrage, consultez le Guide de Dépannage Complet pour des solutions détaillées.

Problèmes Connus Résolus

✅ Python 3.14 incompatibilité avec SQLAlchemy (solution: SQLAlchemy dev version)
✅ Attribut metadata réservé dans modèle Album (solution: renommé en album_metadata)
✅ Import ForeignKey manquant (solution: ajouté à playlist.py)
✅ Chemin base de données incorrect (solution: variable d'environnement PROJECT_ROOT)
✅ Reloads infinis d'Uvicorn (solution: --reload-dir app)

📝 Roadmap

Exports avancés (M3U, Spotify, Apple Music)
Visualisations avancées (genres, découverte)
Recommandations IA personnalisées
Notifications (email, alertes nouveaux albums)
Application mobile (React Native)
Partage de playlists
Dark mode amélioré
Responsive mobile complet
Planification custom des tâches scheduler

🤝 Contribution

Projet personnel de Patrick Ostertag.

📄 License

MIT License

Version: 4.6.3
Date: 9 février 2026
Auteur: Patrick Ostertag

Changelog 4.6.2

Refactorisation Code & Architecture (07/02/2026)

🏗️ Nouvelle Architecture Services : Services organisés par domaine (8 groupes logiques)
- dialog/ - Réponses unifiées (erreurs, succès, streaming)
- external/ - Intégrations externes (Spotify, Last.fm, Discogs, AI)
- collection/ - Gestion collection (albums, artistes, tracks, search)
- content/ - Génération contenu IA (haikus, articles, descriptions)
- playback/ - Playback audio (playlists, queue)
- analytics/ - Statistiques (listening history, patterns)
- tracking/ - Tracking temps réel (Last.fm)
- magazine/ - Feature magazine (déjà bien organisée)
🔧 Module Dialogue Unifié : Réponses HTTP, erreurs, SSE standardisées
- dialog/error_dialog.py - Gestion centralisée des erreurs
- dialog/success_dialog.py - Gestion centralisée des succès
- dialog/streaming_dialog.py - SSE/Streaming standardisé
🐛 Bug Fix Critique : Suppression doublon stream_artist_article() dans articles.py
📚 Documentation Complète : 8 guides de refactorisation (2,300+ lignes)
- Guide d'implémentation avec templates
- Audit complet des duplications
- Plan d'action phase-by-phase
- Visualisations avant/après
✅ Zero Breaking Changes : Système entièrement rétro-compatible
📊 Qualité Code Améliorée :
- Duplications : 30% → 0%
- Temps recherche code : 5+ min → 30 sec
- Organisation : Plate → 8 domaines clairs

Changelog 4.6.1

Améliorations Magazine Éditorial (06/02/2026)

✨ Format Texte Optimisé : Textes affichés en colonnes uniques (pas de fragmentation côte à côte)
🎨 Masquage Intelligent : Les petits contenus (< 50% de taille) à côté de textes longs sont masqués
- Haikus trop courts → masqués
- Style Musical court → masqué si description > 2x plus longue
🎯 Couleur Dynamique : Fond du magazine adapté à la couleur la plus claire de la première image
- Extraction intelligente de couleur par analyse de luminosité
- Fallback au blanc automatique en cas d'erreur
📖 Lisibilité Améliorée : Affichage plus épuré et cohérent
🧹 Cleanup Code : Refactorisation avec functions utilitaires réutilisables

Changelog 4.4.0

Magazine Éditorial (03/02/2026)

📖 Nouvelle Page Magazine : Interface éditorial moderne avec 5 pages scrollables
🎨 Format Rich Media : Images, textes, haïkus générés par EurIA
🎯 5 Sections :
1. Artiste Aléatoire avec ses albums et haïku IA
2. Album Spotlight avec description longue (2000+ caractères)
3. Haïkus : 3 albums aléatoires avec haïkus EurIA
4. Timeline : Récapitulatif des écoutes récentes
5. Playlist Thème : Thème créatif avec albums et description
⏱️ Auto-Refresh : Nouvelle édition toutes les 15 minutes + minuteur visible
🎨 Design Moderne : Glassmorphism avec couleurs et layouts variables
📱 Responsive : Desktop, Tablet, Mobile optimisés
📚 Documentation Complète : 7 fichiers de documentation (125+ pages)
🔌 Endpoints API : /api/v1/magazines/generate et /api/v1/magazines/regenerate

Changelog 4.3.0

Synchronisation Complète des Formats (31/01/2026)

✨ Les fichiers générés par le scheduler sont maintenant strictement identiques aux fichiers de l'API
🎋 Format Haiku enrichi: table des matières, métadonnées complètes, images (4x enrichi)
📝 Format Markdown: utilise MarkdownExportService, TOC, résumés IA (12x complet)
📊 Format JSON: images, métadonnées IA, timestamps, Discogs URL (18x riche)
🔧 Correction alignement interface Settings (tâches planifiées cadrées à gauche)
📚 Documentation complète: 6 nouveaux fichiers de documentation
✅ Tests et scripts de vérification automatiques

Name		Name	Last commit message	Last commit date
backend		backend
config		config
data		data
deploy		deploy
docs		docs
frontend		frontend
roon-bridge		roon-bridge
scripts		scripts
test-reports		test-reports
tests		tests
.gitignore		.gitignore
README.md		README.md
docker-compose.example.yml		docker-compose.example.yml
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation