narractive 2.0.0__py3-none-any.whl

narractive-2.0.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: narractive
+Version: 2.0.0
+Summary: Modular framework for automating desktop application demo video production
+Author: Simon Ducorneau
+License: MIT
+Project-URL: Homepage, https://github.com/imagodata/narractive
+Project-URL: Repository, https://github.com/imagodata/narractive
+Keywords: video,automation,pyautogui,obs,tts,ffmpeg,demo,screencast,narractive
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: Pillow>=10.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.1
+Requires-Dist: edge-tts>=6.1.0
+Requires-Dist: mutagen>=1.47.0
+Provides-Extra: obs
+Requires-Dist: obsws-python>=1.7.0; extra == "obs"
+Provides-Extra: windows
+Requires-Dist: pywin32>=306; extra == "windows"
+Provides-Extra: png
+Requires-Dist: playwright>=1.40; extra == "png"
+Provides-Extra: elevenlabs
+Requires-Dist: elevenlabs; extra == "elevenlabs"
+Provides-Extra: all
+Requires-Dist: obsws-python>=1.7.0; extra == "all"
+Requires-Dist: pywin32>=306; extra == "all"
+Requires-Dist: playwright>=1.40; extra == "all"
+Provides-Extra: headless
+Requires-Dist: python-xlib>=0.33; extra == "headless"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# Narractive
+
+A modular Python framework for automated video production — from narration to final cut.
+
+Narractive orchestrates the full pipeline: UI interaction (PyAutoGUI), screen recording (OBS or headless), text-to-speech narration, Mermaid diagram generation, and FFmpeg assembly. Script your sequences, define narration cues, and let the framework produce polished demo videos hands-free.
+
+## Features
+
+- **Dual recording backends**: OBS WebSocket (desktop) or headless frame capture (Docker/Xvfb)
+- **Multi-engine TTS narration**: edge-tts (free), ElevenLabs (premium), F5-TTS (voice cloning)
+- **Timeline-synchronized sequences**: Narration cues paired with UI actions
+- **Mermaid diagram slides**: HTML + PNG generation with dark theme
+- **FFmpeg post-production**: Clip concatenation, narration mixing, timecode-based assembly
+- **Interactive calibration**: Record UI element positions for pixel-perfect automation
+- **Docker support**: Reproducible headless production in CI/CD
+
+## Quick Start
+
+```bash
+# Install
+pip install -e .
+
+# Copy and configure
+cp config.template.yaml config.yaml
+
+# Calibrate UI positions (interactive)
+video-automation --calibrate --config config.yaml
+
+# Generate narration
+video-automation --narration --narrations-file narrations.yaml
+
+# Generate diagrams
+video-automation --diagrams --diagrams-module my_project.diagrams.mermaid_definitions
+
+# Record all sequences
+video-automation --all --sequences-package my_project.sequences --config config.yaml
+
+# Or headless (Docker)
+docker compose run --rm video --all --sequences-package my_project.sequences
+```
+
+## Architecture
+
+```
+narractive/
+├── video_automation/              # Framework (pip-installable)
+│   ├── core/                      # Generic modules
+│   │   ├── app_automator.py      # PyAutoGUI + window control
+│   │   ├── obs_controller.py     # OBS WebSocket 5.x
+│   │   ├── frame_capturer.py     # Headless Xvfb capture
+│   │   ├── narrator.py           # TTS (edge-tts/ElevenLabs/F5-TTS)
+│   │   ├── timeline.py           # Narration-synchronized cues
+│   │   ├── diagram_generator.py  # Mermaid → HTML/PNG
+│   │   └── video_assembler.py    # FFmpeg post-production
+│   ├── sequences/
+│   │   └── base.py               # VideoSequence + TimelineSequence
+│   ├── scripts/
+│   │   ├── calibrate.py          # Interactive UI calibration
+│   │   └── setup_obs.py          # OBS auto-configuration
+│   └── cli.py                    # Click-based CLI
+│
+├── examples/
+│   └── filtermate/               # Example project (QGIS plugin demo)
+│       ├── sequences/            # 11 original + 7 v01 sequences
+│       ├── diagrams/             # 20 Mermaid diagram definitions
+│       ├── narrations.yaml       # French narration scripts
+│       └── config.yaml           # Calibrated UI positions
+│
+├── config.template.yaml          # Configuration template
+├── Dockerfile                    # Headless Docker image
+├── docker-compose.yml
+└── pyproject.toml
+```
+
+## Creating Sequences for Your App
+
+### 1. Simple sequence (manual timing)
+
+```python
+from video_automation.sequences.base import VideoSequence
+
+class MyIntro(VideoSequence):
+    name = "Introduction"
+    sequence_id = "seq00"
+    duration_estimate = 30.0
+    obs_scene = "Main"
+
+    def execute(self, obs, app, config):
+        app.focus_app()
+        app.click_at("my_button")
+        app.wait(2.0)
+        app.scroll_down(3)
+```
+
+### 2. Timeline sequence (narration-synchronized)
+
+```python
+from video_automation.sequences.base import TimelineSequence
+from video_automation.core.timeline import NarrationCue
+
+class MyDemo(TimelineSequence):
+    name = "Live Demo"
+    sequence_id = "seq01"
+    duration_estimate = 60.0
+
+    def build_timeline(self, obs, app, config):
+        return [
+            NarrationCue(
+                text="Welcome to the demo.",
+                actions=lambda: app.wait(1.0),
+                sync="during",
+            ),
+            NarrationCue(
+                text="Let's open the settings.",
+                actions=lambda: app.click_at("settings_button"),
+                sync="after",
+            ),
+        ]
+```
+
+### 3. Register sequences
+
+Create `my_project/sequences/__init__.py`:
+
+```python
+from video_automation.sequences.base import VideoSequence
+# Import your sequence modules here to register them
+from my_project.sequences.seq00_intro import MyIntro
+from my_project.sequences.seq01_demo import MyDemo
+
+SEQUENCES = [MyIntro, MyDemo]
+```
+
+Then run:
+```bash
+video-automation --list --sequences-package my_project.sequences
+video-automation --all --sequences-package my_project.sequences
+```
+
+## Configuration
+
+See `config.template.yaml` for all available options. Key sections:
+
+| Section | Purpose |
+|---------|---------|
+| `obs` | OBS WebSocket connection, scenes, output directory |
+| `app` | Window title, panel name, calibrated UI positions |
+| `timing` | Click/type/scroll delays, transition pauses |
+| `diagrams` | Mermaid rendering (resolution, theme, colors) |
+| `narration` | TTS engine, voice, speed, F5-TTS options |
+| `capture` | Headless frame capture (FPS, resolution, display) |
+| `output` | Final video encoding (resolution, fps, codec) |
+
+## TTS Engines
+
+| Engine | Cost | Quality | Setup |
+|--------|------|---------|-------|
+| edge-tts | Free | Good | `pip install edge-tts` |
+| ElevenLabs | Paid | Excellent | `pip install elevenlabs` + API key |
+| F5-TTS | Free | Excellent | Conda env + GPU recommended |
+
+## Requirements
+
+- Python 3.10+
+- FFmpeg (for video assembly)
+- OBS Studio (desktop mode) or Docker (headless mode)
+- Your target application installed and running
+
+## License
+
+MIT

