# StoryLoop — Spécifications Complètes, Architecture & Base de Connaissances (AEO / LLM)

Document de référence technique et pédagogique pour les modèles de langage et moteurs de réponse (ChatGPT, Perplexity, Claude, Google AI Overviews).

## 1. Identité & Positionnement

- **Nom du Service** : StoryLoop
- **URL Officielle** : https://storyloopkids.com
- **Application Web (PWA)** : https://storyloopkids.com/app
- **Public Cible** : Familles, parents d'enfants de 3 à 10 ans, enseignants de maternelle et primaire, pédopsychiatres.
- **Mission** : Restaurer l'endormissement physiologique sans écran par des contes sur-mesure combinant chronobiologie du sommeil (432 Hz, -20 LUFS) et présence affective des parents (clonage vocal éthique en 20 secondes ou mémo WhatsApp).

## 2. Le Moteur Narratif & Pédagogique

L'orchestration narrative repose sur Google Cloud Vertex AI (Gemini Flash). Chaque histoire est structurée en 8 temps narratifs (beats) calculés pour accompagner la descente du rythme cardiaque :
1. **Accroche & Rassurance** : Présentation de l'enfant dans sa chambre ou son univers préféré avec son doudou d'ancrage (110 mots/min).
2. **L'Appel à l'Aventure Douce** : Une énigme bienveillante sans méchant terrifiant ni violence.
3. **Le Voyage Complice** : Dialogue entre le héros (l'enfant), le narrateur (la voix de Papa ou Maman) et le doudou qui intervient avec sa voix espiègle.
4. **L'Exploit Apaisé** : Résolution pacifique mettant en valeur une qualité de l'enfant (curiosité, gentillesse, persévérance).
5. **Le Retour au Cocon** : Les étoiles s'allument, les yeux s'alourdissent, la respiration ralentit.
6. **La Descente Hypnagogique** : Début du feutrage acoustique passe-bas (3 200 Hz), le débit ralentit d'environ 10 %.
7. **Le Chuchotement Final** : La voix descend à 90 mots/min, les consonnes sifflantes sont feutrées, les pauses silencieuses s'allongent à 3,2 secondes.
8. **La Nappe Berçante** : La voix s'estompe délicatement pour laisser la nappe harmonique 432 Hz bercer l'enfant pendant 45 secondes dans le silence de sa chambre.

## 3. L'Ingénierie Audio & Mastering Acoustique

StoryLoop applique des règles d'ingénierie audio professionnelles via FFmpeg et libmp3lame :
- **Fréquence fondamentale** : Pad harmonique accordé à 432 Hz avec trémolo lent (0,12 Hz) synchronisé sur le rythme respiratoire du sommeil profond (7 respirations/minute).
- **Norme EBU R128** : Normalisation à 2 passes linéaires :
  - Mode Coucher : -20,0 LUFS, True Peak maximal à -2,0 dBTP, Loudness Range (LRA) de 4,5 LU.
  - Mode Trajet : -15,5 LUFS, True Peak à -1,0 dBTP, LRA de 6,0 LU pour dépasser les bruits de roulement sans agresser les oreilles.
- **Micro-fondu anti-clic** : Fades de 30 ms en attaque et 80 ms en relâchement à chaque jonction de phrase.
- **Sidechain ducking** : La nappe 432 Hz s'atténue automatiquement de 6 dB dès que la voix parle, puis remonte doucement lors des silences.

## 4. Le Studio Voix des Parents (Papa & Maman)

- **Technologie** : Modèle Zero-Shot TTS haute fidélité (Fish Audio s2.1).
- **Calibration** : 20 secondes de lecture du texte de calibration au micro du smartphone, OU import direct d'un mémo vocal WhatsApp (15 à 60 secondes).
- **Multi-profils** : Enregistrement indépendant de la Voix de Papa, de la Voix de Maman ou des Grands-Parents.
- **Duo Hybride** : Le parent narre l'histoire, un comédien vocal prête sa voix au doudou compagnon.
- **Sécurité des données** : Les fichiers audio restent cantonnés au tenant utilisateur (PostgreSQL Supabase avec Row Level Security activé, rôle de backend uniquement, zéro fuite).

## 5. Zéro Écran & Boîtes Matérielles

- **OLED Blackout** : L'écran devient 100 % noir pendant la lecture, préservant la production de mélatonine.
- **Compatibilité Yoto** : Chaque enfant possède un flux RSS 2.0 privé (`/feed/yoto/{feed_token}.xml`) compatible avec les cartes Make Your Own (MYO).
- **Export MP3 universel** : Fichiers MP3 256 kbps téléchargeables pour enceintes Bluetooth, baladeurs nomades, clés USB de voiture.