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

figrecipe/_dev/browser/__init__.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Browser automation utilities for demo generation.
+
+This module provides tools for creating visual demos of figrecipe features
+using Playwright for browser automation.
+
+Features:
+- Mouse cursor visualization
+- Click effect animations
+- Caption overlays
+- Element highlighting
+- Video/GIF recording
+"""
+
+from ._audio import generate_tts_segments, mix_narration_with_bgm
+from ._caption import hide_caption, show_caption, show_title_screen
+from ._click_effect import inject_click_effect, remove_click_effect
+from ._cursor import (
+    inject_cursor,
+    move_cursor_to,
+    move_cursor_to_element,
+    remove_cursor,
+)
+from ._highlight import highlight_element
+from ._narration import (
+    add_narration_to_video,
+    estimate_caption_times,
+    extract_captions_from_script,
+    get_video_duration,
+)
+from ._recorder import DemoRecorder
+from ._utils import concatenate_videos, convert_to_gif
+from ._video_trim import (
+    detect_markers,
+    inject_end_marker,
+    inject_start_marker,
+    process_video_with_markers,
+    trim_video_by_markers,
+)
+
+__all__ = [
+    "inject_cursor",
+    "remove_cursor",
+    "move_cursor_to",
+    "move_cursor_to_element",
+    "inject_click_effect",
+    "remove_click_effect",
+    "show_caption",
+    "hide_caption",
+    "show_title_screen",
+    "highlight_element",
+    "DemoRecorder",
+    "convert_to_gif",
+    "concatenate_videos",
+    "inject_start_marker",
+    "inject_end_marker",
+    "detect_markers",
+    "trim_video_by_markers",
+    "process_video_with_markers",
+    "generate_tts_segments",
+    "mix_narration_with_bgm",
+    "extract_captions_from_script",
+    "get_video_duration",
+    "estimate_caption_times",
+    "add_narration_to_video",
+]
+
+# EOF

figrecipe/_dev/browser/_audio.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Audio processing for demo videos.
+
+Provides TTS generation and audio mixing for demo narration.
+"""
+
+import hashlib
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import List, Tuple
+
+# Check for ElevenLabs API key
+ELEVENLABS_API_KEY = os.environ.get("ELEVENLABS_API_KEY")
+
+
+def _sanitize_filename(text: str, max_length: int = 50) -> str:
+    """Convert text to a safe filename prefix.
+
+    Parameters
+    ----------
+    text : str
+        Text to convert.
+    max_length : int
+        Maximum length of the result.
+
+    Returns
+    -------
+    str
+        Sanitized filename-safe string.
+    """
+    # Remove special characters, keep alphanumeric and spaces
+    clean = re.sub(r"[^a-zA-Z0-9\s]", "", text)
+    # Replace spaces with underscores
+    clean = re.sub(r"\s+", "_", clean.strip())
+    # Truncate and lowercase
+    return clean[:max_length].lower().rstrip("_")
+
+
+def _get_cache_path(text: str, cache_dir: Path) -> Path:
+    """Get cache file path using transcription-based naming.
+
+    Format: {sanitized_text}_{hash}.mp3
+    Example: enable_dark_mode_demo_a1b2c3d4.mp3
+
+    Parameters
+    ----------
+    text : str
+        Text content for TTS.
+    cache_dir : Path
+        Cache directory.
+
+    Returns
+    -------
+    Path
+        Cache file path.
+    """
+    # Create short hash for uniqueness
+    text_hash = hashlib.md5(text.encode()).hexdigest()[:8]
+    # Sanitize text for filename
+    sanitized = _sanitize_filename(text)
+    # Combine: readable prefix + hash for uniqueness
+    filename = f"{sanitized}_{text_hash}.mp3"
+    return cache_dir / filename
+
+
+def generate_tts_segments(
+    narrations: List[Tuple[str, str]],
+    output_dir: Path,
+) -> List[Path]:
+    """Generate TTS audio files for narrations.
+
+    Uses ElevenLabs if API key is available, falls back to gTTS.
+    Cache files are named using transcription text for easy identification.
+
+    Parameters
+    ----------
+    narrations : List[Tuple[str, str]]
+        List of (name, text) tuples.
+    output_dir : Path
+        Output directory for audio files.
+
+    Returns
+    -------
+    List[Path]
+        List of generated audio file paths.
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    audio_files = []
+
+    if ELEVENLABS_API_KEY:
+        print("Using ElevenLabs TTS (high quality)")
+        try:
+            from elevenlabs import ElevenLabs
+
+            client = ElevenLabs(api_key=ELEVENLABS_API_KEY)
+
+            for name, text in narrations:
+                cache_path = _get_cache_path(text, output_dir)
+
+                # Check cache
+                if cache_path.exists():
+                    print(f"  [cache] {cache_path.name}")
+                    audio_files.append(cache_path)
+                    continue
+
+                # Generate TTS
+                audio = client.text_to_speech.convert(
+                    voice_id="21m00Tcm4TlvDq8ikWAM",  # Rachel
+                    text=text,
+                    model_id="eleven_monolingual_v1",
+                )
+
+                # Save audio
+                with open(cache_path, "wb") as f:
+                    for chunk in audio:
+                        f.write(chunk)
+
+                print(f"  ✓ ElevenLabs: {cache_path.name} - '{text[:40]}...'")
+                audio_files.append(cache_path)
+
+            return audio_files
+
+        except Exception as e:
+            print(f"  ElevenLabs failed: {e}, falling back to gTTS")
+
+    # Fallback to gTTS
+    print("Using gTTS (fallback)")
+    try:
+        from gtts import gTTS
+
+        for name, text in narrations:
+            cache_path = _get_cache_path(text, output_dir)
+
+            # Check cache
+            if cache_path.exists():
+                print(f"  [cache] {cache_path.name}")
+                audio_files.append(cache_path)
+                continue
+
+            # Generate TTS
+            tts = gTTS(text=text, lang="en")
+            tts.save(str(cache_path))
+
+            print(f"  ✓ gTTS: {cache_path.name} - '{text[:40]}...'")
+            audio_files.append(cache_path)
+
+        return audio_files
+
+    except ImportError:
+        raise RuntimeError("Neither ElevenLabs nor gTTS available")
+
+
+def mix_narration_with_bgm(
+    narration_files: List[Path],
+    narration_times: List[float],
+    bgm_path: Path,
+    output_path: Path,
+    duration: float,
+    bgm_volume: float = 0.10,
+    narration_delay: float = 0.3,
+    fade_in_duration: float = 0.5,
+    fade_out_duration: float = 1.0,
+) -> Path:
+    """Mix narration audio with background music.
+
+    Parameters
+    ----------
+    narration_files : List[Path]
+        List of narration audio files.
+    narration_times : List[float]
+        Start times for each narration.
+    bgm_path : Path
+        Path to background music file.
+    output_path : Path
+        Output path for mixed audio.
+    duration : float
+        Total duration in seconds.
+    bgm_volume : float
+        Background music volume (0.0-1.0).
+    narration_delay : float
+        Delay before narration starts.
+    fade_in_duration : float
+        BGM fade-in duration.
+    fade_out_duration : float
+        BGM fade-out duration.
+
+    Returns
+    -------
+    Path
+        Path to mixed audio file.
+    """
+    # Build ffmpeg filter for mixing
+    inputs = ["-i", str(bgm_path)]
+    for f in narration_files:
+        inputs.extend(["-i", str(f)])
+
+    # BGM filter: loop, trim, volume, fade
+    bgm_filter = (
+        f"[0:a]aloop=loop=-1:size=2e+09,atrim=0:{duration},"
+        f"volume={bgm_volume},"
+        f"afade=t=in:st=0:d={fade_in_duration},"
+        f"afade=t=out:st={duration - fade_out_duration}:d={fade_out_duration}[bgm]"
+    )
+
+    # Narration filters with delays
+    narration_filters = []
+    mix_inputs = "[bgm]"
+
+    for i, (f, t) in enumerate(zip(narration_files, narration_times)):
+        delay_ms = int((t + narration_delay) * 1000)
+        narration_filters.append(f"[{i + 1}:a]adelay={delay_ms}|{delay_ms}[n{i}]")
+        mix_inputs += f"[n{i}]"
+
+    # Combine all filters
+    all_filters = [bgm_filter] + narration_filters
+    mix_filter = (
+        f"{mix_inputs}amix=inputs={len(narration_files) + 1}:duration=first[out]"
+    )
+    all_filters.append(mix_filter)
+
+    filter_complex = ";".join(all_filters)
+
+    # Run ffmpeg
+    cmd = (
+        ["ffmpeg", "-y"]
+        + inputs
+        + ["-filter_complex", filter_complex, "-map", "[out]", str(output_path)]
+    )
+
+    subprocess.run(cmd, check=True, capture_output=True)
+
+    return output_path
+
+
+__all__ = ["generate_tts_segments", "mix_narration_with_bgm"]

figrecipe/_dev/browser/_caption.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Caption overlay for demo recordings.
+
+Shows text captions/banners during demo recordings to explain
+what is happening in the demo.
+"""
+
+# JavaScript template for showing caption
+SHOW_CAPTION_JS = """
+(text) => {
+    // Remove existing caption if any
+    const existing = document.getElementById('demo-caption');
+    if (existing) existing.remove();
+
+    // Add CSS if not exists
+    if (!document.getElementById('demo-caption-style')) {
+        const style = document.createElement('style');
+        style.id = 'demo-caption-style';
+        style.textContent = `
+            @keyframes demo-caption-fade-in {
+                0% { opacity: 0; transform: translateY(20px); }
+                100% { opacity: 1; transform: translateY(0); }
+            }
+            @keyframes demo-caption-fade-out {
+                0% { opacity: 1; transform: translateY(0); }
+                100% { opacity: 0; transform: translateY(-20px); }
+            }
+        `;
+        document.head.appendChild(style);
+    }
+
+    // Create caption element
+    const caption = document.createElement('div');
+    caption.id = 'demo-caption';
+    caption.textContent = text;
+    caption.style.cssText = `
+        position: fixed;
+        bottom: 50px;
+        left: 50%;
+        transform: translateX(-50%);
+        background: rgba(0, 0, 0, 0.85);
+        color: white;
+        padding: 18px 40px;
+        border-radius: 10px;
+        font-size: 24px;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        font-weight: 500;
+        box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+        z-index: 2147483645;
+        pointer-events: none;
+        animation: demo-caption-fade-in 0.3s ease-out forwards;
+        max-width: 80%;
+        text-align: center;
+    `;
+    document.body.appendChild(caption);
+
+    return true;
+}
+"""
+
+HIDE_CAPTION_JS = """
+() => {
+    const caption = document.getElementById('demo-caption');
+    if (caption) {
+        caption.style.animation = 'demo-caption-fade-out 0.3s ease-out forwards';
+        setTimeout(() => caption.remove(), 300);
+    }
+    return true;
+}
+"""
+
+# JavaScript for title screen with blur overlay
+TITLE_SCREEN_JS = """
+async (args) => {
+    const { title, subtitle = '', timestamp = '', duration = 2000 } = args;
+
+    // Add CSS animations if not exists
+    if (!document.getElementById('demo-title-style')) {
+        const style = document.createElement('style');
+        style.id = 'demo-title-style';
+        style.textContent = `
+            @keyframes demo-title-fade-in {
+                0% { opacity: 0; }
+                100% { opacity: 1; }
+            }
+            @keyframes demo-title-fade-out {
+                0% { opacity: 1; }
+                100% { opacity: 0; }
+            }
+            @keyframes demo-title-text-in {
+                0% { opacity: 0; transform: scale(0.9); }
+                100% { opacity: 1; transform: scale(1); }
+            }
+        `;
+        document.head.appendChild(style);
+    }
+
+    // Create blur overlay
+    const overlay = document.createElement('div');
+    overlay.id = 'demo-title-overlay';
+    overlay.style.cssText = `
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        background: rgba(0, 0, 0, 0.7);
+        backdrop-filter: blur(8px);
+        -webkit-backdrop-filter: blur(8px);
+        z-index: 2147483646;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        animation: demo-title-fade-in 0.5s ease-out forwards;
+    `;
+
+    // Create title text
+    const titleEl = document.createElement('div');
+    titleEl.style.cssText = `
+        color: white;
+        font-size: 48px;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        font-weight: 700;
+        text-align: center;
+        animation: demo-title-text-in 0.6s ease-out 0.2s both;
+        text-shadow: 0 4px 20px rgba(0, 0, 0, 0.5);
+    `;
+    titleEl.textContent = title;
+    overlay.appendChild(titleEl);
+
+    // Create subtitle if provided
+    if (subtitle) {
+        const subtitleEl = document.createElement('div');
+        subtitleEl.style.cssText = `
+            color: rgba(255, 255, 255, 0.8);
+            font-size: 24px;
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            font-weight: 400;
+            margin-top: 16px;
+            text-align: center;
+            animation: demo-title-text-in 0.6s ease-out 0.4s both;
+        `;
+        subtitleEl.textContent = subtitle;
+        overlay.appendChild(subtitleEl);
+    }
+
+    // Create timestamp if provided
+    if (timestamp) {
+        const timestampEl = document.createElement('div');
+        timestampEl.style.cssText = `
+            color: rgba(255, 255, 255, 0.5);
+            font-size: 14px;
+            font-family: monospace;
+            margin-top: 24px;
+            text-align: center;
+            animation: demo-title-text-in 0.6s ease-out 0.5s both;
+        `;
+        timestampEl.textContent = timestamp;
+        overlay.appendChild(timestampEl);
+    }
+
+    document.body.appendChild(overlay);
+
+    // Wait and fade out
+    await new Promise(r => setTimeout(r, duration));
+
+    overlay.style.animation = 'demo-title-fade-out 0.5s ease-out forwards';
+    await new Promise(r => setTimeout(r, 500));
+    overlay.remove();
+
+    return true;
+}
+"""
+
+
+async def show_caption(page, text: str) -> bool:
+    """Show caption text overlay on page.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+    text : str
+        Caption text to display.
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    return await page.evaluate(SHOW_CAPTION_JS, text)
+
+
+async def hide_caption(page) -> bool:
+    """Hide caption overlay from page.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    return await page.evaluate(HIDE_CAPTION_JS)
+
+
+async def show_title_screen(
+    page,
+    title: str,
+    subtitle: str = "",
+    timestamp: str = "",
+    duration_ms: int = 2000,
+) -> bool:
+    """Show title screen with blur overlay and fade effect.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+    title : str
+        Main title text.
+    subtitle : str, optional
+        Subtitle text (default: "").
+    timestamp : str, optional
+        Timestamp to display (default: "").
+    duration_ms : int, optional
+        Duration to show title in milliseconds (default: 2000).
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    args = {
+        "title": title,
+        "subtitle": subtitle,
+        "timestamp": timestamp,
+        "duration": duration_ms,
+    }
+    return await page.evaluate(TITLE_SCREEN_JS, args)
+
+
+# JavaScript for closing branding screen
+CLOSING_SCREEN_JS = """
+async (args) => {
+    const { duration = 2500 } = args;
+
+    // Add CSS animations
+    if (!document.getElementById('demo-closing-style')) {
+        const style = document.createElement('style');
+        style.id = 'demo-closing-style';
+        style.textContent = `
+            @keyframes demo-closing-fade-in {
+                0% { opacity: 0; }
+                100% { opacity: 1; }
+            }
+            @keyframes demo-closing-fade-out {
+                0% { opacity: 1; }
+                100% { opacity: 0; }
+            }
+        `;
+        document.head.appendChild(style);
+    }
+
+    // Create overlay
+    const overlay = document.createElement('div');
+    overlay.id = 'demo-closing-overlay';
+    overlay.style.cssText = `
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+        z-index: 2147483646;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        animation: demo-closing-fade-in 0.5s ease-out forwards;
+    `;
+
+    // FigRecipe title
+    const title = document.createElement('div');
+    title.style.cssText = `
+        color: white;
+        font-size: 56px;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        font-weight: 700;
+        margin-bottom: 16px;
+    `;
+    title.textContent = 'FigRecipe';
+    overlay.appendChild(title);
+
+    // Part of SciTeX
+    const scitex = document.createElement('div');
+    scitex.style.cssText = `
+        color: rgba(255, 255, 255, 0.7);
+        font-size: 20px;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        margin-bottom: 24px;
+    `;
+    scitex.innerHTML = 'Part of SciTeX™';
+    overlay.appendChild(scitex);
+
+    // URL
+    const url = document.createElement('div');
+    url.style.cssText = `
+        color: #4da6ff;
+        font-size: 18px;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    `;
+    url.textContent = 'https://scitex.ai';
+    overlay.appendChild(url);
+
+    document.body.appendChild(overlay);
+
+    // Wait and fade out
+    await new Promise(r => setTimeout(r, duration));
+
+    overlay.style.animation = 'demo-closing-fade-out 0.5s ease-out forwards';
+    await new Promise(r => setTimeout(r, 500));
+    overlay.remove();
+
+    return true;
+}
+"""
+
+
+async def show_closing_screen(page, duration_ms: int = 2500) -> bool:
+    """Show closing branding screen with FigRecipe and SciTeX.
+
+    Parameters
+    ----------
+    page : playwright.async_api.Page
+        Playwright page object.
+    duration_ms : int, optional
+        Duration to show screen in milliseconds (default: 2500).
+
+    Returns
+    -------
+    bool
+        True if successful.
+    """
+    args = {"duration": duration_ms}
+    return await page.evaluate(CLOSING_SCREEN_JS, args)
+
+
+__all__ = ["show_caption", "hide_caption", "show_title_screen", "show_closing_screen"]
+
+# EOF