karaoke-gen 0.71.27__py3-none-any.whl → 0.75.16__py3-none-any.whl

karaoke_gen/lyrics_processor.py

@@ -11,6 +11,9 @@ from .utils import sanitize_filename
 
 # Placeholder class or functions for lyrics processing
 class LyricsProcessor:
+    # Standard countdown padding duration used by LyricsTranscriber
+    COUNTDOWN_PADDING_SECONDS = 3.0
+    
     def __init__(
         self, logger, style_params_json, lyrics_file, skip_transcription, skip_transcription_review, render_video, subtitle_offset_ms
     ):
@@ -22,6 +25,60 @@ class LyricsProcessor:
         self.render_video = render_video
         self.subtitle_offset_ms = subtitle_offset_ms
 
+    def _detect_countdown_padding_from_lrc(self, lrc_filepath):
+        """
+        Detect if countdown padding was applied by checking the first lyric timestamp in the LRC file.
+        
+        LRC format timestamps look like: [mm:ss.xx] or [mm:ss.xxx]
+        If the first lyric timestamp is >= 3.0 seconds, countdown padding was likely applied.
+        
+        Args:
+            lrc_filepath: Path to the LRC file
+            
+        Returns:
+            Tuple of (countdown_padding_added: bool, countdown_padding_seconds: float)
+        """
+        try:
+            with open(lrc_filepath, 'r', encoding='utf-8') as f:
+                content = f.read()
+            
+            # Find all timestamp patterns in the LRC file
+            # LRC timestamps: [mm:ss.xx] or [mm:ss.xxx]
+            timestamp_pattern = r'\[(\d{1,2}):(\d{2})\.(\d{2,3})\]'
+            matches = re.findall(timestamp_pattern, content)
+            
+            if not matches:
+                self.logger.debug("No timestamps found in LRC file")
+                return (False, 0.0)
+            
+            # Find the first non-metadata timestamp (metadata like [ar:Artist] doesn't have decimal)
+            # We already filtered for decimal timestamps in our pattern
+            first_timestamp = matches[0]
+            minutes = int(first_timestamp[0])
+            seconds = int(first_timestamp[1])
+            # Handle both .xx and .xxx formats
+            centiseconds = first_timestamp[2]
+            if len(centiseconds) == 2:
+                milliseconds = int(centiseconds) * 10
+            else:
+                milliseconds = int(centiseconds)
+            
+            first_lyric_time = minutes * 60 + seconds + milliseconds / 1000.0
+            
+            self.logger.debug(f"First lyric timestamp in LRC: {first_lyric_time:.3f}s")
+            
+            # If first lyric is at or after 3 seconds, countdown padding was applied
+            # Use a small buffer (2.5s) to account for songs that naturally start a bit late
+            if first_lyric_time >= 2.5:
+                self.logger.info(f"Detected countdown padding from LRC: first lyric at {first_lyric_time:.2f}s")
+                return (True, self.COUNTDOWN_PADDING_SECONDS)
+            
+            return (False, 0.0)
+            
+        except Exception as e:
+            self.logger.warning(f"Failed to detect countdown padding from LRC file: {e}")
+            return (False, 0.0)
+
     def find_best_split_point(self, line):
         """
         Find the best split point in a line based on the specified criteria.
@@ -138,23 +195,43 @@ class LyricsProcessor:
         lyrics_video_path = os.path.join(lyrics_dir, f"{sanitized_artist} - {sanitized_title} (With Vocals).mkv")
         lyrics_lrc_path = os.path.join(lyrics_dir, f"{sanitized_artist} - {sanitized_title} (Karaoke).lrc")
 
-        # If files exist in parent directory, return early
+        # If files exist in parent directory, return early (but detect countdown padding first)
         if os.path.exists(parent_video_path) and os.path.exists(parent_lrc_path):
-            self.logger.info(f"Found existing video and LRC files in parent directory, skipping transcription")
+            self.logger.info("Found existing video and LRC files in parent directory, skipping transcription")
+            
+            # Detect countdown padding from existing LRC file
+            countdown_padding_added, countdown_padding_seconds = self._detect_countdown_padding_from_lrc(parent_lrc_path)
+            
+            if countdown_padding_added:
+                self.logger.info(f"Existing files have countdown padding: {countdown_padding_seconds}s")
+            
             return {
                 "lrc_filepath": parent_lrc_path,
                 "ass_filepath": parent_video_path,
+                "countdown_padding_added": countdown_padding_added,
+                "countdown_padding_seconds": countdown_padding_seconds,
+                "padded_audio_filepath": None,  # Original padded audio may not exist
             }
 
-        # If files exist in lyrics directory, copy to parent and return
+        # If files exist in lyrics directory, copy to parent and return (but detect countdown padding first)
         if os.path.exists(lyrics_video_path) and os.path.exists(lyrics_lrc_path):
-            self.logger.info(f"Found existing video and LRC files in lyrics directory, copying to parent")
+            self.logger.info("Found existing video and LRC files in lyrics directory, copying to parent")
             os.makedirs(track_output_dir, exist_ok=True)
             shutil.copy2(lyrics_video_path, parent_video_path)
             shutil.copy2(lyrics_lrc_path, parent_lrc_path)
+            
+            # Detect countdown padding from existing LRC file
+            countdown_padding_added, countdown_padding_seconds = self._detect_countdown_padding_from_lrc(parent_lrc_path)
+            
+            if countdown_padding_added:
+                self.logger.info(f"Existing files have countdown padding: {countdown_padding_seconds}s")
+            
             return {
                 "lrc_filepath": parent_lrc_path,
                 "ass_filepath": parent_video_path,
+                "countdown_padding_added": countdown_padding_added,
+                "countdown_padding_seconds": countdown_padding_seconds,
+                "padded_audio_filepath": None,  # Original padded audio may not exist
             }
 
         # Create lyrics directory if it doesn't exist

karaoke_gen/utils/bulk_cli.py

@@ -19,6 +19,9 @@ from karaoke_gen.karaoke_finalise import KaraokeFinalise
 # Global logger
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)  # Set initial log level
+# Prevent log propagation to root logger to avoid duplicate logs
+# when external packages (like lyrics_converter) configure root logger handlers
+logger.propagate = False
 
 
 async def process_track_prep(row, args, logger, log_formatter):

karaoke_gen/utils/cli_args.py

@@ -208,6 +208,11 @@ def create_parser(prog: str = "karaoke-gen") -> argparse.ArgumentParser:
         default="flac",
         help="Optional: format / file extension for instrumental track to use for remux (default: %(default)s). Example: --instrumental_format=mp3",
     )
+    audio_group.add_argument(
+        "--skip_instrumental_review",
+        action="store_true",
+        help="Optional: Skip the interactive instrumental review UI and use the old numeric selection. Example: --skip_instrumental_review",
+    )
 
     # Lyrics Configuration
     lyrics_group = parser.add_argument_group("Lyrics Configuration")
@@ -347,8 +352,10 @@ def create_parser(prog: str = "karaoke-gen") -> argparse.ArgumentParser:
     )
     remote_group.add_argument(
         "--review-ui-url",
-        default=os.environ.get('REVIEW_UI_URL', 'https://lyrics.nomadkaraoke.com'),
-        help="Lyrics review UI URL (default: https://lyrics.nomadkaraoke.com)",
+        default=os.environ.get('REVIEW_UI_URL', os.environ.get('LYRICS_REVIEW_UI_URL', 'https://lyrics.nomadkaraoke.com')),
+        help="Lyrics review UI URL. Default: 'https://lyrics.nomadkaraoke.com'. "
+             "Use 'http://localhost:5173' for Vite dev server during development. "
+             "(env: REVIEW_UI_URL or LYRICS_REVIEW_UI_URL)",
     )
     remote_group.add_argument(
         "--poll-interval",

karaoke_gen/utils/gen_cli.py

@@ -14,14 +14,295 @@ import sys
 import json
 import asyncio
 import time
+import glob
 import pyperclip
 from karaoke_gen import KaraokePrep
 from karaoke_gen.karaoke_finalise import KaraokeFinalise
+from karaoke_gen.audio_fetcher import UserCancelledError
+from karaoke_gen.instrumental_review import (
+    AudioAnalyzer,
+    WaveformGenerator,
+    InstrumentalReviewServer,
+)
 from .cli_args import create_parser, process_style_overrides, is_url, is_file
 
 
+def _resolve_path_for_cwd(path: str, track_dir: str) -> str:
+    """
+    Resolve a path that may have been created relative to the original working directory.
+    
+    After os.chdir(track_dir), paths like './TrackDir/stems/file.flac' become invalid.
+    This function converts such paths to work from the new current directory.
+    
+    Args:
+        path: The path to resolve (may be relative or absolute)
+        track_dir: The track directory we've chdir'd into
+        
+    Returns:
+        A path that's valid from the current working directory
+    """
+    if os.path.isabs(path):
+        return path
+    
+    # Normalize both paths for comparison
+    norm_path = os.path.normpath(path)
+    norm_track_dir = os.path.normpath(track_dir)
+    
+    # If path starts with track_dir, strip it to get the relative path from within track_dir
+    # e.g., './Four Lanes Male Choir - The White Rose/stems/file.flac' -> 'stems/file.flac'
+    if norm_path.startswith(norm_track_dir + os.sep):
+        return norm_path[len(norm_track_dir) + 1:]
+    elif norm_path.startswith(norm_track_dir):
+        return norm_path[len(norm_track_dir):].lstrip(os.sep) or '.'
+    
+    # If path doesn't start with track_dir, it might already be relative to track_dir
+    # or it's a path that doesn't need transformation
+    return path
+
+
+def auto_select_instrumental(track: dict, track_dir: str, logger: logging.Logger) -> str:
+    """
+    Auto-select the best instrumental file when --skip_instrumental_review is used.
+    
+    Selection priority:
+    1. Padded combined instrumental (+BV) - synchronized with vocals + backing vocals
+    2. Non-padded combined instrumental (+BV) - has backing vocals
+    3. Padded clean instrumental - synchronized with vocals
+    4. Non-padded clean instrumental - basic instrumental
+    
+    Args:
+        track: The track dictionary from KaraokePrep containing separated audio info
+        track_dir: The track output directory (we're already chdir'd into it)
+        logger: Logger instance
+        
+    Returns:
+        Path to the selected instrumental file
+        
+    Raises:
+        FileNotFoundError: If no suitable instrumental file can be found
+    """
+    separated = track.get("separated_audio", {})
+    
+    # Look for combined instrumentals first (they include backing vocals)
+    combined = separated.get("combined_instrumentals", {})
+    for model, path in combined.items():
+        if path:
+            resolved = _resolve_path_for_cwd(path, track_dir)
+            # Prefer padded version if it exists
+            base, ext = os.path.splitext(resolved)
+            padded = f"{base} (Padded){ext}"
+            if os.path.exists(padded):
+                logger.info(f"Auto-selected padded combined instrumental: {padded}")
+                return padded
+            if os.path.exists(resolved):
+                logger.info(f"Auto-selected combined instrumental: {resolved}")
+                return resolved
+    
+    # Fall back to clean instrumental
+    clean = separated.get("clean_instrumental", {})
+    if clean.get("instrumental"):
+        resolved = _resolve_path_for_cwd(clean["instrumental"], track_dir)
+        # Prefer padded version if it exists
+        base, ext = os.path.splitext(resolved)
+        padded = f"{base} (Padded){ext}"
+        if os.path.exists(padded):
+            logger.info(f"Auto-selected padded clean instrumental: {padded}")
+            return padded
+        if os.path.exists(resolved):
+            logger.info(f"Auto-selected clean instrumental: {resolved}")
+            return resolved
+    
+    # If separated_audio doesn't have what we need, search the directory
+    # This handles edge cases and custom instrumentals
+    logger.info("No instrumental found in separated_audio, searching directory...")
+    instrumental_files = glob.glob("*(Instrumental*.flac") + glob.glob("*(Instrumental*.wav")
+    
+    # Sort to prefer padded versions and combined instrumentals
+    padded_combined = [f for f in instrumental_files if "(Padded)" in f and "+BV" in f]
+    if padded_combined:
+        logger.info(f"Auto-selected from directory: {padded_combined[0]}")
+        return padded_combined[0]
+    
+    padded_files = [f for f in instrumental_files if "(Padded)" in f]
+    if padded_files:
+        logger.info(f"Auto-selected from directory: {padded_files[0]}")
+        return padded_files[0]
+    
+    combined_files = [f for f in instrumental_files if "+BV" in f]
+    if combined_files:
+        logger.info(f"Auto-selected from directory: {combined_files[0]}")
+        return combined_files[0]
+    
+    if instrumental_files:
+        logger.info(f"Auto-selected from directory: {instrumental_files[0]}")
+        return instrumental_files[0]
+    
+    raise FileNotFoundError(
+        "No instrumental file found. Audio separation may have failed. "
+        "Check the stems/ directory for separated audio files."
+    )
+
+
+def run_instrumental_review(track: dict, logger: logging.Logger) -> str | None:
+    """
+    Run the instrumental review UI to let user select the best instrumental track.
+    
+    This analyzes the backing vocals, generates a waveform, and opens a browser
+    with an interactive UI for reviewing and selecting the instrumental.
+    
+    Args:
+        track: The track dictionary from KaraokePrep containing separated audio info
+        logger: Logger instance
+        
+    Returns:
+        Path to the selected instrumental file, or None to use the old numeric selection
+    """
+    track_dir = track.get("track_output_dir", ".")
+    artist = track.get("artist", "")
+    title = track.get("title", "")
+    base_name = f"{artist} - {title}"
+    
+    # Get separation results
+    separated = track.get("separated_audio", {})
+    if not separated:
+        logger.info("No separated audio found, skipping instrumental review UI")
+        return None
+    
+    # Find the backing vocals file
+    # Note: Paths in separated_audio may be relative to the original working directory,
+    # but we've already chdir'd into track_dir. Use _resolve_path_for_cwd to fix paths.
+    backing_vocals_path = None
+    backing_vocals_result = separated.get("backing_vocals", {})
+    for model, paths in backing_vocals_result.items():
+        if paths.get("backing_vocals"):
+            backing_vocals_path = _resolve_path_for_cwd(paths["backing_vocals"], track_dir)
+            break
+    
+    if not backing_vocals_path or not os.path.exists(backing_vocals_path):
+        logger.info("No backing vocals file found, skipping instrumental review UI")
+        return None
+    
+    # Find the clean instrumental file
+    clean_result = separated.get("clean_instrumental", {})
+    raw_clean_path = clean_result.get("instrumental")
+    clean_instrumental_path = _resolve_path_for_cwd(raw_clean_path, track_dir) if raw_clean_path else None
+    
+    if not clean_instrumental_path or not os.path.exists(clean_instrumental_path):
+        logger.info("No clean instrumental file found, skipping instrumental review UI")
+        return None
+    
+    # Find the combined instrumental (with backing vocals) file - these have "(Padded)" suffix if padded
+    combined_result = separated.get("combined_instrumentals", {})
+    with_backing_path = None
+    for model, path in combined_result.items():
+        resolved_path = _resolve_path_for_cwd(path, track_dir) if path else None
+        if resolved_path and os.path.exists(resolved_path):
+            with_backing_path = resolved_path
+            break
+    
+    # Find the original audio file (with vocals)
+    original_audio_path = None
+    raw_original_path = track.get("input_audio_wav")
+    if raw_original_path:
+        original_audio_path = _resolve_path_for_cwd(raw_original_path, track_dir)
+        if not os.path.exists(original_audio_path):
+            logger.warning(f"Original audio file not found: {original_audio_path}")
+            original_audio_path = None
+    
+    try:
+        logger.info("=== Starting Instrumental Review ===")
+        logger.info(f"Analyzing backing vocals: {backing_vocals_path}")
+        
+        # Analyze backing vocals
+        analyzer = AudioAnalyzer()
+        analysis = analyzer.analyze(backing_vocals_path)
+        
+        logger.info(f"Analysis complete:")
+        logger.info(f"  Has audible content: {analysis.has_audible_content}")
+        logger.info(f"  Total duration: {analysis.total_duration_seconds:.1f}s")
+        logger.info(f"  Audible segments: {len(analysis.audible_segments)}")
+        logger.info(f"  Recommendation: {analysis.recommended_selection.value}")
+        
+        # Generate waveform
+        # Note: We're already in track_dir after chdir, so use current directory
+        logger.info("Generating waveform visualization...")
+        waveform_generator = WaveformGenerator()
+        waveform_path = f"{base_name} (Backing Vocals Waveform).png"
+        waveform_generator.generate(
+            audio_path=backing_vocals_path,
+            output_path=waveform_path,
+            segments=analysis.audible_segments,
+        )
+        
+        # Start the review server
+        # Note: We're already in track_dir after chdir, so output_dir is "."
+        logger.info("Starting instrumental review UI...")
+        server = InstrumentalReviewServer(
+            output_dir=".",
+            base_name=base_name,
+            analysis=analysis,
+            waveform_path=waveform_path,
+            backing_vocals_path=backing_vocals_path,
+            clean_instrumental_path=clean_instrumental_path,
+            with_backing_path=with_backing_path,
+            original_audio_path=original_audio_path,
+        )
+        
+        # Start server and open browser, wait for selection
+        server.start_and_open_browser()
+        
+        logger.info("Waiting for instrumental selection in browser...")
+        logger.info("(Close the browser tab or press Ctrl+C to cancel)")
+        
+        try:
+            # Wait for user selection (blocking)
+            server._selection_event.wait()
+            selection = server.get_selection()
+            
+            logger.info(f"User selected: {selection}")
+            
+            # Stop the server
+            server.stop()
+            
+            # Return the selected instrumental path
+            if selection == "clean":
+                return clean_instrumental_path
+            elif selection == "with_backing":
+                return with_backing_path
+            elif selection == "custom":
+                custom_path = server.get_custom_instrumental_path()
+                if custom_path and os.path.exists(custom_path):
+                    return custom_path
+                else:
+                    logger.warning("Custom instrumental not found, falling back to clean")
+                    return clean_instrumental_path
+            elif selection == "uploaded":
+                uploaded_path = server.get_uploaded_instrumental_path()
+                if uploaded_path and os.path.exists(uploaded_path):
+                    return uploaded_path
+                else:
+                    logger.warning("Uploaded instrumental not found, falling back to clean")
+                    return clean_instrumental_path
+            else:
+                logger.warning(f"Unknown selection: {selection}, falling back to numeric selection")
+                return None
+                
+        except KeyboardInterrupt:
+            logger.info("Instrumental review cancelled by user")
+            server.stop()
+            return None
+            
+    except Exception as e:
+        logger.error(f"Error during instrumental review: {e}")
+        logger.info("Falling back to numeric selection")
+        return None
+
+
 async def async_main():
     logger = logging.getLogger(__name__)
+    # Prevent log propagation to root logger to avoid duplicate logs
+    # when external packages (like lyrics_converter) configure root logger handlers
+    logger.propagate = False
     log_handler = logging.StreamHandler()
     log_formatter = logging.Formatter(fmt="%(asctime)s.%(msecs)03d - %(levelname)s - %(module)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
     log_handler.setFormatter(log_formatter)
@@ -31,6 +312,11 @@ async def async_main():
     parser = create_parser(prog="karaoke-gen")
     args = parser.parse_args()
 
+    # Set review UI URL environment variable for the lyrics transcriber review server
+    # This allows development against a local frontend dev server (e.g., http://localhost:5173)
+    if hasattr(args, 'review_ui_url') and args.review_ui_url:
+        os.environ['LYRICS_REVIEW_UI_URL'] = args.review_ui_url
+        
     # Process style overrides
     try:
         style_overrides = process_style_overrides(args.style_override, logger)
@@ -122,7 +408,21 @@ async def async_main():
         kprep.input_media = input_audio_wav
         
         # Run KaraokePrep
-        tracks = await kprep.process()
+        try:
+            tracks = await kprep.process()
+        except UserCancelledError:
+            logger.info("Operation cancelled by user")
+            return
+        except KeyboardInterrupt:
+            logger.info("Operation cancelled by user (Ctrl+C)")
+            return
+        
+        # Filter out None tracks (can happen if prep failed for some tracks)
+        tracks = [t for t in tracks if t is not None] if tracks else []
+        
+        if not tracks:
+            logger.warning("No tracks to process")
+            return
         
         # Load CDG styles if CDG generation is enabled
         cdg_styles = None
@@ -441,7 +741,21 @@ async def async_main():
     kprep = kprep_coroutine
 
     # Create final tracks data structure
-    tracks = await kprep.process()
+    try:
+        tracks = await kprep.process()
+    except UserCancelledError:
+        logger.info("Operation cancelled by user")
+        return
+    except KeyboardInterrupt:
+        logger.info("Operation cancelled by user (Ctrl+C)")
+        return
+
+    # Filter out None tracks (can happen if prep failed for some tracks)
+    tracks = [t for t in tracks if t is not None] if tracks else []
+    
+    if not tracks:
+        logger.warning("No tracks to process")
+        return
 
     # If prep-only mode, we're done
     if args.prep_only:
@@ -461,6 +775,67 @@ async def async_main():
         logger.info(f"Changing to directory: {track_dir}")
         os.chdir(track_dir)
 
+        # Select instrumental file - either via web UI or auto-selection
+        # This ALWAYS produces a selected file - no silent fallback to legacy code
+        selected_instrumental_file = None
+        skip_review = getattr(args, 'skip_instrumental_review', False)
+        
+        if skip_review:
+            # Auto-select instrumental when review is skipped (non-interactive mode)
+            logger.info("Instrumental review skipped (--skip_instrumental_review), auto-selecting instrumental file...")
+            try:
+                selected_instrumental_file = auto_select_instrumental(
+                    track=track,
+                    track_dir=track_dir,
+                    logger=logger,
+                )
+            except FileNotFoundError as e:
+                logger.error(f"Failed to auto-select instrumental: {e}")
+                logger.error("Check that audio separation completed successfully.")
+                sys.exit(1)
+                return  # Explicit return for testing
+        else:
+            # Run instrumental review web UI
+            selected_instrumental_file = run_instrumental_review(
+                track=track,
+                logger=logger,
+            )
+            
+            # If instrumental review failed/returned None, show error and exit
+            # NO SILENT FALLBACK - we want to know if the new flow has issues
+            if selected_instrumental_file is None:
+                logger.error("")
+                logger.error("=" * 70)
+                logger.error("INSTRUMENTAL SELECTION FAILED")
+                logger.error("=" * 70)
+                logger.error("")
+                logger.error("The instrumental review UI could not find the required files.")
+                logger.error("")
+                logger.error("Common causes:")
+                logger.error("  - No backing vocals file was found (check stems/ directory)")
+                logger.error("  - No clean instrumental was found (audio separation may have failed)")
+                logger.error("  - Path resolution failed after directory change")
+                logger.error("")
+                logger.error("To investigate:")
+                logger.error("  - Check the stems/ directory for: *Backing Vocals*.flac and *Instrumental*.flac")
+                logger.error("  - Look for separation errors earlier in the log")
+                logger.error("  - Verify audio separation completed without errors")
+                logger.error("")
+                logger.error("Workarounds:")
+                logger.error("  - Re-run with --skip_instrumental_review to auto-select an instrumental")
+                logger.error("  - Re-run the full pipeline to regenerate stems")
+                logger.error("")
+                sys.exit(1)
+                return  # Explicit return for testing
+        
+        logger.info(f"Selected instrumental file: {selected_instrumental_file}")
+        
+        # Get countdown padding info from track (if vocals were padded, instrumental must match)
+        countdown_padding_seconds = None
+        if track.get("countdown_padding_added", False):
+            countdown_padding_seconds = track.get("countdown_padding_seconds", 3.0)
+            logger.info(f"Countdown padding detected: {countdown_padding_seconds}s (will be applied to instrumental if needed)")
+        
         # Load CDG styles if CDG generation is enabled
         cdg_styles = None
         if args.enable_cdg:
@@ -504,6 +879,8 @@ async def async_main():
             cdg_styles=cdg_styles,
             keep_brand_code=getattr(args, 'keep_brand_code', False),
             non_interactive=args.yes,
+            selected_instrumental_file=selected_instrumental_file,
+            countdown_padding_seconds=countdown_padding_seconds,
         )
 
         try: