karaoke-gen 0.76.28__tar.gz → 0.92.0__tar.gz

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karaoke-gen
-Version: 0.76.28
+Version: 0.92.0
 Summary: Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens.
 License: MIT
 License-File: LICENSE
@@ -14,12 +14,14 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: local-whisper
+Requires-Dist: aiohttp (>=3.13.2,<4.0.0)
 Requires-Dist: argparse (>=1.4.0)
 Requires-Dist: attrs (>=24.2.0)
 Requires-Dist: audio-separator[cpu] (>=0.34.0)
 Requires-Dist: beautifulsoup4 (>=4)
 Requires-Dist: cattrs (>=24.1.2)
 Requires-Dist: dropbox (>=12)
+Requires-Dist: email-validator (>=2.0.0)
 Requires-Dist: fastapi (>=0.104.0)
 Requires-Dist: fetch-lyrics-from-genius (>=0.1)
 Requires-Dist: ffmpeg-python (>=0.2.0,<0.3.0)
@@ -41,6 +43,7 @@ Requires-Dist: kbputils (>=0.0.16,<0.0.17)
 Requires-Dist: langchain (>=0.3.0)
 Requires-Dist: langchain-anthropic (>=0.2.0)
 Requires-Dist: langchain-core (>=0.3.0)
+Requires-Dist: langchain-google-genai (>=2.0.0)
 Requires-Dist: langchain-ollama (>=0.2.0)
 Requires-Dist: langchain-openai (>=0.2.0)
 Requires-Dist: langfuse (>=3.0.0)
@@ -75,10 +78,12 @@ Requires-Dist: python-levenshtein (>=0.26)
 Requires-Dist: python-multipart (>=0.0.20,<0.0.21)
 Requires-Dist: python-slugify (>=8)
 Requires-Dist: requests (>=2)
+Requires-Dist: sendgrid (>=6.10.0)
 Requires-Dist: shortuuid (>=1.0.13)
 Requires-Dist: spacy (>=3.8.7)
 Requires-Dist: spacy-syllables (>=3)
 Requires-Dist: srsly (>=2.5.1)
+Requires-Dist: stripe (>=7.0.0)
 Requires-Dist: syllables (>=1)
 Requires-Dist: syrics (>=0)
 Requires-Dist: thefuzz (>=0.22)

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/karaoke_gen/instrumental_review/static/index.html

@@ -786,8 +786,8 @@
                 
                 if (waveformRes.ok) {
                     waveformData = await waveformRes.json();
-                    // API returns duration_seconds, not duration
-                    duration = waveformData.duration_seconds || 0;
+                    // API may return duration_seconds (cloud) or duration (local)
+                    duration = waveformData.duration_seconds || waveformData.duration || 0;
                 }
                 
                 // Set initial selection based on recommendation

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/karaoke_gen/lyrics_processor.py

@@ -3,6 +3,7 @@ import re
 import logging
 import shutil
 import json
+from typing import Optional
 from lyrics_transcriber import LyricsTranscriber, OutputConfig, TranscriberConfig, LyricsConfig
 from lyrics_transcriber.core.controller import LyricsControllerResult
 from dotenv import load_dotenv
@@ -252,10 +253,11 @@ class LyricsProcessor:
             "See README.md 'Transcription Providers' section for detailed setup instructions."
         )
 
-    def transcribe_lyrics(self, input_audio_wav, artist, title, track_output_dir, lyrics_artist=None, lyrics_title=None):
+    def transcribe_lyrics(self, input_audio_wav, artist, title, track_output_dir, lyrics_artist=None, lyrics_title=None,
+                          agentic_deadline: Optional[float] = None):
         """
         Transcribe lyrics for a track.
-        
+
         Args:
             input_audio_wav: Path to the audio file
             artist: Original artist name (used for filename generation)
@@ -263,7 +265,9 @@ class LyricsProcessor:
             track_output_dir: Output directory path
             lyrics_artist: Artist name for lyrics processing (defaults to artist if None)
             lyrics_title: Title for lyrics processing (defaults to title if None)
-            
+            agentic_deadline: Optional Unix timestamp. If agentic correction is still
+                running after this time, it will abort and return uncorrected results.
+
         Raises:
             ValueError: If transcription is enabled but no providers are configured
         """
@@ -423,8 +427,8 @@ class LyricsProcessor:
             logger=self.logger,
         )
 
