devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/core/video/browser_recorder.py

@@ -0,0 +1,118 @@
+"""
+Browser recorder — manages Playwright browser for screen recording.
+Opens URLs, executes user actions (click, type, scroll, wait),
+and captures screen recordings at 1920x1080 resolution.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+VALID_ACTION_TYPES = {"click", "type", "wait", "scroll", "hover"}
+
+
+@dataclass
+class BrowserAction:
+    """A single browser interaction."""
+
+    action_type: str
+    selector: Optional[str] = None
+    value: Optional[str] = None
+    delay: float = 0.5
+
+
+class BrowserRecorder:
+    """Records browser sessions using Playwright's native video recording."""
+
+    def __init__(
+        self,
+        output_dir: Path,
+        width: int = 1920,
+        height: int = 1080,
+        slow_mo: int = 200,
+    ):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.width = width
+        self.height = height
+        self.slow_mo = slow_mo
+
+    async def record_step(
+        self,
+        url: str,
+        actions: list[BrowserAction],
+        filename_prefix: str,
+        duration_hint: float = 10.0,
+    ) -> Path:
+        from playwright.async_api import async_playwright
+
+        output_path = self.output_dir / f"{filename_prefix}.webm"
+        logger.info(f"Recording step: {filename_prefix} -> {url}")
+
+        async with async_playwright() as p:
+            browser = await p.chromium.launch(headless=True, slow_mo=self.slow_mo)
+            context = await browser.new_context(
+                viewport={"width": self.width, "height": self.height},
+                record_video_dir=str(self.output_dir),
+                record_video_size={"width": self.width, "height": self.height},
+            )
+            page = await context.new_page()
+            try:
+                await page.goto(url, wait_until="networkidle", timeout=30000)
+                for action in actions:
+                    await self._execute_action(page, action)
+                remaining = max(0, duration_hint - len(actions) * 0.5)
+                if remaining > 0:
+                    await asyncio.sleep(remaining)
+            finally:
+                # Capture video path BEFORE closing context — page.video
+                # becomes invalid after context.close() finalizes the recording.
+                video_path = await page.video.path() if page.video else None
+                await context.close()
+                await browser.close()
+                if video_path and Path(video_path).exists():
+                    Path(video_path).rename(output_path)
+
+        logger.info(f"Step recorded: {output_path}")
+        return output_path
+
+    async def _execute_action(self, page, action: BrowserAction) -> None:
+        try:
+            if action.action_type == "click" and action.selector:
+                await page.click(action.selector, timeout=5000)
+            elif action.action_type == "type" and action.selector and action.value:
+                await page.fill(action.selector, action.value)
+            elif action.action_type == "scroll" and action.selector:
+                await page.evaluate(
+                    f"document.querySelector('{action.selector}')"
+                    f"?.scrollIntoView({{behavior: 'smooth'}})"
+                )
+            elif action.action_type == "hover" and action.selector:
+                await page.hover(action.selector, timeout=5000)
+            elif action.action_type == "wait":
+                await asyncio.sleep(action.delay)
+            if action.action_type != "wait":
+                await asyncio.sleep(action.delay)
+        except Exception as exc:
+            logger.warning(f"Action failed ({action.action_type} {action.selector}): {exc}")
+
+    def parse_actions(self, action_dicts: list[dict]) -> list[BrowserAction]:
+        actions = []
+        for d in action_dicts:
+            action_type = d.get("type", "")
+            if action_type not in VALID_ACTION_TYPES:
+                logger.warning(f"Skipping unknown action type: {action_type}")
+                continue
+            actions.append(
+                BrowserAction(
+                    action_type=action_type,
+                    selector=d.get("selector"),
+                    value=d.get("value"),
+                    delay=d.get("delay", 0.5),
+                )
+            )
+        return actions

devrel_origin/core/video/desktop_recorder.py

