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

karaoke_gen/utils/remote_cli.py

@@ -36,11 +36,18 @@ from typing import Any, Dict, 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
 
 
 class JobStatus(str, Enum):
     """Job status values (matching backend)."""
     PENDING = "pending"
+    # Audio search states (Batch 5)
+    SEARCHING_AUDIO = "searching_audio"
+    AWAITING_AUDIO_SELECTION = "awaiting_audio_selection"
+    DOWNLOADING_AUDIO = "downloading_audio"
+    # Main workflow
     DOWNLOADING = "downloading"
     SEPARATING_STAGE1 = "separating_stage1"
     SEPARATING_STAGE2 = "separating_stage2"
@@ -62,6 +69,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"
@@ -247,6 +255,132 @@ class RemoteKaraokeClient:
         
         return asset_files
     
+    def submit_job_from_url(
+        self,
+        url: str,
+        artist: Optional[str] = None,
+        title: Optional[str] = None,
+        enable_cdg: bool = True,
+        enable_txt: bool = True,
+        brand_prefix: Optional[str] = None,
+        discord_webhook_url: Optional[str] = None,
+        youtube_description: Optional[str] = None,
+        organised_dir_rclone_root: Optional[str] = None,
+        enable_youtube_upload: bool = False,
+        dropbox_path: Optional[str] = None,
+        gdrive_folder_id: Optional[str] = None,
+        lyrics_artist: Optional[str] = None,
+        lyrics_title: Optional[str] = None,
+        subtitle_offset_ms: int = 0,
+        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.
+        
+        The backend will download the audio from the URL and process it.
+        Artist and title will be auto-detected from the URL if not provided.
+        
+        Note: Custom style configuration is not supported for URL-based jobs.
+        If you need custom styles, download the audio locally first and use
+        the regular file upload flow with submit_job().
+        
+        Args:
+            url: YouTube or other video URL to download audio from
+            artist: Artist name (optional - auto-detected if not provided)
+            title: Song title (optional - auto-detected if not provided)
+            enable_cdg: Generate CDG+MP3 package
+            enable_txt: Generate TXT+MP3 package
+            brand_prefix: Brand code prefix (e.g., "NOMAD")
+            discord_webhook_url: Discord webhook for notifications
+            youtube_description: YouTube video description
+            organised_dir_rclone_root: Legacy rclone path (deprecated)
+            enable_youtube_upload: Enable YouTube upload
+            dropbox_path: Dropbox folder path for organized output (native API)
+            gdrive_folder_id: Google Drive folder ID for public share (native API)
+            lyrics_artist: Override artist name for lyrics search
+            lyrics_title: Override title for lyrics search
+            subtitle_offset_ms: Subtitle timing offset in milliseconds
+            clean_instrumental_model: Model for clean instrumental separation
+            backing_vocals_models: List of models for backing vocals separation
+            other_stems_models: List of models for other stems (bass, drums, etc.)
+        """
+        self.logger.info(f"Submitting URL-based job: {url}")
+        
+        # Build request payload
+        create_request = {
+            'url': url,
+            'enable_cdg': enable_cdg,
+            'enable_txt': enable_txt,
+        }
+        
+        if artist:
+            create_request['artist'] = artist
+        if title:
+            create_request['title'] = title
+        if brand_prefix:
+            create_request['brand_prefix'] = brand_prefix
+        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
+        if organised_dir_rclone_root:
+            create_request['organised_dir_rclone_root'] = organised_dir_rclone_root
+        if lyrics_artist:
+            create_request['lyrics_artist'] = lyrics_artist
+        if lyrics_title:
+            create_request['lyrics_title'] = lyrics_title
+        if subtitle_offset_ms != 0:
+            create_request['subtitle_offset_ms'] = subtitle_offset_ms
+        if clean_instrumental_model:
+            create_request['clean_instrumental_model'] = clean_instrumental_model
+        if backing_vocals_models:
+            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")
+        
+        response = self._request('POST', '/api/jobs/create-from-url', json=create_request)
+        
+        if response.status_code != 200:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise RuntimeError(f"Error creating job from URL: {error_detail}")
+        
+        result = response.json()
+        if result.get('status') != 'success':
+            raise RuntimeError(f"Error creating job from URL: {result}")
+        
+        job_id = result['job_id']
+        detected_artist = result.get('detected_artist')
+        detected_title = result.get('detected_title')
+        
+        self.logger.info(f"Job {job_id} created from URL")
+        if detected_artist:
+            self.logger.info(f"  Artist: {detected_artist}")
+        if detected_title:
+            self.logger.info(f"  Title: {detected_title}")
+        
+        return result
+    
     def submit_job(
         self, 
         filepath: str, 
@@ -274,6 +408,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.
@@ -418,6 +555,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)
         
@@ -505,6 +647,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}')
@@ -645,7 +1036,18 @@ class RemoteKaraokeClient:
                 error_detail = response.text
             raise RuntimeError(f"Error getting instrumental options: {error_detail}")
         return response.json()
-    
+
+    def get_instrumental_analysis(self, job_id: str) -> Dict[str, Any]:
+        """Get instrumental analysis data including backing vocals detection."""
+        response = self._request('GET', f'/api/jobs/{job_id}/instrumental-analysis')
+        if response.status_code != 200:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise RuntimeError(f"Error getting instrumental analysis: {error_detail}")
+        return response.json()
+
     def select_instrumental(self, job_id: str, selection: str) -> Dict[str, Any]:
         """Submit instrumental selection."""
         response = self._request(
@@ -757,6 +1159,122 @@ class RemoteKaraokeClient:
                 error_detail = response.text
             raise RuntimeError(f"Error completing review: {error_detail}")
         return response.json()
+    
+    def search_audio(
+        self,
+        artist: str,
+        title: str,
+        auto_download: bool = False,
+        style_params_path: Optional[str] = None,
+        enable_cdg: bool = True,
+        enable_txt: bool = True,
+        brand_prefix: 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,
+        lyrics_artist: Optional[str] = None,
+        lyrics_title: Optional[str] = None,
+        subtitle_offset_ms: int = 0,
+        clean_instrumental_model: Optional[str] = None,
+        backing_vocals_models: Optional[list] = None,
+        other_stems_models: Optional[list] = None,
+    ) -> Dict[str, Any]:
+        """
+        Search for audio by artist and title (Batch 5 - Flacfetch integration).
+        
+        This creates a job and searches for audio sources. If auto_download is True,
+        it automatically selects the best source. Otherwise, it returns search results
+        for user selection.
+        
+        Args:
+            artist: Artist name to search for
+            title: Song title to search for
+            auto_download: Automatically select best audio source (skip interactive selection)
+            ... other args same as submit_job()
+        
+        Returns:
+            Dict with job_id, status, and optionally search results
+        """
+        self.logger.info(f"Searching for audio: {artist} - {title}")
+        
+        request_data = {
+            'artist': artist,
+            'title': title,
+            'auto_download': auto_download,
+            'enable_cdg': enable_cdg,
+            'enable_txt': enable_txt,
+        }
+        
+        if brand_prefix:
+            request_data['brand_prefix'] = brand_prefix
+        if discord_webhook_url:
+            request_data['discord_webhook_url'] = discord_webhook_url
+        if youtube_description:
+            request_data['youtube_description'] = youtube_description
+        if enable_youtube_upload:
+            request_data['enable_youtube_upload'] = enable_youtube_upload
+        if dropbox_path:
+            request_data['dropbox_path'] = dropbox_path
+        if gdrive_folder_id:
+            request_data['gdrive_folder_id'] = gdrive_folder_id
+        if lyrics_artist:
+            request_data['lyrics_artist'] = lyrics_artist
+        if lyrics_title:
+            request_data['lyrics_title'] = lyrics_title
+        if subtitle_offset_ms != 0:
+            request_data['subtitle_offset_ms'] = subtitle_offset_ms
+        if clean_instrumental_model:
+            request_data['clean_instrumental_model'] = clean_instrumental_model
+        if backing_vocals_models:
+            request_data['backing_vocals_models'] = backing_vocals_models
+        if other_stems_models:
+            request_data['other_stems_models'] = other_stems_models
+        
+        response = self._request('POST', '/api/audio-search/search', json=request_data)
+        
+        if response.status_code == 404:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise ValueError(f"No audio sources found: {error_detail}")
+        
+        if response.status_code != 200:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise RuntimeError(f"Error searching for audio: {error_detail}")
+        
+        return response.json()
+    
+    def get_audio_search_results(self, job_id: str) -> Dict[str, Any]:
+        """Get audio search results for a job awaiting selection."""
+        response = self._request('GET', f'/api/audio-search/{job_id}/results')
+        if response.status_code != 200:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise RuntimeError(f"Error getting search results: {error_detail}")
+        return response.json()
+    
+    def select_audio_source(self, job_id: str, selection_index: int) -> Dict[str, Any]:
+        """Select an audio source and start processing."""
+        response = self._request(
+            'POST',
+            f'/api/audio-search/{job_id}/select',
+            json={'selection_index': selection_index}
+        )
+        if response.status_code != 200:
+            try:
+                error_detail = response.json()
+            except Exception:
+                error_detail = response.text
+            raise RuntimeError(f"Error selecting audio: {error_detail}")
+        return response.json()
 
 
 class JobMonitor:
@@ -768,6 +1286,7 @@ class JobMonitor:
         self.logger = logger
         self._review_opened = False
         self._instrumental_prompted = False
+        self._audio_selection_prompted = False  # Batch 5: audio source selection
         self._last_timeline_index = 0
         self._last_log_index = 0
         self._show_worker_logs = True  # Enable worker log display
@@ -777,6 +1296,11 @@ class JobMonitor:
     # Status descriptions for user-friendly logging
     STATUS_DESCRIPTIONS = {
         'pending': 'Job queued, waiting to start',
+        # Audio search states (Batch 5)
+        'searching_audio': 'Searching for audio sources',
+        'awaiting_audio_selection': 'Waiting for audio source selection',
+        'downloading_audio': 'Downloading selected audio',
+        # Main workflow
         'downloading': 'Downloading and preparing input files',
         'separating_stage1': 'AI audio separation (stage 1 of 2)',
         'separating_stage2': 'AI audio separation (stage 2 of 2)',
@@ -798,6 +1322,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',
     }
@@ -806,6 +1331,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()
@@ -891,39 +1464,97 @@ class JobMonitor:
                 time.sleep(self.config.poll_interval)
     
     def handle_instrumental_selection(self, job_id: str) -> None:
-        """Handle instrumental selection interaction."""
+        """Handle instrumental selection interaction with analysis-based recommendations."""
         self.logger.info("=" * 60)
         self.logger.info("INSTRUMENTAL SELECTION NEEDED")
         self.logger.info("=" * 60)
         
-        # In non-interactive mode, auto-select clean instrumental
-        if self.config.non_interactive:
-            self.logger.info("Non-interactive mode: Auto-selecting clean instrumental")
-            selection = 'clean'
-        else:
-            self.logger.info("")
-            self.logger.info("Choose which instrumental track to use for the final video:")
-            self.logger.info("")
-            self.logger.info("  1) Clean Instrumental (no backing vocals)")
-            self.logger.info("     Best for songs where you want ONLY the lead vocal removed")
+        # Try to get analysis data for smart recommendations
+        analysis_data = None
+        try:
+            analysis_data = self.client.get_instrumental_analysis(job_id)
+            analysis = analysis_data.get('analysis', {})
+            
+            # Display analysis summary
             self.logger.info("")
-            self.logger.info("  2) Instrumental with Backing Vocals")
-            self.logger.info("     Best for songs where backing vocals add to the karaoke experience")
+            self.logger.info("=== Backing Vocals Analysis ===")
+            if analysis.get('has_audible_content'):
+                self.logger.info(f"  Backing vocals detected: YES")
+                self.logger.info(f"  Audible segments: {len(analysis.get('audible_segments', []))}")
+                self.logger.info(f"  Audible duration: {analysis.get('total_audible_duration_seconds', 0):.1f}s "
+                               f"({analysis.get('audible_percentage', 0):.1f}% of track)")
+            else:
+                self.logger.info(f"  Backing vocals detected: NO")
+            self.logger.info(f"  Recommendation: {analysis.get('recommended_selection', 'review_needed')}")
             self.logger.info("")
+        except Exception as e:
+            self.logger.warning(f"Could not fetch analysis data: {e}")
+            self.logger.info("Falling back to manual selection...")
+        
+        # In non-interactive mode, use analysis recommendation or default to clean
+        if self.config.non_interactive:
+            if analysis_data and analysis_data.get('analysis', {}).get('recommended_selection') == 'clean':
+                self.logger.info("Non-interactive mode: Auto-selecting clean instrumental (recommended)")
+                selection = 'clean'
+            else:
+                self.logger.info("Non-interactive mode: Auto-selecting clean instrumental (default)")
+                selection = 'clean'
+        else:
+            # Check if we should recommend clean based on analysis
+            recommend_clean = (
+                analysis_data and 
+                not analysis_data.get('analysis', {}).get('has_audible_content', True)
+            )
             
-            selection = ""
-            while not selection:
+            if recommend_clean:
+                self.logger.info("No backing vocals detected - recommending clean instrumental.")
+                self.logger.info("")
+                self.logger.info("Options:")
+                self.logger.info("  1) Accept recommendation (clean instrumental)")
+                self.logger.info("  2) Open browser to review and select")
+                self.logger.info("")
+                
                 try:
                     choice = input("Enter your choice (1 or 2): ").strip()
                     if choice == '1':
                         selection = 'clean'
-                    elif choice == '2':
-                        selection = 'with_backing'
                     else:
-                        self.logger.error("Invalid choice. Please enter 1 or 2.")
+                        self._open_instrumental_review_and_wait(job_id)
+                        return  # Selection will be submitted via browser
                 except KeyboardInterrupt:
                     print()
                     raise
+            else:
+                # Backing vocals detected or analysis unavailable - offer browser review
+                self.logger.info("Choose how to select your instrumental:")
+                self.logger.info("")
+                self.logger.info("  1) Clean Instrumental (no backing vocals)")
+                self.logger.info("     Best for songs where you want ONLY the lead vocal removed")
+                self.logger.info("")
+                self.logger.info("  2) Instrumental with Backing Vocals")
+                self.logger.info("     Best for songs where backing vocals add to the karaoke experience")
+                self.logger.info("")
+                self.logger.info("  3) Open Browser for Advanced Review")
+                self.logger.info("     Listen to audio, view waveform, and optionally mute sections")
+                self.logger.info("     to create a custom instrumental")
+                self.logger.info("")
+                
+                selection = ""
+                while not selection:
+                    try:
+                        choice = input("Enter your choice (1, 2, or 3): ").strip()
+                        if choice == '1':
+                            selection = 'clean'
+                        elif choice == '2':
+                            selection = 'with_backing'
+                        elif choice == '3':
+                            self._open_instrumental_review_and_wait(job_id)
+                            return  # Selection will be submitted via browser
+                        else:
+                            self.logger.error("Invalid choice. Please enter 1, 2, or 3.")
+                    except KeyboardInterrupt:
+                        print()
+                        raise
         
         self.logger.info(f"Submitting selection: {selection}")
         
@@ -936,6 +1567,153 @@ 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 handle_audio_selection(self, job_id: str) -> None:
+        """Handle audio source selection interaction (Batch 5)."""
+        self.logger.info("=" * 60)
+        self.logger.info("AUDIO SOURCE SELECTION NEEDED")
+        self.logger.info("=" * 60)
+        
+        try:
+            # Get search results
+            results_data = self.client.get_audio_search_results(job_id)
+            results = results_data.get('results', [])
+            artist = results_data.get('artist', 'Unknown')
+            
+            if not results:
+                self.logger.error("No search results available")
+                return
+            
+            # In non-interactive mode, auto-select first result
+            if self.config.non_interactive:
+                self.logger.info("Non-interactive mode: Auto-selecting first result")
+                selection_index = 0
+            else:
+                # 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]
+                
+                # Use flacfetch's shared display function
+                print_releases(release_dicts, target_artist=artist, use_colors=True)
+                
+                selection_index = -1
+                while selection_index < 0:
+                    try:
+                        choice = input(f"\nSelect a release (1-{len(results)}, 0 to cancel): ").strip()
+                        if choice == "0":
+                            self.logger.info("Selection cancelled by user")
+                            raise KeyboardInterrupt
+                        choice_num = int(choice)
+                        if 1 <= choice_num <= len(results):
+                            selection_index = choice_num - 1
+                        else:
+                            print(f"Please enter a number between 0 and {len(results)}")
+                    except ValueError:
+                        print("Please enter a valid number")
+                    except KeyboardInterrupt:
+                        print()
+                        raise
+            
+            selected = results[selection_index]
+            self.logger.info(f"Selected: [{selected.get('provider')}] {selected.get('artist')} - {selected.get('title')}")
+            self.logger.info("")
+            
+            # Submit selection
+            result = self.client.select_audio_source(job_id, selection_index)
+            if result.get('status') == 'success':
+                self.logger.info(f"Selection submitted successfully")
+            else:
+                self.logger.error(f"Error submitting selection: {result}")
+                
+        except Exception as e:
+            self.logger.error(f"Error handling audio selection: {e}")
+
+    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"
+        
+        self.logger.info("")
+        self.logger.info("=" * 60)
+        self.logger.info("OPENING BROWSER FOR INSTRUMENTAL REVIEW")
+        self.logger.info("=" * 60)
+        self.logger.info(f"Review URL: {review_url}")
+        self.logger.info("")
+        self.logger.info("In the browser you can:")
+        self.logger.info("  - View the backing vocals waveform")
+        self.logger.info("  - Listen to clean instrumental, backing vocals, or combined")
+        self.logger.info("  - Select regions to mute and create a custom instrumental")
+        self.logger.info("  - Submit your final selection")
+        self.logger.info("")
+        self.logger.info("Waiting for selection to be submitted...")
+        self.logger.info("(Press Ctrl+C to cancel)")
+        self.logger.info("")
+        
+        # Open browser
+        webbrowser.open(review_url)
+        
+        # Poll until job status changes from awaiting_instrumental_selection
+        while True:
+            try:
+                job_data = self.client.get_job(job_id)
+                current_status = job_data.get('status')
+                
+                if current_status != 'awaiting_instrumental_selection':
+                    selection = job_data.get('state_data', {}).get('instrumental_selection', 'unknown')
+                    self.logger.info(f"Selection received: {selection}")
+                    self.logger.info(f"Job status: {current_status}")
+                    return
+                
+                time.sleep(self.config.poll_interval)
+                
+            except KeyboardInterrupt:
+                print()
+                self.logger.info("Cancelled. You can resume this job later with --resume")
+                raise
+            except Exception as e:
+                self.logger.warning(f"Error checking status: {e}")
+                time.sleep(self.config.poll_interval)
+
+    
     def download_outputs(self, job_id: str, job_data: Dict[str, Any]) -> None:
         """
         Download all output files for a completed job.
@@ -1337,13 +2115,26 @@ 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
-                if status in ['awaiting_review', 'in_review']:
+                if status == 'awaiting_audio_selection':
+                    if not self._audio_selection_prompted:
+                        self.logger.info("")
+                        self.handle_audio_selection(job_id)
+                        self._audio_selection_prompted = True
+                        self._last_timeline_index = 0  # Reset to catch any events
+                
+                elif status in ['awaiting_review', 'in_review']:
                     if not self._review_opened:
                         self.logger.info("")
                         self.handle_review(job_id)
@@ -1368,6 +2159,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)
@@ -1756,10 +2565,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")
@@ -1771,8 +2682,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:
@@ -1781,8 +2691,7 @@ def main():
         ignored_features.append("--lyrics-only")
     if args.background_video:
         ignored_features.append("--background_video")
