karaoke-gen 0.90.1__py3-none-any.whl → 0.96.0__py3-none-any.whl

backend/workers/worker_logging.py

@@ -0,0 +1,278 @@
+"""
+Worker logging utilities.
+
+Provides logging that sends to both standard output AND Firestore
+for remote debugging via the CLI.
+
+Two approaches are provided:
+1. JobLogger - A custom logger class for explicit logging in workers
+2. JobLogHandler - A logging.Handler that captures logs from any logger (including dependencies)
+
+IMPORTANT: Uses contextvars to ensure log isolation between concurrent jobs.
+When multiple jobs run in parallel on the same Cloud Run instance, each job's
+worker logs are correctly filtered to only include logs from that job.
+"""
+import contextvars
+import logging
+from contextlib import contextmanager
+from typing import Optional, Set
+
+
+# Context variable to track the current job being processed
+# This is used to filter logs when multiple jobs run concurrently
+_current_job_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    'current_job_id', default=None
+)
+
+
+@contextmanager
+def job_logging_context(job_id: str):
+    """
+    Context manager to set the current job ID for log filtering.
+    
+    When multiple jobs run concurrently on the same Cloud Run instance,
+    this ensures that each job's handler only captures logs from its own
+    processing thread/context.
+    
+    Usage:
+        with job_logging_context(job_id):
+            # All logs emitted here will be associated with this job_id
+            process_job(job_id)
+    
+    Args:
+        job_id: The job ID to set as the current context
+    """
+    token = _current_job_id.set(job_id)
+    try:
+        yield
+    finally:
+        _current_job_id.reset(token)
+
+
+class JobLogHandler(logging.Handler):
+    """
+    A logging handler that captures log records and stores them in Firestore.
+    
+    This handler can be added to any logger (including dependency loggers like
+    LyricsTranscriber) to capture their output for remote debugging.
+    
+    Usage:
+        # Capture logs from LyricsTranscriber and its sub-components
+        handler = JobLogHandler(job_id, "lyrics", job_manager)
+        
+        # Add to the logger that will be passed to LyricsTranscriber
+        lyrics_logger = logging.getLogger("karaoke_gen.lyrics_processor")
+        lyrics_logger.addHandler(handler)
+        
+        # Also capture logs from lyrics_transcriber package itself
+        lt_logger = logging.getLogger("lyrics_transcriber")
+        lt_logger.addHandler(handler)
+    """
+    
+    def __init__(self, job_id: str, worker_name: str, job_manager, level: int = logging.INFO):
+        """
+        Initialize the job log handler.
+        
+        Args:
+            job_id: Job ID to log to
+            worker_name: Worker name for log entries
+            job_manager: JobManager instance for Firestore access
+            level: Minimum log level to capture (default INFO)
+        """
+        super().__init__(level)
+        self.job_id = job_id
+        self.worker_name = worker_name
+        self.job_manager = job_manager
+        
+        # Track which messages we've already logged to avoid duplicates
+        self._logged_messages: Set[str] = set()
+    
+    def emit(self, record: logging.LogRecord) -> None:
+        """Process a log record."""
+        try:
+            # CRITICAL: Filter by current job context to prevent log mixing
+            # When multiple jobs run concurrently, each attaches handlers to
+            # the same global loggers. Without this check, logs from Job A
+            # would be captured by Job B's handler and vice versa.
+            current_job = _current_job_id.get()
+            if current_job is not None and current_job != self.job_id:
+                # This log is from a different job's context, skip it
+                return
+            
+            # Format the log message
+            message = self.format(record)
+            
+            # Create a dedup key (to avoid duplicate messages from multiple handlers)
+            dedup_key = f"{record.created}:{record.levelname}:{message[:100]}"
+            if dedup_key in self._logged_messages:
+                return
+            self._logged_messages.add(dedup_key)
+            
+            # Keep the set from growing unbounded
+            if len(self._logged_messages) > 1000:
+                self._logged_messages = set(list(self._logged_messages)[-500:])
+            
+            # Store in Firestore
+            self.job_manager.append_worker_log(
+                job_id=self.job_id,
+                worker=self.worker_name,
+                level=record.levelname,
+                message=message
+            )
+        except Exception:
+            # Don't let logging errors break the worker
+            self.handleError(record)
+
+
+class JobLogger:
+    """
+    Logger that writes to both standard logging and Firestore job logs.
+    
+    This allows worker logs to be viewed remotely via the CLI.
+    
+    Usage:
+        job_logger = JobLogger(job_id, "audio", job_manager)
+        job_logger.info("Processing audio...")
+        job_logger.error("Failed to process", exc_info=True)
+    """
+    
+    def __init__(self, job_id: str, worker_name: str, job_manager):
+        """
+        Initialize job logger.
+        
+        Args:
+            job_id: Job ID to log to
+            worker_name: Worker name (audio, lyrics, screens, video, render)
+            job_manager: JobManager instance for Firestore access
+        """
+        self.job_id = job_id
+        self.worker_name = worker_name
+        self.job_manager = job_manager
+        self._logger = logging.getLogger(f"worker.{worker_name}.{job_id}")
+    
+    def _log(self, level: str, message: str, *args, **kwargs):
+        """Internal logging method."""
+        # Format message with args if provided
+        if args:
+            try:
+                formatted_message = message % args
+            except (TypeError, ValueError):
+                formatted_message = f"{message} {args}"
+        else:
+            formatted_message = message
+        
+        # Log to standard logging
+        log_method = getattr(self._logger, level.lower())
+        log_method(formatted_message)
+        
+        # Also append to Firestore job logs (async-safe)
+        try:
+            self.job_manager.append_worker_log(
+                job_id=self.job_id,
+                worker=self.worker_name,
+                level=level.upper(),
+                message=formatted_message
+            )
+        except Exception as e:
+            # Don't let Firestore errors break worker processing
+            self._logger.warning(f"Failed to append job log: {e}")
+    
+    def debug(self, message: str, *args, **kwargs):
+        """Log debug message."""
+        self._log("DEBUG", message, *args, **kwargs)
+    
+    def info(self, message: str, *args, **kwargs):
+        """Log info message."""
+        self._log("INFO", message, *args, **kwargs)
+    
+    def warning(self, message: str, *args, **kwargs):
+        """Log warning message."""
+        self._log("WARNING", message, *args, **kwargs)
+    
+    def error(self, message: str, *args, exc_info: bool = False, **kwargs):
+        """Log error message."""
+        self._log("ERROR", message, *args, **kwargs)
+        if exc_info:
+            import traceback
+            tb = traceback.format_exc()
+            if tb and tb != "NoneType: None\n":
+                self._log("ERROR", f"Traceback:\n{tb}")
+    
+    def exception(self, message: str, *args, **kwargs):
+        """Log exception with traceback."""
+        self.error(message, *args, exc_info=True, **kwargs)
+
+
+def create_job_logger(job_id: str, worker_name: str) -> JobLogger:
+    """
+    Create a JobLogger for a worker.
+    
+    This is a convenience function that creates the JobManager internally.
+    
+    Args:
+        job_id: Job ID
+        worker_name: Worker name
+        
+    Returns:
+        JobLogger instance
+    """
+    from backend.services.job_manager import JobManager
+    job_manager = JobManager()
+    return JobLogger(job_id, worker_name, job_manager)
+
+
+def setup_job_logging(job_id: str, worker_name: str, *logger_names: str) -> JobLogHandler:
+    """
+    Set up job logging for a worker and its dependencies.
+    
+    This adds a JobLogHandler to capture logs from specified loggers
+    (including dependency loggers like lyrics_transcriber).
+    
+    IMPORTANT: When using this function, wrap your job processing code in
+    `job_logging_context(job_id)` to ensure proper log isolation when multiple
+    jobs run concurrently on the same Cloud Run instance.
+    
+    Args:
+        job_id: Job ID
+        worker_name: Worker name
+        *logger_names: Names of loggers to capture (e.g., "lyrics_transcriber", "karaoke_gen")
+        
+    Returns:
+        The JobLogHandler (can be removed later if needed)
+        
+    Example:
+        # In lyrics_worker.py:
+        handler = setup_job_logging(
+            job_id, 
+            "lyrics",
+            "karaoke_gen.lyrics_processor",
+            "lyrics_transcriber",  # Capture LyricsTranscriber logs
+        )
+        
+        # IMPORTANT: Use job_logging_context for proper isolation
+        with job_logging_context(job_id):
+            # ... do work ...
+            pass
+        
+        # Optional: remove handler when done
+        for name in logger_names:
+            logging.getLogger(name).removeHandler(handler)
+    """
+    from backend.services.job_manager import JobManager
+    
+    job_manager = JobManager()
+    handler = JobLogHandler(job_id, worker_name, job_manager, level=logging.INFO)
+    
+    # Simple formatter that just shows the message
+    formatter = logging.Formatter('%(message)s')
+    handler.setFormatter(formatter)
+    
+    # Add handler to all specified loggers
+    for logger_name in logger_names:
+        logger = logging.getLogger(logger_name)
+        logger.addHandler(handler)
+        # Ensure logger level allows INFO messages through
+        if logger.level > logging.INFO or logger.level == logging.NOTSET:
+            logger.setLevel(logging.INFO)
+    
+    return handler

karaoke_gen/instrumental_review/static/index.html

@@ -6,21 +6,24 @@
     <title>Instrumental Review</title>
     <style>
         :root {
+            /* Nomad Karaoke brand colors - see docs/BRAND-STYLE-GUIDE.md */
             --bg: #0f0f0f;
             --card: #1a1a1a;
             --card-border: #2a2a2a;
             --waveform-bg: #0d1117;
             --text: #e5e5e5;
             --text-muted: #888;
-            --primary: #3b82f6;
-            --primary-hover: #2563eb;
+            --primary: #ff7acc;
+            --primary-hover: #ff5bb8;
             --secondary: #252525;
             --secondary-hover: #333;
             --success: #22c55e;
             --warning: #f59e0b;
             --danger: #ef4444;
-            --pink: #ec4899;
-            --blue: #60a5fa;
+            --brand-pink: #ff7acc;
+            --brand-gold: #ffdf6b;
+            --brand-purple: #8b5cf6;
+            --blue: #3b82f6;
         }
         
         * { box-sizing: border-box; margin: 0; padding: 0; }

karaoke_gen/karaoke_finalise/karaoke_finalise.py

@@ -20,6 +20,7 @@ from google.oauth2.credentials import Credentials
 import base64
 from email.mime.text import MIMEText
 from lyrics_transcriber.output.cdg import CDGGenerator
