Metadata-Version: 2.4
Name: plotagon-director
Version: 0.12.0
Summary: Génération de films Plotagon Studio Desktop (.plot) avec voix Edge TTS et synchro labiale
Author: Mohamed Amine Ben Mallessa
License: MIT
Project-URL: LinkedIn, https://www.linkedin.com/in/benmallessa/
Keywords: plotagon,tts,video,animation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml
Requires-Dist: edge-tts
Requires-Dist: soundfile
Requires-Dist: numpy
Requires-Dist: truststore
Provides-Extra: library
Requires-Dist: UnityPy; extra == "library"
Provides-Extra: storyteller
Requires-Dist: yt-dlp; extra == "storyteller"
Requires-Dist: yapsnap; extra == "storyteller"
Provides-Extra: mcp
Requires-Dist: mcp; extra == "mcp"
Provides-Extra: http
Requires-Dist: fastapi; extra == "http"
Requires-Dist: uvicorn; extra == "http"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: UnityPy; extra == "dev"
Requires-Dist: mcp; extra == "dev"
Requires-Dist: fastapi; extra == "dev"
Requires-Dist: uvicorn; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: jsonschema; extra == "dev"
Dynamic: license-file

# Plotagon Director

Génération de films [Plotagon Studio Desktop](https://www.plotagon.com) 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

```bash
pip install plotagon-director            # depuis PyPI
# extras : [storyteller] video->film | [mcp] serveur MCP | [http] API HTTP
#          [library] reconstruction de la bibliothèque (UnityPy)
pip install "plotagon-director[storyteller,mcp,http]"

# ou depuis un clone :
pip install -e .                         # + pip install -r requirements.txt (tout)
```

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

## Usage

```bash
# É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)

# Personnages custom (créés dans le créateur de Plotagon Studio)
plotagon-director casting add export.plot     # récolte les persos d'un export
plotagon-director casting list [--json]       # registre local (./casting)
#   puis dans le cast du yaml : `custom: Leo` au lieu de `character: ...`
#   (clé racine `casting_dir:` optionnelle ; défaut ./casting, sinon
#   variable PLOTAGON_CASTING_DIR) — voix TTS et synchro labiale incluses

# 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`.

```bash
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

```yaml
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)
    camera: establishing shot     # optionnel : une scène cadre aussi
    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/casting.py` — registre des personnages custom
  (récolte des `.pcd` d'un export, résolution du cast `custom:`)
- `plotagon_director/storyteller.py` — pipeline vidéo/transcription → .plot
  (`plotagon-storyteller`)
- `plotagon_director/cli/` — parseur/dispatch (`main.py`), build+preview
  (`build.py`), exploration bibliothèque (`library_cmds.py`), rapports,
  gabarit `new`
- `plotagon_director/mcp/` / `http/` — serveur MCP
  (`plotagon-director mcp`) et API HTTP (`plotagon-director serve`)
- `plotagon_director/schemas/` — JSON Schema formel du project.yaml
  (embarqué ; `schemas/project.schema.yaml` = version commentée pour humains)
- `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-showrunner/` — créer une SÉRIE : bible (concept, casting,
    relations, world state) → épisodes cohérents (gabarits + exemple
    complet « Flash Info »)
  - `plotagon-casting-designer/` — personnages custom : description →
    recette (catalogue des 592 pièces embarqué) → création automatique en
    lot dans l'appli (injection UI) → récolte `casting add`
  - `plotagon-script-doctor/` — passe de révision d'un film existant
    (rythme, expressions, caméras, punch-up)
  - `plotagon-adaptateur/` — texte (article, thread, nouvelle) → film
    dialogué (complément du storyteller, qui part d'une vidéo)
  - `plotagon-chaine/` — chaîne TV complète : identité, grille de
    plusieurs émissions, habillage, crossovers (orchestre showrunner)
  - `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, casting_add, casting_list. 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

```bash
python -m pytest -q
```