narractive-2.0.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+narractive-2.0.0.dist-info/licenses/LICENSE,sha256=tAmFdl5fPmXgRYL0Ini_u5tmNFzYTaG0sz4qvVtY-Ac,1072
+video_automation/__init__.py,sha256=B3X06kMUwnJKZLzWOlUMbbqgJfHVwrLe9twYDPj7VAU,868
+video_automation/__main__.py,sha256=SBDIyIOM65-ulv7-Qd8upXmKM-NBszG2Ph3FPO9ioe8,97
+video_automation/cli.py,sha256=X29d1B1YUP3NGA1GerA-Kd493uEFDFN7BGOK4CAhEL0,21337
+video_automation/bridges/__init__.py,sha256=TViMqxCAOIgg5lrSIW0-xRsD7ZXwUxWPLOkj0SYbGCE,78
+video_automation/bridges/f5_tts_bridge.py,sha256=_P5cvbcLVRj7PajF932THyjnwfxcC1iKtOSFsH36Wnw,5773
+video_automation/core/__init__.py,sha256=7kqaoS-BatVNqvhXPDw7k44Z3K9KW6jkfWT9XqlCZvA,179
+video_automation/core/app_automator.py,sha256=pvC_GO0nHrBZBd__bCMYTuwoN8BhsuHIwkFECfshCug,19568
+video_automation/core/diagram_generator.py,sha256=AswQTeoXNzPnFASLxnkZQEh56rNfIMn0kgvI0IrgYzc,11657
+video_automation/core/frame_capturer.py,sha256=MKLCepsmIO4cYumUIMYJF2mFxWYR0G19jn_lwL9Hm9M,18521
+video_automation/core/narrator.py,sha256=tAX4okIbQpJ8AugD_1gDxtZjq6d4F4cSz7DLn3CgqFo,11391
+video_automation/core/obs_controller.py,sha256=KiNr7tSQd0swvOItaLAd1mbLGJTtAsqGuC_AEPoK-Zk,11451
+video_automation/core/qgis_automator.py,sha256=bbmaNBXt9wLPorSB007SogqIgaH2RXSdUVlZYcEx6sY,254
+video_automation/core/timeline.py,sha256=zSpOl16t6A9wX0Wjif-uT-SHGqv3ZKDdtzZrsYoWHeU,12373
+video_automation/core/video_assembler.py,sha256=p_T4WoXhMXKK9uo8hl4j-7-8NzB0sxq9fr8tYEN83xQ,21069
+video_automation/diagrams/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+video_automation/diagrams/template.html,sha256=PDt4JZHFXzgTcKosh6-vy0p9zpv9WUtFArnudd4wxFY,6886
+video_automation/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+video_automation/scripts/_recal_sidebar.py,sha256=4wzolHK1PgXrS_CQQIHB-RGDFa-oNrfwKL1_T1BQ7JI,1033
+video_automation/scripts/calibrate.py,sha256=xls8ERZUcLIu8UmrGzQXIYoduwEt7zkWSaLuPERDNuI,55747
+video_automation/scripts/setup_obs.py,sha256=QnPeF3VEQThZ_VStdxeyA85aLWgFf4Zx2e_nR6OMCvw,7825
+video_automation/sequences/__init__.py,sha256=CC_7YHzsjYrMpT_HbJRQ0gPhW-ieL6Od6a3v2j2f1tE,487
+video_automation/sequences/base.py,sha256=TC5x5tPWioH6FDF_sgmqLRKuvp2FMHmpA6xw60Wzmu8,8991
+narractive-2.0.0.dist-info/METADATA,sha256=vpl3e6HBhccSUuv78qLnXIvPzcFScF2unkHvnhP4s_0,7603
+narractive-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+narractive-2.0.0.dist-info/entry_points.txt,sha256=LpW9nHnQw7OoExd5Z7x6H2mhx_EXSmvBnL7F4TR5VmM,102
+narractive-2.0.0.dist-info/top_level.txt,sha256=2kpQ9LGATNN5HoEsM7uZa00vCryKB4kgVbokaq3FIsA,17
+narractive-2.0.0.dist-info/RECORD,,

