Update app.py

app.py

@@ -17,6 +17,8 @@ from datetime import datetime
 import pyloudnorm as pyln
 
 # --- OPTIONAL: MIDI IMPORT ---
+# We wrap this in a try/except block so the app doesn't crash if the user
+# hasn't installed the heavy 'basic-pitch' library yet.
 try:
     from basic_pitch.inference import predict_and_save
     MIDI_AVAILABLE = True
@@ -25,249 +27,531 @@ except ImportError:
     print("WARNING: 'basic-pitch' not installed. MIDI extraction will be disabled.")
 
 # --- PATCH FOR PILLOW 10.0+ ---
+# MoviePy v1.0.3 relies on 'ANTIALIAS', which was removed in Pillow 10.0.
+# We monkey-patch it here to prevent the 'AttributeError'.
 import PIL.Image
 if not hasattr(PIL.Image, 'ANTIALIAS'):
     PIL.Image.ANTIALIAS = PIL.Image.LANCZOS
 
-# --- CONFIG ---
+# --- CONFIGURATION ---
 OUTPUT_DIR = Path("nightpulse_output")
 TEMP_DIR = Path("temp_processing")
 
-# -----------------------------
-# Startup Checks
-# -----------------------------
+
+# ==========================================
+# 1. SYSTEM UTILITIES
+# ==========================================
+
 def check_ffmpeg():
+    """
+    Checks if FFmpeg is installed and accessible in the system PATH.
+    Audio processing libraries (pydub, demucs) heavily rely on this.
+    """
     if shutil.which("ffmpeg") is None:
         print("CRITICAL WARNING: FFmpeg not found in system PATH.")
+        print("Audio processing will likely fail.")
         return False
     return True
 
+# Run check on startup
 check_ffmpeg()
 
-# -----------------------------
-# Key Detection
-# -----------------------------
+
+# ==========================================
+# 2. AUDIO ANALYSIS ENGINES
+# ==========================================
+
 def detect_key(audio_path):
+    """
+    Estimates the musical key (e.g., 'Cmaj', 'F#min') using Librosa chroma features.
+    It compares the audio's pitch profile against standard major/minor profiles.
+    """
     try:
+        # Load audio (first 60 seconds is usually enough for key detection)
         y, sr = librosa.load(str(audio_path), sr=None, duration=60)
+        
+        # Extract Pitch Class Profile (Chroma)
         chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
         chroma_vals = np.sum(chroma, axis=1)
+        
+        # Standard Krumhansl-Schmuckler profiles for Major and Minor keys
         maj_profile = [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]
         min_profile = [6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17]
+        
         pitches = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']
+        
         best_score = -1
         best_key = "Unknown"
+        
+        # Test all 12 pitches as the tonic
         for i in range(12):
+            # Shift profiles to align with the current pitch 'i'
             p_maj = np.roll(maj_profile, i)
             p_min = np.roll(min_profile, i)
+            
+            # Calculate correlation
             score_maj = np.corrcoef(chroma_vals, p_maj)[0, 1]
             score_min = np.corrcoef(chroma_vals, p_min)[0, 1]
+            
             if score_maj > best_score:
                 best_score = score_maj
                 best_key = f"{pitches[i]}maj"
+                
             if score_min > best_score:
                 best_score = score_min
                 best_key = f"{pitches[i]}min"
+                
         return best_key
-    except Exception:
+    except Exception as e:
+        print(f"Key detection warning: {e}")
         return "Unknown"
 
-# -----------------------------
-# Helpers
-# -----------------------------
+
+# ==========================================
+# 3. FILE HANDLING & DOWNLOADS
+# ==========================================
+
 def download_from_url(url):
-    if not url: return None
-    if TEMP_DIR.exists(): shutil.rmtree(TEMP_DIR, ignore_errors=True)
+    """
+    Downloads audio from YouTube, SoundCloud, etc., using yt-dlp.
+    Returns the path to the downloaded WAV file.
+    """
+    if not url:
+        return None
+        
+    print(f"Fetching URL: {url}")
+    
+    # clear temp dir to prevent filename collisions
+    if TEMP_DIR.exists():
+        shutil.rmtree(TEMP_DIR, ignore_errors=True)
     TEMP_DIR.mkdir(parents=True, exist_ok=True)
+
     ydl_opts = {
         "format": "bestaudio/best",
         "outtmpl": str(TEMP_DIR / "%(title)s.%(ext)s"),
-        "postprocessors": [{"key": "FFmpegExtractAudio", "preferredcodec": "wav", "preferredquality": "192"}],
-        "quiet": True, "no_warnings": True,
+        "postprocessors": [
+            {"key": "FFmpegExtractAudio", "preferredcodec": "wav", "preferredquality": "192"}
+        ],
+        "quiet": True,
+        "no_warnings": True,
     }
