loukai-app 0.3.0

package/src/renderer/js/player.js

@@ -0,0 +1,232 @@
+import { KaraokeRenderer } from './karaokeRenderer.js';
+import { CDGPlayer } from './cdgPlayer.js';
+
+export class PlayerController {
+  constructor(kaiPlayer = null) {
+    this.kaiPlayer = kaiPlayer;
+    // lyricsContainer removed - KaraokeRenderer handles canvas-based lyrics now
+
+    // Initialize karaoke renderer for KAI format lyrics
+    this.karaokeRenderer = new KaraokeRenderer('karaokeCanvas');
+
+    // Set up singer change callback for backup:PA feature
+    // When a line with singer="backup:PA" becomes active, route vocals to PA
+    this.karaokeRenderer.onSingerChange = (singer) => {
+      if (this.kaiPlayer) {
+        const shouldEnableVocalsPA = singer === 'backup:PA';
+        this.kaiPlayer.setVocalsPAEnabled(shouldEnableVocalsPA);
+      }
+    };
+
+    // Initialize CDG player for CDG format (audio + graphics)
+    this.cdgPlayer = new CDGPlayer('karaokeCanvas');
+
+    // Track current format and active player
+    this.currentFormat = null; // 'kai' or 'cdg'
+    this.currentPlayer = null; // Reference to active PlayerInterface instance
+
+    // Ensure canvas is properly sized after initialization
+    setTimeout(() => {
+      if (this.karaokeRenderer && this.karaokeRenderer.resizeHandler) {
+        this.karaokeRenderer.resizeHandler();
+      }
+    }, 200);
+
+    // DOM element references removed - React PlayerControls handles time/progress display now
+    // Progress bar click-to-seek handled by React PlayerControls
+    // Time display handled by React PlayerControls
+
+    this.isPlaying = false;
+
+    this.init();
+  }
+
+  init() {
+    this.setupEventListeners();
+
+    this.updateTimer = setInterval(() => {
+      if (this.isPlaying) {
+        this.updatePosition();
+        // if (Math.random() < 0.05) { // Debug occasionally
+        // }
+      }
+    }, 100);
+  }
+
+  setupEventListeners() {
+    // Progress bar click-to-seek now handled by React PlayerControls component
+    // Transport controls (play/pause/restart/next) handled by React TransportControlsWrapper
+  }
+
+  onSongLoaded(metadata) {
+    // Store song metadata for display
+    if (this.karaokeRenderer && metadata) {
+      this.karaokeRenderer.setSongMetadata({
+        title: metadata.title,
+        artist: metadata.artist,
+        requester: metadata.requester,
+      });
+    }
+
+    // Get duration from player for karaokeRenderer
+    let duration = this.currentPlayer?.getDuration() || metadata?.duration || 0;
+
+    // If still zero, try to estimate from lyrics end time as fallback
+    if (duration === 0 && metadata?.lyrics && Array.isArray(metadata.lyrics)) {
+      let maxLyricTime = 0;
+      for (const line of metadata.lyrics) {
+        const endTime = line.end || line.end_time || (line.start || line.time || 0) + 3;
+        maxLyricTime = Math.max(maxLyricTime, endTime);
+      }
+      if (maxLyricTime > 0) {
+        duration = maxLyricTime + 10; // Add some padding
+      }
+    }
+
+    // Load lyrics into karaoke renderer
+    const lyrics = metadata?.lyrics || null;
+    if (lyrics) {
+      this.karaokeRenderer.loadLyrics(lyrics, duration);
+      // Initial render at position 0 to show title
+      this.karaokeRenderer.setCurrentTime(0);
+    }
+
+    // Load vocals audio data for waveform visualization
+    if (metadata?.audio?.sources) {
+      const vocalsSource = metadata.audio.sources.find(
+        (source) => source.name === 'vocals' || source.filename?.includes('vocals')
+      );
+
+      if (vocalsSource && vocalsSource.audioData) {
+        this.karaokeRenderer.setVocalsAudio(vocalsSource.audioData);
+      } else {
+        // No vocals track available - waveform disabled
+      }
+
+      // Note: Butterchurn visualization now uses PA analyser from kaiPlayer
+      // Connected in songLoaders.js during song load
+      // No need to decode mixdown buffer separately
+    } else {
+      // No audio sources available - waveforms disabled
+    }
+
+    // Display updates handled by React PlayerControls via IPC state
+
+    // Ensure we're in stopped state
+    this.pause();
+  }
+
+  // renderLyrics() method removed - KaraokeRenderer handles canvas-based lyrics now
+
+  updatePosition() {
+    // Update karaokeRenderer for lyrics sync ONLY
+    // (PlayerInterface handles state broadcasting, song end detection, UI updates)
+    if (this.currentPlayer && this.karaokeRenderer) {
+      const position = this.currentPlayer.getCurrentPosition();
+      this.karaokeRenderer.setCurrentTime(position);
+    }
+  }
+
+  // updateTimeDisplay() method removed - React PlayerControls handles time display via IPC state
+  // updateProgressBar() method removed - React PlayerControls handles progress bar via IPC state
+
+  // updateActiveLyrics() method removed - KaraokeRenderer handles canvas-based lyrics now
+  // seekToProgressPosition() method removed - React PlayerControls handles click-to-seek now
+
+  async setPosition(positionSec) {
+    if (!this.currentPlayer) return;
+
+    // Bounds check using player's duration
+    const duration = this.currentPlayer.getDuration();
+    const boundedPosition = Math.max(0, Math.min(duration, positionSec));
+
+    // Seek player
+    try {
+      await this.currentPlayer.seek(boundedPosition);
+    } catch (error) {
+      console.error('Seek error:', error);
+    }
+
+    // Update karaoke renderer immediately for lyrics sync
+    if (this.karaokeRenderer) {
+      this.karaokeRenderer.setCurrentTime(boundedPosition);
+      // Reset the locked upcoming lyric so it recalculates based on new position
+      this.karaokeRenderer.lockedUpcomingIndex = null;
+    }
+
+    // Player engine will broadcast new position via reportStateChange() for UI updates
+  }
+
+  async play() {
+    this.isPlaying = true;
+
+    // Update renderer's current time BEFORE starting playback
+    // This ensures butterchurn starts from the correct position on resume
+    if (this.currentPlayer && this.karaokeRenderer) {
+      const position = this.currentPlayer.getCurrentPosition();
+      this.karaokeRenderer.setCurrentTime(position);
+    }
+
+    if (this.karaokeRenderer) {
+      this.karaokeRenderer.setPlaying(true);
+    }
+
+    // Play the actual audio
+    if (this.currentPlayer) {
+      await this.currentPlayer.play();
+    }
+  }
+
+  async pause() {
+    this.isPlaying = false;
+
+    if (this.karaokeRenderer) {
+      this.karaokeRenderer.setPlaying(false);
+    }
+
+    // Pause the actual audio
+    if (this.currentPlayer) {
+      await this.currentPlayer.pause();
+    }
+  }
+
+  // Utility methods removed - no longer needed (formatTime handled by formatUtils.js)
+  // debugLoadVocals removed - no longer needed
+
+  applyWaveformSettings(settings) {
+    // Apply settings to active renderer (KAI or CDG)
+    if (this.currentFormat === 'kai' && this.karaokeRenderer) {
+      // Update waveformPreferences object (used by renderer)
+      if (settings.enableWaveforms !== undefined) {
+        this.karaokeRenderer.waveformPreferences.enableWaveforms = settings.enableWaveforms;
+      }
+      if (settings.enableEffects !== undefined) {
+        this.karaokeRenderer.waveformPreferences.enableEffects = settings.enableEffects;
+      }
+      if (settings.showUpcomingLyrics !== undefined) {
+        this.karaokeRenderer.waveformPreferences.showUpcomingLyrics = settings.showUpcomingLyrics;
+      }
+      if (settings.overlayOpacity !== undefined) {
+        this.karaokeRenderer.waveformPreferences.overlayOpacity = settings.overlayOpacity;
+      }
+    } else if (this.currentFormat === 'cdg' && this.cdgPlayer) {
+      // CDG player settings
+      if (settings.enableEffects !== undefined) {
+        this.cdgPlayer.setEffectsEnabled(settings.enableEffects);
+      }
+      if (settings.overlayOpacity !== undefined) {
+        this.cdgPlayer.overlayOpacity = settings.overlayOpacity;
+      }
+    }
+  }
+
+  destroy() {
+    if (this.updateTimer) {
+      clearInterval(this.updateTimer);
+    }
+
+    if (this.karaokeRenderer) {
+      this.karaokeRenderer.destroy();
+    }
+  }
+}

