karaoke-gen 0.71.42__py3-none-any.whl → 0.75.53__py3-none-any.whl

karaoke_gen/utils/remote_cli.py

@@ -31,11 +31,16 @@ import webbrowser
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 import requests
 
 from .cli_args import create_parser, process_style_overrides, is_url, is_file
+# Use flacfetch's shared display functions for consistent formatting
+from flacfetch import print_releases, Release
+from flacfetch.core.categorize import categorize_releases
+from flacfetch.core.models import TrackQuery
+from flacfetch.interface.cli import print_categorized_releases
 
 
 class JobStatus(str, Enum):
@@ -67,6 +72,7 @@ class JobStatus(str, Enum):
     UPLOADING = "uploading"
     NOTIFYING = "notifying"
     COMPLETE = "complete"
+    PREP_COMPLETE = "prep_complete"  # Batch 6: Prep-only jobs stop here
     FAILED = "failed"
     CANCELLED = "cancelled"
     ERROR = "error"
@@ -134,7 +140,18 @@ class RemoteKaraokeClient:
             return None
     
     def refresh_auth(self) -> bool:
-        """Refresh authentication token."""
+        """Refresh authentication token.
+        
+        Only refreshes if we're using a gcloud-based token. If the user
+        provided a static token via KARAOKE_GEN_AUTH_TOKEN, we keep that
+        since it doesn't expire like gcloud identity tokens.
+        """
+        # Don't refresh if using a static admin token from env
+        if os.environ.get('KARAOKE_GEN_AUTH_TOKEN'):
+            # Already have a valid static token, no need to refresh
+            return True
+        
+        # Try to refresh gcloud identity token
         token = self._get_auth_token_from_gcloud()
         if token:
             self.config.auth_token = token
@@ -272,6 +289,9 @@ class RemoteKaraokeClient:
         clean_instrumental_model: Optional[str] = None,
         backing_vocals_models: Optional[list] = None,
         other_stems_models: Optional[list] = None,
+        # Two-phase workflow (Batch 6)
+        prep_only: bool = False,
+        keep_brand_code: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         Submit a new karaoke generation job from a YouTube/online URL.
@@ -342,6 +362,11 @@ class RemoteKaraokeClient:
             create_request['backing_vocals_models'] = backing_vocals_models
         if other_stems_models:
             create_request['other_stems_models'] = other_stems_models
+        # Two-phase workflow (Batch 6)
+        if prep_only:
+            create_request['prep_only'] = prep_only
+        if keep_brand_code:
+            create_request['keep_brand_code'] = keep_brand_code
         
         self.logger.info(f"Creating URL-based job at {self.config.service_url}/api/jobs/create-from-url")
         
@@ -397,6 +422,9 @@ class RemoteKaraokeClient:
         other_stems_models: Optional[list] = None,
         # Existing instrumental (Batch 3)
         existing_instrumental: Optional[str] = None,
+        # Two-phase workflow (Batch 6)
+        prep_only: bool = False,
+        keep_brand_code: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         Submit a new karaoke generation job with optional style configuration.
@@ -541,6 +569,11 @@ class RemoteKaraokeClient:
             create_request['backing_vocals_models'] = backing_vocals_models
         if other_stems_models:
             create_request['other_stems_models'] = other_stems_models
+        # Two-phase workflow (Batch 6)
+        if prep_only:
+            create_request['prep_only'] = prep_only
+        if keep_brand_code:
+            create_request['keep_brand_code'] = keep_brand_code
         
         response = self._request('POST', '/api/jobs/create-with-upload-urls', json=create_request)
         
@@ -628,6 +661,255 @@ class RemoteKaraokeClient:
         
         return result
     
