Plotagon Director

Génération de films Plotagon Studio Desktop de bout en bout : écriture du scénario en YAML, validation contre la bibliothèque de ressources réelle, génération d'un fichier .plot importable dans l'application officielle — avec voix custom Edge TTS et synchro labiale.

Le format .plot a été entièrement rétro-ingénieré et confirmé par analyse d'exports officiels (v1.11.0) : ZIP contenant un document JSON .plotdoc (liste plate d'instructions scene, dialogue, music, action) et, par réplique vocalisée, un WAV mono 44,1 kHz + un fichier .phonemes (protobuf) pour la synchro labiale. Spécification complète : docs/PLOT_FORMAT.md.

Installation

pip install -e .                 # depuis un clone: commande `plotagon-director`
# ou directement depuis GitHub :
pip install git+https://github.com/mohamed-amine-ben-mallessa/plotagon-director.git

La bibliothèque de ressources (library.json) est embarquée dans le package : le générateur fonctionne sans installation Plotagon. L'extra [library] (pip install -e .[library], ajoute UnityPy) n'est nécessaire que pour reconstruire la bibliothèque depuis une installation Plotagon.

Usage

# Écrire un scénario
plotagon-director new "Mon film"              # squelette commenté
plotagon-director search bureau               # cherche dans toute la bibliothèque
plotagon-director list scenes --filter cafe   # aussi: characters, expressions,
plotagon-director list actions                #   music, sounds, voices
plotagon-director positions restaurants.cafe  # slots d'acteurs d'une scène
plotagon-director voices fr --male            # voix Edge TTS (--female, --filter)
plotagon-director say "Bonjour" fr-FR-DeniseNeural  # écouter une voix
#   list/search/positions/voices/validate acceptent --json

# Valider puis générer
plotagon-director validate mon-film.yaml [--strict] [--json]
plotagon-director preview mon-film.yaml       # durées estimées sans builder
plotagon-director build mon-film.yaml mon-film.plot
#   --no-voices : hors ligne | --srt subs.srt : sous-titres
#   --no-cache : resynthétise tout (sinon cache TTS automatique)
plotagon-director batch scenarios/ sorties/   # tous les .yaml d'un dossier

# Importer mon-film.plot dans Plotagon Studio (menu import)

# Analyse / rétro-ingénierie
plotagon-director parse export.plot           # JSON brut d'un .plot
plotagon-director decompile export.plot film.yaml   # .plot -> YAML éditable
plotagon-director diff avant.plot apres.plot  # isoler un format inconnu
plotagon-director doctor                      # diagnostic environnement

# (Reconstruire la bibliothèque depuis une installation Plotagon)
python -m plotagon_director.library.builder [chemin/builtincontentmanifest.json]

Storyteller : d'une vidéo au film

Pipeline automatisé en 7 étapes : URL vidéo (YouTube, TikTok, Instagram, X — tout ce que yt-dlp supporte), fichier média local ou transcription [MM:SS] → téléchargement (yt-dlp) → transcription horodatée (yapsnap, modèle Kroko local) → parsing → suggestion d'expressions → project.yaml → validation → .plot.

pip install plotagon-director[storyteller]   # ajoute yt-dlp + yapsnap
plotagon-storyteller "https://www.tiktok.com/@x/video/..." --lang fr
plotagon-storyteller transcription.txt --title "Mon pitch" --yaml-only
# alias : plotagon-director storytell ...
# équivalent : python skills/plotagon-storyteller/scripts/transcribe_and_build.py ...

Prérequis : ffmpeg sur le PATH (node recommandé pour YouTube). Le téléchargement passe par l'API yt-dlp in-process avec truststore ( compatible avec les antivirus qui interceptent le TLS). Voix disponibles : docs/VOICES.md. Skill Claude Code dédié : skills/plotagon-storyteller/.

Exemple de scénario

project:
  title: "Conversation au café"

cast:
  - ref: paul
    character: news.paul
    name: "Paul"
    voice: fr-FR-HenriNeural      # optionnel : voix Edge TTS (+ rate/pitch)
  - ref: lucy
    character: news.lucy
    name: "Lucy"
    voice: fr-FR-DeniseNeural

scenes:
  - scene: restaurants.cafe
    music: music.corny            # optionnel (music.stopmusic pour arrêter)
    actors:
      - ref: paul
        position: Table1          # `plotagon-director positions restaurants.cafe`
      - ref: lucy
        position: Table2
    dialogue:
      - actor: paul
        expression: happy
        text: "Bonjour Lucy !"
        camera: wide shot         # optionnel : 10 types (docs/PLOT_FORMAT.md)
      - actor: paul               # interaction à 2 personnages
        action: handshake
        target: lucy

Bibliothèque embarquée : 205 scènes (953 positions), 53 personnages, 88 expressions, 15 actions, 38 musiques, 132 sons.

Architecture

• plotagon_director/core/ — modèle .plotdoc, conteneur ZIP, validateur, décompilateur, diff
• plotagon_director/audio/ — Edge TTS → WAV conforme (cache + parallèle), phonèmes/lip-sync
• plotagon_director/library/ — builder du catalogue + data/library.json
• plotagon_director/storyteller.py — pipeline vidéo/transcription → .plot (plotagon-storyteller)
• docs/ — rétro-ingénierie du format (PLOT_FORMAT.md), API interne de l'appli (APP_JS_ANALYSIS.md), état des connaissances (FINDINGS.md), voix Edge TTS (VOICES.md)
• skills/ — un dossier par skill Claude Code, chacun avec son SKILL.md, ses tests et ses scripts :
  • plotagon-director/ — le skill principal (+ tests du package)
  • plotagon-storyteller/ — pipeline Storyteller (+ scripts/transcribe_and_build.py, tests)
  • plotagon-director-cloud/ — variante claude.ai (sandbox + PyPI, sans voix) ; voir son README.md pour générer le zip d'upload
• projects/ — films d'exemple complets (YAML + sous-titres)
• CHANGELOG.md — historique des versions

Intégration agents IA

Le projet expose plusieurs surfaces pour les agents :

• AGENTS.md (standard Linux Foundation) : instructions repo pour tout agent de code ; llms.txt : plan de la doc pour la découverte web.
• Serveur MCP : pip install plotagon-director[mcp] puis plotagon-director mcp (stdio). Outils : search_library, list_category, scene_positions, list_voices, validate_project, preview_durations, build_film, storytell. Compatible Claude Desktop/Code, Cursor, VS Code, Gemini CLI... Exemple de config client : {"command": "plotagon-director", "args": ["mcp"]}
• API HTTP + OpenAPI : pip install plotagon-director[http] puis plotagon-director serve (docs interactives sur /docs) : /search, /library, /positions, /validate, /preview, /build (renvoie le .plot).
• JSON Schema : plotagon_director/schemas/project.schema.json (aussi servi sur /schema) — validation côté agent avant tout appel.
• Sorties machine : --json sur validate/list/search/positions/voices ; validate --json renvoie les suggestions d'IDs dans un champ structuré.
• Skills packagés : python skills/package.py génère dans dist-skills/ un zip par skill, uploadable sur claude.ai et compatible clients Agent Skills.

Principes

• Aucun mod, aucun binaire tiers, aucun credential.
• Installation officielle en lecture seule.
• Seuls les éléments confirmés par un export officiel sont générés ; le reste (effets visuels, sons importés) est documenté UNKNOWN dans docs/FINDINGS.md.

Tests

python -m pytest -q