+
     with yt_dlp.YoutubeDL(ydl_opts) as ydl:
         info = ydl.extract_info(url, download=True)
         filename = ydl.prepare_filename(info)
-        return str(Path(filename).with_suffix(".wav"))
+        final_path = Path(filename).with_suffix(".wav")
+        return str(final_path)
+
 
 def safe_copy_to_temp(audio_file: str) -> str:
+    """
+    Copies an uploaded file to the temp directory with a sanitized filename.
+    This prevents issues with spaces or special characters in shell commands.
+    """
     src = Path(audio_file)
     TEMP_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # Replace non-alphanumeric chars with underscores
     safe_stem = "".join(c if c.isalnum() or c in "._-" else "_" for c in src.stem)
     dst = TEMP_DIR / f"{safe_stem}{src.suffix.lower()}"
-    try: shutil.copy(src, dst)
-    except Exception: return str(src)
+    
+    try:
+        shutil.copy(src, dst)
+    except Exception:
+        # Fallback if copy fails (e.g., same file)
+        return str(src)
     return str(dst)
 
+
 def ensure_wav(input_path: str) -> str:
+    """
+    Ensures the input is a WAV file. If not (mp3, m4a, etc.), converts it.
+    Demucs works best with WAV input.
+    """
     p = Path(input_path)
-    if p.suffix.lower() == ".wav": return str(p)
+    if p.suffix.lower() == ".wav":
+        return str(p)
+
     TEMP_DIR.mkdir(parents=True, exist_ok=True)
     out = TEMP_DIR / f"{p.stem}.wav"
-    AudioSegment.from_file(str(p)).export(str(out), format="wav")
+    
+    audio = AudioSegment.from_file(str(p))
+    audio.export(str(out), format="wav")
     return str(out)
 
-# -----------------------------
-# Demucs + MIDI
-# -----------------------------
+
+# ==========================================
+# 4. EXTERNAL TOOLS (DEMUCS & MIDI)
+# ==========================================
+
 def run_demucs(cmd):
+    """
+    Executes the Demucs command line tool via subprocess.
+    Captures stdout/stderr to display errors in the UI if it crashes.
+    """
+    print(f"Running Demucs: {' '.join(cmd)}")
     p = subprocess.run(cmd, capture_output=True, text=True)
-    if p.returncode != 0: raise gr.Error(f"Demucs Error:\n{p.stderr[-2000:]}")
+    
+    if p.returncode != 0:
+        # Pass the error log back to Gradio
+        raise gr.Error(f"Demucs Separation Failed:\n\n{p.stderr[-2000:]}")
     return p.stdout
 
+
 def extract_midi(audio_path, out_path):
-    if not MIDI_AVAILABLE: return
+    """
+    Uses Spotify's 'basic-pitch' library to convert a monophonic or polyphonic 
+    stem (like Bass or Piano) into a MIDI file.
+    """
+    if not MIDI_AVAILABLE:
+        return
+
+    # Basic-pitch saves to a directory, usually naming the file based on the input.
     out_dir = out_path.parent
     name = out_path.stem
-    predict_and_save([str(audio_path)], str(out_dir), True, False, False, sonify_midi=False, save_midi_path=str(out_path))
-    expected = out_dir / f"{name}_basic_pitch.mid"
-    if expected.exists(): shutil.move(expected, out_path)
+    
+    try:
+        predict_and_save(
+            audio_path_list=[str(audio_path)],
+            output_directory=str(out_dir),
+            save_midi=True,
+            save_model_outputs=False,
+            save_notes=False,
+            sonify_midi=False,
+            # Force the name if supported by this version of basic-pitch
+            save_midi_path=str(out_path) 
+        )
+        
+        # Basic-pitch might ignore 'save_midi_path' in some versions and use 
+        # the default name "<stem>_basic_pitch.mid". We check for that.
+        expected_default = out_dir / f"{name}_basic_pitch.mid"
+        if expected_default.exists() and expected_default != out_path:
+            shutil.move(expected_default, out_path)
+            
+    except Exception as e:
+        print(f"MIDI Extraction failed for {audio_path.name}: {e}")
+
+
+# ==========================================
+# 5. AUDIO PROCESSING (LOUDNESS & ONE SHOTS)
+# ==========================================
 
-# -----------------------------
-# Audio Processing
-# -----------------------------
 def apply_loudness(seg: AudioSegment, mode: str, target: float = -14.0) -> AudioSegment:
+    """
+    Normalizes audio using Peak, RMS, or integrated LUFS (Standard).
+    """
     mode = (mode or "none").lower().strip()
-    if mode == "none": return seg
-    if mode == "peak": return seg.normalize()
+    
+    if mode == "none":
+        return seg
+        
+    if mode == "peak":
+        return seg.normalize()
+        
     if mode == "rms":
+        # Simple dBFS adjustment
         change = target - seg.dBFS
         return seg.apply_gain(change)