+    def submit_finalise_only_job(
+        self,
+        prep_folder: str,
+        artist: str,
+        title: str,
+        enable_cdg: bool = True,
+        enable_txt: bool = True,
+        brand_prefix: Optional[str] = None,
+        keep_brand_code: Optional[str] = None,
+        discord_webhook_url: Optional[str] = None,
+        youtube_description: Optional[str] = None,
+        enable_youtube_upload: bool = False,
+        dropbox_path: Optional[str] = None,
+        gdrive_folder_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Submit a finalise-only job with prep output files.
+        
+        This is used when the user previously ran --prep-only and now wants
+        to continue with the finalisation phase using cloud resources.
+        
+        Args:
+            prep_folder: Path to the prep output folder containing stems, screens, etc.
+            artist: Artist name
+            title: Song title
+            enable_cdg: Generate CDG+MP3 package
+            enable_txt: Generate TXT+MP3 package
+            brand_prefix: Brand code prefix (e.g., "NOMAD")
+            keep_brand_code: Preserve existing brand code from folder name
+            discord_webhook_url: Discord webhook for notifications
+            youtube_description: YouTube video description
+            enable_youtube_upload: Enable YouTube upload
+            dropbox_path: Dropbox folder path for organized output
+            gdrive_folder_id: Google Drive folder ID for public share
+        """
+        prep_path = Path(prep_folder)
+        
+        if not prep_path.exists() or not prep_path.is_dir():
+            raise FileNotFoundError(f"Prep folder not found: {prep_folder}")
+        
+        # Detect files in prep folder
+        files_info = []
+        local_files = {}  # file_type -> local_path
+        
+        base_name = f"{artist} - {title}"
+        
+        # Required files - with_vocals video
+        for ext in ['.mkv', '.mov', '.mp4']:
+            with_vocals_path = prep_path / f"{base_name} (With Vocals){ext}"
+            if with_vocals_path.exists():
+                files_info.append({
+                    'filename': with_vocals_path.name,
+                    'content_type': f'video/{ext[1:]}',
+                    'file_type': 'with_vocals'
+                })
+                local_files['with_vocals'] = str(with_vocals_path)
+                break
+        
+        if 'with_vocals' not in local_files:
+            raise FileNotFoundError(f"with_vocals video not found in {prep_folder}")
+        
+        # Title screen
+        for ext in ['.mov', '.mkv', '.mp4']:
+            title_path = prep_path / f"{base_name} (Title){ext}"
+            if title_path.exists():
+                files_info.append({
+                    'filename': title_path.name,
+                    'content_type': f'video/{ext[1:]}',
+                    'file_type': 'title_screen'
+                })
+                local_files['title_screen'] = str(title_path)
+                break
+        
+        if 'title_screen' not in local_files:
+            raise FileNotFoundError(f"title_screen video not found in {prep_folder}")
+        
+        # End screen
+        for ext in ['.mov', '.mkv', '.mp4']:
+            end_path = prep_path / f"{base_name} (End){ext}"
+            if end_path.exists():
+                files_info.append({
+                    'filename': end_path.name,
+                    'content_type': f'video/{ext[1:]}',
+                    'file_type': 'end_screen'
+                })
+                local_files['end_screen'] = str(end_path)
+                break
+        
+        if 'end_screen' not in local_files:
+            raise FileNotFoundError(f"end_screen video not found in {prep_folder}")
+        
+        # Instrumentals (at least one required)
+        stems_dir = prep_path / 'stems'
+        if stems_dir.exists():
+            for stem_file in stems_dir.iterdir():
+                if 'Instrumental' in stem_file.name and stem_file.suffix.lower() == '.flac':
+                    if '+BV' not in stem_file.name:
+                        if 'instrumental_clean' not in local_files:
+                            files_info.append({
+                                'filename': stem_file.name,
+                                'content_type': 'audio/flac',
+                                'file_type': 'instrumental_clean'
+                            })
+                            local_files['instrumental_clean'] = str(stem_file)
+                    elif '+BV' in stem_file.name:
+                        if 'instrumental_backing' not in local_files:
+                            files_info.append({
+                                'filename': stem_file.name,
+                                'content_type': 'audio/flac',
+                                'file_type': 'instrumental_backing'
+                            })
+                            local_files['instrumental_backing'] = str(stem_file)
+        
+        # Also check root for instrumental files
+        for stem_file in prep_path.iterdir():
+            if 'Instrumental' in stem_file.name and stem_file.suffix.lower() == '.flac':
+                if '+BV' not in stem_file.name and 'instrumental_clean' not in local_files:
+                    files_info.append({
+                        'filename': stem_file.name,
+                        'content_type': 'audio/flac',
+                        'file_type': 'instrumental_clean'
+                    })
+                    local_files['instrumental_clean'] = str(stem_file)
+                elif '+BV' in stem_file.name and 'instrumental_backing' not in local_files:
+                    files_info.append({
+                        'filename': stem_file.name,
+                        'content_type': 'audio/flac',
+                        'file_type': 'instrumental_backing'
+                    })
+                    local_files['instrumental_backing'] = str(stem_file)
+        
+        if 'instrumental_clean' not in local_files and 'instrumental_backing' not in local_files:
+            raise FileNotFoundError(f"No instrumental file found in {prep_folder}")
+        
+        # Optional files - LRC
+        lrc_path = prep_path / f"{base_name} (Karaoke).lrc"
+        if lrc_path.exists():
+            files_info.append({
+                'filename': lrc_path.name,
+                'content_type': 'text/plain',
+                'file_type': 'lrc'
+            })
+            local_files['lrc'] = str(lrc_path)
+        
+        # Optional - Title/End JPG/PNG
+        for img_type, file_type in [('Title', 'title'), ('End', 'end')]:
+            for ext in ['.jpg', '.png']:
+                img_path = prep_path / f"{base_name} ({img_type}){ext}"
+                if img_path.exists():
+                    files_info.append({
+                        'filename': img_path.name,
+                        'content_type': f'image/{ext[1:]}',
+                        'file_type': f'{file_type}_{ext[1:]}'
+                    })
+                    local_files[f'{file_type}_{ext[1:]}'] = str(img_path)
+        
+        self.logger.info(f"Found {len(files_info)} files in prep folder")
+        for file_type in local_files:
+            self.logger.info(f"  {file_type}: {Path(local_files[file_type]).name}")
+        
+        # Create finalise-only job
+        create_request = {
+            'artist': artist,
+            'title': title,
+            'files': files_info,
+            'enable_cdg': enable_cdg,
+            'enable_txt': enable_txt,
+        }
+        
+        if brand_prefix:
+            create_request['brand_prefix'] = brand_prefix
+        if keep_brand_code:
+            create_request['keep_brand_code'] = keep_brand_code
+        if discord_webhook_url:
+            create_request['discord_webhook_url'] = discord_webhook_url
+        if youtube_description:
+            create_request['youtube_description'] = youtube_description
+        if enable_youtube_upload:
+            create_request['enable_youtube_upload'] = enable_youtube_upload
+        if dropbox_path:
+            create_request['dropbox_path'] = dropbox_path
+        if gdrive_folder_id:
+            create_request['gdrive_folder_id'] = gdrive_folder_id
+        
+        self.logger.info(f"Creating finalise-only job at {self.config.service_url}/api/jobs/create-finalise-only")
+        
+        response = self._request('POST', '/api/jobs/create-finalise-only', json=create_request)
+        
+        if response.status_code != 200:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise RuntimeError(f"Error creating finalise-only job: {error_detail}")
+        
+        create_result = response.json()
+        if create_result.get('status') != 'success':
+            raise RuntimeError(f"Error creating finalise-only job: {create_result}")
+        
+        job_id = create_result['job_id']
+        upload_urls = create_result['upload_urls']
+        
+        self.logger.info(f"Job {job_id} created. Uploading {len(upload_urls)} files directly to storage...")
+        
+        # Upload each file
+        uploaded_files = []
+        for url_info in upload_urls:
+            file_type = url_info['file_type']
+            signed_url = url_info['upload_url']
+            content_type = url_info['content_type']
+            local_path = local_files.get(file_type)
+            
+            if not local_path:
+                self.logger.warning(f"No local file found for file_type: {file_type}")
+                continue
+            
+            file_size = os.path.getsize(local_path)
+            file_size_mb = file_size / (1024 * 1024)
+            self.logger.info(f"  Uploading {file_type} ({file_size_mb:.1f} MB)...")
+            
+            success = self._upload_file_to_signed_url(signed_url, local_path, content_type)
+            if not success:
+                raise RuntimeError(f"Failed to upload {file_type} to storage")
+            
+            uploaded_files.append(file_type)
+            self.logger.info(f"  ✓ Uploaded {file_type}")
+        
+        # Mark uploads complete
+        self.logger.info(f"Notifying backend that uploads are complete...")
+        
+        complete_request = {
+            'uploaded_files': uploaded_files
+        }
+        
+        response = self._request('POST', f'/api/jobs/{job_id}/finalise-uploads-complete', json=complete_request)
+        
+        if response.status_code != 200:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise RuntimeError(f"Error completing finalise-only uploads: {error_detail}")
+        
+        result = response.json()
+        if result.get('status') != 'success':
+            raise RuntimeError(f"Error completing finalise-only uploads: {result}")
+        
+        return result
+    
     def get_job(self, job_id: str) -> Dict[str, Any]:
         """Get job status and details."""
         response = self._request('GET', f'/api/jobs/{job_id}')
@@ -813,7 +1095,8 @@ class RemoteKaraokeClient:
             if url.startswith('/'):
                 url = f"{self.config.service_url}{url}"
             
-            response = requests.get(url, stream=True, timeout=600)
+            # Use session headers (includes Authorization) for authenticated downloads
+            response = self.session.get(url, stream=True, timeout=600)
             if response.status_code != 200:
                 return False
             
@@ -924,6 +1207,7 @@ class RemoteKaraokeClient:
             artist: Artist name to search for
             title: Song title to search for
             auto_download: Automatically select best audio source (skip interactive selection)
+            style_params_path: Path to style_params.json (optional)
             ... other args same as submit_job()
         
         Returns:
@@ -964,6 +1248,40 @@ class RemoteKaraokeClient:
         if other_stems_models:
             request_data['other_stems_models'] = other_stems_models
         
+        # Prepare style files for upload if provided
+        style_files = []
+        local_style_files: Dict[str, str] = {}  # file_type -> local_path
+        
+        if style_params_path and os.path.isfile(style_params_path):
+            self.logger.info(f"Parsing style configuration: {style_params_path}")
+            
+            # Add the style_params.json itself
+            style_files.append({
+                'filename': Path(style_params_path).name,
+                'content_type': 'application/json',
+                'file_type': 'style_params'
+            })
+            local_style_files['style_params'] = style_params_path
+            
+            # Parse style params to find referenced files (backgrounds, fonts)
+            style_assets = self._parse_style_params(style_params_path)
+            
+            for asset_key, asset_path in style_assets.items():
+                if os.path.isfile(asset_path):
+                    # Use full path for content type detection (not just extension)
+                    content_type = self._get_content_type(asset_path)
+                    style_files.append({
+                        'filename': Path(asset_path).name,
+                        'content_type': content_type,
+                        'file_type': asset_key  # e.g., 'style_intro_background'
+                    })
+                    local_style_files[asset_key] = asset_path
+                    self.logger.info(f"  Will upload style asset: {asset_key}")
+            
+            if style_files:
+                request_data['style_files'] = style_files
+                self.logger.info(f"Including {len(style_files)} style files in request")
+        
         response = self._request('POST', '/api/audio-search/search', json=request_data)
         
         if response.status_code == 404:
@@ -980,7 +1298,52 @@ class RemoteKaraokeClient:
                 error_detail = response.text
             raise RuntimeError(f"Error searching for audio: {error_detail}")
         
-        return response.json()
+        result = response.json()
+        
+        # Upload style files if we have signed URLs
+        style_upload_urls = result.get('style_upload_urls', [])
+        if style_upload_urls and local_style_files:
+            self.logger.info(f"Uploading {len(style_upload_urls)} style files...")
+            
+            for url_info in style_upload_urls:
+                file_type = url_info['file_type']
+                upload_url = url_info['upload_url']
+                
+                local_path = local_style_files.get(file_type)
+                if not local_path:
+                    self.logger.warning(f"No local file for {file_type}, skipping upload")
+                    continue
+                
+                self.logger.info(f"  Uploading {file_type}: {Path(local_path).name}")
+                
+                try:
+                    with open(local_path, 'rb') as f:
+                        file_content = f.read()
+                    
+                    # Use the content type from the original file info, not re-derived
+                    # This ensures it matches the signed URL which was generated with
+                    # the same content type we specified in the request
+                    content_type = self._get_content_type(local_path)
+                    
+                    # Use PUT to upload directly to signed URL
+                    upload_response = requests.put(
+                        upload_url,
+                        data=file_content,
+                        headers={'Content-Type': content_type},
+                        timeout=60
+                    )
+                    
+                    if upload_response.status_code not in (200, 201):
+                        self.logger.error(f"Failed to upload {file_type}: {upload_response.status_code}")
+                    else:
+                        self.logger.info(f"    ✓ Uploaded {file_type}")
+                        
+                except Exception as e:
+                    self.logger.error(f"Error uploading {file_type}: {e}")
+            
+            self.logger.info("Style file uploads complete")
+        
+        return result
     
     def get_audio_search_results(self, job_id: str) -> Dict[str, Any]:
         """Get audio search results for a job awaiting selection."""
@@ -1054,6 +1417,7 @@ class JobMonitor:
         'uploading': 'Uploading to distribution services',
         'notifying': 'Sending notifications',
         'complete': 'All processing complete',
+        'prep_complete': 'Prep phase complete - ready for local finalisation',
         'failed': 'Job failed',
         'cancelled': 'Job cancelled',
     }
@@ -1062,6 +1426,54 @@ class JobMonitor:
         """Get user-friendly description for a status."""
         return self.STATUS_DESCRIPTIONS.get(status, status)
     
+    def _show_download_progress(self, job_data: Dict[str, Any]) -> None:
+        """Show detailed download progress during audio download."""
+        try:
+            # Get provider from job state_data
+            state_data = job_data.get('state_data', {})
+            provider = state_data.get('selected_audio_provider', 'unknown')
+            
+            # For non-torrent providers (YouTube), just show simple message
+            if provider.lower() == 'youtube':
+                self.logger.info(f"  [Downloading from YouTube...]")
+                return
+            
+            # Query health endpoint for transmission status (torrent providers)
+            health_url = f"{self.config.service_url}/api/health/detailed"
+            response = requests.get(health_url, timeout=5)
+            
+            if response.status_code == 200:
+                health = response.json()
+                transmission = health.get('dependencies', {}).get('transmission', {})
+                
+                if transmission.get('available'):
+                    torrents = transmission.get('torrents', [])
+                    if torrents:
+                        # Show info about active torrents
+                        for t in torrents:
+                            progress = t.get('progress', 0)
+                            peers = t.get('peers', 0)
+                            speed = t.get('download_speed', 0)
+                            stalled = t.get('stalled', False)
+                            
+                            if stalled:
+                                self.logger.info(f"  [Downloading from {provider}] {progress:.1f}% - STALLED (no peers)")
+                            elif progress < 100:
+                                self.logger.info(f"  [Downloading from {provider}] {progress:.1f}% @ {speed:.1f} KB/s ({peers} peers)")
+                            else:
+                                self.logger.info(f"  [Downloading from {provider}] Complete, processing...")
+                    else:
+                        # No torrents - might be starting or YouTube download
+                        self.logger.info(f"  [Downloading from {provider}] Starting download...")
+                else:
+                    self.logger.info(f"  [Downloading from {provider}] Transmission not available - download may fail")
+            else:
+                self.logger.info(f"  [Downloading from {provider}]...")
+                
+        except Exception as e:
+            # Fall back to simple message
+            self.logger.info(f"  [Downloading audio...]")
+    
     def open_browser(self, url: str) -> None:
         """Open URL in the default browser."""
         system = platform.system()
@@ -1081,16 +1493,21 @@ class JobMonitor:
         base_api_url = f"{self.config.service_url}/api/review/{job_id}"
         encoded_api_url = urllib.parse.quote(base_api_url, safe='')
         
-        # Try to get audio hash from job data
+        # Try to get audio hash and review token from job data
+        audio_hash = ''
+        review_token = ''
         try:
             job_data = self.client.get_job(job_id)
             audio_hash = job_data.get('audio_hash', '')
+            review_token = job_data.get('review_token', '')
         except Exception:
-            audio_hash = ''
+            pass
         
         url = f"{self.config.review_ui_url}/?baseApiUrl={encoded_api_url}"
         if audio_hash:
             url += f"&audioHash={audio_hash}"
+        if review_token:
+            url += f"&reviewToken={review_token}"
         
         self.logger.info(f"Opening lyrics review UI: {url}")
         self.open_browser(url)
@@ -1250,8 +1667,75 @@ class JobMonitor:
         except Exception as e:
             self.logger.error(f"Error submitting selection: {e}")
     
+    def _convert_api_result_to_release_dict(self, result: dict) -> dict:
+        """
+        Convert API search result to a dict compatible with flacfetch's Release.from_dict().
+        
+        This enables using flacfetch's shared display functions for consistent,
+        rich formatting between local and remote CLIs.
+        """
+        # Build quality dict from API response
+        quality_data = result.get('quality_data') or {
+            "format": "OTHER",
+            "media": "OTHER",
+        }
+        
+        return {
+            "title": result.get('title', ''),
+            "artist": result.get('artist', ''),
+            "source_name": result.get('provider', 'Unknown'),
+            "download_url": result.get('url'),
+            "info_hash": result.get('source_id'),
+            "size_bytes": result.get('size_bytes'),
+            "year": result.get('year'),
+            "edition_info": result.get('edition_info'),
+            "label": result.get('label'),
+            "release_type": result.get('release_type'),
+            "seeders": result.get('seeders'),
+            "channel": result.get('channel'),
+            "view_count": result.get('view_count'),
+            "duration_seconds": result.get('duration'),
+            "target_file": result.get('target_file'),
+            "target_file_size": result.get('target_file_size'),
+            "track_pattern": result.get('track_pattern'),
+            "match_score": result.get('match_score', 0.0),
+            "quality": quality_data,
+            # Pre-computed fields
+            "formatted_size": result.get('formatted_size'),
+            "formatted_duration": result.get('formatted_duration'),
+            "formatted_views": result.get('formatted_views'),
+            "is_lossless": result.get('is_lossless', False),
+            "quality_str": result.get('quality_str') or result.get('quality', ''),
+        }
+    
+    def _convert_to_release_objects(self, release_dicts: List[Dict[str, Any]]) -> List[Release]:
+        """
+        Convert API result dicts to Release objects for categorization.
+        
+        Used by handle_audio_selection() to enable categorized display
+        for large result sets (10+ results).
+        
+        Args:
+            release_dicts: List of dicts in Release-compatible format
+            
+        Returns:
+            List of Release objects (skipping any that fail to convert)
+        """
+        releases = []
+        for d in release_dicts:
+            try:
+                releases.append(Release.from_dict(d))
+            except Exception as e:
+                self.logger.debug(f"Failed to convert result to Release: {e}")
+        return releases
+    
     def handle_audio_selection(self, job_id: str) -> None:
-        """Handle audio source selection interaction (Batch 5)."""
+        """Handle audio source selection interaction (Batch 5).
+        
+        For 10+ results, uses categorized display (grouped by Top Seeded,
+        Album Releases, Hi-Res, etc.) with a 'more' command to show full list.
+        For smaller result sets, uses flat list display.
+        """
         self.logger.info("=" * 60)
         self.logger.info("AUDIO SOURCE SELECTION NEEDED")
         self.logger.info("=" * 60)
@@ -1260,6 +1744,8 @@ class JobMonitor:
             # Get search results
             results_data = self.client.get_audio_search_results(job_id)
             results = results_data.get('results', [])
+            artist = results_data.get('artist', 'Unknown')
+            title = results_data.get('title', 'Unknown')
             
             if not results:
                 self.logger.error("No search results available")
@@ -1270,42 +1756,75 @@ class JobMonitor:
                 self.logger.info("Non-interactive mode: Auto-selecting first result")
                 selection_index = 0
             else:
-                self.logger.info("")
-                self.logger.info("Choose which audio source to download:")
-                self.logger.info("")
+                # Convert API results to Release-compatible dicts for flacfetch display
+                # This gives us the same rich, colorized output as the local CLI
+                release_dicts = [self._convert_api_result_to_release_dict(r) for r in results]
                 
-                for result in results:
-                    index = result.get('index', 0)
-                    provider = result.get('provider', 'Unknown')
-                    artist = result.get('artist', 'Unknown')
-                    title = result.get('title', 'Unknown')
-                    quality = result.get('quality', '')
-                    duration = result.get('duration')
-                    
-                    # Format duration if available
-                    duration_str = ""
-                    if duration:
-                        minutes = duration // 60
-                        seconds = duration % 60
-                        duration_str = f" [{minutes}:{seconds:02d}]"
-                    
-                    quality_str = f" ({quality})" if quality else ""
-                    
-                    self.logger.info(f"  {index + 1}) [{provider}] {artist} - {title}{quality_str}{duration_str}")
+                # Convert to Release objects for categorization
+                release_objects = self._convert_to_release_objects(release_dicts)
                 
-                self.logger.info("")
+                # Use categorized display for large result sets (10+)
+                # This groups results into categories: Top Seeded, Album Releases, Hi-Res, etc.
+                use_categorized = len(release_objects) >= 10
+                
+                if use_categorized:
+                    # Create query for categorization
+                    query = TrackQuery(artist=artist, title=title)
+                    categorized = categorize_releases(release_objects, query)
+                    # print_categorized_releases returns the flattened list of displayed releases
+                    display_releases = print_categorized_releases(categorized, target_artist=artist, use_colors=True)
+                    showing_categorized = True
+                else:
+                    # Small result set - use simple flat list
+                    print_releases(release_dicts, target_artist=artist, use_colors=True)
+                    display_releases = release_objects
+                    showing_categorized = False
                 
                 selection_index = -1
                 while selection_index < 0:
                     try:
-                        choice = input(f"Enter your choice (1-{len(results)}): ").strip()
+                        if showing_categorized:
+                            prompt = f"\nSelect (1-{len(display_releases)}), 'more' for full list, 0 to cancel: "
+                        else:
+                            prompt = f"\nSelect a release (1-{len(display_releases)}, 0 to cancel): "
+                        
+                        choice = input(prompt).strip().lower()
+                        
+                        if choice == "0":
+                            self.logger.info("Selection cancelled by user")
+                            raise KeyboardInterrupt
+                        
+                        # Handle 'more' command to show full flat list
+                        if choice in ('more', 'm', 'all', 'a') and showing_categorized:
+                            print("\n" + "=" * 60)
+                            print("FULL LIST (all results)")
+                            print("=" * 60 + "\n")
+                            print_releases(release_dicts, target_artist=artist, use_colors=True)
+                            display_releases = release_objects
+                            showing_categorized = False
+                            continue
+                        
                         choice_num = int(choice)
-                        if 1 <= choice_num <= len(results):
-                            selection_index = choice_num - 1
+                        if 1 <= choice_num <= len(display_releases):
+                            # Map selection back to original results index for API call
+                            selected_release = display_releases[choice_num - 1]
+                            
+                            # Find matching index in original results by download_url
+                            selection_index = self._find_original_index(
+                                selected_release, results, release_objects
+                            )
+                            
+                            if selection_index < 0:
+                                # Fallback: use display index if mapping fails
+                                self.logger.warning("Could not map selection to original index, using display index")
+                                selection_index = choice_num - 1
                         else:
-                            self.logger.error(f"Please enter a number between 1 and {len(results)}")
+                            print(f"Please enter a number between 0 and {len(display_releases)}")
                     except ValueError:
-                        self.logger.error("Please enter a valid number")
+                        if showing_categorized:
+                            print("Please enter a number or 'more'")
+                        else:
+                            print("Please enter a valid number")
                     except KeyboardInterrupt:
                         print()
                         raise
@@ -1323,10 +1842,80 @@ class JobMonitor:
                 
         except Exception as e:
             self.logger.error(f"Error handling audio selection: {e}")
+    
+    def _find_original_index(
+        self,
+        selected_release: Release,
+        original_results: List[Dict[str, Any]],
+        release_objects: List[Release],
+    ) -> int:
+        """
+        Map a selected Release back to its index in the original API results.
+        
+        This is needed because categorized display may reorder results,
+        but the API selection endpoint needs the original index.
+        
+        Args:
+            selected_release: The Release object user selected
+            original_results: Original API results (list of dicts)
+            release_objects: Release objects in same order as original_results
+            
+        Returns:
+            Index in original_results, or -1 if not found
+        """
+        # First try: match by object identity in release_objects
+        for i, release in enumerate(release_objects):
+            if release is selected_release:
+                return i
+        
+        # Second try: match by download_url
+        selected_url = getattr(selected_release, 'download_url', None)
+        if selected_url:
+            for i, r in enumerate(original_results):
+                if r.get('url') == selected_url:
+                    return i
+        
+        # Third try: match by info_hash (for torrent sources)
+        selected_hash = getattr(selected_release, 'info_hash', None)
+        if selected_hash:
+            for i, r in enumerate(original_results):
+                if r.get('source_id') == selected_hash:
+                    return i
+        
+        # Fourth try: match by title + artist + provider
+        selected_title = getattr(selected_release, 'title', '')
+        selected_artist = getattr(selected_release, 'artist', '')
+        selected_source = getattr(selected_release, 'source_name', '')
+        
+        for i, r in enumerate(original_results):
+            if (r.get('title') == selected_title and 
+                r.get('artist') == selected_artist and
+                r.get('provider') == selected_source):
+                return i
+        
+        return -1
 
     def _open_instrumental_review_and_wait(self, job_id: str) -> None:
         """Open browser to instrumental review UI and wait for selection."""
-        review_url = f"{self.config.review_ui_url}/jobs/{job_id}/instrumental-review"
+        # Get instrumental token from job data
+        instrumental_token = ''
+        try:
+            job_data = self.client.get_job(job_id)
+            instrumental_token = job_data.get('instrumental_token', '')
+        except Exception:
+            pass
+        
+        # Build the review URL with API endpoint and token
+        # The instrumental UI is hosted at /instrumental/ on the frontend domain
+        base_api_url = f"{self.config.service_url}/api/jobs/{job_id}"
+        encoded_api_url = urllib.parse.quote(base_api_url, safe='')
+        
+        # Use /instrumental/ path on the frontend (same domain as review_ui_url but different path)
+        # review_ui_url is like https://gen.nomadkaraoke.com/lyrics, we want /instrumental/
+        frontend_base = self.config.review_ui_url.rsplit('/', 1)[0]  # Remove /lyrics
+        review_url = f"{frontend_base}/instrumental/?baseApiUrl={encoded_api_url}"
+        if instrumental_token:
+            review_url += f"&instrumentalToken={instrumental_token}"
         
         self.logger.info("")
         self.logger.info("=" * 60)
@@ -1771,9 +2360,15 @@ class JobMonitor:
                     self._polls_without_updates = 0
                 else:
                     self._polls_without_updates += 1
-                    if self._polls_without_updates >= self._heartbeat_interval:
-                        description = self._get_status_description(status)
-                        self.logger.info(f"  [Still processing: {description}]")
+                    # More frequent updates during audio download (every poll)
+                    heartbeat_threshold = 1 if status == 'downloading_audio' else self._heartbeat_interval
+                    if self._polls_without_updates >= heartbeat_threshold:
+                        if status == 'downloading_audio':
+                            # Show detailed download progress including transmission status
+                            self._show_download_progress(job_data)
+                        else:
+                            description = self._get_status_description(status)
+                            self.logger.info(f"  [Still processing: {description}]")
                         self._polls_without_updates = 0
                 
                 # Handle human interaction points
@@ -1799,6 +2394,14 @@ class JobMonitor:
                         self.handle_instrumental_selection(job_id)
                         self._instrumental_prompted = True
                 
+                elif status == 'instrumental_selected':
+                    # Check if this was auto-selected due to existing instrumental
+                    selection = job_data.get('state_data', {}).get('instrumental_selection', '')
+                    if selection == 'custom' and not self._instrumental_prompted:
+                        self.logger.info("")
+                        self.logger.info("Using user-provided instrumental (--existing_instrumental)")
+                        self._instrumental_prompted = True
+                
                 elif status == 'complete':
                     self.logger.info("")
                     self.logger.info("=" * 60)
@@ -1809,6 +2412,24 @@ class JobMonitor:
                     self.download_outputs(job_id, job_data)
                     return 0
                 
+                elif status == 'prep_complete':
+                    self.logger.info("")
+                    self.logger.info("=" * 60)
+                    self.logger.info("PREP PHASE COMPLETE!")
+                    self.logger.info("=" * 60)
+                    self.logger.info(f"Track: {artist} - {title}")
+                    self.logger.info("")
+                    self.logger.info("Downloading all prep outputs...")
+                    self.download_outputs(job_id, job_data)
+                    self.logger.info("")
+                    self.logger.info("To continue with finalisation, run:")
+                    # Use shlex.quote for proper shell escaping of artist/title
+                    import shlex
+                    escaped_artist = shlex.quote(artist)
+                    escaped_title = shlex.quote(title)
+                    self.logger.info(f"  karaoke-gen-remote --finalise-only ./<output_folder> {escaped_artist} {escaped_title}")
+                    return 0
+                
                 elif status in ['failed', 'error']:
                     self.logger.info("")
                     self.logger.error("=" * 60)
@@ -2197,10 +2818,112 @@ def main():
             logger.error(f"Error deleting job: {e}")
             return 1
     
-    # Warn about unsupported features
+    # Handle finalise-only mode (Batch 6)
     if args.finalise_only:
-        logger.error("--finalise-only is not supported in remote mode")
-        return 1
+        logger.info("=" * 60)
+        logger.info("Karaoke Generator (Remote) - Finalise Only Mode")
+        logger.info("=" * 60)
+        
+        # For finalise-only, we expect the current directory to be the prep output folder
+        # OR a folder path as the first argument
+        prep_folder = "."
+        artist_arg_idx = 0
+        
+        if args.args:
+            # Check if first argument is a directory
+            if os.path.isdir(args.args[0]):
+                prep_folder = args.args[0]
+                artist_arg_idx = 1
+            
+            # Get artist and title from arguments
+            if len(args.args) > artist_arg_idx + 1:
+                artist = args.args[artist_arg_idx]
+                title = args.args[artist_arg_idx + 1]
+            elif len(args.args) > artist_arg_idx:
+                logger.error("Finalise-only mode requires both Artist and Title")
+                return 1
+            else:
+                # Try to extract from folder name
+                folder_name = os.path.basename(os.path.abspath(prep_folder))
+                parts = folder_name.split(" - ", 2)
+                if len(parts) >= 2:
+                    # Format: "BRAND-XXXX - Artist - Title" or "Artist - Title"
+                    if "-" in parts[0] and parts[0].split("-")[1].isdigit():
+                        # Has brand code
+                        artist = parts[1] if len(parts) > 2 else "Unknown"
+                        title = parts[2] if len(parts) > 2 else parts[1]
+                    else:
+                        artist = parts[0]
+                        title = parts[1]
+                    logger.info(f"Extracted from folder name: {artist} - {title}")
+                else:
+                    logger.error("Could not extract Artist and Title from folder name")
+                    logger.error("Please provide: karaoke-gen-remote --finalise-only <folder> \"Artist\" \"Title\"")
+                    return 1
+        else:
+            logger.error("Finalise-only mode requires folder path and/or Artist and Title")
+            return 1
+        
+        # Extract brand code from folder name if --keep-brand-code is set
+        keep_brand_code = None
+        if getattr(args, 'keep_brand_code', False):
+            folder_name = os.path.basename(os.path.abspath(prep_folder))
+            parts = folder_name.split(" - ", 1)
+            if parts and "-" in parts[0]:
+                # Check if it's a brand code format (e.g., "NOMAD-1234")
+                potential_brand = parts[0]
+                brand_parts = potential_brand.split("-")
+                if len(brand_parts) == 2 and brand_parts[1].isdigit():
+                    keep_brand_code = potential_brand
+                    logger.info(f"Preserving brand code: {keep_brand_code}")
+        
+        logger.info(f"Prep folder: {os.path.abspath(prep_folder)}")
+        logger.info(f"Artist: {artist}")
+        logger.info(f"Title: {title}")
+        if keep_brand_code:
+            logger.info(f"Brand Code: {keep_brand_code} (preserved)")
+        logger.info("")
+        
+        # Read youtube description from file if provided
+        youtube_description = None
+        if args.youtube_description_file and os.path.isfile(args.youtube_description_file):
+            try:
+                with open(args.youtube_description_file, 'r') as f:
+                    youtube_description = f.read()
+            except Exception as e:
+                logger.warning(f"Failed to read YouTube description file: {e}")
+        
+        try:
+            result = client.submit_finalise_only_job(
+                prep_folder=prep_folder,
+                artist=artist,
+                title=title,
+                enable_cdg=args.enable_cdg,
+                enable_txt=args.enable_txt,
+                brand_prefix=args.brand_prefix,
+                keep_brand_code=keep_brand_code,
+                discord_webhook_url=args.discord_webhook_url,
+                youtube_description=youtube_description,
+                enable_youtube_upload=getattr(args, 'enable_youtube_upload', False),
+                dropbox_path=getattr(args, 'dropbox_path', None),
+                gdrive_folder_id=getattr(args, 'gdrive_folder_id', None),
+            )
+            job_id = result.get('job_id')
+            logger.info(f"Finalise-only job submitted: {job_id}")
+            logger.info("")
+            
+            # Monitor job
+            return monitor.monitor(job_id)
+            
+        except FileNotFoundError as e:
+            logger.error(str(e))
+            return 1
+        except RuntimeError as e:
+            logger.error(str(e))
+            return 1
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return 1
     
     if args.edit_lyrics:
         logger.error("--edit-lyrics is not yet supported in remote mode")
@@ -2212,8 +2935,7 @@ def main():
     
     # Warn about features that are not yet supported in remote mode
     ignored_features = []
-    if args.prep_only:
-        ignored_features.append("--prep-only")
+    # Note: --prep-only is now supported in remote mode (Batch 6)
     if args.skip_separation:
         ignored_features.append("--skip-separation")
     if args.skip_transcription:
@@ -2333,6 +3055,7 @@ def main():
                 artist=artist,
                 title=title,
                 auto_download=auto_download,
+                style_params_path=args.style_params_json,
                 enable_cdg=args.enable_cdg,
                 enable_txt=args.enable_txt,
                 brand_prefix=args.brand_prefix,
@@ -2418,6 +3141,8 @@ def main():
         logger.info(f"Other Stems Models: {args.other_stems_models}")
     if getattr(args, 'existing_instrumental', None):
         logger.info(f"Existing Instrumental: {args.existing_instrumental}")
+    if getattr(args, 'prep_only', False):
+        logger.info(f"Mode: prep-only (will stop after review)")
     logger.info(f"Service URL: {config.service_url}")
     logger.info(f"Review UI: {config.review_ui_url}")
     if config.non_interactive:
@@ -2434,6 +3159,18 @@ def main():
         except Exception as e:
             logger.warning(f"Failed to read YouTube description file: {e}")
     
+    # Extract brand code from current directory if --keep-brand-code is set
+    keep_brand_code_value = None
+    if getattr(args, 'keep_brand_code', False):
+        cwd_name = os.path.basename(os.getcwd())
+        parts = cwd_name.split(" - ", 1)
+        if parts and "-" in parts[0]:
+            potential_brand = parts[0]
+            brand_parts = potential_brand.split("-")
+            if len(brand_parts) == 2 and brand_parts[1].isdigit():
+                keep_brand_code_value = potential_brand
+                logger.info(f"Preserving brand code: {keep_brand_code_value}")
+    
     try:
         # Submit job - different endpoint for URL vs file
         if is_url_input:
@@ -2466,6 +3203,9 @@ def main():
                 clean_instrumental_model=getattr(args, 'clean_instrumental_model', None),
                 backing_vocals_models=getattr(args, 'backing_vocals_models', None),
                 other_stems_models=getattr(args, 'other_stems_models', None),
+                # Two-phase workflow (Batch 6)
+                prep_only=getattr(args, 'prep_only', False),
+                keep_brand_code=keep_brand_code_value,
             )
         else:
             # File-based job submission
@@ -2495,6 +3235,9 @@ def main():
                 other_stems_models=getattr(args, 'other_stems_models', None),
                 # Existing instrumental (Batch 3)
                 existing_instrumental=getattr(args, 'existing_instrumental', None),
+                # Two-phase workflow (Batch 6)
+                prep_only=getattr(args, 'prep_only', False),
+                keep_brand_code=keep_brand_code_value,
             )
         job_id = result.get('job_id')
         style_assets = result.get('style_assets_uploaded', [])