narractive-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

narractive-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+narractive = video_automation.cli:main
+video-automation = video_automation.cli:main

narractive-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Ducorneau
+
+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.

narractive-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+video_automation

video_automation/__init__.py

@@ -0,0 +1,25 @@
+"""
+Video Automation — Desktop Application Video Production Framework
+================================================================
+A modular, reusable framework for automating demo videos of any
+desktop application.
+
+Core modules:
+  - app_automator: PyAutoGUI-based UI control
+  - obs_controller: OBS WebSocket 5.x recording
+  - frame_capturer: Headless Xvfb frame capture (Docker)
+  - narrator: Multi-engine TTS (edge-tts, ElevenLabs, F5-TTS)
+  - timeline: Narration-synchronized cue execution
+  - diagram_generator: Mermaid → HTML/PNG slides
+  - video_assembler: FFmpeg post-production pipeline
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("narractive")
+except PackageNotFoundError:
+    try:
+        __version__ = version("video-automation")
+    except PackageNotFoundError:
+        __version__ = "2.0.0"

video_automation/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m video_automation"""
+from video_automation.cli import main
+
+main()

video_automation/bridges/__init__.py

@@ -0,0 +1 @@
+"""Bridge scripts for external TTS engines (run in separate environments)."""

video_automation/bridges/f5_tts_bridge.py