-        # Process and get results
-        results: LyricsControllerResult = transcriber.process()
+        # Process and get results (pass deadline for agentic timeout)
+        results: LyricsControllerResult = transcriber.process(agentic_deadline=agentic_deadline)
         self.logger.info(f"Transcriber Results Filepaths:")
         for key, value in results.__dict__.items():
             if key.endswith("_filepath"):

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/karaoke_gen/style_loader.py

@@ -70,7 +70,9 @@ DEFAULT_KARAOKE_STYLE = {
     "background_color": "#000000",
     "background_image": None,
     # Font settings
-    "font": "Arial",
+    # Using "Noto Sans" for full Unicode support (CJK, Arabic, symbols, etc.)
+    # Requires fonts-noto-* packages installed in Docker image
+    "font": "Noto Sans",
     "font_path": "",  # Must be string, not None (for ASS generator)
     "ass_name": "Default",
     # Colors in "R, G, B, A" format (required by ASS)

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/karaoke_gen/video_background_processor.py

@@ -156,15 +156,20 @@ class VideoBackgroundProcessor:
         """
         Escape a file path for use in ffmpeg filter expressions.
 
+        FFmpeg filter syntax uses single quotes to protect special characters
+        like spaces, colons, and semicolons. Single quotes within the path
+        are escaped using the '\\'' pattern (end quote, literal quote, start quote).
+
         Args:
             path: File path to escape
 
         Returns:
-            str: Escaped path
+            str: Escaped path (wrapped in single quotes)
         """
-        # Escape backslashes and colons for ffmpeg filter syntax
-        escaped = path.replace("\\", "\\\\").replace(":", "\\:")
-        return escaped
+        # Escape single quotes: ' becomes '\'' (end quote, \', start quote)
+        escaped = path.replace("'", "'\\''")
+        # Wrap entire path in single quotes
+        return f"'{escaped}'"
 
     def build_video_filter(self, ass_subtitles_path, darkness_percent, fonts_dir=None):
         """

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/lyrics_transcriber_temp/lyrics_transcriber/core/controller.py

@@ -289,8 +289,13 @@ class LyricsTranscriber:
         """Initialize output generation service."""
         return OutputGenerator(config=self.output_config, logger=self.logger)
 
-    def process(self) -> LyricsControllerResult:
-        """Main processing method that orchestrates the entire workflow."""
+    def process(self, agentic_deadline: Optional[float] = None) -> LyricsControllerResult:
+        """Main processing method that orchestrates the entire workflow.
+
+        Args:
+            agentic_deadline: Optional Unix timestamp. If agentic correction is still
+                running after this time, it will abort and return uncorrected results.
+        """
 
         self.logger.info(f"LyricsTranscriber controller beginning processing for {self.artist} - {self.title}")
 
@@ -390,7 +395,7 @@ class LyricsTranscriber:
 
         # Step 3: Process and correct lyrics if enabled AND we have transcription results
         if self.output_config.run_correction and self.results.transcription_results:
-            self.correct_lyrics()
+            self.correct_lyrics(agentic_deadline=agentic_deadline)
         elif self.output_config.run_correction:
             self.logger.info("Skipping lyrics correction - no transcription results available")
 
@@ -494,8 +499,13 @@ class LyricsTranscriber:
         else:
             self.logger.debug("  - LocalWhisper: DISABLED (enable_local_whisper=False)")
 
-    def correct_lyrics(self) -> None:
-        """Run lyrics correction using transcription and internet lyrics."""
+    def correct_lyrics(self, agentic_deadline: Optional[float] = None) -> None:
+        """Run lyrics correction using transcription and internet lyrics.
+
+        Args:
+            agentic_deadline: Optional Unix timestamp. If agentic correction is still
+                running after this time, it will abort and return uncorrected results.
+        """
         self.logger.info("Starting lyrics correction process")
 
         # Check if we have reference lyrics to work with
@@ -553,6 +563,7 @@ class LyricsTranscriber:
                 transcription_results=self.results.transcription_results,
                 lyrics_results=self.results.lyrics_results,
                 metadata=metadata,
+                agentic_deadline=agentic_deadline,
             )
 
             # Store corrected results

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/lyrics_transcriber_temp/lyrics_transcriber/correction/agentic/agent.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 import os
 import json
+import time
 from typing import Dict, Any, List, Optional
 
 from .providers.base import BaseAIProvider
@@ -120,7 +121,7 @@ class AgenticCorrector:
         title: Optional[str] = None
     ) -> Optional[GapClassification]:
         """Classify a gap using the AI provider.
-        
+
         Args:
             gap_id: Unique identifier for the gap
             gap_text: The text of the gap
@@ -129,10 +130,13 @@ class AgenticCorrector:
             reference_contexts: Dictionary of reference lyrics from each source
             artist: Song artist name
             title: Song title
-        
+
         Returns:
             GapClassification object or None if classification fails
         """
+        logger.info(f"🤖 Classifying gap {gap_id} ({len(gap_text)} chars)")
+        start_time = time.time()
+
         # Build classification prompt
         prompt = build_classification_prompt(
             gap_text=gap_text,
@@ -143,7 +147,7 @@ class AgenticCorrector:
             title=title,
             gap_id=gap_id
         )
-        
+
         # Call AI provider to get classification
         try:
             data = self._provider.generate_correction_proposals(
@@ -151,17 +155,25 @@ class AgenticCorrector:
                 schema=GapClassification.model_json_schema(),
                 session_id=self._session_id
             )
-            
+
+            elapsed = time.time() - start_time
+
             # Extract first result
             if data and len(data) > 0:
                 item = data[0]
                 if isinstance(item, dict) and "error" not in item:
                     classification = GapClassification.model_validate(item)
-                    logger.debug(f"🤖 Classified gap {gap_id} as {classification.category} (confidence: {classification.confidence})")
+                    logger.info(
+                        f"🤖 Classified gap {gap_id} as {classification.category} "
+                        f"(confidence: {classification.confidence:.2f}) in {elapsed:.2f}s"
+                    )
                     return classification
+                else:
+                    logger.warning(f"🤖 Classification returned error for gap {gap_id}: {item}")
         except Exception as e:
-            logger.warning(f"🤖 Failed to classify gap {gap_id}: {e}")
-        
+            elapsed = time.time() - start_time
+            logger.warning(f"🤖 Failed to classify gap {gap_id} after {elapsed:.2f}s: {e}")
+
         return None
     
     def propose_for_gap(

karaoke_gen-0.92.0/lyrics_transcriber_temp/lyrics_transcriber/correction/agentic/observability/langfuse_integration.py

@@ -0,0 +1,208 @@
+"""LangFuse integration for agentic correction observability and prompt management.
+
+This module provides:
+- Client initialization with fail-fast behavior when configured
+- Metrics recording for observability
+- Prompt fetching for dynamic prompt management
+- Dataset fetching for few-shot examples
+"""
+
+from typing import Optional, Dict, Any, List
+import os
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Module-level client singleton
+_langfuse_client: Optional[Any] = None
+_client_initialized: bool = False
+
+
+class LangFuseConfigError(Exception):
+    """Raised when LangFuse is configured but initialization fails."""
+    pass
+
+
+def is_langfuse_configured() -> bool:
+    """Check if LangFuse credentials are configured in environment."""
+    public_key = os.getenv("LANGFUSE_PUBLIC_KEY")
+    secret_key = os.getenv("LANGFUSE_SECRET_KEY")
+    return bool(public_key and secret_key)
+
+
+def setup_langfuse() -> Optional[object]:
+    """Initialize Langfuse client if keys are present; return client or None.
+
+    This avoids hard dependency at import time; caller can check for None and
+    no-op if observability is not configured.
+
+    Note: This function does NOT fail fast - use get_langfuse_client() for
+    fail-fast behavior when LangFuse is required.
+    """
+    secret = os.getenv("LANGFUSE_SECRET_KEY")
+    public = os.getenv("LANGFUSE_PUBLIC_KEY")
+    host = os.getenv("LANGFUSE_HOST", "https://us.cloud.langfuse.com")
+    if not (secret and public):
+        return None
+    try:
+        from langfuse import Langfuse  # type: ignore
+
+        client = Langfuse(secret_key=secret, public_key=public, host=host)
+        return client
+    except Exception:
+        return None
+
+
+def get_langfuse_client() -> Optional[Any]:
+    """Get or create the LangFuse client singleton.
+
+    Unlike setup_langfuse(), this function implements fail-fast behavior:
+    if LangFuse keys are configured but initialization fails, it raises
+    an exception rather than returning None.
+
+    Returns:
+        Langfuse client instance, or None if not configured
+
+    Raises:
+        LangFuseConfigError: If keys are set but initialization fails
+    """
+    global _langfuse_client, _client_initialized
+
+    if _client_initialized:
+        return _langfuse_client
+
+    secret = os.getenv("LANGFUSE_SECRET_KEY")
+    public = os.getenv("LANGFUSE_PUBLIC_KEY")
+    host = os.getenv("LANGFUSE_HOST", "https://us.cloud.langfuse.com")
+
+    if not (secret and public):
+        logger.debug("LangFuse keys not configured, client disabled")
+        _client_initialized = True
+        return None
+
+    try:
+        from langfuse import Langfuse
+
+        _langfuse_client = Langfuse(
+            secret_key=secret,
+            public_key=public,
+            host=host,
+        )
+        _client_initialized = True
+        logger.info(f"LangFuse client initialized (host: {host})")
+        return _langfuse_client
+
+    except Exception as e:
+        # Fail fast - if keys are set, we expect LangFuse to work
+        raise LangFuseConfigError(
+            f"LangFuse keys are set but initialization failed: {e}\n"
+            f"Check:\n"
+            f"  - LANGFUSE_PUBLIC_KEY: {public[:10] if public else 'not set'}...\n"
+            f"  - LANGFUSE_SECRET_KEY: {'set' if secret else 'not set'}\n"
+            f"  - LANGFUSE_HOST: {host}"
+        ) from e
+
+
+def reset_langfuse_client() -> None:
+    """Reset the global LangFuse client (for testing)."""
+    global _langfuse_client, _client_initialized
+    _langfuse_client = None
+    _client_initialized = False
+
+
+def record_metrics(client: Optional[object], name: str, metrics: Dict[str, Any]) -> None:
+    """Record custom metrics to Langfuse if initialized."""
+    if client is None:
+        return
+    try:
+        # Minimal shape to avoid strict coupling; callers can extend
+        client.trace(name=name, metadata=metrics)
+    except Exception:
+        # Swallow observability errors to never impact core flow
+        pass
+
+
+def fetch_prompt(name: str, client: Optional[Any] = None, label: Optional[str] = "production") -> Any:
+    """Fetch a prompt template from LangFuse.
+
+    Args:
+        name: The prompt name in LangFuse
+        client: Optional pre-initialized client. If None, uses get_langfuse_client()
+        label: Prompt label to fetch (default: "production"). If the labeled version
+               is not found, falls back to version 1.
+
+    Returns:
+        LangFuse prompt object
+
+    Raises:
+        LangFuseConfigError: If LangFuse is not configured
+        RuntimeError: If prompt fetch fails
+    """
+    if client is None:
+        client = get_langfuse_client()
+
+    if client is None:
+        raise LangFuseConfigError(
+            f"Cannot fetch prompt '{name}': LangFuse is not configured. "
+            f"Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY."
+        )
+
+    try:
+        # Try to fetch with the specified label (default: production)
+        prompt = client.get_prompt(name, label=label)
+        logger.debug(f"Fetched prompt '{name}' (label={label}) from LangFuse")
+        return prompt
+    except Exception as label_error:
+        # If labeled version not found, try fetching version 1 as fallback
+        # This handles newly created prompts that haven't been promoted yet
+        try:
+            prompt = client.get_prompt(name, version=1)
+            logger.warning(
+                f"Prompt '{name}' label '{label}' not found, using version 1. "
+                f"Consider promoting this prompt in LangFuse UI."
+            )
+            return prompt
+        except Exception as version_error:
+            raise RuntimeError(
+                f"Failed to fetch prompt '{name}' from LangFuse: "
+                f"Label '{label}' error: {label_error}, "
+                f"Version 1 fallback error: {version_error}"
+            ) from version_error
+
+
+def fetch_dataset(name: str, client: Optional[Any] = None) -> List[Dict[str, Any]]:
+    """Fetch a dataset from LangFuse and return its items.
+
+    Args:
+        name: The dataset name in LangFuse
+        client: Optional pre-initialized client. If None, uses get_langfuse_client()
+
+    Returns:
+        List of dataset item inputs (the actual example data)
+
+    Raises:
+        LangFuseConfigError: If LangFuse is not configured
+        RuntimeError: If dataset fetch fails
+    """
+    if client is None:
+        client = get_langfuse_client()
+
+    if client is None:
+        raise LangFuseConfigError(
+            f"Cannot fetch dataset '{name}': LangFuse is not configured. "
+            f"Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY."
+        )
+
+    try:
+        dataset = client.get_dataset(name)
+        items = []
+        for item in dataset.items:
+            if hasattr(item, 'input') and item.input:
+                items.append(item.input)
+
+        logger.debug(f"Fetched {len(items)} items from dataset '{name}'")
+        return items
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to fetch dataset '{name}' from LangFuse: {e}"
+        ) from e

karaoke_gen-0.92.0/lyrics_transcriber_temp/lyrics_transcriber/correction/agentic/prompts/__init__.py

@@ -0,0 +1,25 @@
+"""Prompt templates for agentic correction."""
+
+from .classifier import (
+    build_classification_prompt,
+    build_classification_prompt_hardcoded,
+    get_hardcoded_examples,
+)
+from .langfuse_prompts import (
+    LangFusePromptService,
+    LangFusePromptError,
+    LangFuseDatasetError,
+    get_prompt_service,
+    reset_prompt_service,
+)
+
+__all__ = [
+    "build_classification_prompt",
+    "build_classification_prompt_hardcoded",
+    "get_hardcoded_examples",
+    "LangFusePromptService",
+    "LangFusePromptError",
+    "LangFuseDatasetError",
+    "get_prompt_service",
+    "reset_prompt_service",
+]

{karaoke_gen-0.76.28 → karaoke_gen-0.92.0}/lyrics_transcriber_temp/lyrics_transcriber/correction/agentic/prompts/classifier.py

@@ -1,23 +1,35 @@
-"""Gap classification prompt builder for agentic correction."""
+"""Gap classification prompt builder for agentic correction.
+
+This module provides two modes of operation:
+1. LangFuse mode: Prompts and examples fetched from LangFuse for dynamic iteration
+2. Hardcoded mode: Fallback for local development when LangFuse is not configured
+
+The main entry point is `build_classification_prompt()` which automatically
+selects the appropriate mode based on LangFuse configuration.
+"""
 
 from typing import Dict, List, Optional
 import yaml
 import os
+import logging
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 
 def load_few_shot_examples() -> Dict[str, List[Dict]]:
     """Load few-shot examples from examples.yaml if it exists."""
     examples_path = Path(__file__).parent / "examples.yaml"
-    
+
     if not examples_path.exists():
         return get_hardcoded_examples()
-    
+
     try:
         with open(examples_path, 'r') as f:
             data = yaml.safe_load(f)
             return data.get('examples_by_category', {})
-    except Exception:
+    except Exception as e:
+        logger.warning(f"Failed to load examples.yaml, using hardcoded examples: {e}")
         return get_hardcoded_examples()
 
 
@@ -122,7 +134,12 @@ def build_classification_prompt(
     gap_id: Optional[str] = None
 ) -> str:
     """Build a prompt for classifying a gap in the transcription.
-    
+
+    This function automatically selects between LangFuse and hardcoded prompts:
+    - If LangFuse is configured (LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY set),
+      fetches the prompt template and examples from LangFuse.
+    - Otherwise, uses hardcoded prompts for local development.
+
     Args:
         gap_text: The text of the gap that needs classification
         preceding_words: Text immediately before the gap
@@ -131,7 +148,50 @@ def build_classification_prompt(
         artist: Song artist name for context
         title: Song title for context
         gap_id: Identifier for the gap
-    
+
+    Returns:
+        Formatted prompt string for the LLM
+
+    Raises:
+        LangFusePromptError: If LangFuse is configured but prompt fetch fails
+    """
+    from .langfuse_prompts import get_prompt_service
+
+    service = get_prompt_service()
+    return service.get_classification_prompt(
+        gap_text=gap_text,
+        preceding_words=preceding_words,
+        following_words=following_words,
+        reference_contexts=reference_contexts,
+        artist=artist,
+        title=title,
+        gap_id=gap_id
+    )
+
+
+def build_classification_prompt_hardcoded(
+    gap_text: str,
+    preceding_words: str,
+    following_words: str,
+    reference_contexts: Dict[str, str],
+    artist: Optional[str] = None,
+    title: Optional[str] = None,
+    gap_id: Optional[str] = None
+) -> str:
+    """Build a prompt for classifying a gap using hardcoded templates.
+
+    This is the fallback implementation used when LangFuse is not configured.
+    It is also used as the source of truth for migrating prompts to LangFuse.
+
+    Args:
+        gap_text: The text of the gap that needs classification
+        preceding_words: Text immediately before the gap
+        following_words: Text immediately after the gap
+        reference_contexts: Dictionary of reference lyrics from each source
+        artist: Song artist name for context
+        title: Song title for context
+        gap_id: Identifier for the gap
+
     Returns:
         Formatted prompt string for the LLM
     """