+from ..utils import sanitize_filename
 
 
 class KaraokeFinalise:
@@ -1514,7 +1515,11 @@ class KaraokeFinalise:
 
         email_body = template.format(youtube_url=youtube_url, dropbox_url=dropbox_url)
 
-        subject = f"{self.brand_code}: {artist} - {title}"
+        # Sanitize artist/title to handle Unicode characters (curly quotes, em dashes, etc.)
+        # that cause email header encoding issues (MIME headers use latin-1)
+        safe_artist = sanitize_filename(artist) if artist else "Unknown"
+        safe_title = sanitize_filename(title) if title else "Unknown"
+        subject = f"{self.brand_code}: {safe_artist} - {safe_title}"
 
         if self.dry_run:
             self.logger.info(f"DRY RUN: Would create email draft with subject: {subject}")

karaoke_gen/utils/__init__.py

@@ -1,7 +1,85 @@
 import re
 
-# Unicode character replacements for ASCII-safe filenames
-# These characters cause issues with HTTP headers (latin-1 encoding) and some filesystems
+# =============================================================================
+# Text Normalization
+# =============================================================================
+# These mappings normalize visually-similar Unicode characters to their standard
+# ASCII equivalents. This ensures consistency in stored data and reliable search.
+
+# Apostrophe-like characters -> standard apostrophe (U+0027)
+APOSTROPHE_REPLACEMENTS = {
+    "\u2018": "'",  # LEFT SINGLE QUOTATION MARK (')
+    "\u2019": "'",  # RIGHT SINGLE QUOTATION MARK (') - common from Word/macOS
+    "\u201A": "'",  # SINGLE LOW-9 QUOTATION MARK (‚)
+    "\u201B": "'",  # SINGLE HIGH-REVERSED-9 QUOTATION MARK (‛)
+    "\u0060": "'",  # GRAVE ACCENT (`) - backtick
+    "\u00B4": "'",  # ACUTE ACCENT (´)
+    "\u2032": "'",  # PRIME (′)
+    "\u02B9": "'",  # MODIFIER LETTER PRIME (ʹ)
+    "\u02BC": "'",  # MODIFIER LETTER APOSTROPHE (ʼ)
+    "\u02C8": "'",  # MODIFIER LETTER VERTICAL LINE (ˈ)
+    "\u0301": "'",  # COMBINING ACUTE ACCENT (standalone, rare)
+}
+
+# Double quote-like characters -> standard double quote (U+0022)
+DOUBLE_QUOTE_REPLACEMENTS = {
+    "\u201C": '"',  # LEFT DOUBLE QUOTATION MARK (")
+    "\u201D": '"',  # RIGHT DOUBLE QUOTATION MARK (")
+    "\u201E": '"',  # DOUBLE LOW-9 QUOTATION MARK („)
+    "\u201F": '"',  # DOUBLE HIGH-REVERSED-9 QUOTATION MARK (‟)
+    "\u2033": '"',  # DOUBLE PRIME (″)
+    "\u02DD": '"',  # DOUBLE ACUTE ACCENT (˝)
+    "\u3003": '"',  # DITTO MARK (〃) - CJK
+}
+
+# Dash-like characters -> standard hyphen-minus (U+002D)
+DASH_REPLACEMENTS = {
+    "\u2013": "-",  # EN DASH (–)
+    "\u2014": "-",  # EM DASH (—)
+    "\u2015": "-",  # HORIZONTAL BAR (―)
+    "\u2212": "-",  # MINUS SIGN (−)
+    "\u2010": "-",  # HYPHEN (‐)
+    "\u2011": "-",  # NON-BREAKING HYPHEN (‑)
+    "\u2012": "-",  # FIGURE DASH (‒)
+    "\u00AD": "-",  # SOFT HYPHEN (invisible, but normalize anyway)
+}
+
+# Whitespace characters -> standard space (U+0020)
+WHITESPACE_REPLACEMENTS = {
+    "\u00A0": " ",  # NO-BREAK SPACE
+    "\u2002": " ",  # EN SPACE
+    "\u2003": " ",  # EM SPACE
+    "\u2004": " ",  # THREE-PER-EM SPACE
+    "\u2005": " ",  # FOUR-PER-EM SPACE
+    "\u2006": " ",  # SIX-PER-EM SPACE
+    "\u2007": " ",  # FIGURE SPACE
+    "\u2008": " ",  # PUNCTUATION SPACE
+    "\u2009": " ",  # THIN SPACE
+    "\u200A": " ",  # HAIR SPACE
+    "\u200B": "",   # ZERO WIDTH SPACE (remove entirely)
+    "\u202F": " ",  # NARROW NO-BREAK SPACE
+    "\u205F": " ",  # MEDIUM MATHEMATICAL SPACE
+    "\u3000": " ",  # IDEOGRAPHIC SPACE (CJK full-width space)
+    "\uFEFF": "",   # ZERO WIDTH NO-BREAK SPACE / BOM (remove entirely)
+}
+
+# Other replacements
+OTHER_REPLACEMENTS = {
+    "\u2026": "...",  # HORIZONTAL ELLIPSIS (…)
+    "\u22EF": "...",  # MIDLINE HORIZONTAL ELLIPSIS (⋯)
+}
+
+# Combined replacement dict for normalize_text()
+TEXT_NORMALIZATIONS = {
+    **APOSTROPHE_REPLACEMENTS,
+    **DOUBLE_QUOTE_REPLACEMENTS,
+    **DASH_REPLACEMENTS,
+    **WHITESPACE_REPLACEMENTS,
+    **OTHER_REPLACEMENTS,
+}
+
+# Legacy dict for backwards compatibility (used by sanitize_filename)
+# This is a subset focused on HTTP header safety
 UNICODE_REPLACEMENTS = {
     # Curly/smart quotes -> straight quotes
     "\u2018": "'",  # LEFT SINGLE QUOTATION MARK
@@ -20,25 +98,102 @@ UNICODE_REPLACEMENTS = {
 }
 
 
+def normalize_text(text: str) -> str:
+    """
+    Normalize visually-similar Unicode characters to standard ASCII equivalents.
+
+    This function standardizes text for consistency in stored data and reliable
+    search/matching. It converts:
+    - Curly quotes and backticks -> straight quotes
+    - Various dashes (en dash, em dash, minus) -> hyphen
+    - Various whitespace characters -> regular space
+    - Ellipsis character -> three dots
+
+    This function also:
+    - Collapses multiple spaces to a single space
+    - Strips leading/trailing whitespace
+
+    Unlike sanitize_filename(), this does NOT:
+    - Remove filesystem-unsafe characters (/, \, :, *, ?, ", <, >, |)
+    - Collapse multiple underscores
+    - Strip leading/trailing periods
+
+    This should be applied to user-facing text like artist names and song titles
+    at input time to ensure data consistency.
+
+    Args:
+        text: The text to normalize
+
+    Returns:
+        Normalized text with standard ASCII equivalents, or None if input is None
+
+    Examples:
+        >>> normalize_text("Don't Stop")  # curly apostrophe
+        "Don't Stop"
+        >>> normalize_text("Song — Title")  # em dash
+        "Song - Title"
+        >>> normalize_text("Hello\u00A0World")  # non-breaking space
+        "Hello World"
+    """
+    if text is None:
+        return None
+
+    if not isinstance(text, str):
+        return text
+
+    # Apply all normalizations
+    for unicode_char, replacement in TEXT_NORMALIZATIONS.items():
+        text = text.replace(unicode_char, replacement)
+
+    # Collapse multiple spaces (but preserve intentional spacing structure)
+    text = re.sub(r' {2,}', ' ', text)
+
+    # Strip leading/trailing whitespace
+    text = text.strip()
+
+    return text
+
+
 def sanitize_filename(filename):
-    """Replace or remove characters that are unsafe for filenames."""
+    """
+    Replace or remove characters that are unsafe for filenames.
+
+    This function makes text safe for use in:
+    - Filesystem paths
+    - HTTP headers (Content-Disposition)
+    - API requests (Modal, Google Drive, Dropbox)
+
+    It applies normalize_text() first, then additionally:
+    - Replaces filesystem-unsafe characters with underscores
+    - Strips leading/trailing periods and spaces
+    - Collapses multiple underscores/spaces
+
+    Args:
+        filename: The filename to sanitize
+
+    Returns:
+        Sanitized filename safe for filesystems and HTTP headers
+    """
     if filename is None:
         return None
 
-    # First, normalize Unicode characters that cause HTTP header encoding issues
-    # (e.g., curly quotes from macOS/Word that can't be encoded in latin-1)
-    for unicode_char, ascii_replacement in UNICODE_REPLACEMENTS.items():
-        filename = filename.replace(unicode_char, ascii_replacement)
+    # First, normalize Unicode characters
+    filename = normalize_text(filename)
+
+    if filename is None:
+        return None
 
     # Replace problematic characters with underscores
     for char in ["\\", "/", ":", "*", "?", '"', "<", ">", "|"]:
         filename = filename.replace(char, "_")
+
     # Remove any trailing periods or spaces
-    filename = filename.rstrip(". ") # Added period here as well
+    filename = filename.rstrip(". ")
     # Remove any leading periods or spaces
     filename = filename.lstrip(". ")
     # Replace multiple underscores with a single one
     filename = re.sub(r'_+', '_', filename)
     # Replace multiple spaces with a single one
     filename = re.sub(r' +', ' ', filename)
+
     return filename

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.90.1.dist-info → karaoke_gen-0.96.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karaoke-gen
-Version: 0.90.1
+Version: 0.96.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