@@ -0,0 +1,140 @@
+"""
+F5-TTS bridge script — runs inside the f5-tts conda env.
+
+Called as:
+    python f5_tts_bridge.py --ref_audio REF.wav --ref_text "..." \
+        --gen_text "..." --output_file OUT.wav [--speed 1.0] [--model F5TTS_v1_Base] \
+        [--remove_silence]
+
+This avoids importing the full infer_cli module (which has heavy
+module-level imports that can crash on some Windows setups) and uses
+the Python API directly.
+"""
+
+import os
+import sys
+import types
+
+# ---------------------------------------------------------------------------
+# Pre-import mocks for modules that are NOT needed for F5-TTS inference
+# but whose C-extensions crash on some Windows 11 setups (DLL policy / GIL).
+# ---------------------------------------------------------------------------
+
+def _make_mock(name, attrs=()):
+    """Create a stub module with no-op callables and a valid __spec__."""
+    mod = types.ModuleType(name)
+    # torch._dynamo.trace_rules checks __spec__ via importlib.util.find_spec
+    from importlib.machinery import ModuleSpec
+    mod.__spec__ = ModuleSpec(name, None)
+    for a in attrs:
+        setattr(mod, a, lambda *_a, **_kw: None)
+    return mod
+
+# matplotlib — used only for spectrogram visualization
+_noop_attrs = ["figure", "show", "savefig", "plot", "subplot", "close",
+               "clf", "title", "xlabel", "ylabel", "use"]
+_mpl = _make_mock("matplotlib", _noop_attrs)
+_mpl.__path__ = []  # make it look like a package
+sys.modules["matplotlib"] = _mpl
+sys.modules["matplotlib.pylab"] = _make_mock("matplotlib.pylab", _noop_attrs)
+sys.modules["matplotlib.pyplot"] = _make_mock("matplotlib.pyplot", _noop_attrs)
+
+# sklearn / scipy.sparse — pulled in by transformers but not used for TTS inference.
+# On Windows, scipy/sklearn compiled DLLs can be incompatible with numpy versions.
+for _mod_name in (
+    "sklearn", "sklearn.base", "sklearn.utils", "sklearn.utils._chunking",
+    "sklearn.utils._param_validation", "sklearn.utils.validation",
+    "sklearn.utils._array_api", "sklearn.utils.fixes",
+    "sklearn.utils._metadata_requests", "sklearn.utils._estimator_html_repr",
+    "sklearn.metrics", "sklearn.metrics._ranking",
+):
+    sys.modules[_mod_name] = _make_mock(_mod_name)
+
+# Also mock sklearn.metrics.roc_curve since transformers imports it directly
+_mock_metrics = sys.modules["sklearn.metrics"]
+_mock_metrics.roc_curve = lambda *a, **kw: ([], [], [])
+
+# ---------------------------------------------------------------------------
+
+# Patch torchaudio to use soundfile backend instead of torchcodec
+# (torchcodec requires ffmpeg DLLs which are problematic on Windows)
+import torchaudio
+import soundfile as sf
+import torch
+
+def _load_soundfile(filepath, **kwargs):
+    """Load audio using soundfile as fallback for torchaudio.load."""
+    data, samplerate = sf.read(filepath, dtype="float32")
+    # soundfile returns (samples, channels), torch wants (channels, samples)
+    tensor = torch.from_numpy(data)
+    if tensor.ndim == 1:
+        tensor = tensor.unsqueeze(0)
+    else:
+        tensor = tensor.T
+    return tensor, samplerate
+
+torchaudio.load = _load_soundfile
+
+import argparse
+
+
+def main():
+    parser = argparse.ArgumentParser(description="F5-TTS bridge for narration generation")
+    parser.add_argument("--ref_audio", required=True, help="Path to reference audio WAV")
+    parser.add_argument("--ref_text", default="", help="Transcription of reference audio")
+    parser.add_argument("--gen_text", default="", help="Text to synthesize")
+    parser.add_argument("--gen_text_file", default="", help="UTF-8 text file with text to synthesize (overrides --gen_text)")
+    parser.add_argument("--ref_text_file", default="", help="UTF-8 text file with ref transcription (overrides --ref_text)")
+    parser.add_argument("--output_file", required=True, help="Output WAV path")
+    parser.add_argument("--speed", type=float, default=1.0, help="Speech speed multiplier")
+    parser.add_argument("--model", default="F5TTS_v1_Base", help="Model type")
+    parser.add_argument("--remove_silence", action="store_true", help="Remove silence")
+    args = parser.parse_args()
+
+    # Read text from files if provided (avoids Windows CLI encoding issues)
+    gen_text = args.gen_text
+    if args.gen_text_file and os.path.exists(args.gen_text_file):
+        with open(args.gen_text_file, encoding="utf-8") as f:
+            gen_text = f.read().strip()
+
+    ref_text = args.ref_text
+    if args.ref_text_file and os.path.exists(args.ref_text_file):
+        with open(args.ref_text_file, encoding="utf-8") as f:
+            ref_text = f.read().strip()
+
+    if not gen_text:
+        print("ERROR: no gen_text provided (use --gen_text or --gen_text_file)", file=sys.stderr)
+        sys.exit(1)
+
+    from f5_tts.api import F5TTS
+
+    print(f"Loading F5-TTS model: {args.model}", flush=True)
+    tts = F5TTS(model=args.model)
+
+    print(f"Generating: {os.path.basename(args.output_file)}", flush=True)
+    wav, sr, spec = tts.infer(
+        ref_file=args.ref_audio,
+        ref_text=ref_text,
+        gen_text=gen_text,
+        file_wave=args.output_file,
+        speed=args.speed,
+    )
+
+    if args.remove_silence and os.path.exists(args.output_file):
+        try:
+            from f5_tts.infer.utils_infer import remove_silence_for_generated_wav
+            remove_silence_for_generated_wav(args.output_file)
+            print("Silence removed.", flush=True)
+        except Exception as e:
+            print(f"Warning: could not remove silence: {e}", file=sys.stderr)
+
+    if os.path.exists(args.output_file):
+        size = os.path.getsize(args.output_file)
+        print(f"OK: {args.output_file} ({size} bytes)", flush=True)
+    else:
+        print("ERROR: output file not created", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()