plotagon-director 0.6.0__tar.gz

plotagon_director-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Amine Ben Mallessa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plotagon_director-0.6.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: plotagon-director
+Version: 0.6.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: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: UnityPy; 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 -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
+
+```bash
+# Écrire un scénario
+plotagon-director new "Mon film"              # squelette commenté
+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                   # voix Edge TTS disponibles
+plotagon-director say "Bonjour" fr-FR-DeniseNeural  # écouter une voix
+
+# Valider puis générer
+plotagon-director validate mon-film.yaml [--strict]
+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]
+```
+
+## 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)
+    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`
+- `docs/` — rétro-ingénierie du format (`PLOT_FORMAT.md`), API interne de
+  l'appli (`APP_JS_ANALYSIS.md`), état des connaissances (`FINDINGS.md`)
+- `SKILL.md` — utilisation comme skill Claude Code
+
+## 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 tests/ -q
+```

plotagon_director-0.6.0/README.md

@@ -0,0 +1,117 @@
+# 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 -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
+
+```bash
+# Écrire un scénario
+plotagon-director new "Mon film"              # squelette commenté
+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                   # voix Edge TTS disponibles
+plotagon-director say "Bonjour" fr-FR-DeniseNeural  # écouter une voix
+
+# Valider puis générer
+plotagon-director validate mon-film.yaml [--strict]
+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]
+```
+
+## 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)
+    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`
+- `docs/` — rétro-ingénierie du format (`PLOT_FORMAT.md`), API interne de
+  l'appli (`APP_JS_ANALYSIS.md`), état des connaissances (`FINDINGS.md`)
+- `SKILL.md` — utilisation comme skill Claude Code
+
+## 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 tests/ -q
+```

plotagon_director-0.6.0/plotagon_director/__init__.py

@@ -0,0 +1,3 @@
+"""plotagon_director — generation de films Plotagon Studio Desktop (.plot)."""
+
+__version__ = "0.6.0"

plotagon_director-0.6.0/plotagon_director/audio/phonemes.py

@@ -0,0 +1,70 @@
+"""Fichiers .phonemes (synchro labiale) au format de Plotagon Studio.
+
+Format CONFIRME par decodage d'un export officiel : messages protobuf
+concatenes, un par trame de 2048 echantillons (~46.4 ms a 44100 Hz) :
+
+    champ 1 (tag 0x0d, float32 LE) : debut en secondes (omis si 0)
+    champ 2 (tag 0x15, float32 LE) : fin en secondes
+    champ 3 (tag 0x1a, string)     : phoneme
+
+Phonemes observes : sil, ae, d, eh, l, m, n, ow, uu, uw.
+"""
+
+import io
+import struct
+import wave
+
+FRAME_SAMPLES = 2048
+
+# Cycle de voyelles pour la synchro labiale approximative (amplitude-based).
+_MOUTH_CYCLE = ["eh", "ae", "ow", "eh", "uw", "ae"]
+
+
+def phonemes_from_wav(wav_bytes):
+    """Synchro labiale approximative par enveloppe d'amplitude.
+
+    L'appli genere les phonemes par analyse du signal ; ici on approxime :
+    trames silencieuses -> "sil", trames parlees -> cycle de voyelles.
+    """
+    import numpy as np
+
+    with wave.open(io.BytesIO(wav_bytes)) as w:
+        rate = w.getframerate()
+        pcm = np.frombuffer(w.readframes(w.getnframes()), dtype="<i2")
+
+    records = []
+    n_frames = max(1, (len(pcm) + FRAME_SAMPLES - 1) // FRAME_SAMPLES)
+    rms = np.array([
+        np.sqrt(np.mean(
+            pcm[i * FRAME_SAMPLES:(i + 1) * FRAME_SAMPLES].astype("f8") ** 2
+        )) if len(pcm[i * FRAME_SAMPLES:(i + 1) * FRAME_SAMPLES]) else 0.0
+        for i in range(n_frames)
+    ])
+    threshold = max(300.0, float(rms.max()) * 0.08)
+
+    mouth = 0
+    for i in range(n_frames):
+        start = i * FRAME_SAMPLES / rate
+        end = min((i + 1) * FRAME_SAMPLES, len(pcm)) / rate
+        if rms[i] >= threshold:
+            label = _MOUTH_CYCLE[(mouth // 2) % len(_MOUTH_CYCLE)]
+            mouth += 1
+        else:
+            label = "sil"
+            mouth = 0
+        records.append((start, end, label))
+    return records
+
+
+def encode_phonemes(records):
+    """Encode les enregistrements au format protobuf observe."""
+    out = bytearray()
+    for start, end, label in records:
+        body = bytearray()
+        if start > 0.0:
+            body += b"\x0d" + struct.pack("<f", start)
+        body += b"\x15" + struct.pack("<f", end)
+        raw = label.encode()
+        body += b"\x1a" + bytes([len(raw)]) + raw
+        out += b"\x0a" + bytes([len(body)]) + body
+    return bytes(out)

plotagon_director-0.6.0/plotagon_director/audio/tts.py

@@ -0,0 +1,163 @@
+"""Synthese vocale Edge TTS au format audio de Plotagon Studio.
+
+Format CONFIRME (export officiel 1.11.0) : WAV PCM mono 44100 Hz 16 bits.
+
+Deux optimisations pour l'iteration rapide :
+- cache disque (%LOCALAPPDATA%/plotagon-director/tts-cache) par hash de
+  (texte, voix, rate, pitch) — un rebuild sans changement ne touche pas
+  au reseau ;
+- synthese parallele (asyncio) pour les films a nombreuses repliques.
+"""
+
+import asyncio
+import hashlib
+import io
+import os
+import wave
+from pathlib import Path
+
+TARGET_RATE = 44100
+CONCURRENCY = 4
+
+CACHE_DIR = (
+    Path(os.environ.get("LOCALAPPDATA", str(Path.home())))
+    / "plotagon-director" / "tts-cache"
+)
+
+
+def _inject_truststore():
+    """Fait utiliser a Python le magasin de certificats Windows.
+
+    Indispensable derriere un antivirus qui intercepte le TLS (ex. Norton).
+    """
+    try:
+        import truststore
+        truststore.inject_into_ssl()
+    except ImportError:
+        pass
+
+
+def _cache_path(text, voice, rate, pitch):
+    key = "%s|%s|%s|%s" % (text, voice, rate or "", pitch or "")
+    return CACHE_DIR / (hashlib.sha256(key.encode("utf-8")).hexdigest() + ".wav")
+
+
+async def _fetch_mp3(text, voice, rate=None, pitch=None):
+    import edge_tts
+
+    kwargs = {}
+    if rate:
+        kwargs["rate"] = rate
+    if pitch:
+        kwargs["pitch"] = pitch
+    communicate = edge_tts.Communicate(text, voice, **kwargs)
+    buf = io.BytesIO()
+    async for chunk in communicate.stream():
+        if chunk["type"] == "audio":
+            buf.write(chunk["data"])
+    return buf.getvalue()
+
+
+def _mp3_to_wav(mp3_bytes):
+    import numpy as np
+    import soundfile as sf
+
+    data, sr = sf.read(io.BytesIO(mp3_bytes), dtype="float32")
+    if data.ndim > 1:
+        data = data.mean(axis=1)
+    if sr != TARGET_RATE:
+        n_out = int(round(len(data) * TARGET_RATE / sr))
+        x_old = np.linspace(0.0, 1.0, num=len(data), endpoint=False)
+        x_new = np.linspace(0.0, 1.0, num=n_out, endpoint=False)
+        data = np.interp(x_new, x_old, data).astype("float32")
+
+    pcm = (np.clip(data, -1.0, 1.0) * 32767).astype("<i2")
+    out = io.BytesIO()
+    with wave.open(out, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(TARGET_RATE)
+        w.writeframes(pcm.tobytes())
+    return out.getvalue()
+
+
+def synthesize_wav(text, voice, rate=None, pitch=None, use_cache=True):
+    """Synthetise une replique et retourne des octets WAV 44.1k mono 16b."""
+    if use_cache:
+        cached = _cache_path(text, voice, rate, pitch)
+        if cached.exists():
+            return cached.read_bytes()
+
+    _inject_truststore()
+    wav = _mp3_to_wav(asyncio.run(_fetch_mp3(text, voice, rate, pitch)))
+
+    if use_cache:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        cached.write_bytes(wav)
+    return wav
+
+
+def synthesize_many(jobs, use_cache=True, progress=None):
+    """Synthetise plusieurs repliques en parallele.
+
+    jobs : liste de dicts {"guid", "text", "voice", "rate", "pitch"}.
+    progress : callback(job, from_cache) appele apres chaque replique.
+    Retourne {guid: wav_bytes}.
+    """
+    results = {}
+    to_fetch = []
+    for job in jobs:
+        cached = _cache_path(job["text"], job["voice"], job.get("rate"), job.get("pitch"))
+        if use_cache and cached.exists():
+            results[job["guid"]] = cached.read_bytes()
+            if progress:
+                progress(job, True)
+        else:
+            to_fetch.append(job)
+
+    if to_fetch:
+        _inject_truststore()
+
+        async def _run_all():
+            sem = asyncio.Semaphore(CONCURRENCY)
+
+            async def _one(job):
+                async with sem:
+                    mp3 = await _fetch_mp3(
+                        job["text"], job["voice"], job.get("rate"), job.get("pitch")
+                    )
+                return job, mp3
+
+            return await asyncio.gather(*(_one(j) for j in to_fetch))
+
+        for job, mp3 in asyncio.run(_run_all()):
+            wav = _mp3_to_wav(mp3)
+            results[job["guid"]] = wav
+            if use_cache:
+                CACHE_DIR.mkdir(parents=True, exist_ok=True)
+                _cache_path(
+                    job["text"], job["voice"], job.get("rate"), job.get("pitch")
+                ).write_bytes(wav)
+            if progress:
+                progress(job, False)
+
+    return results
+
+
+def list_voices(locale_prefix=None):
+    """Liste les voix Edge TTS, filtrees par prefixe de locale (ex. 'fr')."""
+    _inject_truststore()
+    import edge_tts
+
+    voices = asyncio.run(edge_tts.list_voices())
+    if locale_prefix:
+        voices = [
+            v for v in voices
+            if v["Locale"].lower().startswith(locale_prefix.lower())
+        ]
+    return sorted(voices, key=lambda v: v["ShortName"])
+
+
+def wav_duration_ms(wav_bytes):
+    with wave.open(io.BytesIO(wav_bytes)) as w:
+        return int(round(1000.0 * w.getnframes() / w.getframerate()))