figrecipe 0.6.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

figrecipe/_dev/browser/_click_effect.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Click effect visualization for demo recordings.
+
+Shows ripple/pulse animation at click locations to make
+mouse clicks visible in recordings.
+"""
+
+# JavaScript to inject click effect handler
+CLICK_EFFECT_JS = """
+() => {
+    // Add CSS animation if not exists
+    if (!document.getElementById('demo-click-style')) {
+        const style = document.createElement('style');
+        style.id = 'demo-click-style';
+        style.textContent = `
+            @keyframes demo-click-ripple {
+                0% {
+                    transform: translate(-50%, -50%) scale(0);
+                    opacity: 1;
+                }
+                100% {
+                    transform: translate(-50%, -50%) scale(1);
+                    opacity: 0;
+                }
+            }
+            .demo-click-ripple {
+                position: fixed;
+                width: 60px;
+                height: 60px;
+                border: 4px solid #FF4444;
+                border-radius: 50%;
+                pointer-events: none;
+                z-index: 2147483646;
+                animation: demo-click-ripple 0.6s ease-out forwards;
+            }
+        `;
+        document.head.appendChild(style);
+    }
+
+    // Initialize click sound audio element
+    if (!window._demoClickAudio) {
+        window._demoClickAudio = new Audio('/static/audio/click.mp3');
+        window._demoClickAudio.volume = 0.15;
+    }
+
+    // Function to play click sound
+    window._playClickSound = () => {
+        if (window._demoClickAudio) {
+            window._demoClickAudio.currentTime = 0;
+            window._demoClickAudio.play().catch(() => {});
+        }
+    };
+
+    // Remove existing handler if any
+    if (window._demoClickHandler) {
+        document.removeEventListener('mousedown', window._demoClickHandler);
+    }
+
+    // Add click handler
+    window._demoClickHandler = (e) => {
+        // Play click sound
+        if (window._playClickSound) window._playClickSound();
+
+        const ripple = document.createElement('div');
+        ripple.className = 'demo-click-ripple';
+        ripple.style.left = e.clientX + 'px';
+        ripple.style.top = e.clientY + 'px';
+        document.body.appendChild(ripple);
+
+        // Also pulse the cursor if it exists
+        const cursor = document.getElementById('demo-cursor');
+        if (cursor) {
+            cursor.style.transform = 'translate(-50%, -50%) scale(1.3)';
+            setTimeout(() => {
+                cursor.style.transform = 'translate(-50%, -50%) scale(1)';
+            }, 150);
+        }
+
+        // Remove ripple after animation
+        setTimeout(() => ripple.remove(), 600);
+    };
+    document.addEventListener('mousedown', window._demoClickHandler);
+
+    return true;
+}
+"""
+
+REMOVE_CLICK_EFFECT_JS = """
+() => {
+    // Remove handler
+    if (window._demoClickHandler) {
+        document.removeEventListener('mousedown', window._demoClickHandler);
+        delete window._demoClickHandler;
+    }
+    // Remove audio element
+    if (window._demoClickAudio) {
+        window._demoClickAudio.pause();
+        delete window._demoClickAudio;
+    }
+    delete window._playClickSound;
+    // Remove style
+    const style = document.getElementById('demo-click-style');
+    if (style) style.remove();
+    // Remove any remaining ripples
+    document.querySelectorAll('.demo-click-ripple').forEach(el => el.remove());
+    return true;
+}
+"""
+
+
+async def inject_click_effect(page) -> bool:
+    """Inject click ripple effect handler into page.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    return await page.evaluate(CLICK_EFFECT_JS)
+
+
+async def remove_click_effect(page) -> bool:
+    """Remove click effect handler from page.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    return await page.evaluate(REMOVE_CLICK_EFFECT_JS)
+
+
+__all__ = ["inject_click_effect", "remove_click_effect"]
+
+# EOF

figrecipe/_dev/browser/_cursor.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Mouse cursor visualization for demo recordings.
+
+Injects a visible cursor element that follows mouse movements,
+making demos more intuitive when the system cursor isn't captured.
+"""
+
+# JavaScript to inject cursor visualization
+CURSOR_JS = """
+() => {
+    // Remove existing cursor if any
+    const existing = document.getElementById('demo-cursor');
+    if (existing) existing.remove();
+
+    // Create cursor element
+    const cursor = document.createElement('div');
+    cursor.id = 'demo-cursor';
+    cursor.style.cssText = `
+        position: fixed;
+        width: 24px;
+        height: 24px;
+        border: 3px solid #FF4444;
+        border-radius: 50%;
+        pointer-events: none;
+        z-index: 2147483647;
+        box-shadow: 0 0 10px rgba(255, 68, 68, 0.5);
+        transform: translate(-50%, -50%);
+        transition: transform 0.05s ease-out;
+    `;
+    document.body.appendChild(cursor);
+
+    // Create inner dot
+    const dot = document.createElement('div');
+    dot.style.cssText = `
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        width: 6px;
+        height: 6px;
+        background: #FF4444;
+        border-radius: 50%;
+        transform: translate(-50%, -50%);
+    `;
+    cursor.appendChild(dot);
+
+    // Track mouse movement
+    window._demoCursorHandler = (e) => {
+        cursor.style.left = e.clientX + 'px';
+        cursor.style.top = e.clientY + 'px';
+    };
+    document.addEventListener('mousemove', window._demoCursorHandler);
+
+    // Initial position at center
+    cursor.style.left = window.innerWidth / 2 + 'px';
+    cursor.style.top = window.innerHeight / 2 + 'px';
+
+    return true;
+}
+"""
+
+REMOVE_CURSOR_JS = """
+() => {
+    const cursor = document.getElementById('demo-cursor');
+    if (cursor) cursor.remove();
+    if (window._demoCursorHandler) {
+        document.removeEventListener('mousemove', window._demoCursorHandler);
+        delete window._demoCursorHandler;
+    }
+    return true;
+}
+"""
+
+# JavaScript to animate cursor to a position
+MOVE_CURSOR_JS = """
+async (args) => {
+    const { x, y, duration = 500 } = args;
+    const cursor = document.getElementById('demo-cursor');
+    if (!cursor) return false;
+
+    // Get current position
+    const startX = parseFloat(cursor.style.left) || window.innerWidth / 2;
+    const startY = parseFloat(cursor.style.top) || window.innerHeight / 2;
+
+    // Animate to target
+    const startTime = performance.now();
+
+    return new Promise((resolve) => {
+        function animate(currentTime) {
+            const elapsed = currentTime - startTime;
+            const progress = Math.min(elapsed / duration, 1);
+
+            // Ease-out cubic for natural motion
+            const eased = 1 - Math.pow(1 - progress, 3);
+
+            const currentX = startX + (x - startX) * eased;
+            const currentY = startY + (y - startY) * eased;
+
+            cursor.style.left = currentX + 'px';
+            cursor.style.top = currentY + 'px';
+
+            if (progress < 1) {
+                requestAnimationFrame(animate);
+            } else {
+                resolve(true);
+            }
+        }
+        requestAnimationFrame(animate);
+    });
+}
+"""
+
+
+async def inject_cursor(page) -> bool:
+    """Inject visible cursor element into page.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    return await page.evaluate(CURSOR_JS)
+
+
+async def remove_cursor(page) -> bool:
+    """Remove cursor visualization from page.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    return await page.evaluate(REMOVE_CURSOR_JS)
+
+
+async def move_cursor_to(page, x: float, y: float, duration_ms: int = 500) -> bool:
+    """Animate cursor to a specific position.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+    x : float
+        Target X coordinate.
+    y : float
+        Target Y coordinate.
+    duration_ms : int, optional
+        Animation duration in milliseconds (default: 500).
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    args = {"x": x, "y": y, "duration": duration_ms}
+    return await page.evaluate(MOVE_CURSOR_JS, args)
+
+
+async def move_cursor_to_element(page, locator, duration_ms: int = 500) -> bool:
+    """Animate cursor to an element's center.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+    locator : playwright.async_api.Locator
+        Playwright locator for target element.
+    duration_ms : int, optional
+        Animation duration in milliseconds (default: 500).
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    box = await locator.bounding_box()
+    if not box:
+        return False
+    x = box["x"] + box["width"] / 2
+    y = box["y"] + box["height"] / 2
+    return await move_cursor_to(page, x, y, duration_ms)
+
+
+__all__ = ["inject_cursor", "remove_cursor", "move_cursor_to", "move_cursor_to_element"]
+
+# EOF

figrecipe/_dev/browser/_highlight.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Element highlighting for demo recordings.
+
+Highlights elements with colored overlays to draw attention
+during demo recordings. Based on scitex browser debugging patterns.
+"""
+
+# JavaScript for highlighting element
+HIGHLIGHT_JS = """
+async (args) => {
+    const { selector, duration = 1000, color = '#FF4444' } = args;
+
+    // Find element
+    const element = document.querySelector(selector);
+    if (!element) {
+        console.warn('Element not found:', selector);
+        return false;
+    }
+
+    // Scroll into view
+    element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+
+    // Wait for scroll
+    await new Promise(r => setTimeout(r, 300));
+
+    // Get position after scroll
+    const rect = element.getBoundingClientRect();
+
+    // Create highlight overlay
+    const overlay = document.createElement('div');
+    overlay.className = 'demo-highlight';
+    overlay.style.cssText = `
+        position: fixed;
+        top: ${rect.top - 4}px;
+        left: ${rect.left - 4}px;
+        width: ${rect.width + 8}px;
+        height: ${rect.height + 8}px;
+        border: 4px solid ${color};
+        border-radius: 4px;
+        background: ${color}20;
+        pointer-events: none;
+        z-index: 2147483644;
+        box-shadow: 0 0 20px ${color}80;
+        animation: demo-highlight-pulse 0.5s ease-in-out infinite alternate;
+    `;
+
+    // Add animation style if not exists
+    if (!document.getElementById('demo-highlight-style')) {
+        const style = document.createElement('style');
+        style.id = 'demo-highlight-style';
+        style.textContent = `
+            @keyframes demo-highlight-pulse {
+                0% { box-shadow: 0 0 10px ${color}40; }
+                100% { box-shadow: 0 0 25px ${color}80; }
+            }
+        `;
+        document.head.appendChild(style);
+    }
+
+    document.body.appendChild(overlay);
+
+    // Remove after duration
+    setTimeout(() => {
+        overlay.style.transition = 'opacity 0.3s';
+        overlay.style.opacity = '0';
+        setTimeout(() => overlay.remove(), 300);
+    }, duration);
+
+    return true;
+}
+"""
+
+
+async def highlight_element(
+    page,
+    selector: str,
+    duration_ms: int = 1000,
+    color: str = "#FF4444",
+) -> bool:
+    """Highlight an element with colored overlay.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+    selector : str
+        CSS selector for element to highlight.
+    duration_ms : int, optional
+        Duration to show highlight in milliseconds (default: 1000).
+    color : str, optional
+        Highlight color in hex format (default: "#FF4444").
+
+    Returns
+    -------
+    bool
+        True if element was found and highlighted.
+    """
+    args = {"selector": selector, "duration": duration_ms, "color": color}
+    return await page.evaluate(HIGHLIGHT_JS, args)
+
+
+__all__ = ["highlight_element"]
+
+# EOF

figrecipe/_dev/browser/_narration.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Narration processing for demo videos.
+
+Provides utilities to extract captions from demo scripts,
+estimate timing, and add TTS narration with BGM.
+"""
+
+import re
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from ._audio import generate_tts_segments, mix_narration_with_bgm
+
+
+def extract_captions_from_script(script_path: Path) -> List[str]:
+    """Extract caption texts from a demo script.
+
+    Parameters
+    ----------
+    script_path : Path
+        Path to demo Python script.
+
+    Returns
+    -------
+    List[str]
+        List of caption texts in order.
+    """
+    content = script_path.read_text()
+    pattern = r'await\s+self\.caption\s*\(\s*["\']([^"\']+)["\']'
+    return re.findall(pattern, content)
+
+
+def get_video_duration(video_path: Path) -> float:
+    """Get video duration in seconds.
+
+    Parameters
+    ----------
+    video_path : Path
+        Path to video file.
+
+    Returns
+    -------
+    float
+        Duration in seconds.
+    """
+    result = subprocess.run(
+        [
+            "ffprobe",
+            "-v",
+            "error",
+            "-show_entries",
+            "format=duration",
+            "-of",
+            "default=noprint_wrappers=1:nokey=1",
+            str(video_path),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    return float(result.stdout.strip())
+
+
+def estimate_caption_times(
+    captions: List[str],
+    video_duration: float,
+    title_duration: float = 2.5,
+    closing_duration: float = 2.5,
+) -> List[float]:
+    """Estimate caption start times based on video duration.
+
+    Assumes captions are evenly distributed in the content portion
+    (between title and closing screens).
+
+    Parameters
+    ----------
+    captions : List[str]
+        List of caption texts.
+    video_duration : float
+        Total video duration.
+    title_duration : float
+        Title screen duration at start.
+    closing_duration : float
+        Closing screen duration at end.
+
+    Returns
+    -------
+    List[float]
+        Estimated start times for each caption.
+    """
+    content_duration = video_duration - title_duration - closing_duration
+    if len(captions) == 0:
+        return []
+    if len(captions) == 1:
+        return [title_duration + content_duration / 2]
+    interval = content_duration / (len(captions) + 1)
+    return [title_duration + interval * (i + 1) for i in range(len(captions))]
+
+
+def add_narration_to_video(
+    video_path: Path,
+    captions: List[str],
+    output_path: Path,
+    bgm_path: Path,
+    tts_cache_dir: Path,
+    title_text: str = "",
+    bgm_volume: float = 0.08,
+    narration_delay: float = 0.2,
+    fade_in_duration: float = 0.5,
+    fade_out_duration: float = 2.0,
+    verbose: bool = True,
+) -> Tuple[bool, Dict]:
+    """Add TTS narration and BGM to a video.
+
+    Parameters
+    ----------
+    video_path : Path
+        Input video file.
+    captions : List[str]
+        List of caption texts.
+    output_path : Path
+        Output video file path.
+    bgm_path : Path
+        Path to BGM audio file.
+    tts_cache_dir : Path
+        Directory for TTS cache.
+    title_text : str, optional
+        Title narration text (spoken at start).
+    bgm_volume : float, optional
+        BGM volume level (0.0-1.0).
+    narration_delay : float, optional
+        Delay before each narration.
+    fade_in_duration : float, optional
+        BGM fade-in duration.
+    fade_out_duration : float, optional
+        BGM fade-out duration.
+    verbose : bool, optional
+        Print progress messages.
+
+    Returns
+    -------
+    Tuple[bool, Dict]
+        (success, info_dict)
+    """
+    try:
+        duration = get_video_duration(video_path)
+        if verbose:
+            print(f"  Video duration: {duration:.2f}s")
+
+        # Build narrations list
+        narrations = []
+        if title_text:
+            narrations.append(("title", title_text))
+        for i, caption in enumerate(captions):
+            narrations.append((f"caption_{i}", caption))
+
+        if verbose:
+            print(f"  {len(narrations)} narration segments")
+
+        # Estimate timing
+        caption_times = estimate_caption_times(captions, duration)
+        narration_times = [1.0] + caption_times if title_text else caption_times
+
+        # Generate TTS
+        tts_cache_dir.mkdir(parents=True, exist_ok=True)
+        if verbose:
+            print("  Generating TTS...")
+        narration_files = generate_tts_segments(narrations, tts_cache_dir)
+
+        # Mix audio
+        mixed_audio = Path(f"/tmp/narration_mixed_{video_path.stem}.mp3")
+        if verbose:
+            print("  Mixing audio...")
+        mix_narration_with_bgm(
+            narration_files=narration_files,
+            narration_times=narration_times,
+            bgm_path=bgm_path,
+            output_path=mixed_audio,
+            duration=duration,
+            bgm_volume=bgm_volume,
+            narration_delay=narration_delay,
+            fade_in_duration=fade_in_duration,
+            fade_out_duration=fade_out_duration,
+        )
+
+        # Create final video
+        if verbose:
+            print(f"  Creating: {output_path.name}")
+
+        result = subprocess.run(
+            [
+                "ffmpeg",
+                "-y",
+                "-i",
+                str(video_path),
+                "-i",
+                str(mixed_audio),
+                "-c:v",
+                "copy",
+                "-c:a",
+                "aac",
+                "-b:a",
+                "192k",
+                "-shortest",
+                str(output_path),
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        # Cleanup
+        mixed_audio.unlink(missing_ok=True)
+
+        if result.returncode != 0:
+            return False, {"error": result.stderr[:200]}
+
+        return True, {
+            "duration": duration,
+            "captions": len(captions),
+            "output": str(output_path),
+        }
+
+    except Exception as e:
+        import traceback
+
+        return False, {"error": str(e), "traceback": traceback.format_exc()}
+
+
+__all__ = [
+    "extract_captions_from_script",
+    "get_video_duration",
+    "estimate_caption_times",
+    "add_narration_to_video",
+]
+
+# EOF