+
     if mode == "lufs":
-        samples = np.array(seg.get_array_of_samples())
-        if seg.channels == 2: samples = samples.reshape((-1, 2))
-        samples_float = samples.astype(np.float64) / 32768.0
-        meter = pyln.Meter(seg.frame_rate) 
-        loudness = meter.integrated_loudness(samples_float)
-        if loudness == -float('inf'): return seg
-        gain_db = max(min(target - loudness, 20.0), -20.0)
-        return seg.apply_gain(gain_db)
+        # Professional standard (Broadcast loudness)
+        try:
+            # Get raw samples as numpy array
+            samples = np.array(seg.get_array_of_samples())
+            
+            # Pyloudnorm expects float data between -1.0 and 1.0
+            # AudioSegment uses 16-bit int (usually), so we divide by 32768.0
+            if seg.channels == 2:
+                samples = samples.reshape((-1, 2))
+            
+            samples_float = samples.astype(np.float64) / 32768.0
+            
+            meter = pyln.Meter(seg.frame_rate) 
+            loudness = meter.integrated_loudness(samples_float)
+            
+            if loudness == -float('inf'):
+                return seg # Silence, skip
+            
+            gain_db = target - loudness
+            
+            # Safety clamp to prevent exploding headers
+            gain_db = max(min(gain_db, 20.0), -20.0)
+            
+            return seg.apply_gain(gain_db)
+        except Exception as e:
+            print(f"LUFS normalization failed: {e}")
+            return seg
+        
     return seg
 
+
 def extract_one_shots(drum_stem_path, bpm, out_dir, loudness_mode, target_dbfs):
+    """
+    Slices the 'Drums' stem into individual hits (Kick, Snare, etc.) using Onset Detection.
+    """
+    # Load raw audio for analysis
     y, sr = librosa.load(str(drum_stem_path), sr=None)
+    
+    # Detect onset frames (start of hits)
     onset_frames = librosa.onset.onset_detect(y=y, sr=sr, backtrack=True)
     onset_times = librosa.frames_to_time(onset_frames, sr=sr)
+    
+    # Load Pydub object for slicing
     audio = AudioSegment.from_wav(str(drum_stem_path))
     hits = []
+    
     for i in range(len(onset_times)):
         start_ms = int(onset_times[i] * 1000)
-        dur = min(int(onset_times[i+1] * 1000) - start_ms, 450) if i < len(onset_times) - 1 else 450
+        
+        # Determine duration: either until the next hit, or max 450ms
+        if i < len(onset_times) - 1:
+            next_ms = int(onset_times[i+1] * 1000)
+            dur = min(next_ms - start_ms, 450)
+        else:
+            dur = 450
+            
         hit = audio[start_ms : start_ms + dur]
+        
+        # Filter out ghost notes or tiny noise
         if hit.rms > 100 and len(hit) > 30:
-            hits.append(hit.fade_out(10))
+            # Tiny fade out to prevent clicking at the cut
+            hit = hit.fade_out(10)
+            hits.append(hit)
+            
+    # Sort by loudness to ensure the main Kicks/Snares are at the top of the list
     hits.sort(key=lambda x: x.rms, reverse=True)
+    
+    # Keep top 32 hits to avoid clutter
     hits = hits[:32]
+    
+    out_dir.mkdir(parents=True, exist_ok=True)
+    
     for i, hit in enumerate(hits):
         hit = apply_loudness(hit, mode=loudness_mode, target=target_dbfs)
         hit.export(out_dir / f"DrumShot_{i+1:02d}.wav", format="wav")
 
-# -----------------------------
-# Loop Engine
-# -----------------------------
-def make_quantized_loops(stem_path, stem_name, bpm, key, bar_starts_ms, bar_lengths, 
-                         hop_bars, loops_per, top_k, fade_ms, loop_seam, seam_ms, 
-                         min_bar_gap, loudness_mode, target_dbfs, out_dir):
-    if not stem_path.exists(): return []
+
+# ==========================================
+# 6. LOOP GENERATION ENGINE
+# ==========================================
+
+def make_quantized_loops(
+    stem_path, stem_name, bpm, key, bar_starts_ms, bar_lengths, 
+    hop_bars, loops_per, top_k, fade_ms, loop_seam, seam_ms, 
+    min_bar_gap, loudness_mode, target_dbfs, out_dir
+):
+    """
+    The core engine. Slices stems into loops based on bar grid, ranks them by loudness,
+    and applies crossfades/normalization.
+    """
+    if not stem_path.exists():
+        return []
+        
     audio = AudioSegment.from_wav(str(stem_path))
     ms_per_bar = (240000.0 / bpm) 
-    trim_win = 8
+
+    # Seam/Trim Buffer Logic
+    trim_win = 8 # ms to shave off ends to prevent zero-crossing clicks
+    
+    # If we are crossfading the seam, we need extra audio at the end
     extra_ms = (seam_ms if loop_seam else 0) + (trim_win * 2)
+
+    # Generate grid points
     grid = bar_starts_ms[::max(1, int(hop_bars))] if bar_starts_ms else []
     candidates = []
 
     for bar_len in bar_lengths:
         t_dur = int(ms_per_bar * bar_len)
         x_dur = t_dur + extra_ms
+        
         for start_ms in grid:
-            if start_ms + x_dur > len(audio): continue
+            # Check boundaries
+            if start_ms + x_dur > len(audio):
+                continue
+            
             seg = audio[start_ms : start_ms + x_dur]
-            if len(seg) < x_dur: continue
+            
+            # Double check length
+            if len(seg) < x_dur:
+                continue
+                
+            # Store candidate with loudness score
             candidates.append((seg.dBFS, int(start_ms), int(bar_len)))
 
+    # Sort by loudness (loudest/busiest loops first)
     candidates.sort(key=lambda x: x[0], reverse=True)
-    if top_k > 0: candidates = candidates[:int(top_k)]
+    
+    # Filter top K
+    if top_k > 0:
+        candidates = candidates[:int(top_k)]
+    
+    # De-duplicate (don't pick loops that are too close to each other)
     selected = []
     used_bars = []
+    
     for score, start, blen in candidates:
         b_idx = int(np.argmin([abs(start - b) for b in bar_starts_ms]))
-        if any(abs(b_idx - u) < min_bar_gap for u in used_bars): continue
+        
+        # If this bar index is close to an already used one, skip
+        if any(abs(b_idx - u) < min_bar_gap for u in used_bars):
+            continue
+            
         selected.append((score, start, blen))
         used_bars.append(b_idx)
-        if len(selected) >= loops_per: break
+        
+        if len(selected) >= loops_per:
+            break
 
+    # Process and Export
     exported = []
+    out_dir.mkdir(parents=True, exist_ok=True)
+    
     for i, (_, start, blen) in enumerate(selected, 1):
         t_dur = int(ms_per_bar * blen)
         x_dur = t_dur + extra_ms
+        
         loop = audio[start : start + x_dur]
-        loop = loop[trim_win : -trim_win] if len(loop) > trim_win*2 else loop
-        if loop_seam and len(loop) > seam_ms*2:
+        
+        # 1. Trim Tiny
+        if len(loop) > trim_win * 2:
+            loop = loop[trim_win : -trim_win]
+        
+        # 2. Seam Crossfade
+        if loop_seam and len(loop) > seam_ms * 2:
             head = loop[:seam_ms]
             tail = loop[-seam_ms:]
             body = loop[seam_ms:-seam_ms]
+            # Blend tail into head
             loop = body.append(tail.append(head, crossfade=seam_ms), crossfade=seam_ms)
         else:
+            # Hard crop
             loop = loop[:t_dur]
-            if fade_ms > 0: loop = loop.fade_in(fade_ms).fade_out(fade_ms)
+            if fade_ms > 0:
+                loop = loop.fade_in(fade_ms).fade_out(fade_ms)
+            
+        # 3. Final Length Quantize
         loop = loop[:t_dur] 
+        
+        # 4. Loudness
         loop = apply_loudness(loop, mode=loudness_mode, target=target_dbfs)
+        
+        # 5. Filename
         fname = f"{bpm}BPM_{key}_{stem_name}_L{blen}bars_{i:02d}.wav"
         out_path = out_dir / fname
+        
         loop.export(out_path, format="wav")
         exported.append(out_path)
+        
     return exported
 
-# -----------------------------
-# Phase 1: Analyze
-# -----------------------------
+
+# ==========================================
+# 7. PHASE 1: ANALYZE & SEPARATE
+# ==========================================
+
 def analyze_and_separate(file_in, url_in, mode, manual_bpm):
-    if TEMP_DIR.exists(): shutil.rmtree(TEMP_DIR, ignore_errors=True)
+    """
+    Handles file ingest, BPM/Key detection, and Demucs separation.
+    Returns preview paths and sets up the UI for Phase 2.
+    """
+    # 1. Prepare Temp Dir
+    if TEMP_DIR.exists():
+        shutil.rmtree(TEMP_DIR, ignore_errors=True)
     TEMP_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # 2. Ingest
     fpath = download_from_url(url_in) if url_in else file_in
-    if not fpath: raise gr.Error("No Audio Source")
+    if not fpath:
+        raise gr.Error("No Audio Source Provided.")
+    
     fpath = safe_copy_to_temp(fpath)
     fpath = ensure_wav(fpath)
     
-    bpm = manual_bpm if manual_bpm else int(librosa.beat.beat_track(y=librosa.load(fpath, duration=60)[0])[0])
+    # 3. Analyze (BPM & Key)
+    if manual_bpm:
+        bpm = int(manual_bpm)
+    else:
+        # Detect BPM from first 60s
+        y, sr = librosa.load(fpath, duration=60)
+        tempo, _ = librosa.beat.beat_track(y=y, sr=sr)
+        bpm = int(tempo[0] if np.ndim(tempo) > 0 else tempo)
+        
     key = detect_key(fpath)
+    print(f"Analysis Complete: {bpm} BPM, Key: {key}")
+    
+    # 4. Separate (Demucs)
+    cmd = [
+        sys.executable, "-m", "demucs", 
+        "-n", "htdemucs_6s" if mode=="6stem" else "htdemucs", 
+        "--out", str(TEMP_DIR), 
+        fpath
+    ]
+    if mode == "2stem":
+        cmd += ["--two-stems", "vocals"]
     
-    cmd = [sys.executable, "-m", "demucs", "-n", "htdemucs_6s" if mode=="6stem" else "htdemucs", "--out", str(TEMP_DIR), fpath]
-    if mode == "2stem": cmd += ["--two-stems", "vocals"]
     run_demucs(cmd)
     
+    # 5. Map Outputs
     track_dir = next((TEMP_DIR / ("htdemucs_6s" if mode=="6stem" else "htdemucs")).iterdir())
+    
     stem_map = {
-        "Drums": track_dir/"drums.wav", "Bass": track_dir/"bass.wav",
-        "Vocals": track_dir/"vocals.wav", "Other": track_dir/"other.wav",
-        "Piano": track_dir/"piano.wav", "Guitar": track_dir/"guitar.wav",
+        "Drums": track_dir/"drums.wav", 
+        "Bass": track_dir/"bass.wav",
+        "Vocals": track_dir/"vocals.wav", 
+        "Other": track_dir/"other.wav",
+        "Piano": track_dir/"piano.wav", 
+        "Guitar": track_dir/"guitar.wav",
         "Instrumental": track_dir/"no_vocals.wav"
     }
-    valid = [k for k,v in stem_map.items() if v.exists()]
-    loops_def = [s for s in valid if s != "Vocals"]
     
-    # UI Updates for Checkboxes
-    cb_export = gr.CheckboxGroup(choices=valid, value=valid)
-    cb_loops = gr.CheckboxGroup(choices=valid, value=loops_def)
+    # Determine which stems actually exist
+    valid_stems = [k for k,v in stem_map.items() if v.exists()]
     
-    # Previews
-    p_d = str(stem_map["Drums"]) if "Drums" in valid else None
-    p_b = str(stem_map["Bass"]) if "Bass" in valid else None
-    p_v = str(stem_map["Vocals"]) if "Vocals" in valid else None
+    # Smart defaults for checkboxes:
+    # Export: All available stems
+    # Loops: All available stems EXCEPT Vocals (unless manually added)
+    loops_defaults = [s for s in valid_stems if s != "Vocals"]
     
-    return (p_d, p_b, p_v, f"**Detected:** {bpm} BPM | **Key:** {key}", bpm, key, str(track_dir), mode, cb_export, cb_loops)
-
-# -----------------------------
-# Phase 2: Package (With Smart Video Resize)
-# -----------------------------
-def package_and_export(track_folder, bpm, key, stem_mode, art, 
-                       ex_stems, loop_stems, do_midi, do_oneshots, do_vocal_chops,
-                       loops_per, bars, hop, topk, fadems, loopseam, seamms, mingap,
-                       loud_mode, loud_target, vid_fmt):
+    # Create UI update components
+    cb_export = gr.CheckboxGroup(choices=valid_stems, value=valid_stems)
+    cb_loops = gr.CheckboxGroup(choices=valid_stems, value=loops_defaults)
     
-    if not track_folder: raise gr.Error("Run Phase 1 First.")
+    # Get paths for previews (safe handling if stems missing)
+    p_d = str(stem_map["Drums"]) if "Drums" in valid_stems else None
+    p_b = str(stem_map["Bass"]) if "Bass" in valid_stems else None
+    p_v = str(stem_map["Vocals"]) if "Vocals" in valid_stems else None
     
-    if OUTPUT_DIR.exists(): shutil.rmtree(OUTPUT_DIR, ignore_errors=True)
+    analysis_text = f"### 🎵 Detected: {bpm} BPM | Key: {key}"
+    
+    return (
+        p_d, p_b, p_v,          # Previews
+        analysis_text,          # Info Text
+        bpm, key, str(track_dir), mode,  # Hidden State
+        cb_export, cb_loops     # Checkbox Updates
+    )
+
+
+# ==========================================
+# 8. PHASE 2: PACKAGE & EXPORT
+# ==========================================
+
+def package_and_export(
+    track_folder, bpm, key, stem_mode, art, 
+    ex_stems, loop_stems, do_midi, do_oneshots, do_vocal_chops,
+    loops_per, bars, hop, topk, fadems, loopseam, seamms, mingap,
+    loud_mode, loud_target, vid_fmt
+):
+    """
+    Generates all content (Stems, Loops, MIDI, Video) and zips it up.
+    """
+    
+    if not track_folder:
+        raise gr.Error("Run Phase 1 First.")
+    
+    # 1. Setup Output Directories
+    if OUTPUT_DIR.exists():
+        shutil.rmtree(OUTPUT_DIR, ignore_errors=True)
+        
     for d in ["Stems", "Loops", "MIDI", "OneShots", "Vocal_Chops"]:
         (OUTPUT_DIR / d).mkdir(parents=True, exist_ok=True)
         
@@ -279,45 +563,78 @@ def package_and_export(track_folder, bpm, key, stem_mode, art,
         "Instrumental": t_dir/"no_vocals.wav"
     }
     
-    # Exports (Stems, MIDI, Shots, Loops)
+    # 2. Export Full Stems
     for s in ex_stems:
         if stems.get(s, Path("x")).exists():
             shutil.copy(stems[s], OUTPUT_DIR/"Stems"/f"{bpm}BPM_{key}_{s}.wav")
+            
+    # 3. Extract MIDI
     if do_midi and MIDI_AVAILABLE:
         for s in ["Bass", "Piano", "Guitar", "Other"]:
-            if stems.get(s, Path("x")).exists(): extract_midi(stems[s], OUTPUT_DIR/"MIDI"/f"{bpm}BPM_{key}_{s}.mid")
-    if do_oneshots and stems["Drums"].exists():
+            if stems.get(s, Path("x")).exists():
+                extract_midi(stems[s], OUTPUT_DIR/"MIDI"/f"{bpm}BPM_{key}_{s}.mid")
+
+    # 4. Extract One Shots
+    if do_oneshots and stems.get("Drums", Path("x")).exists():
         extract_one_shots(stems["Drums"], bpm, OUTPUT_DIR/"OneShots", loud_mode, loud_target)
     
-    grid_src = stems["Drums"] if stems["Drums"].exists() else next((stems[k] for k in stems if stems[k].exists()), None)
+    # 5. Build Grid for Looping
+    # Prefer Drums for rhythmic grid, fallback to whatever is available
+    grid_src = stems.get("Drums")
+    if not grid_src or not grid_src.exists():
+        # Fallback to first available stem
+        grid_src = next((stems[k] for k in stems if stems[k].exists()), None)
+    
+    # Load audio to detect beats
     y, sr = librosa.load(str(grid_src), sr=22050, duration=240)
     _, beats = librosa.beat.beat_track(y=y, sr=sr)
     beat_times = librosa.frames_to_time(beats, sr=sr)
