# AI Artiste

Studio local pour créer des **artistes musicaux virtuels** et produire leur musique avec [Suno](https://suno.com).

L'usage passe **principalement par le dashboard** (interface web locale) : tu remplis des formulaires, le dashboard pilote **Claude Code en local** (ton abonnement, pas l'API) qui exécute des workflows markdown — création d'artiste, écriture de tracks travaillées comme un songwriter, vérification linguistique, brief prêt pour Suno. Les **commandes Claude Code** restent disponibles en alternative.

> **Tes artistes et tracks sont locaux** : le dossier `artists/` est gitignoré (tu ne versionnes pas tes créations). Voir `artists/README.md` pour les conventions.

## Démarrage rapide (dashboard)

```
start.bat      # démarre tout en arrière-plan, ouvre http://localhost:5173, et pose une icône dans le tray
stop.bat       # arrête tout (ou via l'icône → « Arrêter & quitter »)
```

Aucune fenêtre n'est affichée : une **icône dans la barre des tâches** (system tray) pilote le dashboard — clic droit pour **Ouvrir le dashboard / Logs / Redémarrer / Arrêter & quitter** (double-clic = ouvrir).

Premier lancement : `start.bat` installe les dépendances (Node 20+ requis). Prérequis : [Claude Code](https://docs.claude.com/en/docs/claude-code) **installé et connecté** (`claude --version`).

*Alternative en ligne de commande* (dans Claude Code) : `/create-artist`, `/auto-artist`, `/create-track <artiste>` — voir plus bas.

## Interface — le dashboard

Interface **Node + React** locale (`dashboard/`) qui lit `artists/` et **pilote le CLI Claude Code local** (aucune clé API). Tout se fait par **formulaires** :

- **Créer un artiste** — onglet **Automatique** (génération autonome biaisée tendances, langue au choix) ou **Guidé** (un seul formulaire reprenant tous les champs des étapes, envoyés d'un coup).
- **Produire un track** — depuis la page de l'artiste (formulaire ; concept **optionnel**).
- **Explorer** — grille d'artistes, détail (bible en onglets), tracks (fiche + lecteur audio), **graphes** (palette émotionnelle, thèmes).
- **Console discrète** — barre repliable avec **progression k/N**, **tokens & coût $**, durée, et réponse multi-tours quand Claude pose une question. Rafraîchissement auto quand un artiste/track est écrit.

Détails techniques : `dashboard/README.md`.

## Alternative — commandes Claude Code

| Commande | Rôle |
|----------|------|
| `/create-artist` | Wizard guidé → bible d'artiste complète |
| `/auto-artist [tiktok\|<genre>\|random]` | Génère un artiste **complet sans questions**, biaisé tendances (par langue) |
| `/create-track <artiste> [concept]` | Produit un track (concept **optionnel**) |
| `/verify-track <artiste> <track>` | Re-vérifie un track existant |
| `/revise-track <artiste> <track> <feedback>` | Applique du feedback puis re-vérifie |

Le dashboard ne fait qu'appeler ces mêmes workflows — mêmes résultats, pré-remplis par formulaire.

---

## Sous le capot

### La bible d'artiste (dossier éclaté)

Chaque artiste = `artists/<nom>/bible/`, chargé **just-in-time** :

| Fichier | Contenu |
|---------|---------|
| `README.md` | Carte : pitch 1 ligne, genre, langues, index |
| `sound.md` | Identité musicale, **signature structurelle**, influences, reference tracks, signature sonore |
| `voice.md` | Identité vocale, tags Suno, **Suno Persona**, instruments signature, prononciation |
| `world.md` | Palette émotionnelle (primaires/secondaires/**interdites**), thèmes, univers |
| `lore.md` | Backstory, arc narratif, cadre surréaliste autorisé |
| `persona.md` | Personnalité, **USP**, public cible, **bios ×3**, tagline, motifs signature |
| `visual.md` | Palette, esthétique, mots-clés, motifs, **prompt de génération d'image**, style physique |
| `coherence.md` | Règles de cohérence (garde-fous) |

### Production d'un track

| Étape | Action |
|-------|--------|
| 1 — Inputs & direction | Charge la bible (just-in-time), template de structure, analyse cross-track |
| 1.5 — Concept & matière | **Object-writing**, image centrale / angle frais, POV/temps, **décision de structure** (genre × artiste × concept), carte d'énergie |
| 2 — Écriture | Lyrics depuis la matière + contrôles inline (sémantique, craft, flow, rimes, hook) ; style prompt auto depuis la bible |
| 3 — Vérification & sauvegarde | **Déléguée à un subagent** (`track-verifier`) ; sauvegarde + discographie |

### Moteurs de qualité

- **Craft** (`reference/craft/`) — object-writing, image centrale/conceit, show-don't-tell, spécificité (POV, le « turn »), prosodie, **tests 7-9**.
- **Structure** (`reference/craft/song-architecture.md`) — forme **décidée** (verse-chorus / strophique / AABA / hook-first / build-drop), comptes de **barres** par genre, arc d'énergie, spécialisés par la signature structurelle de l'artiste.
- **Linguistique** (`reference/linguistic/`) — syllabes FR/EN (IPA), rimes (FR avec **consonne d'appui** ; EN familles A/B/C) + ratios, flow, prononciation FR, **6 tests sémantiques**.
- **Cohérence & cross-track** — chaque track vérifié contre la bible (genre, voix, thème, émotion, filiation) et la discographie (drift, répétitions, progression).

### Tendances (génération autonome)

`reference/trends/` — base **bilingue** (FR ≠ EN/global), datée. `/auto-artist` route selon la langue. `scripts/fetch_trends.py` rafraîchit un **ancrage factuel** réel (charts Apple/Deezer par pays, gratuit, sans clé).

### Outils (scripts Python déterministes)

`suno_count.py` (chars/tags) · `lyric_assist.py` (rimes+fréquence, Datamuse EN / Lexique FR) · `structure_check.py` (barres/durée/time-to-hook) · `fetch_trends.py` (tendances réelles) · `fetch_lexique.py` (base lexicale FR).

### Contraintes Suno

| Champ | Limite | Sweet spot |
|-------|--------|------------|
| Style Prompt | 1 000 chars | 200-500 |
| Lyrics | 5 000 chars | 2 000-3 000 |
| Titre | 100 chars | 30-50 |

## Structure du projet

```
AI_ARTISTE/
  dashboard/   server/ (Node, pilote le CLI) · web/ (React)   ← interface principale
  start.bat  stop.bat
  CLAUDE.md  README.md  STRUCTURE.md  best-practices.md
  reference/   craft/ · linguistic/{french,english,semantic} · suno/ · trends/ · templates/ · naming/
  scripts/     suno_count · lyric_assist · structure_check · fetch_trends · fetch_lexique
  .claude/     agents/track-verifier · skills/{create-artist,auto-artist,create-track,verify-track,revise-track}
  artists/     LOCAL (gitignoré) — tes artistes & tracks ; voir artists/README.md
```

## Principes

- **Les fichiers de référence font autorité** (en cas de conflit, le fichier gagne)
- **La bible est la loi** — zéro déviation du genre, thèmes, émotions, style vocal
- **Correction ET profondeur** — niveau songwriter, pas seulement métriquement correct
- **Structure dictée par le genre ET l'artiste**, jamais un gabarit par défaut
- **Chargement just-in-time** · **Auto-save** · **Une langue par track**

## Prérequis

- [Claude Code](https://docs.claude.com/en/docs/claude-code) installé et connecté
- Node 20+ (pour le dashboard)
- Un compte [Suno](https://suno.com)