-    if getattr(args, 'auto_download', False):
-        ignored_features.append("--auto-download (audio search not yet supported)")
+    # --auto-download is now supported (Batch 5)
     # These are now supported but server-side handling may be partial
     if args.organised_dir:
         ignored_features.append("--organised_dir (local-only)")
@@ -1803,6 +2712,8 @@ def main():
     
     # Handle new job submission - parse input arguments same as gen_cli
     input_media, artist, title, filename_pattern = None, None, None, None
+    use_audio_search = False  # Batch 5: audio search mode
+    is_url_input = False
     
     if not args.args:
         parser.print_help()
@@ -1810,52 +2721,137 @@ def main():
     
     # Allow 3 forms of positional arguments:
     # 1. URL or Media File only
-    # 2. Artist and Title only
-    # 3. URL, Artist, and Title
+    # 2. Artist and Title only (audio search mode - Batch 5)
+    # 3. URL/File, Artist, and Title
     if args.args and (is_url(args.args[0]) or is_file(args.args[0])):
         input_media = args.args[0]
+        is_url_input = is_url(args.args[0])
         if len(args.args) > 2:
             artist = args.args[1]
             title = args.args[2]
         elif len(args.args) > 1:
             artist = args.args[1]
         else:
-            logger.error("Input media provided without Artist and Title")
-            return 1
+            # For URLs, artist/title can be auto-detected
+            if is_url_input:
+                logger.info("URL provided without Artist and Title - will be auto-detected from video metadata")
+            else:
+                logger.error("Input media provided without Artist and Title")
+                return 1
     elif os.path.isdir(args.args[0]):
         logger.error("Folder processing is not yet supported in remote mode")
         return 1
     elif len(args.args) > 1:
+        # Audio search mode: artist + title without file (Batch 5)
         artist = args.args[0]
         title = args.args[1]
-        logger.error("Audio search (artist+title) is not yet supported in remote mode.")
-        logger.error("Please provide a local audio file path instead.")
-        logger.error("")
-        logger.error("For local flacfetch search, use karaoke-gen instead:")
-        logger.error(f"  karaoke-gen \"{artist}\" \"{title}\"")
-        return 1
+        use_audio_search = True
     else:
         parser.print_help()
         return 1
     
-    # For now, remote mode only supports file uploads
-    if not input_media or not os.path.isfile(input_media):
-        logger.error("Remote mode currently only supports local file uploads")
-        logger.error("Please provide a path to an audio file (mp3, wav, flac, m4a, ogg, aac)")
-        return 1
-    
     # Validate artist and title are provided
     if not artist or not title:
         logger.error("Artist and Title are required")
         parser.print_help()
         return 1
     
+    # For file/URL input modes, validate input exists
+    if not use_audio_search:
+        if not input_media:
+            logger.error("No input media or URL provided")
+            return 1
+        
+        # For file input (not URL), validate file exists
+        if not is_url_input and not os.path.isfile(input_media):
+            logger.error(f"File not found: {input_media}")
+            logger.error("Please provide a valid path to an audio file (mp3, wav, flac, m4a, ogg, aac)")
+            return 1
+    
+    # Handle audio search mode (Batch 5)
+    if use_audio_search:
+        logger.info("=" * 60)
+        logger.info("Karaoke Generator (Remote) - Audio Search Mode")
+        logger.info("=" * 60)
+        logger.info(f"Searching for: {artist} - {title}")
+        if getattr(args, 'auto_download', False) or config.non_interactive:
+            logger.info(f"Auto-download: enabled (will auto-select best source)")
+        if args.style_params_json:
+            logger.info(f"Style: {args.style_params_json}")
+        logger.info(f"CDG: {args.enable_cdg}, TXT: {args.enable_txt}")
+        if args.brand_prefix:
+            logger.info(f"Brand: {args.brand_prefix}")
+        logger.info(f"Service URL: {config.service_url}")
+        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()
+                logger.info(f"Loaded YouTube description from: {args.youtube_description_file}")
+            except Exception as e:
+                logger.warning(f"Failed to read YouTube description file: {e}")
+        
+        try:
+            # Determine auto_download mode
+            auto_download = getattr(args, 'auto_download', False) or config.non_interactive
+            
+            result = client.search_audio(
+                artist=artist,
+                title=title,
+                auto_download=auto_download,
+                enable_cdg=args.enable_cdg,
+                enable_txt=args.enable_txt,
+                brand_prefix=args.brand_prefix,
+                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),
+                lyrics_artist=getattr(args, 'lyrics_artist', None),
+                lyrics_title=getattr(args, 'lyrics_title', None),
+                subtitle_offset_ms=getattr(args, 'subtitle_offset_ms', 0) or 0,
+                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),
+            )
+            
+            job_id = result.get('job_id')
+            results_count = result.get('results_count', 0)
+            server_version = result.get('server_version', 'unknown')
+            
+            logger.info(f"Job created: {job_id}")
+            logger.info(f"Server version: {server_version}")
+            logger.info(f"Audio sources found: {results_count}")
+            logger.info("")
+            
+            # Monitor job
+            return monitor.monitor(job_id)
+            
+        except ValueError as e:
+            logger.error(str(e))
+            return 1
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            logger.exception("Full error details:")
+            return 1
+    
+    # File upload mode (original flow)
     logger.info("=" * 60)
     logger.info("Karaoke Generator (Remote) - Job Submission")
     logger.info("=" * 60)