-    bar_starts = [int(t*1000) for t in beat_times[::4]] if len(beat_times) >= 8 else [int(i * (240000/bpm)) for i in range(int((len(y)/sr)/(240/bpm)))]
+    
+    # If beat detection failed or is sparse, use mathematical grid
+    if len(beat_times) < 8:
+         ms_per_beat = 60000.0 / bpm
+         total_len_ms = (len(y) / sr) * 1000
+         bar_starts = [int(i * (ms_per_beat * 4)) for i in range(int(total_len_ms // (ms_per_beat * 4)))]
+    else:
+        # Every 4th beat is a bar start (assuming 4/4 time)
+        bar_starts = [int(t*1000) for t in beat_times[::4]]
+        
     bar_ints = sorted([int(b) for b in bars])
     
+    # 6. Generate Loops (Instrumental)
     all_loops = {}
     for s in loop_stems:
-        if s == "Vocals" and do_vocal_chops: continue
+        if s == "Vocals" and do_vocal_chops:
+            continue # Handle vocals separately in chop engine
+            
         if stems.get(s, Path("x")).exists():
-            exported = make_quantized_loops(stems[s], s, bpm, key, bar_starts, bar_ints, hop, loops_per, topk, 
-                                            fadems, loopseam, seamms, mingap, loud_mode, loud_target, OUTPUT_DIR/"Loops")
+            exported = make_quantized_loops(
+                stems[s], s, bpm, key, bar_starts, bar_ints, hop, loops_per, topk, 
+                fadems, loopseam, seamms, mingap, loud_mode, loud_target, OUTPUT_DIR/"Loops"
+            )
             all_loops[s] = exported
 
-    if do_vocal_chops and stems["Vocals"].exists():
-        exported = make_quantized_loops(stems["Vocals"], "Vocals_Chop", bpm, key, bar_starts, [1, 2], 1, 30, 0, 
-                                        fadems, False, 0, 0, loud_mode, loud_target, OUTPUT_DIR/"Vocal_Chops")
+    # 7. Generate Vocal Chops
+    if do_vocal_chops and stems.get("Vocals", Path("x")).exists():
+        # We reuse the quantized loop engine but with shorter settings
+        # This creates "Vocal Loops" effectively.
+        exported = make_quantized_loops(
+            stems["Vocals"], "Vocals_Chop", bpm, key, bar_starts, [1, 2], 1, 30, 0, 
+            fadems, False, 0, 0, loud_mode, loud_target, OUTPUT_DIR/"Vocal_Chops"
+        )
         all_loops["Vocals"] = exported
 
-    # --- SMART VIDEO ENGINE ---
+    # 8. Render Social Media Video (Smart Crop)
     vid_path = None
     if art and any(all_loops.values()):
+        # Choose background audio (prefer melodic elements)
         for k in ["Other", "Synths", "Piano", "Guitar", "Instrumental", "Bass", "Drums"]:
             if all_loops.get(k): 
                 a_path = all_loops[k][0]
                 break
         
         print(f"Rendering Video ({vid_fmt})...")
+        
         # Define Resolution
         res_map = {
             "9:16 (TikTok/Reels)": (1080, 1920),
@@ -328,7 +645,7 @@ def package_and_export(track_folder, bpm, key, stem_mode, art,
         
         clip = AudioFileClip(str(a_path))
         
-        # Load & Smart Crop
+        # Load & Smart Crop Image
         bg_clip = ImageClip(art)
         img_w, img_h = bg_clip.size
         
@@ -338,47 +655,59 @@ def package_and_export(track_folder, bpm, key, stem_mode, art,
         
         if img_aspect > target_aspect:
             # Image is wider than target: resize by height, crop width
-            new_h = h
-            new_w = int(img_w * (h / img_h))
             bg_clip = bg_clip.resize(height=h)
-            # Center crop
+            new_w = bg_clip.w
             crop_x = (new_w - w) // 2
             bg_clip = bg_clip.crop(x1=crop_x, width=w)
         else:
             # Image is taller/narrower: resize by width, crop height
-            new_w = w
-            new_h = int(img_h * (w / img_w))
             bg_clip = bg_clip.resize(width=w)
+            new_h = bg_clip.h
             crop_y = (new_h - h) // 2
             bg_clip = bg_clip.crop(y1=crop_y, height=h)
 
-        # Add zoom effect
+        # Add subtle zoom effect
         bg_clip = bg_clip.resize(lambda t: 1 + 0.02*t).set_position("center").set_duration(clip.duration)
         
-        # Progress Bar
-        bar = ColorClip(size=(w, 20), color=(255,255,255)).set_opacity(0.8)
-        bar = bar.set_position(lambda t: (int(-w + w*(t/clip.duration)), h - 50))
+        # Add Progress Bar
+        bar_h = 20
+        # Use ColorClip
+        bar = ColorClip(size=(w, bar_h), color=(255,255,255)).set_opacity(0.8)
+        
+        # Animate bar position from left (-width) to right (0)
+        # Position is (x, y). y is fixed at bottom minus offset.
+        bar_y = h - 100
+        bar = bar.set_position(lambda t: (int(-w + w*(t/clip.duration)), bar_y))
         bar = bar.set_duration(clip.duration)
         
         final = CompositeVideoClip([bg_clip, bar], size=(w,h))
         final.audio = clip
-        vid_path = str(OUTPUT_DIR/"Promo.mp4")
+        
+        vid_path = str(OUTPUT_DIR / "Promo.mp4")
+        
+        # Write file (using libx264 for video, aac for audio)
         final.write_videofile(vid_path, fps=24, codec="libx264", audio_codec="aac", logger=None)
 
+    # 9. Create Zip Archive
     z_path = "NightPulse_Ultimate.zip"
     with zipfile.ZipFile(z_path, "w") as zf:
         for r, _, fs in os.walk(OUTPUT_DIR):
-            for f in fs: zf.write(Path(r)/f, Path(r).relative_to(OUTPUT_DIR)/f)
+            for f in fs:
+                file_path = Path(r) / f
+                arc_name = file_path.relative_to(OUTPUT_DIR)
+                zf.write(file_path, arc_name)
             
     return z_path, vid_path
 
-# -----------------------------
-# UI Layout
-# -----------------------------
+
+# ==========================================
+# 9. USER INTERFACE
+# ==========================================
+
 with gr.Blocks(title="Night Pulse | Ultimate") as app:
     gr.Markdown("# 🎹 Night Pulse | Studio Ultimate")
     
-    # Hidden State
+    # -- HIDDEN STATE --
     folder = gr.State()
     bpm_st = gr.State()
     key_st = gr.State()
@@ -388,11 +717,18 @@ with gr.Blocks(title="Night Pulse | Ultimate") as app:
         # --- COL 1: CONFIGURATION ---
         with gr.Column(scale=1):
             gr.Markdown("### 1. Setup & Source")
+            
             with gr.Tabs():
-                with gr.Tab("Link"): url = gr.Textbox(label="YouTube/SC URL")
-                with gr.Tab("File"): file = gr.Audio(type="filepath", label="Upload File")
+                with gr.Tab("Link"):
+                    url = gr.Textbox(label="YouTube/SC URL", placeholder="https://...")
+                with gr.Tab("File"):
+                    file = gr.Audio(type="filepath", label="Upload File")
             
-            mode = gr.Dropdown([("2 Stems (Vox+Inst)", "2stem"), ("4 Stems (Basic)", "4stem"), ("6 Stems (Full)", "6stem")], value="6stem", label="Separation Model")
+            mode = gr.Dropdown(
+                [("2 Stems (Vox+Inst)", "2stem"), ("4 Stems (Basic)", "4stem"), ("6 Stems (Full)", "6stem")],
+                value="6stem", 
+                label="Separation Model"
+            )
             mbpm = gr.Number(label="Manual BPM (Optional)")
             
             gr.Markdown("#### Extraction Targets")
@@ -406,9 +742,10 @@ with gr.Blocks(title="Night Pulse | Ultimate") as app:
         # --- COL 2: REFINEMENT (Dynamic) ---
         with gr.Column(scale=1):
             gr.Markdown("### 2. Select & Refine")
+            
             info = gr.Markdown("Waiting for analysis...")
             
-            # Dynamic checkboxes
+            # These checkboxes update dynamically after Phase 1
             ex_stems = gr.CheckboxGroup(label="Export Full Stems")
             lp_stems = gr.CheckboxGroup(label="Generate Loops For")
             
@@ -424,13 +761,19 @@ with gr.Blocks(title="Night Pulse | Ultimate") as app:
         # --- COL 3: EXPORT SETTINGS ---
         with gr.Column(scale=1):
             gr.Markdown("### 3. Loop Engine & Video")
+            
             with gr.Row():
                 loops_per = gr.Slider(1, 40, 12, 1, label="Loops Count")
                 hop = gr.Slider(1, 8, 1, 1, label="Hop (Bars)")
+            
             bars = gr.CheckboxGroup(["1","2","4","8"], ["4","8"], label="Loop Lengths")
             
             art = gr.Image(type="filepath", label="Cover Art (Auto-Resize)")
-            vid_fmt = gr.Dropdown(["9:16 (TikTok/Reels)", "16:9 (YouTube)", "1:1 (Square)"], value="9:16 (TikTok/Reels)", label="Video Format")
+            vid_fmt = gr.Dropdown(
+                ["9:16 (TikTok/Reels)", "16:9 (YouTube)", "1:1 (Square)"], 
+                value="9:16 (TikTok/Reels)", 
+                label="Video Format"
+            )
 
             with gr.Accordion("Advanced Audio", open=False):
                 l_mode = gr.Dropdown(["none", "peak", "rms", "lufs"], "lufs", label="Norm Mode")
@@ -449,17 +792,29 @@ with gr.Blocks(title="Night Pulse | Ultimate") as app:
             z_out = gr.File(label="Complete Pack (Zip)")
             v_out = gr.Video(label="Social Media Promo")
 
-    # Wire up
+    # --- EVENT WIRING ---
+    
     def p1_wrap(f, u, m, b):
-        d, ba, v, bpm, key, pth, md, c1, c2 = analyze_and_separate(f, u, m, b)
-        return d, ba, v, f"### 🎵 Detected: {bpm} BPM | Key: {key}", bpm, key, pth, md, c1, c2
+        """Wrapper to unpack results into UI components"""
+        d, ba, v, analysis_text, bpm, key, pth, md, c1, c2 = analyze_and_separate(f, u, m, b)
+        return d, ba, v, analysis_text, bpm, key, pth, md, c1, c2
         
-    btn1.click(p1_wrap, [file, url, mode, mbpm], [p1, p2, p3, info, bpm_st, key_st, folder, mode_st, ex_stems, lp_stems])
+    btn1.click(
+        p1_wrap, 
+        inputs=[file, url, mode, mbpm], 
+        outputs=[p1, p2, p3, info, bpm_st, key_st, folder, mode_st, ex_stems, lp_stems]
+    )
     
-    btn2.click(package_and_export, 
-               [folder, bpm_st, key_st, mode_st, art, ex_stems, lp_stems, do_midi, do_oneshots, do_vox,
-                loops_per, bars, hop, topk, fadems, seam, seamms, mingap, l_mode, l_target, vid_fmt], 
-               [z_out, v_out])
+    btn2.click(
+        package_and_export, 
+        inputs=[
+            folder, bpm_st, key_st, mode_st, art, 
+            ex_stems, lp_stems, do_midi, do_oneshots, do_vox,
+            loops_per, bars, hop, topk, fadems, loopseam, seamms, mingap, 
+            l_mode, l_target, vid_fmt
+        ], 
+        outputs=[z_out, v_out]
+    )
 
 if __name__ == "__main__":
     app.launch(ssr_mode=False)