@@ -0,0 +1,254 @@
+"""
+Desktop recorder — captures desktop app sessions using FFmpeg screen recording
+and PyAutoGUI for mouse/keyboard automation.
+
+Use this when the tutorial target is a native desktop app rather than a browser.
+"""
+
+import asyncio
+import logging
+import platform
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+VALID_DESKTOP_ACTIONS = {"click", "type", "wait", "scroll", "move", "hotkey", "screenshot"}
+
+
+@dataclass
+class DesktopAction:
+    """A single desktop automation action."""
+
+    action_type: str  # "click", "type", "wait", "scroll", "move", "hotkey", "screenshot"
+    x: Optional[int] = None  # screen x coordinate
+    y: Optional[int] = None  # screen y coordinate
+    value: Optional[str] = None  # text to type or hotkey combo (e.g. "command+c")
+    delay: float = 0.5  # seconds to wait after action
+
+
+def _get_ffmpeg_input_format() -> tuple[str, str]:
+    """Return FFmpeg input format and device for the current platform."""
+    system = platform.system()
+    if system == "Darwin":
+        return "avfoundation", "1:none"  # screen:audio — "1" is main display
+    elif system == "Linux":
+        return "x11grab", ":0.0"
+    elif system == "Windows":
+        return "gdigrab", "desktop"
+    raise RuntimeError(f"Unsupported platform for screen recording: {system}")
+
+
+class DesktopRecorder:
+    """Records desktop sessions using FFmpeg screen capture + PyAutoGUI automation."""
+
+    def __init__(
+        self,
+        output_dir: Path,
+        width: int = 1920,
+        height: int = 1080,
+        framerate: int = 30,
+    ):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.width = width
+        self.height = height
+        self.framerate = framerate
+        self._has_ffmpeg = shutil.which("ffmpeg") is not None
+        self._has_pyautogui = self._check_pyautogui()
+
+    @staticmethod
+    def _check_pyautogui() -> bool:
+        try:
+            import pyautogui  # noqa: F401
+
+            return True
+        except ImportError:
+            return False
+
+    async def record_step(
+        self,
+        actions: list[DesktopAction],
+        filename_prefix: str,
+        duration_hint: float = 10.0,
+        app_name: Optional[str] = None,
+    ) -> Path:
+        """Record a desktop step with FFmpeg screen capture.
+
+        Args:
+            actions: List of desktop actions to perform during recording.
+            filename_prefix: Output filename prefix.
+            duration_hint: Minimum recording duration in seconds.
+            app_name: Optional app name to bring to foreground before recording.
+
+        Returns:
+            Path to recorded .mp4 file.
+        """
+        if not self._has_ffmpeg:
+            raise RuntimeError("FFmpeg not found — required for desktop recording")
+
+        output_path = self.output_dir / f"{filename_prefix}.mp4"
+
+        # Bring app to foreground if specified
+        if app_name:
+            await self._activate_app(app_name)
+            await asyncio.sleep(1.0)  # wait for app to come forward
+
+        # Start FFmpeg recording in background
+        ffmpeg_process = await self._start_recording(output_path, duration_hint)
+
+        try:
+            # Wait a moment for recording to begin
+            await asyncio.sleep(0.5)
+
+            # Execute actions
+            for action in actions:
+                await self._execute_action(action)
+
+            # Hold for remaining duration
+            elapsed = sum(a.delay for a in actions) + 0.5
+            remaining = max(0, duration_hint - elapsed)
+            if remaining > 0:
+                await asyncio.sleep(remaining)
+
+        finally:
+            # Stop recording
+            ffmpeg_process.terminate()
+            _stdout, stderr = await ffmpeg_process.communicate()
+            # FFmpeg returns non-zero when terminated mid-encode (rc=255 on SIGTERM
+            # is expected); log only when we have a genuine error code with stderr.
+            if ffmpeg_process.returncode not in (0, -15, 255) and stderr:
+                logger.error(
+                    "Desktop recorder FFmpeg failed (rc=%d). stderr:\n%s",
+                    ffmpeg_process.returncode,
+                    stderr.decode(errors="replace"),
+                )
+
+        logger.info(f"Desktop step recorded: {output_path}")
+        return output_path
+
+    async def _start_recording(
+        self, output_path: Path, duration: float
+    ) -> asyncio.subprocess.Process:
+        """Start FFmpeg screen recording as a background process."""
+        input_format, input_device = _get_ffmpeg_input_format()
+
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-f",
+            input_format,
+        ]
+
+        # Platform-specific options
+        if input_format == "avfoundation":
+            cmd.extend(["-framerate", str(self.framerate)])
+            cmd.extend(["-video_size", f"{self.width}x{self.height}"])
+            cmd.extend(["-capture_cursor", "1"])
+        elif input_format == "x11grab":
+            cmd.extend(["-framerate", str(self.framerate)])
+            cmd.extend(["-video_size", f"{self.width}x{self.height}"])
+        elif input_format == "gdigrab":
+            cmd.extend(["-framerate", str(self.framerate)])
+
+        cmd.extend(["-i", input_device])
+        cmd.extend(["-t", str(duration + 2)])  # extra buffer
+        cmd.extend(["-c:v", "libx264", "-preset", "ultrafast", "-crf", "23"])
+        cmd.extend([str(output_path)])
+
+        logger.info(f"Starting desktop recording: {output_path.name}")
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        return process
+
+    async def _execute_action(self, action: DesktopAction) -> None:
+        """Execute a desktop automation action using PyAutoGUI."""
+        if not self._has_pyautogui:
+            logger.warning("PyAutoGUI not available — skipping action")
+            await asyncio.sleep(action.delay)
+            return
+
+        import pyautogui
+
+        pyautogui.PAUSE = 0.1  # small pause between pyautogui calls
+
+        try:
+            if action.action_type == "click" and action.x is not None and action.y is not None:
+                pyautogui.click(action.x, action.y)
+            elif action.action_type == "type" and action.value:
+                pyautogui.typewrite(action.value, interval=0.05)
+            elif action.action_type == "move" and action.x is not None and action.y is not None:
+                pyautogui.moveTo(action.x, action.y, duration=0.3)
+            elif action.action_type == "scroll":
+                clicks = int(action.value) if action.value else -3
+                pyautogui.scroll(clicks)
+            elif action.action_type == "hotkey" and action.value:
+                keys = action.value.split("+")
+                pyautogui.hotkey(*keys)
+            elif action.action_type == "wait":
+                pass  # delay handled below
+            elif action.action_type == "screenshot":
+                # Take a screenshot (useful for debugging)
+                shot_path = self.output_dir / f"debug_{action.value or 'shot'}.png"
+                pyautogui.screenshot(str(shot_path))
+
+            await asyncio.sleep(action.delay)
+
+        except Exception as exc:
+            logger.warning(f"Desktop action failed ({action.action_type}): {exc}")
+            await asyncio.sleep(action.delay)
+
+    async def _activate_app(self, app_name: str) -> None:
+        """Bring a desktop app to the foreground."""
+        system = platform.system()
+        try:
+            if system == "Darwin":
+                subprocess.run(
+                    ["osascript", "-e", f'tell application "{app_name}" to activate'],
+                    capture_output=True,
+                    timeout=5,
+                )
+            elif system == "Linux":
+                subprocess.run(
+                    ["wmctrl", "-a", app_name],
+                    capture_output=True,
+                    timeout=5,
+                )
+            elif system == "Windows":
+                # PowerShell approach
+                subprocess.run(
+                    [
+                        "powershell",
+                        "-Command",
+                        f"(New-Object -ComObject WScript.Shell).AppActivate('{app_name}')",
+                    ],
+                    capture_output=True,
+                    timeout=5,
+                )
+        except Exception as exc:
+            logger.warning(f"Failed to activate app '{app_name}': {exc}")
+
+    def parse_actions(self, action_dicts: list[dict]) -> list[DesktopAction]:
+        """Convert raw action dicts to DesktopAction objects."""
+        actions = []
+        for d in action_dicts:
+            action_type = d.get("type", "")
+            if action_type not in VALID_DESKTOP_ACTIONS:
+                logger.warning(f"Skipping unknown desktop action type: {action_type}")
+                continue
+            actions.append(
+                DesktopAction(
+                    action_type=action_type,
+                    x=d.get("x"),
+                    y=d.get("y"),
+                    value=d.get("value"),
+                    delay=d.get("delay", 0.5),
+                )
+            )
+        return actions

