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

figrecipe/_composition/_import_axes.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Import axes from external recipes into existing figures."""
+
+from pathlib import Path
+from typing import Tuple, Union
+
+from .._recorder import FigureRecord
+from .._serializer import load_recipe
+from .._wrappers import RecordingAxes, RecordingFigure
+from ._compose import _replay_axes_record
+
+
+def import_axes(
+    fig: RecordingFigure,
+    target_position: Tuple[int, int],
+    source: Union[str, Path, FigureRecord],
+    source_axes: str = "ax_0_0",
+) -> RecordingAxes:
+    """Import axes from another recipe into an existing figure.
+
+    This function copies all plotting calls and decorations from a source
+    axes (in a recipe file or FigureRecord) to a target position in an
+    existing figure. The target axes is cleared before import.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        Target figure to import into.
+    target_position : tuple
+        (row, col) position in target figure.
+    source : str, Path, or FigureRecord
+        Source recipe file path or FigureRecord object.
+    source_axes : str, optional
+        Key of axes to import from source (default: "ax_0_0").
+
+    Returns
+    -------
+    RecordingAxes
+        The target axes after import.
+
+    Raises
+    ------
+    ValueError
+        If source_axes key not found in source.
+    TypeError
+        If source is not a valid type.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, axes = fr.subplots(1, 2)
+    >>> axes[0].plot([1, 2, 3], [1, 4, 9])
+    >>> fr.import_axes(fig, (0, 1), "analysis.yaml")
+    """
+    # Load source if path
+    if isinstance(source, (str, Path)):
+        source_record = load_recipe(source)
+    elif isinstance(source, FigureRecord):
+        source_record = source
+    else:
+        raise TypeError(f"Invalid source type: {type(source)}")
+
+    # Get source axes record
+    ax_record = source_record.axes.get(source_axes)
+    if ax_record is None:
+        available = list(source_record.axes.keys())
+        raise ValueError(
+            f"Axes '{source_axes}' not found in source. Available: {available}"
+        )
+
+    # Get target axes
+    row, col = target_position
+    target_ax = _get_target_axes(fig, row, col)
+
+    # Clear existing content
+    mpl_ax = target_ax._ax if hasattr(target_ax, "_ax") else target_ax
+    mpl_ax.clear()
+
+    # Replay source calls onto target
+    _replay_axes_record(target_ax, ax_record, fig.record, row, col)
+
+    return target_ax
+
+
+def _get_target_axes(
+    fig: RecordingFigure,
+    row: int,
+    col: int,
+) -> RecordingAxes:
+    """Get target axes from figure at position.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure.
+    row, col : int
+        Target position.
+
+    Returns
+    -------
+    RecordingAxes
+        Axes at position.
+
+    Raises
+    ------
+    IndexError
+        If position is out of range.
+    """
+    if not hasattr(fig, "_axes"):
+        raise ValueError("Figure must have _axes attribute")
+
+    axes = fig._axes
+    try:
+        # Handle different axes array structures
+        if isinstance(axes, list):
+            if isinstance(axes[0], list):
+                return axes[row][col]
+            else:
+                return axes[max(row, col)]
+        else:
+            return axes[row, col]
+    except (IndexError, KeyError) as e:
+        raise IndexError(f"Position ({row}, {col}) out of range for figure axes") from e
+
+
+__all__ = ["import_axes"]

figrecipe/_composition/_visibility.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Panel visibility management for composition feature."""
+
+from typing import Tuple
+
+from .._wrappers import RecordingFigure
+
+
+def hide_panel(fig: RecordingFigure, position: Tuple[int, int]) -> None:
+    """Hide a panel (visually drop it without deleting data).
+
+    The panel data is preserved in the recipe but not rendered.
+    Use show_panel() to restore visibility.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure containing the panel.
+    position : tuple
+        (row, col) position of the panel to hide.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, axes = fr.subplots(1, 2)
+    >>> axes[0].plot([1, 2], [1, 2])
+    >>> fr.hide_panel(fig, (0, 1))  # Hide empty second panel
+    """
+    ax_key = f"ax_{position[0]}_{position[1]}"
+    if ax_key in fig.record.axes:
+        fig.record.axes[ax_key].visible = False
+        _set_axes_visible(fig, position, False)
+
+
+def show_panel(fig: RecordingFigure, position: Tuple[int, int]) -> None:
+    """Show a previously hidden panel.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure containing the panel.
+    position : tuple
+        (row, col) position of the panel to show.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, axes = fr.subplots(1, 2)
+    >>> fr.hide_panel(fig, (0, 1))
+    >>> fr.show_panel(fig, (0, 1))  # Restore visibility
+    """
+    ax_key = f"ax_{position[0]}_{position[1]}"
+    if ax_key in fig.record.axes:
+        fig.record.axes[ax_key].visible = True
+        _set_axes_visible(fig, position, True)
+
+
+def toggle_panel(fig: RecordingFigure, position: Tuple[int, int]) -> bool:
+    """Toggle panel visibility.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure containing the panel.
+    position : tuple
+        (row, col) position of the panel.
+
+    Returns
+    -------
+    bool
+        New visibility state (True = visible, False = hidden).
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, ax = fr.subplots()
+    >>> fr.toggle_panel(fig, (0, 0))  # Returns False (now hidden)
+    >>> fr.toggle_panel(fig, (0, 0))  # Returns True (now visible)
+    """
+    ax_key = f"ax_{position[0]}_{position[1]}"
+    if ax_key in fig.record.axes:
+        current = fig.record.axes[ax_key].visible
+        if current:
+            hide_panel(fig, position)
+        else:
+            show_panel(fig, position)
+        return not current
+    return False
+
+
+def _set_axes_visible(
+    fig: RecordingFigure,
+    position: Tuple[int, int],
+    visible: bool,
+) -> None:
+    """Set matplotlib axes visibility.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        The figure.
+    position : tuple
+        (row, col) position.
+    visible : bool
+        Whether to make visible or hidden.
+    """
+    row, col = position
+    try:
+        axes = fig._axes
+        if isinstance(axes, list):
+            if isinstance(axes[0], list):
+                ax = axes[row][col]
+            else:
+                ax = axes[max(row, col)]
+        else:
+            ax = axes[row, col]
+
+        mpl_ax = ax._ax if hasattr(ax, "_ax") else ax
+        mpl_ax.set_visible(visible)
+    except (IndexError, AttributeError, KeyError):
+        pass
+
+
+__all__ = ["hide_panel", "show_panel", "toggle_panel"]

figrecipe/_dev/__init__.py

@@ -16,6 +16,7 @@ Usage:
     results = run_all_demos(fr, output_dir="./outputs")
 """
 
+from . import browser
 from ._plotters import PLOTTERS, get_plotter, list_plotters
 from ._run_demos import run_all_demos
 
@@ -24,6 +25,7 @@ __all__ = [
     "list_plotters",
     "get_plotter",
     "run_all_demos",
+    "browser",
 ]
 
 # EOF

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"]