le-mystere-professeur-zacus/specs/2026-06-13-atelier-asset-authoring-plan.md

Plan — Édition & génération d'assets depuis l'Atelier (écran, audio, fichiers SD/NFS)

Statut : PLAN (aucun code écrit). Rédigé le 2026-06-13. Objectif produit : depuis l'Atelier web, éditer et générer tous les assets d'un scénario (textes d'écran, audio, images, fichiers data) et les déployer sur le firmware (LittleFS aujourd'hui, SD/NFS demain), avec génération assistée par gateway.ailiance.fr (LLM) et les générateurs audio/image existants.

1. Pourquoi ce document

La demande (« mettre à jour l'atelier pour tout éditer : écran, audio, fichiers NFS/SD ; montage web ; ponts firmware↔atelier ; génération d'assets via l'atelier et gateway.ailiance.fr ») couvre 5 chantiers qui touchent 4 systèmes (atelier React, gateway FastAPI, firmware ESP-IDF, gateway LLM externe). C'est un projet multi-semaines. Ce plan le décompose en phases livrables, ordonnées par dépendance et risque, pour exécuter sans tout casser.

2. État réel constaté (audit 2026-06-13)

Domaine	Ce qui existe	Ce qui MANQUE
Scénario	YAML → compile_runtime3.py → IR JSON ; hot-load POST /game/scenario	—
Écran	scene{title,subtitle,symbol,effect} dans l'IR → display_ui (LCD texte+symbole)	Aucune image : picture/ existe mais n'est jamais lu par le firmware
Audio	TTS pool (Piper :8001, F5-TTS voice-bridge :8200), ambiances AudioCraft ; manifests hotline_tts/manifest.json	Pas d'éditeur web ; pas de génération à la demande depuis l'atelier
Images	Printables PNG via OpenAI Images (tools/printables/)	Pas embarquées firmware ; pas d'éditeur web
Stockage firmware	LittleFS 5 Mo (partition storage), monté /littlefs ; scenario.json (≤64 Ko), hotline_tts/, music/, picture/, recorder/	Aucun SD ni NFS — n'existe pas dans le firmware. Plafond 5 Mo strict. Reformaté à chaque flash.
Pont web↔firmware	gateway /v1/flash (hot POST / cold staging / ESP-NOW relay), /v1/studio, /v1/share (neuf)	Pas de /v1/assets/* (génération, staging, sync)
Génération	Scripts offline Python (TTS, printables, ambiances)	Pas d'orchestration web ; pas de file async (gen > 20 s)
gateway.ailiance.fr	ailiance-gateway : LLM texte (chat/completions, embeddings, responses, ~30 modèles). OpenAI-compatible.	Aucune intégration. Ne fait PAS d'image ni d'audio.

Conséquences cadrantes

• « Fichiers sur NFS et SD » et « images à l'écran » = développement firmware (partitions, montage SD SPI/SDMMC, client NFS, décodage image LovyanGFX). Nécessitent la carte en main et des tests hardware. À isoler en fin de parcours.
• gateway.ailiance.fr génère du TEXTE : dialogues NPC, indices, textes/titres d'écran, descriptions, variations de scénario. Images/audio restent sur les générateurs dédiés (OpenAI Images, F5-TTS, AudioCraft).
• Tout le reste (éditeurs web, génération de texte, wiring des générateurs audio existants, staging LittleFS) se fait côté web/gateway sans risque firmware.

3. Architecture cible (vue d'ensemble)

Atelier (React)  ── panneau « Assets »
  │   éditer (textes écran, dialogues, indices, refs audio/image)
  │   générer (texte → ailiance ; audio → voice-bridge ; image → OpenAI)
  ▼
Gateway (FastAPI :8400)  ── /v1/assets/*
  ├─ /text/generate   → proxy gateway.ailiance.fr (LLM)
  ├─ /audio/generate  → voice-bridge F5 / AudioCraft (ASYNC, file de tâches)
  ├─ /image/generate  → OpenAI Images (ASYNC)
  ├─ /manifest        → CRUD manifest d'assets (versionné)
  └─ /stage           → préparer le bundle d'assets pour un board
  ▼
Déploiement
  ├─ hot   : POST /game/scenario (+ assets inline si petits)
  ├─ cold  : staging dans cold_data_dir → flash
  ├─ SD/NFS: (Phase 4) sync vers /sd ou /nfs du firmware
  └─ relay : ESP-NOW vers peers
  ▼
Firmware (ESP-IDF)  ── media_manager + display_ui (+ sd_nfs en Phase 4)

4. Phases (ordonnées par dépendance et risque)

Phase 0 — Fondations & contrats (spec, pas de code applicatif)

• Modèle d'asset unifié : {id, type(text|audio|image|data), scope(scenario|board|global), source, manifest_ref, version}.
• Schéma de manifest versionné (généralise hotline_tts/manifest.json), avec hash de contenu + provenance (générateur, prompt, modèle).
• Contrat de référence d'asset dans l'IR : étendre specs/ZACUS_RUNTIME_3_SPEC.md (comment un step/scene référence un asset par id, résolu au déploiement).
• Décision stockage : budget LittleFS 5 Mo vs SD/NFS — politique « quel asset va où ».
• Livrable : specs/ZACUS_ASSET_SPEC.md.
• Dépend de : rien. Bloque tout le reste.

Phase 1 — Génération de TEXTE via ailiance (web-only, risque nul)

• Gateway : POST /v1/assets/text/generate (proxy gateway.ailiance.fr/v1/chat/completions, modèle paramétrable, prompts templatés : réplique NPC, indice progressif, texte d'écran, variation de scénario). Auth ailiance à câbler (clé en settings).
• Atelier : panneau « Générer » — sélection du type, contexte (puzzle/scène courant), aperçu, insertion dans npc_phrases.yaml / hints_adaptive.yaml / le bloc scene.
• Livrable : éditeur+générateur de texte opérationnel sur zacus.saillant.cc/atelier.
• Dépend de : Phase 0 (modèle d'asset minimal).

Phase 2 — Pipeline AUDIO (web wiring + file async)

• Gateway : file de tâches async (génération > 20 s) + POST /v1/assets/audio/generate (TTS F5 via voice-bridge :8200 ; ambiances AudioCraft), GET /v1/assets/audio/{id}/status, GET /v1/_staged/{key} (preview).
• Atelier : panneau Audio — lister (manifest), prévisualiser (lecteur), (re)générer une réplique/ambiance, voir le statut.
• Déploiement : staging dans hotline_tts/ (LittleFS) via le flux flash existant.
• Dépend de : Phase 0, Phase 1 (UI panneau), file async (commune).

Phase 3 — Éditeur ÉCRAN (web maintenant ; image = firmware plus tard)

• 3a (web) : éditeur de scène dans l'atelier — title/subtitle/symbol/effect avec aperçu fidèle du rendu LCD (limites de caractères, symboles, effets). Génération de textes d'écran via ailiance.
• 3b (firmware, hardware) : support image à l'écran — décodage PNG/RGB565 dans display_ui (LovyanGFX), lecture depuis LittleFS picture/, budget partition. Nécessite la carte + tests. À planifier séparément.
• Dépend de : Phase 0 ; 3b dépend de Phase 4 si les images dépassent 5 Mo.

Phase 4 — Stockage SD / NFS (firmware lourd, hardware, RISQUE ÉLEVÉ)

• Firmware : montage carte SD (SDMMC/SPI) + client NFS optionnel au boot ; structure /sd/zacus/{board_id}/ ; fallback LittleFS ; endpoint POST /assets/sync (pull depuis gateway).
• Partitions : revoir partitions.csv (la SD soulage le plafond 5 Mo).
• Gateway : POST /v1/assets/stage produit un bundle SD/NFS par board ; sync.
• Tests : sur carte réelle uniquement.
• Dépend de : Phase 0 (contrat), accès hardware. C'est le gros morceau — à ne lancer qu'avec la carte et du temps de test.

Phase 5 — Atelier « Assets » unifié + montage web (intégration)

• Workspace Assets cohérent (onglets texte/audio/image/data), manifest versionné visible, rollback.
• Flux de déploiement : choisir quels assets vont sur quel board, par quel canal (hot/cold/SD/relay).
• Multi-board : assets board-spécifiques (aujourd'hui un seul /littlefs/scenario.json master).
• Dépend de : Phases 1–4.

5. Dépendances (résumé)

P0 (contrats) ─┬─> P1 (texte/ailiance) ─┐
               ├─> P2 (audio) ──────────┼─> P5 (atelier unifié)
               ├─> P3a (écran web) ─────┤
               └─> P4 (SD/NFS firmware) ┴─> P3b (image écran)

• Chemin web sans firmware : P0 → P1 → P2 → P3a → P5 (livrable, faible risque).
• Chemin firmware/hardware : P4 (+P3b) — à mener en parallèle quand la carte est dispo.

6. Risques & points durs

1. Firmware SD/NFS (P4) : nécessite hardware, tests, possible révision partitions/boot. Risque élevé. Ne pas bloquer le web dessus.
2. Plafond LittleFS 5 Mo : tant que P4 n'est pas là, les assets audio/image embarqués sont contraints. Politique de budget à définir en P0.
3. Génération async : OpenAI/AudioCraft/F5 peuvent dépasser le timeout gateway (20 s). File de tâches obligatoire dès P2.
4. gateway.ailiance.fr : LLM texte uniquement ; auth (clé) à câbler ; pas d'images/audio — ne pas surpromettre.
5. Pas de versioning d'assets aujourd'hui : à introduire en P0 (manifest + hash) sinon rollback impossible.
6. Images à l'écran (3b) : le firmware ne sait pas afficher d'image — c'est un développement, pas un branchement.

7. Décisions ouvertes (à trancher avant P1)

• Où stockent les assets générés ? Repo game//audio//assets/ (versionné git) vs store gateway (share-store-like) vs les deux ?
• Clé/accès gateway.ailiance.fr : quelle auth, quel(s) modèle(s) par type de texte ?
• SD vs NFS : carte SD locale (simple, robuste terrain) ou NFS (centralisé, besoin réseau fiable) — ou les deux avec fallback ?
• Périmètre P1 : quels types de texte en priorité (dialogues NPC ? indices ? textes d'écran ?).

8. Recommandation de séquencement

1. P0 (contrat asset + spec) — court, débloque tout.
2. P1 (texte/ailiance) — première valeur visible, zéro risque firmware.
3. P2 (audio) puis P3a (écran web).
4. P4/P3b (SD/NFS + image) — bloc firmware séparé, quand la carte et le temps de test sont là.
5. P5 (unification) — quand les briques existent.

---

Réf. : audit pipeline d'assets 2026-06-13 ; specs/ZACUS_RUNTIME_3_SPEC.md ; tools/zacus-gateway/main.py ; ESP32_ZACUS/idf_zacus/{partitions.csv,components/{display_ui,media_manager,game_endpoint}} ; tools/{tts,audio,printables}/. Voir aussi la barre de menu Atelier (PR #125).