devrel_origin/core/video/overlay_renderer.py

@@ -0,0 +1,143 @@
+"""
+Overlay renderer — adds visual polish to recorded video segments using FFmpeg.
+Renders: step title bar, callout text boxes, step number indicator.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Hard cap on FFmpeg subprocess wall-clock time (seconds). 5 minutes is
+# generous for normal overlay encoding but stops a stuck encoder from
+# hanging the whole pipeline.
+FFMPEG_TIMEOUT_S = 300
+
+
+async def _communicate_with_timeout(process: asyncio.subprocess.Process):
+    """Run ``process.communicate()`` with a hard timeout; kill on timeout."""
+    try:
+        return await asyncio.wait_for(process.communicate(), timeout=FFMPEG_TIMEOUT_S)
+    except asyncio.TimeoutError as exc:
+        process.kill()
+        await process.wait()
+        raise RuntimeError(
+            f"FFmpeg subprocess timed out after {FFMPEG_TIMEOUT_S}s; killed"
+        ) from exc
+
+
+@dataclass
+class OverlayConfig:
+    font_size: int = 32
+    title_font_size: int = 48
+    font_color: str = "white"
+    bg_color: str = "black@0.7"
+    padding: int = 20
+    title_position: str = "top"
+    callout_position: str = "bottom"
+    title_display_duration: float = 4.0
+    callout_display_duration: float = 0.0
+
+
+class OverlayRenderer:
+    def __init__(self, output_dir: Path, config: Optional[OverlayConfig] = None):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.config = config or OverlayConfig()
+
+    async def render_overlays(
+        self,
+        video_path: Path,
+        title: str,
+        step_number: int,
+        total_steps: int,
+        callout_text: str = "",
+        filename_prefix: str = "overlay",
+    ) -> Path:
+        output_path = self.output_dir / f"{filename_prefix}_overlaid.mp4"
+        filters = []
+        filters.append(self._build_title_filter(title, step_number))
+        filters.append(self._build_step_indicator(step_number, total_steps))
+        if callout_text:
+            filters.append(self._build_callout_filter(callout_text))
+        filter_chain = ",".join(filters)
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-i",
+            str(video_path),
+            "-vf",
+            filter_chain,
+            "-c:v",
+            "libx264",
+            "-preset",
+            "fast",
+            "-crf",
+            "23",
+            "-c:a",
+            "copy",
+            str(output_path),
+        ]
+        logger.info(f"Rendering overlays for {filename_prefix}")
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+        _, stderr = await _communicate_with_timeout(process)
+        if process.returncode != 0:
+            err_text = stderr.decode()
+            logger.error(f"FFmpeg overlay failed: {err_text[:500]}")
+            raise RuntimeError(f"FFmpeg overlay rendering failed: {err_text[:200]}")
+        logger.info(f"Overlays rendered: {output_path}")
+        return output_path
+
+    def _build_title_filter(self, title: str, step_number: int) -> str:
+        escaped = self._escape_ffmpeg_text(f"Step {step_number}: {title}")
+        c = self.config
+        y_pos = str(c.padding) if c.title_position == "top" else f"h-th-{c.padding}"
+        return (
+            f"drawtext=text='{escaped}'"
+            f":fontsize={c.title_font_size}"
+            f":fontcolor={c.font_color}"
+            f":box=1:boxcolor={c.bg_color}:boxborderw={c.padding}"
+            f":x=(w-tw)/2:y={y_pos}"
+            f":enable='between(t,0,{c.title_display_duration})'"
+        )
+
+    def _build_callout_filter(self, text: str) -> str:
+        escaped = self._escape_ffmpeg_text(text)
+        c = self.config
+        y_pos = f"h-th-{c.padding * 3}" if c.callout_position == "bottom" else str(c.padding * 3)
+        duration_clause = ""
+        if c.callout_display_duration > 0:
+            duration_clause = f":enable='between(t,1,{c.callout_display_duration + 1})'"
+        return (
+            f"drawtext=text='{escaped}'"
+            f":fontsize={c.font_size}"
+            f":fontcolor={c.font_color}"
+            f":font=monospace"
+            f":box=1:boxcolor={c.bg_color}:boxborderw={c.padding}"
+            f":x={c.padding * 2}:y={y_pos}"
+            f"{duration_clause}"
+        )
+
+    def _build_step_indicator(self, step_number: int, total_steps: int) -> str:
+        c = self.config
+        return (
+            f"drawtext=text='{step_number}/{total_steps}'"
+            f":fontsize={c.font_size}"
+            f":fontcolor={c.font_color}"
+            f":box=1:boxcolor={c.bg_color}:boxborderw=10"
+            f":x=w-tw-{c.padding}:y={c.padding}"
+        )
+
+    @staticmethod
+    def _escape_ffmpeg_text(text: str) -> str:
+        text = text.replace("\\", "\\\\")
+        text = text.replace("'", "'\\''")
+        text = text.replace(":", "\\:")
+        text = text.replace("%", "%%")
+        text = text.replace("\n", " ")
+        return text

devrel_origin/core/video/script_parser.py

@@ -0,0 +1,147 @@
+"""
+ScriptParser — Converts markdown scripts and task strings into
+structured TutorialStep sequences for video generation.
+"""
+
+import logging
+import re
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+# --- Regex patterns ---
+STEP_HEADING_RE = re.compile(r"^##\s+(?:Step\s+\d+[:\s]*)?(.+)$", re.MULTILINE)
+CODE_BLOCK_RE = re.compile(r"```[\s\S]*?```")
+
+# Headings to skip (lowercased for comparison)
+SKIP_HEADINGS = {
+    "prerequisites",
+    "introduction",
+    "overview",
+    "conclusion",
+    "summary",
+    "next steps",
+}
+
+
+@dataclass
+class TutorialStep:
+    """A single step in a video tutorial."""
+
+    step_number: int
+    title: str
+    narration: str
+    url: str
+    actions: list[dict] = field(default_factory=list)
+    overlay_text: str = ""
+    duration_hint: float = 5.0
+
+
+@dataclass
+class VideoTutorial:
+    """A complete video tutorial definition."""
+
+    title: str
+    steps: list[TutorialStep]
+    output_path: str
+    source: str
+    resolution: tuple[int, int] = (1920, 1080)
+    total_duration: float = 0.0
+
+
+class ScriptParser:
+    """Parses markdown scripts and task strings into TutorialStep sequences."""
+
+    def parse_markdown(
+        self, markdown: str, base_url: str = "https://example.com"
+    ) -> list[TutorialStep]:
+        """Split markdown by ## headings into TutorialSteps.
+
+        Skips prerequisite/conclusion sections. Extracts narration
+        (stripped of code blocks) and overlay text from first code block.
+        """
+        sections = self._split_by_headings(markdown)
+        steps: list[TutorialStep] = []
+        step_number = 1
+
+        for title, body in sections:
+            # Skip non-content sections
+            if title.strip().lower() in SKIP_HEADINGS:
+                continue
+
+            narration = self._extract_narration(body)
+            if not narration.strip():
+                continue
+
+            overlay = self._extract_first_code(body)
+            duration = max(5.0, len(narration) / 15)
+
+            steps.append(
+                TutorialStep(
+                    step_number=step_number,
+                    title=title.strip(),
+                    narration=narration,
+                    url=base_url,
+                    overlay_text=overlay,
+                    duration_hint=round(duration, 1),
+                )
+            )
+            step_number += 1
+
+        return steps
+
+    def parse_task(self, task: str, base_url: str = "https://example.com") -> list[TutorialStep]:
+        """Create a single TutorialStep from a task string."""
+        narration = self._extract_narration(task)
+        duration = max(5.0, len(narration) / 15)
+
+        return [
+            TutorialStep(
+                step_number=1,
+                title=task[:80].strip(),
+                narration=narration,
+                url=base_url,
+                duration_hint=round(duration, 1),
+            )
+        ]
+
+    def _split_by_headings(self, markdown: str) -> list[tuple[str, str]]:
+        """Split markdown into (heading, body) tuples by ## headings."""
+        matches = list(STEP_HEADING_RE.finditer(markdown))
+        if not matches:
+            return []
+
+        sections: list[tuple[str, str]] = []
+        for i, match in enumerate(matches):
+            title = match.group(1)
+            start = match.end()
+            end = matches[i + 1].start() if i + 1 < len(matches) else len(markdown)
+            body = markdown[start:end]
+            sections.append((title, body))
+
+        return sections
+
+    def _extract_narration(self, text: str) -> str:
+        """Remove code blocks, markdown links, bold/italic, collapse whitespace."""
+        # Remove code blocks
+        cleaned = CODE_BLOCK_RE.sub("", text)
+        # Remove markdown links: [text](url) → text
+        cleaned = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", cleaned)
+        # Remove bold and italic markers
+        cleaned = re.sub(r"\*{1,2}([^*]+)\*{1,2}", r"\1", cleaned)
+        cleaned = re.sub(r"_{1,2}([^_]+)_{1,2}", r"\1", cleaned)
+        # Collapse whitespace
+        cleaned = re.sub(r"\s+", " ", cleaned).strip()
+        return cleaned
+
+    def _extract_first_code(self, text: str) -> str:
+        """Extract content of the first code block, truncated to 5 lines."""
+        match = re.search(r"```(?:\w*\n)?([\s\S]*?)```", text)
+        if not match:
+            return ""
+        code = match.group(1).strip()
+        lines = code.splitlines()
+        if len(lines) > 5:
+            lines = lines[:5]
+            lines.append("...")
+        return "\n".join(lines)