-    logger.info(f"File: {input_media}")
-    logger.info(f"Artist: {artist}")
-    logger.info(f"Title: {title}")
+    if is_url_input:
+        logger.info(f"URL: {input_media}")
+    else:
+        logger.info(f"File: {input_media}")
+    if artist:
+        logger.info(f"Artist: {artist}")
+    if title:
+        logger.info(f"Title: {title}")
+    if not artist and not title and is_url_input:
+        logger.info(f"Artist/Title: (will be auto-detected from URL)")
     if args.style_params_json:
         logger.info(f"Style: {args.style_params_json}")
     logger.info(f"CDG: {args.enable_cdg}, TXT: {args.enable_txt}")
@@ -1891,6 +2887,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:
@@ -1907,35 +2905,86 @@ 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 with all options
-        result = client.submit_job(
-            filepath=input_media,
-            artist=artist,
-            title=title,
-            style_params_path=args.style_params_json,
-            enable_cdg=args.enable_cdg,
-            enable_txt=args.enable_txt,
-            brand_prefix=args.brand_prefix,
-            discord_webhook_url=args.discord_webhook_url,
-            youtube_description=youtube_description,
-            organised_dir_rclone_root=args.organised_dir_rclone_root,
-            enable_youtube_upload=getattr(args, 'enable_youtube_upload', False),
-            # Native API distribution (preferred for remote CLI)
-            dropbox_path=getattr(args, 'dropbox_path', None),
-            gdrive_folder_id=getattr(args, 'gdrive_folder_id', None),
-            # Lyrics configuration
-            lyrics_artist=getattr(args, 'lyrics_artist', None),
-            lyrics_title=getattr(args, 'lyrics_title', None),
-            lyrics_file=getattr(args, 'lyrics_file', None),
-            subtitle_offset_ms=getattr(args, 'subtitle_offset_ms', 0) or 0,
-            # Audio separation model configuration
-            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),
-            # Existing instrumental (Batch 3)
-            existing_instrumental=getattr(args, 'existing_instrumental', None),
-        )
+        # Submit job - different endpoint for URL vs file
+        if is_url_input:
+            # URL-based job submission
+            # Note: style_params_path is not supported for URL-based jobs
+            # If custom styles are needed, download the audio locally first
+            if args.style_params_json:
+                logger.warning("Custom styles (--style_params_json) are not supported for URL-based jobs. "
+                             "Download the audio locally first and use file upload for custom styles.")
+            
+            result = client.submit_job_from_url(
+                url=input_media,
+                artist=artist,
+                title=title,
+                enable_cdg=args.enable_cdg,
+                enable_txt=args.enable_txt,
+                brand_prefix=args.brand_prefix,
+                discord_webhook_url=args.discord_webhook_url,
+                youtube_description=youtube_description,
+                organised_dir_rclone_root=args.organised_dir_rclone_root,
+                enable_youtube_upload=getattr(args, 'enable_youtube_upload', False),
+                # Native API distribution (preferred for remote CLI)
+                dropbox_path=getattr(args, 'dropbox_path', None),
+                gdrive_folder_id=getattr(args, 'gdrive_folder_id', None),
+                # Lyrics configuration
+                lyrics_artist=getattr(args, 'lyrics_artist', None),
+                lyrics_title=getattr(args, 'lyrics_title', None),
+                subtitle_offset_ms=getattr(args, 'subtitle_offset_ms', 0) or 0,
+                # Audio separation model configuration
+                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
+            result = client.submit_job(
+                filepath=input_media,
+                artist=artist,
+                title=title,
+                style_params_path=args.style_params_json,
+                enable_cdg=args.enable_cdg,
+                enable_txt=args.enable_txt,
+                brand_prefix=args.brand_prefix,
+                discord_webhook_url=args.discord_webhook_url,
+                youtube_description=youtube_description,
+                organised_dir_rclone_root=args.organised_dir_rclone_root,
+                enable_youtube_upload=getattr(args, 'enable_youtube_upload', False),
+                # Native API distribution (preferred for remote CLI)
+                dropbox_path=getattr(args, 'dropbox_path', None),
+                gdrive_folder_id=getattr(args, 'gdrive_folder_id', None),
+                # Lyrics configuration
+                lyrics_artist=getattr(args, 'lyrics_artist', None),
+                lyrics_title=getattr(args, 'lyrics_title', None),
+                lyrics_file=getattr(args, 'lyrics_file', None),
+                subtitle_offset_ms=getattr(args, 'subtitle_offset_ms', 0) or 0,
+                # Audio separation model configuration
+                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),
+                # 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', [])
         server_version = result.get('server_version', 'unknown')