protoreel 0.1.0__py3-none-any.whl

protoreel/__init__.py

@@ -0,0 +1,4 @@
+"""Protoreel: turn HTML prototypes into frame-perfect social videos."""
+
+__version__ = "0.1.0"
+HOMEPAGE = "https://github.com/iamkingsleey/protoreel"

protoreel/__main__.py

@@ -0,0 +1,5 @@
+"""Allows `python -m protoreel ...`."""
+
+from .cli import main
+
+main()

protoreel/audio.py

@@ -0,0 +1,29 @@
+"""Prototype sound.
+
+Browsers will not let headless Chromium record its own audio output, so prototypes
+that make sound can opt in by exposing one function:
+
+    window.__recorderAudio(startMs, durationMs) -> base64 WAV (or a Promise of one)
+
+It should render the sounds that played between `startMs` and `startMs + durationMs`
+on the page's clock (for example by replaying a log of sound events into an
+OfflineAudioContext). Protoreel calls it once after the last frame and lays the WAV
+under the video. Pages without the function simply produce a silent video.
+"""
+
+from __future__ import annotations
+
+import base64
+
+
+async def page_soundtrack(page, start_ms: float, duration_ms: float) -> tuple[bytes | None, str]:
+    """Ask the page for its soundtrack. Returns (wav bytes or None, status message)."""
+    try:
+        if not await page.evaluate("typeof window.__recorderAudio === 'function'"):
+            return None, "none"
+        encoded = await page.evaluate("([s, d]) => window.__recorderAudio(s, d)", [start_ms, duration_ms])
+        if not encoded:
+            return None, "empty"
+        return base64.b64decode(encoded), "added"
+    except Exception as error:
+        return None, f"failed: {error}"

protoreel/browser.py

@@ -0,0 +1,37 @@
+"""Headless Chromium via Playwright, installing it on first use if needed."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+INSTALL_HINT = "Run `protoreel setup` (or `python -m playwright install chromium`) and try again."
+
+
+def install_chromium(quiet: bool = False) -> None:
+    """Download Playwright's Chromium (about 150 MB, once per machine)."""
+    subprocess.run(
+        [sys.executable, "-m", "playwright", "install", "chromium"],
+        check=True,
+        stdout=subprocess.DEVNULL if quiet else None,
+        stderr=subprocess.STDOUT if quiet else None,
+    )
+
+
+async def launch(playwright):
+    """Launch Chromium. If the browser has not been downloaded yet, download it once and retry.
+
+    Set PROTOREEL_CHROMIUM to use a Chromium/Chrome binary you already have.
+    """
+    executable = os.environ.get("PROTOREEL_CHROMIUM") or None
+    try:
+        return await playwright.chromium.launch(executable_path=executable)
+    except Exception as error:
+        if executable or "Executable doesn't exist" not in str(error):
+            raise
+    try:
+        install_chromium(quiet=True)
+    except Exception as error:
+        raise RuntimeError(f"Chromium is not installed and could not be downloaded. {INSTALL_HINT}") from error
+    return await playwright.chromium.launch()

protoreel/cli.py

@@ -0,0 +1,176 @@
+"""Command line: `protoreel <command>`.
+
+protoreel studio                 open the Studio (capture takes by hand, render them)
+protoreel record PAGE SCRIPT     film a scripted interaction
+protoreel render-take TAKE       film a take captured in the Studio
+protoreel mcp                    run the MCP server (your AI client starts this for you)
+protoreel setup                  download Chromium and print MCP client config
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import shutil
+import sys
+from pathlib import Path
+
+from . import __version__
+from .browser import install_chromium
+from .encoder import find_ffmpeg
+from .renderer import RenderOptions, output_path, render
+from .settings import DEFAULT_FORMAT, DEFAULT_FPS, DEFAULT_RESOLUTION, DEFAULT_ZOOM, FORMATS, RESOLUTIONS
+from .takes import Take
+from .workspace import Workspace
+
+
+def _add_folder(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--folder", help="workspace folder (default: $PROTOREEL_HOME or ~/Protoreel)")
+
+
+def _add_video_options(parser: argparse.ArgumentParser, format_default: str | None = DEFAULT_FORMAT) -> None:
+    parser.add_argument("--format", choices=list(FORMATS), default=format_default, help="video shape")
+    parser.add_argument(
+        "--zoom",
+        type=float,
+        default=None if format_default is None else DEFAULT_ZOOM,
+        help="0.6–3.6; higher makes the prototype bigger in frame",
+    )
+    parser.add_argument("--res", choices=list(RESOLUTIONS), default=DEFAULT_RESOLUTION, help="export resolution")
+    parser.add_argument("--fps", type=int, choices=(30, 60), default=DEFAULT_FPS)
+    parser.add_argument("--no-cursor", action="store_true", help="hide the on-screen pointer")
+    parser.add_argument("--no-sound", action="store_true", help="skip the prototype's own sound")
+    parser.add_argument("--bg", help="background colour behind the page, e.g. '#ffffff'")
+    parser.add_argument("--caption", help="small caption near the bottom of the frame")
+    parser.add_argument("--out", help="output file name (saved in renders/)")
+
+
+def _options(args, fmt: str, zoom: float) -> RenderOptions:
+    return RenderOptions(
+        format=fmt,
+        zoom=zoom,
+        resolution=args.res,
+        fps=args.fps,
+        cursor=not args.no_cursor,
+        sound=not args.no_sound,
+        background=args.bg,
+        caption=args.caption,
+    )
+
+
+def _progress(done: int, total: int | None) -> None:
+    if done % 10 == 0 or done == total:
+        text = f"  frame {done}" + (f" of {total}" if total else "")
+        print(f"\r{text}", end="", file=sys.stderr, flush=True)
+
+
+# ---------------------------------------------------------------- commands
+def cmd_studio(args) -> None:
+    from .studio.server import Studio
+
+    studio = Studio(Workspace.open(args.folder), args.port)
+    try:
+        studio.start()
+    except OSError:
+        print(f"The Studio is already running at {studio.url}")
+        if not args.no_browser:
+            studio.open_in_browser()
+        return
+    print(f"Protoreel Studio is running at {studio.url}  (workspace: {studio.workspace.folder})")
+    print("Press Ctrl+C or Quit in the app to stop.")
+    if not args.no_browser:
+        studio.open_in_browser()
+    studio.serve_forever()
+
+
+def cmd_record(args) -> None:
+    workspace = Workspace.open(args.folder)
+    page = args.page if args.page.startswith(("http://", "https://")) else workspace.find_prototype(args.page)
+    script = json.loads(Path(args.script).read_text(encoding="utf-8"))
+    options = _options(args, args.format, args.zoom)
+    out = output_path(workspace.renders, str(page), options, args.out)
+    result = asyncio.run(render(page, script, options, out, _progress))
+    print(f"\nSaved {result.summary()}\n{result.path}")
+
+
+def cmd_render_take(args) -> None:
+    workspace = Workspace.open(args.folder)
+    take = Take.load(workspace.find_take(args.take))
+    options = _options(args, args.format or take.format, args.zoom or take.zoom)
+    page = workspace.find_prototype(take.page)
+    out = output_path(workspace.renders, page.name, options, args.out)
+    result = asyncio.run(render(page, take, options, out, _progress))
+    print(f"\nSaved {result.summary()}\n{result.path}")
+
+
+def cmd_mcp(args) -> None:
+    from .mcp_server import run
+
+    run(args.folder, args.studio_port)
+
+
+def cmd_setup(args) -> None:
+    print(f"Protoreel {__version__}")
+    print(f"ffmpeg:   {find_ffmpeg()}")
+    print("Chromium: downloading if needed…")
+    install_chromium()
+    folder = str(Workspace.open(args.folder).folder)
+    print(f"Workspace: {folder}\n")
+    print(client_config(folder))
+
+
+def client_config(folder: str) -> str:
+    """Copy-paste snippets for the common MCP clients."""
+    uvx = shutil.which("uvx") or "uvx"
+    server = {"command": uvx, "args": ["protoreel", "mcp", "--folder", folder]}
+    desktop = json.dumps({"mcpServers": {"protoreel": server}}, indent=2)
+    return (
+        "Claude Desktop / Cowork — add to claude_desktop_config.json:\n" + desktop + "\n\n"
+        f'Claude Code:\n  claude mcp add protoreel -- uvx protoreel mcp --folder "{folder}"\n\n'
+        'Cursor (.cursor/mcp.json) / VS Code (.vscode/mcp.json, key "servers"):\n'
+        + json.dumps({"mcpServers": {"protoreel": server}}, indent=2)
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="protoreel", description="Turn HTML prototypes into social videos.")
+    parser.add_argument("--version", action="version", version=f"protoreel {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    studio = commands.add_parser("studio", help="open the Studio web app")
+    _add_folder(studio)
+    studio.add_argument("--port", type=int, default=8765)
+    studio.add_argument("--no-browser", action="store_true", help="don't open a browser tab")
+    studio.set_defaults(run=cmd_studio)
+
+    record = commands.add_parser("record", help="film a scripted interaction")
+    record.add_argument("page", help="prototype file or http(s) URL")
+    record.add_argument("script", help="JSON script (see examples/)")
+    _add_folder(record)
+    _add_video_options(record)
+    record.set_defaults(run=cmd_record)
+
+    take = commands.add_parser("render-take", help="film a take captured in the Studio")
+    take.add_argument("take", help="take file name in takes/ or a path")
+    _add_folder(take)
+    _add_video_options(take, format_default=None)
+    take.set_defaults(run=cmd_render_take)
+
+    mcp = commands.add_parser("mcp", help="run the MCP server over stdio")
+    _add_folder(mcp)
+    mcp.add_argument("--studio-port", type=int, default=8765)
+    mcp.set_defaults(run=cmd_mcp)
+
+    setup = commands.add_parser("setup", help="install Chromium and print client config")
+    _add_folder(setup)
+    setup.set_defaults(run=cmd_setup)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    try:
+        args.run(args)
+    except (FileNotFoundError, ValueError) as error:
+        sys.exit(f"protoreel: {error}")

protoreel/encoder.py

@@ -0,0 +1,127 @@
+"""Video encoding with ffmpeg.
+
+Frames arrive as PNG bytes and are piped straight into ffmpeg, which writes an H.264
+MP4 that plays everywhere (yuv420p, +faststart). If ffmpeg is not installed, the copy
+bundled with the `imageio-ffmpeg` package is used, so no separate install is needed.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .settings import VIDEO_CRF
+
+
+def find_ffmpeg() -> str:
+    """Path to an ffmpeg binary: the system one if present, else the bundled one."""
+    for candidate in (shutil.which("ffmpeg"), "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg"):
+        if candidate and Path(candidate).exists():
+            return candidate
+    try:
+        import imageio_ffmpeg
+
+        return imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception as error:  # pragma: no cover - only when both are missing
+        raise RuntimeError(
+            "ffmpeg was not found. Install it (macOS: brew install ffmpeg) "
+            "or reinstall Protoreel so its bundled copy is available."
+        ) from error
+
+
+class VideoEncoder:
+    """Context manager: `with VideoEncoder(path, fps, w, h) as enc: enc.add_frame(png)`."""
+
+    def __init__(self, out: Path, fps: int, width: int, height: int, crf: int = VIDEO_CRF):
+        self.out = out
+        self._cmd = [
+            find_ffmpeg(),
+            "-v",
+            "error",
+            "-y",
+            "-f",
+            "image2pipe",
+            "-framerate",
+            str(fps),
+            "-c:v",
+            "png",
+            "-i",
+            "-",
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-preset",
+            "medium",
+            "-crf",
+            str(crf),
+            "-vf",
+            f"scale={width}:{height}:flags=lanczos",
+            "-movflags",
+            "+faststart",
+            str(out),
+        ]
+        self._process: subprocess.Popen | None = None
+
+    def __enter__(self) -> VideoEncoder:
+        self.out.parent.mkdir(parents=True, exist_ok=True)
+        self._process = subprocess.Popen(self._cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+        return self
+
+    def add_frame(self, png: bytes) -> None:
+        assert self._process and self._process.stdin
+        self._process.stdin.write(png)
+
+    def __exit__(self, exc_type, *rest) -> None:
+        assert self._process and self._process.stdin
+        self._process.stdin.close()
+        stderr = self._process.stderr.read().decode(errors="replace") if self._process.stderr else ""
+        code = self._process.wait()
+        if code != 0 and exc_type is None:
+            raise RuntimeError(f"ffmpeg could not encode the video: {stderr.strip()[-400:]}")
+
+
+def add_soundtrack(video: Path, wav: bytes) -> bool:
+    """Lay a WAV soundtrack under a finished video (AAC, trimmed to the video's length)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        sound = Path(tmp) / "sound.wav"
+        sound.write_bytes(wav)
+        muxed = Path(tmp) / f"muxed{video.suffix}"
+        result = subprocess.run(
+            [
+                find_ffmpeg(),
+                "-v",
+                "error",
+                "-y",
+                "-i",
+                str(video),
+                "-i",
+                str(sound),
+                "-map",
+                "0:v:0",
+                "-map",
+                "1:a:0",
+                "-c:v",
+                "copy",
+                "-c:a",
+                "aac",
+                "-b:a",
+                "192k",
+                "-shortest",
+                "-movflags",
+                "+faststart",
+                str(muxed),
+            ]
+        )
+        if result.returncode != 0:
+            return False
+        shutil.move(str(muxed), str(video))
+        return True
+
+
+def has_audio(video: Path) -> bool:
+    """Cheap check used by the renders list: MP4s with sound contain a 'soun' handler box."""
+    with open(video, "rb") as handle:
+        return b"soun" in handle.read(262144)

protoreel/mcp_server.py

@@ -0,0 +1,264 @@
+"""Protoreel as an MCP server, so AI clients (Claude, Cursor, VS Code…) can film prototypes.
+
+Start it with `protoreel mcp --folder ~/Prototypes`. Your MCP client launches this for you
+once it is configured (see README.md); you never need to open a terminal.
+
+Tools
+-----
+list_workspace   what can be recorded, plus recent takes and videos
+record_video     film a prototype by following a script of clicks, drags and typing
+render_take      film a take someone captured by hand in the Studio, in any format
+preview_frame    a single PNG frame, to check framing and zoom before a full render
+open_studio      open the Studio in the browser to capture a take by hand
+check_setup      confirm Chromium and ffmpeg are ready
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from pathlib import Path
+from typing import Any
+
+from mcp.server.mcpserver import Context, Image, MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+
+from . import HOMEPAGE, __version__
+from .browser import install_chromium
+from .encoder import find_ffmpeg, has_audio
+from .renderer import RenderOptions, output_path, render, still
+from .settings import FORMATS, RESOLUTIONS
+from .studio.server import Studio
+from .takes import Take
+from .timeline import __doc__ as SCRIPT_GUIDE
+from .workspace import Workspace
+
+INSTRUCTIONS = f"""Protoreel films HTML prototypes into social-media videos (MP4) with a smooth on-screen cursor.
+
+Typical flow:
+1. list_workspace to see the prototypes (.html files) in the workspace folder.
+2. preview_frame to check framing; raise `zoom` to make the prototype larger in frame.
+3. record_video with a script that performs the interaction. Use CSS selectors from the
+   prototype's HTML so clicks land on the right elements.
+4. Tell the user where the video was saved. To re-cut a hand-made take, use render_take.
+
+Formats: {", ".join(f"{f.key} ({f.use})" for f in FORMATS.values())}.
+Resolutions: {", ".join(RESOLUTIONS)} (same framing, more pixels).
+
+Script format
+{SCRIPT_GUIDE}"""
+
+# Problems the user can fix (a wrong file name, a bad option, a missing selector) are sent
+# back to the AI client as readable messages instead of a generic "tool failed".
+EXPECTED_ERRORS = (FileNotFoundError, ValueError, KeyError, RuntimeError)
+
+
+def user_errors(tool):
+    """Decorator: turn expected errors into ToolErrors with the original message."""
+    if inspect.iscoroutinefunction(tool):
+
+        @functools.wraps(tool)
+        async def run_async(*args, **kwargs):
+            try:
+                return await tool(*args, **kwargs)
+            except EXPECTED_ERRORS as error:
+                raise ToolError(str(error)) from error
+
+        return run_async
+
+    @functools.wraps(tool)
+    def run(*args, **kwargs):
+        try:
+            return tool(*args, **kwargs)
+        except EXPECTED_ERRORS as error:
+            raise ToolError(str(error)) from error
+
+    return run
+
+
+def build_server(workspace: Workspace, studio_port: int = 8765) -> MCPServer:
+    """Create the MCP server for one workspace folder."""
+    server = MCPServer(name="protoreel", version=__version__, instructions=INSTRUCTIONS, website_url=HOMEPAGE)
+    studio = Studio(workspace, studio_port)
+
+    def options_from(
+        fmt: str,
+        zoom: float,
+        resolution: str,
+        fps: int,
+        cursor: bool,
+        sound: bool,
+        background: str | None,
+        caption: str | None,
+    ) -> RenderOptions:
+        options = RenderOptions(
+            format=fmt,
+            zoom=zoom,
+            resolution=resolution,
+            fps=fps,
+            cursor=cursor,
+            sound=sound,
+            background=background or None,
+            caption=caption or None,
+        )
+        options.geometry()  # validates the values early, with a readable message
+        return options
+
+    def progress_reporter(ctx: Context):
+        async def report(done: int, total: int | None):
+            if done % 15 == 0 or done == total:
+                await ctx.report_progress(done, total, f"Filming frame {done}" + (f" of {total}" if total else ""))
+
+        return report
+
+    # ------------------------------------------------------------ tools
+    @server.tool(annotations=ToolAnnotations(read_only_hint=True))
+    @user_errors
+    def list_workspace() -> dict[str, Any]:
+        """List the prototypes that can be recorded, plus recent takes and rendered videos."""
+        renders = workspace.recent(workspace.renders, "*.mp4", 15)
+        return {
+            "folder": str(workspace.folder),
+            "prototypes": [p.name for p in workspace.prototypes()],
+            "takes": [p.name for p in workspace.recent(workspace.takes, "*.json", 15)],
+            "renders": [
+                {"file": str(p), "size_mb": round(p.stat().st_size / 1048576, 1), "sound": has_audio(p)}
+                for p in renders
+            ],
+            "formats": {f.key: f"{f.width}x{f.height} · {f.use}" for f in FORMATS.values()},
+        }
+
+    @server.tool()
+    @user_errors
+    async def record_video(
+        prototype: str,
+        script: dict[str, Any] | str,
+        format: str = "4x5",
+        zoom: float = 2.0,
+        resolution: str = "1080",
+        fps: int = 60,
+        cursor: bool = True,
+        sound: bool = True,
+        background: str | None = None,
+        caption: str | None = None,
+        output_name: str | None = None,
+        ctx: Context | None = None,
+    ) -> str:
+        """Film a prototype following a script, and save an MP4 in the workspace's renders/ folder.
+
+        prototype: file name in the workspace (e.g. "checkout.html"), an absolute path, or an http(s) URL.
+        script: {"start": POINT, "actions": [...]} - see the server instructions for every action.
+          Example: {"actions": [{"wait": 400}, {"click": "#add", "dur": 700}, {"wait": 1200}]}
+        format: 4x5 (feed), 9x16 (reels), 1x1, 16x9, 4x3 or 3x2 (Dribbble).
+        zoom: 0.6-3.6. Higher makes the prototype bigger in frame (default 2).
+        resolution: 1080, 2k, 3k or 4k. background: optional colour behind the page, e.g. "#ffffff".
+        """
+        if isinstance(script, str):
+            script = json.loads(script)
+        options = options_from(format, zoom, resolution, fps, cursor, sound, background, caption)
+        source = prototype if prototype.startswith(("http://", "https://")) else workspace.find_prototype(prototype)
+        out = output_path(workspace.renders, str(source), options, output_name)
+        result = await render(source, script, options, out, progress_reporter(ctx) if ctx else None)
+        return f"Saved {result.path}\n{result.summary()}"
+
+    @server.tool()
+    @user_errors
+    async def render_take(
+        take: str,
+        format: str | None = None,
+        zoom: float | None = None,
+        resolution: str = "1080",
+        fps: int = 60,
+        cursor: bool = True,
+        smooth: bool = True,
+        sound: bool = True,
+        background: str | None = None,
+        caption: str | None = None,
+        ctx: Context | None = None,
+    ) -> str:
+        """Render a take that was captured by hand in the Studio (a .json file in takes/).
+
+        Leave format and zoom empty to match how the take was captured, or pick another
+        format to re-cut the same performance (the motion is re-centred in the new frame).
+        """
+        saved = Take.load(workspace.find_take(take))
+        options = options_from(
+            format or saved.format, zoom or saved.zoom, resolution, fps, cursor, sound, background, caption
+        )
+        options.smooth = smooth
+        prototype = workspace.find_prototype(saved.page)
+        out = output_path(workspace.renders, prototype.name, options)
+        result = await render(prototype, saved, options, out, progress_reporter(ctx) if ctx else None)
+        return f"Saved {result.path}\n{result.summary()}"
+
+    @server.tool(annotations=ToolAnnotations(read_only_hint=True))
+    @user_errors
+    async def preview_frame(
+        prototype: str,
+        format: str = "4x5",
+        zoom: float = 2.0,
+        script: dict[str, Any] | str | None = None,
+        at_ms: float | None = None,
+        background: str | None = None,
+    ) -> Image:
+        """Return one frame as an image, exactly as it would appear in the video.
+
+        Without a script you see the first frame. With a script you see the page after it
+        has played (or after `at_ms` milliseconds of it). Use this to tune zoom and format.
+        """
+        if isinstance(script, str):
+            script = json.loads(script)
+        options = options_from(format, zoom, "1080", 60, True, False, background, None)
+        source = prototype if prototype.startswith(("http://", "https://")) else workspace.find_prototype(prototype)
+        png = await still(source, options, script, at_ms)
+        return Image(data=png, format="png")
+
+    @server.tool()
+    @user_errors
+    def open_studio(prototype: str | None = None) -> str:
+        """Open the Protoreel Studio in the user's browser to capture a take by hand.
+
+        Takes captured there are saved to takes/, so you can render them with render_take.
+        """
+        if prototype:
+            prototype = workspace.find_prototype(prototype).name
+        try:
+            studio.serve_in_background()
+        except OSError:
+            pass  # the port is busy: almost always a Studio that is already running, so just open it
+        return f"The Studio is open at {studio.open_in_browser(prototype)}"
+
+    @server.tool()
+    @user_errors
+    async def check_setup(install_missing: bool = False) -> dict[str, str]:
+        """Check that ffmpeg and Chromium are available. Set install_missing to download Chromium."""
+        report = {"version": __version__, "workspace": str(workspace.folder)}
+        try:
+            report["ffmpeg"] = find_ffmpeg()
+        except RuntimeError as error:
+            report["ffmpeg"] = f"missing: {error}"
+        report["chromium"] = await _chromium_status()
+        if install_missing and report["chromium"] != "ready":
+            install_chromium(quiet=True)
+            report["chromium"] = await _chromium_status()
+        return report
+
+    return server
+
+
+async def _chromium_status() -> str:
+    try:
+        from playwright.async_api import async_playwright
+
+        async with async_playwright() as playwright:
+            path = Path(playwright.chromium.executable_path)
+        return "ready" if path.exists() else "not installed (call check_setup with install_missing=true)"
+    except Exception as error:
+        return f"unavailable: {error}"
+
+
+def run(folder: str | None = None, studio_port: int = 8765) -> None:
+    """Serve over stdio, the transport desktop MCP clients use."""
+    build_server(Workspace.open(folder), studio_port).run("stdio")