package/src/renderer/js/referencePitchTracker.js

@@ -0,0 +1,130 @@
+/**
+ * Reference Pitch Tracker
+ * Manages real-time pitch reference from vocal stem analysis
+ * Provides target pitch for auto-tune correction and scoring
+ *
+ * Note: Pitch detection is now done at runtime from the vocal stem audio,
+ * not from stored data. This simplifies the file format and provides
+ * consistent behavior across all songs.
+ */
+
+export class ReferencePitchTracker {
+  constructor() {
+    // Real-time vocal pitch detection
+    this.vocalPitch = null;
+    this.vocalPitchTimestamp = 0;
+
+    // Settings
+    this.enabled = false;
+
+    // Playback state
+    this.currentTime = 0;
+    this.isPlaying = false;
+  }
+
+  /**
+   * Clear all reference data (when song unloads)
+   */
+  clear() {
+    this.vocalPitch = null;
+    this.vocalPitchTimestamp = 0;
+    this.currentTime = 0;
+    this.isPlaying = false;
+  }
+
+  /**
+   * Update current playback time
+   * @param {number} time - Current playback time in seconds
+   */
+  updateTime(time) {
+    this.currentTime = time;
+  }
+
+  /**
+   * Set playback state
+   * @param {boolean} playing - Whether playback is active
+   */
+  setPlaying(playing) {
+    this.isPlaying = playing;
+  }
+
+  /**
+   * Update vocal pitch from real-time detection
+   * Called by the vocal stem pitch detection worklet
+   * @param {number} frequency - Detected frequency in Hz
+   * @param {number} timestamp - Detection timestamp (playback time)
+   */
+  updateVocalPitch(frequency, timestamp) {
+    this.vocalPitch = frequency;
+    this.vocalPitchTimestamp = timestamp;
+  }
+
+  /**
+   * Enable/disable pitch tracking
+   * @param {boolean} enabled - Whether tracking is enabled
+   */
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Get target pitch at current playback time
+   * @returns {number|null} - Target frequency in Hz, or null if none available
+   */
+  getCurrentTargetPitch() {
+    if (!this.enabled || !this.isPlaying) {
+      return null;
+    }
+
+    return this.getVocalPitch();
+  }
+
+  /**
+   * Get pitch from real-time vocal analysis
+   * @returns {number|null} - Frequency in Hz or null
+   * @private
+   */
+  getVocalPitch() {
+    // Vocal pitch should be relatively recent (within 100ms)
+    const maxAge = 0.1; // 100ms
+    const age = this.currentTime - this.vocalPitchTimestamp;
+
+    if (this.vocalPitch && this.vocalPitch > 0 && age < maxAge) {
+      return this.vocalPitch;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get current reference source
+   * @returns {string} - 'vocals' or 'none'
+   */
+  getCurrentSource() {
+    if (!this.enabled || !this.isPlaying) {
+      return 'none';
+    }
+
+    if (this.getVocalPitch() !== null) {
+      return 'vocals';
+    }
+
+    return 'none';
+  }
+
+  // Legacy methods for backward compatibility (no-ops)
+  loadVocalsF0() {
+    console.log(
+      '[ReferencePitchTracker] Stored pitch data no longer used - using real-time detection'
+    );
+  }
+
+  setPreferVocals() {
+    // No-op - always uses real-time vocal detection
+  }
+
+  updateMusicPitch(frequency, timestamp) {
+    // Alias for updateVocalPitch for backward compatibility
+    this.updateVocalPitch(frequency, timestamp);
+  }
+}

package/src/renderer/js/songLoaders.js

@@ -0,0 +1,334 @@
+/**
+ * Song Loading Utilities
+ * Extracted from main.js to simplify song loading logic
+ */
+
+/**
+ * Load CDG format song
+ */
+export async function loadCDGSong(app, songData, metadata) {
+  app.player.currentFormat = 'cdg';
+  app.player.currentPlayer = app.player.cdgPlayer;
+
+  // Set song end callback
+  app.player.currentPlayer.onSongEnded(() => app.handleSongEnded());
+
+  // Set up audio context for CDG renderer (PA output only)
+  if (!app.kaiPlayer) {
+    console.error('💿 Audio engine not initialized');
+    app.updateStatus('Error: Audio engine not ready');
+    return;
+  }
+
+  // Get PA audio context for playback
+  const paContext = app.kaiPlayer.audioContexts.PA;
+  const paMasterGain = app.kaiPlayer.outputNodes.PA.masterGain;
+
+  // Create gain node for CDG audio in PA context
+  const cdgGainNode = paContext.createGain();
+  cdgGainNode.connect(paMasterGain);
+
+  // Create analyser in PA context
+  const analyserNode = paContext.createAnalyser();
+  analyserNode.fftSize = 2048;
+  // Analyser taps the signal but doesn't affect routing
+  cdgGainNode.connect(analyserNode);
+
+  // Set audio context in CDG renderer (PA context for playback)
+  app.player.cdgPlayer.setAudioContext(paContext, cdgGainNode, analyserNode);
+
+  // Load CDG data
+  await app.player.cdgPlayer.loadSong(songData);
+
+  // Load microphone settings for CDG (after micEngine is initialized)
+  if (app.player.cdgPlayer.micEngine) {
+    const micToSpeakers = await window.kaiAPI.settings.get('micToSpeakers', true);
+    const enableMic = await window.kaiAPI.settings.get('enableMic', true);
+    const autoTunePrefs = await window.kaiAPI.settings.get('autoTunePreferences', {});
+
+    // Apply settings to microphone engine
+    app.player.cdgPlayer.micEngine.micToSpeakers = micToSpeakers;
+    app.player.cdgPlayer.micEngine.enableMic = enableMic;
+
+    if (autoTunePrefs.enabled !== undefined) {
+      app.player.cdgPlayer.micEngine.autotuneSettings.enabled = autoTunePrefs.enabled;
+    }
+    if (autoTunePrefs.strength !== undefined) {
+      app.player.cdgPlayer.micEngine.autotuneSettings.strength = autoTunePrefs.strength;
+    }
+    if (autoTunePrefs.speed !== undefined) {
+      app.player.cdgPlayer.micEngine.autotuneSettings.speed = autoTunePrefs.speed;
+    }
+
+    // Start microphone if enabled
+    if (enableMic) {
+      const devicePrefs = await window.kaiAPI.settings.get('devicePreferences', {});
+      const inputDeviceId = devicePrefs?.input?.id || 'default';
+      await app.player.cdgPlayer.startMicrophoneInput(inputDeviceId);
+    }
+  }
+
+  // Load and apply waveform preferences from settings for CDG
+  const waveformPrefs = await window.kaiAPI.settings.get('waveformPreferences', {
+    enableEffects: true,
+    randomEffectOnSong: false,
+    overlayOpacity: 0.7,
+  });
+
+  // Load device preferences for microphone
+  await app.player.karaokeRenderer.ensureInputDeviceSelection();
+
+  // Apply preferences to CDG player
+  app.player.cdgPlayer.setOverlayOpacity(waveformPrefs.overlayOpacity);
+  app.player.cdgPlayer.setEffectsEnabled(waveformPrefs.enableEffects);
+
+  // Set Butterchurn effects canvas for CDG background
+  await setupButterchurnForCDG(app, songData, waveformPrefs);
+
+  // CDG doesn't use audio engine or lyrics
+  // Include requester from songData if not in metadata
+  const fullMetadata = {
+    ...metadata,
+    requester: metadata.requester || songData.requester || app.currentSong?.requester,
+  };
+  app.player.onSongLoaded(fullMetadata);
+
+  // Broadcast that CDG is ready (clear loading state)
+  if (window.kaiAPI?.renderer) {
+    window.kaiAPI.renderer.songLoaded({
+      path: app.currentSong?.originalFilePath || app.currentSong?.filePath,
+      metadata: metadata,
+      isLoading: false,
+      title: metadata?.title || 'CDG Song',
+      artist: metadata?.artist || 'Unknown Artist',
+      format: 'cdg',
+      duration: app.player.cdgPlayer?.getDuration() || 0,
+      requester: app.currentSong?.requester || 'KJ',
+    });
+  }
+
+  // Controls now managed by React TransportControlsWrapper
+  app.updateStatus(`Loaded: ${metadata?.title || 'CDG Song'}`);
+}
+
+/**
+ * Load KAI format song
+ */
+export async function loadKAISong(app, songData, metadata) {
+  app.player.currentFormat = 'kai';
+  app.player.currentPlayer = app.kaiPlayer;
+
+  // Set song end callback
+  app.player.currentPlayer.onSongEnded(() => app.handleSongEnded());
+
+  // CLEAN SLATE APPROACH: Reinitialize audio engine
+  if (app.kaiPlayer && app.currentSong) {
+    // Create a backup copy of the song data BEFORE reinitialize
+    const songDataBackup = {
+      ...app.currentSong,
+      audio: app.currentSong.audio
+        ? {
+            ...app.currentSong.audio,
+            sources: app.currentSong.audio.sources ? [...app.currentSong.audio.sources] : [],
+          }
+        : null,
+    };
+
+    await app.kaiPlayer.reinitialize();
+    await app.kaiPlayer.loadSong(songDataBackup);
+
+    // Restore the original song data if it was corrupted
+    if (!app.currentSong.audio && songDataBackup.audio) {
+      app.currentSong.audio = songDataBackup.audio;
+    }
+    if (!app.currentSong.lyrics && songDataBackup.lyrics) {
+      app.currentSong.lyrics = songDataBackup.lyrics;
+    }
+  }
+
+  // CLEAN SLATE APPROACH: Reinitialize karaoke renderer
+  if (app.player && app.currentSong) {
+    if (app.player.karaokeRenderer) {
+      app.player.karaokeRenderer.reinitialize();
+    }
+
+    // Pass full song data which includes lyrics, audio sources, and updated duration from audio engine
+    const fullMetadata = {
+      ...metadata,
+      lyrics: app.currentSong.lyrics,
+      duration: app.kaiPlayer
+        ? app.kaiPlayer.getDuration()
+        : app.currentSong.metadata?.duration || 0,
+      audio: app.currentSong.audio, // Include audio sources for vocals waveform
+      requester: metadata.requester || songData.requester || app.currentSong.requester,
+    };
+    app.player.onSongLoaded(fullMetadata);
+
+    // Load and apply waveform preferences from settings for KAI
+    // Defaults are now provided by settingsManager from shared/defaults.js
+    const waveformPrefs = await window.kaiAPI.settings.get('waveformPreferences');
+
+    // Apply preferences to karaokeRenderer
+    if (app.player.karaokeRenderer) {
+      app.player.karaokeRenderer.setWaveformsEnabled(waveformPrefs.enableWaveforms);
+      app.player.karaokeRenderer.setEffectsEnabled(waveformPrefs.enableEffects);
+      app.player.karaokeRenderer.setShowUpcomingLyrics(waveformPrefs.showUpcomingLyrics);
+      app.player.karaokeRenderer.waveformPreferences.overlayOpacity = waveformPrefs.overlayOpacity;
+
+      // Connect butterchurn to PA analyser for visualization (KAI format)
+      if (app.kaiPlayer?.outputNodes?.PA?.analyser) {
+        app.player.karaokeRenderer.setVisualizationAnalyser(app.kaiPlayer.outputNodes.PA.analyser);
+      }
+
+      // Restart microphone capture if waveforms are enabled
+      if (waveformPrefs.enableWaveforms) {
+        setTimeout(() => {
+          app.player.karaokeRenderer.startMicrophoneCapture();
+        }, 100);
+      }
+
+      // Update effect display with current preset
+      setTimeout(() => app.updateEffectDisplay(), 100);
+
+      // Apply random effect if enabled
+      await applyRandomEffectIfEnabled(app, waveformPrefs);
+    }
+  }
+
+  // Wait for all contexts and buffers to be ready
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  // Clear pending metadata
+  app._pendingMetadata = null;
+}
+
+/**
+ * Setup Butterchurn for CDG visualization
+ */
+async function setupButterchurnForCDG(app, songData, waveformPrefs) {
+  if (app.player.karaokeRenderer.effectsCanvas && app.player.karaokeRenderer.butterchurn) {
+    app.player.cdgPlayer.setEffectsCanvas(
+      app.player.karaokeRenderer.effectsCanvas,
+      app.player.karaokeRenderer.butterchurn
+    );
+
+    // Connect butterchurn to CDG's PA analyser (already connected to CDG audio source)
+    if (app.player.cdgPlayer.analyserNode) {
+      app.player.karaokeRenderer.setVisualizationAnalyser(app.player.cdgPlayer.analyserNode);
+    }
+
+    // Apply random effect if enabled
+    await applyRandomEffectIfEnabled(app, waveformPrefs);
+  }
+}
+
+/**
+ * Load M4A Stems format song
+ */
+export async function loadM4ASong(app, songData, metadata) {
+  app.player.currentFormat = 'm4a-stems';
+  app.player.currentPlayer = app.kaiPlayer;
+
+  // Set song end callback
+  app.player.currentPlayer.onSongEnded(() => app.handleSongEnded());
+
+  // CLEAN SLATE APPROACH: Reinitialize audio engine (same as KAI)
+  if (app.kaiPlayer && app.currentSong) {
+    // Create a backup copy of the song data BEFORE reinitialize
+    const songDataBackup = {
+      ...app.currentSong,
+      audio: app.currentSong.audio
+        ? {
+            ...app.currentSong.audio,
+            sources: app.currentSong.audio.sources ? [...app.currentSong.audio.sources] : [],
+          }
+        : null,
+    };
+
+    await app.kaiPlayer.reinitialize();
+    await app.kaiPlayer.loadSong(songDataBackup);
+
+    // Restore the original song data if it was corrupted
+    if (!app.currentSong.audio && songDataBackup.audio) {
+      app.currentSong.audio = songDataBackup.audio;
+    }
+    if (!app.currentSong.lyrics && songDataBackup.lyrics) {
+      app.currentSong.lyrics = songDataBackup.lyrics;
+    }
+  }
+
+  // CLEAN SLATE APPROACH: Reinitialize karaoke renderer
+  if (app.player && app.currentSong) {
+    if (app.player.karaokeRenderer) {
+      app.player.karaokeRenderer.reinitialize();
+    }
+
+    // Pass full song data which includes lyrics, audio sources, and updated duration
+    const fullMetadata = {
+      ...metadata,
+      lyrics: app.currentSong.lyrics,
+      duration: app.kaiPlayer
+        ? app.kaiPlayer.getDuration()
+        : app.currentSong.metadata?.duration || 0,
+      audio: app.currentSong.audio, // Include audio sources for vocals waveform
+      requester: metadata.requester || songData.requester || app.currentSong.requester,
+    };
+    app.player.onSongLoaded(fullMetadata);
+
+    // Load and apply waveform preferences from settings
+    // Defaults are now provided by settingsManager from shared/defaults.js
+    const waveformPrefs = await window.kaiAPI.settings.get('waveformPreferences');
+
+    // Apply preferences to karaokeRenderer
+    if (app.player.karaokeRenderer) {
+      app.player.karaokeRenderer.setWaveformsEnabled(waveformPrefs.enableWaveforms);
+      app.player.karaokeRenderer.setEffectsEnabled(waveformPrefs.enableEffects);
+      app.player.karaokeRenderer.setShowUpcomingLyrics(waveformPrefs.showUpcomingLyrics);
+      app.player.karaokeRenderer.waveformPreferences.overlayOpacity = waveformPrefs.overlayOpacity;
+
+      // Connect butterchurn to PA analyser for visualization (M4A format)
+      if (app.kaiPlayer?.outputNodes?.PA?.analyser) {
+        app.player.karaokeRenderer.setVisualizationAnalyser(app.kaiPlayer.outputNodes.PA.analyser);
+      }
+
+      // Restart microphone capture if waveforms are enabled
+      if (waveformPrefs.enableWaveforms) {
+        setTimeout(() => {
+          app.player.karaokeRenderer.startMicrophoneCapture();
+        }, 100);
+      }
+
+      // Update effect display with current preset
+      setTimeout(() => app.updateEffectDisplay(), 100);
+
+      // Apply random effect if enabled
+      await applyRandomEffectIfEnabled(app, waveformPrefs);
+    }
+  }
+
+  // Wait for all contexts and buffers to be ready
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  // Clear pending metadata
+  app._pendingMetadata = null;
+}
+
+/**
+ * Apply random Butterchurn effect if enabled (with debouncing)
+ */
+function applyRandomEffectIfEnabled(app, waveformPrefs) {
+  if (waveformPrefs.randomEffectOnSong && app.player.karaokeRenderer.butterchurn) {
+    // Clear any existing timeout
+    if (app.randomEffectTimeout) {
+      clearTimeout(app.randomEffectTimeout);
+    }
+
+    app.randomEffectTimeout = setTimeout(async () => {
+      try {
+        await window.kaiAPI.effects.random();
+      } catch (error) {
+        console.error('Failed to apply random effect:', error);
+      }
+    }, 500);
+  }
+}