loukai-app 0.3.0

package/src/shared/contexts/SettingsContext.jsx

@@ -0,0 +1,50 @@
+/**
+ * SettingsContext - Application settings/preferences
+ *
+ * Manages device preferences, waveform settings, autotune settings
+ * Uses unified defaults from shared/defaults.js
+ */
+
+import { createContext, useContext, useState } from 'react';
+import { AUDIO_DEVICE_DEFAULTS, WAVEFORM_DEFAULTS, AUTOTUNE_DEFAULTS } from '../defaults.js';
+
+const SettingsContext = createContext(null);
+
+export function SettingsProvider({ children }) {
+  const [devicePreferences, setDevicePreferences] = useState({
+    ...AUDIO_DEVICE_DEFAULTS,
+  });
+
+  const [waveformPreferences, setWaveformPreferences] = useState({
+    ...WAVEFORM_DEFAULTS,
+    micToSpeakers: true,
+    enableMic: true,
+    disabledEffects: [],
+  });
+
+  const [autoTunePreferences, setAutoTunePreferences] = useState({
+    ...AUTOTUNE_DEFAULTS,
+  });
+
+  const value = {
+    // Settings
+    devicePreferences,
+    waveformPreferences,
+    autoTunePreferences,
+
+    // Actions
+    setDevicePreferences,
+    setWaveformPreferences,
+    setAutoTunePreferences,
+  };
+
+  return <SettingsContext.Provider value={value}>{children}</SettingsContext.Provider>;
+}
+
+export function useSettings() {
+  const context = useContext(SettingsContext);
+  if (!context) {
+    throw new Error('useSettings must be used within SettingsProvider');
+  }
+  return context;
+}

package/src/shared/defaults.js

@@ -0,0 +1,158 @@
+/**
+ * Unified defaults for all settings
+ * Single source of truth - import this everywhere instead of defining defaults inline
+ */
+
+export const MIXER_DEFAULTS = {
+  PA: { gain: 0, muted: false, mono: false },
+  IEM: { gain: 0, muted: true, mono: true },
+  mic: { gain: 0, muted: true },
+  stems: {
+    vocals: { gain: 0, muted: false },
+    instrumental: { gain: 0, muted: false },
+    bass: { gain: 0, muted: false },
+    drums: { gain: 0, muted: false },
+  },
+};
+
+export const EFFECTS_DEFAULTS = {
+  current: null,
+  disabled: [],
+  enableWaveforms: false,
+  enableEffects: true,
+  randomEffectOnSong: false,
+  overlayOpacity: 0.7,
+  showUpcomingLyrics: true,
+};
+
+export const AUTOTUNE_DEFAULTS = {
+  enabled: false,
+  strength: 50,
+  speed: 20,
+  preferVocals: false,
+};
+
+export const MICROPHONE_DEFAULTS = {
+  enabled: false,
+  gain: 1.0,
+  toSpeakers: true,
+};
+
+export const AUDIO_DEVICE_DEFAULTS = {
+  PA: { id: 'default', name: 'Default Output' },
+  IEM: { id: 'default', name: 'Default Output' },
+  input: { id: 'default', name: 'Default Input' },
+};
+
+export const SERVER_DEFAULTS = {
+  requireKJApproval: true,
+  allowSongRequests: true,
+  serverName: 'Loukai Karaoke',
+  port: 3069,
+  maxRequestsPerIP: 10,
+  showQrCode: true,
+  displayQueue: true,
+};
+
+export const LLM_DEFAULTS = {
+  enabled: true,
+  provider: 'lmstudio',
+  model: '',
+  apiKey: '',
+  baseUrl: 'http://localhost:1234/v1',
+};
+
+export const CREATOR_DEFAULTS = {
+  outputToSongsFolder: false,
+  whisperModel: 'large-v3-turbo',
+  enableCrepe: true,
+  llm: LLM_DEFAULTS,
+};
+
+// Waveform preferences (alias for effects for backward compatibility)
+export const WAVEFORM_DEFAULTS = {
+  enableWaveforms: EFFECTS_DEFAULTS.enableWaveforms,
+  enableEffects: EFFECTS_DEFAULTS.enableEffects,
+  randomEffectOnSong: EFFECTS_DEFAULTS.randomEffectOnSong,
+  overlayOpacity: EFFECTS_DEFAULTS.overlayOpacity,
+  showUpcomingLyrics: EFFECTS_DEFAULTS.showUpcomingLyrics,
+};
+
+// UI defaults
+export const UI_DEFAULTS = {
+  sidebarCollapsed: true, // Start with sidebar collapsed for less overwhelming first experience
+};
+
+// All defaults in one object
+export const ALL_DEFAULTS = {
+  mixer: MIXER_DEFAULTS,
+  effects: EFFECTS_DEFAULTS,
+  autoTune: AUTOTUNE_DEFAULTS,
+  microphone: MICROPHONE_DEFAULTS,
+  audioDevices: AUDIO_DEVICE_DEFAULTS,
+  server: SERVER_DEFAULTS,
+  creator: CREATOR_DEFAULTS,
+  waveformPreferences: WAVEFORM_DEFAULTS,
+  autoTunePreferences: AUTOTUNE_DEFAULTS,
+  ui: UI_DEFAULTS,
+  sidebarCollapsed: UI_DEFAULTS.sidebarCollapsed,
+  iemMonoVocals: true,
+  songsFolder: null,
+  lastOpenedFile: null,
+  windowBounds: null,
+};
+
+/**
+ * Deep merge saved settings over defaults
+ * @param {Object} saved - Saved settings from disk
+ * @param {Object} defaults - Default values
+ * @returns {Object} Merged settings
+ */
+export function mergeWithDefaults(saved, defaults = ALL_DEFAULTS) {
+  if (!saved) return { ...defaults };
+
+  const result = {};
+  for (const key of Object.keys(defaults)) {
+    const defaultValue = defaults[key];
+    const savedValue = saved[key];
+
+    if (
+      defaultValue !== null &&
+      typeof defaultValue === 'object' &&
+      !Array.isArray(defaultValue) &&
+      savedValue !== null &&
+      typeof savedValue === 'object' &&
+      !Array.isArray(savedValue)
+    ) {
+      // Deep merge objects
+      result[key] = { ...defaultValue, ...savedValue };
+    } else if (savedValue !== undefined) {
+      result[key] = savedValue;
+    } else {
+      result[key] = defaultValue;
+    }
+  }
+
+  // Include any extra keys from saved that aren't in defaults
+  for (const key of Object.keys(saved)) {
+    if (!(key in result)) {
+      result[key] = saved[key];
+    }
+  }
+
+  return result;
+}
+
+export default {
+  MIXER_DEFAULTS,
+  EFFECTS_DEFAULTS,
+  AUTOTUNE_DEFAULTS,
+  MICROPHONE_DEFAULTS,
+  AUDIO_DEVICE_DEFAULTS,
+  SERVER_DEFAULTS,
+  LLM_DEFAULTS,
+  CREATOR_DEFAULTS,
+  WAVEFORM_DEFAULTS,
+  ALL_DEFAULTS,
+  mergeWithDefaults,
+};

package/src/shared/formatUtils.js

@@ -0,0 +1,59 @@
+/**
+ * Shared utility functions for formatting and display
+ * Used across renderer, web UI, and main process
+ */
+
+export function getFormatIcon(format) {
+  switch (format) {
+    case 'm4a-stems':
+      return '⚡'; // M4A stems format
+    case 'cdg-archive':
+    case 'cdg-pair':
+      return '💿';
+    default:
+      return '🎵'; // Default music icon
+  }
+}
+
+/**
+ * Format duration in seconds to MM:SS format
+ * @param {number} seconds - Duration in seconds
+ * @returns {string} Formatted duration (e.g., "3:45")
+ */
+export function formatDuration(seconds) {
+  if (!seconds || seconds <= 0) return '-';
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = Math.floor(seconds % 60);
+
+  return `${minutes}:${remainingSeconds.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Format time in seconds to MM:SS.T format (with tenths)
+ * @param {number} seconds - Time in seconds
+ * @returns {string} Formatted time (e.g., "3:45.7")
+ */
+export function formatTime(seconds) {
+  if (!seconds || isNaN(seconds)) return '0:00.0';
+
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  const tenths = Math.floor((seconds % 1) * 10);
+  return `${mins}:${secs.toString().padStart(2, '0')}.${tenths}`;
+}
+
+/**
+ * Format file size in bytes to human-readable format
+ * @param {number} bytes - File size in bytes
+ * @returns {string} Formatted size (e.g., "1.2 MB")
+ */
+export function formatFileSize(bytes) {
+  if (bytes === 0) return '0 B';
+
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+}

package/src/shared/formatUtils.test.js

@@ -0,0 +1,207 @@
+/**
+ * Format Utils Tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getFormatIcon, formatDuration, formatTime, formatFileSize } from './formatUtils.js';
+
+describe('formatUtils', () => {
+  describe('getFormatIcon', () => {
+    it('should return lightning icon for m4a-stems format', () => {
+      expect(getFormatIcon('m4a-stems')).toBe('⚡');
+    });
+
+    it('should return disc icon for cdg-archive format', () => {
+      expect(getFormatIcon('cdg-archive')).toBe('💿');
+    });
+
+    it('should return disc icon for cdg-pair format', () => {
+      expect(getFormatIcon('cdg-pair')).toBe('💿');
+    });
+
+    it('should return default music icon for unknown format', () => {
+      expect(getFormatIcon('unknown')).toBe('🎵');
+      expect(getFormatIcon('mp3')).toBe('🎵');
+      expect(getFormatIcon('')).toBe('🎵');
+    });
+
+    it('should return default icon for null/undefined', () => {
+      expect(getFormatIcon(null)).toBe('🎵');
+      expect(getFormatIcon(undefined)).toBe('🎵');
+    });
+  });
+
+  describe('formatDuration', () => {
+    it('should format zero seconds as dash', () => {
+      expect(formatDuration(0)).toBe('-');
+    });
+
+    it('should format null/undefined as dash', () => {
+      expect(formatDuration(null)).toBe('-');
+      expect(formatDuration(undefined)).toBe('-');
+    });
+
+    it('should format negative seconds as dash', () => {
+      expect(formatDuration(-10)).toBe('-');
+    });
+
+    it('should format seconds less than 1 minute', () => {
+      expect(formatDuration(5)).toBe('0:05');
+      expect(formatDuration(30)).toBe('0:30');
+      expect(formatDuration(59)).toBe('0:59');
+    });
+
+    it('should format exactly 1 minute', () => {
+      expect(formatDuration(60)).toBe('1:00');
+    });
+
+    it('should format minutes and seconds', () => {
+      expect(formatDuration(65)).toBe('1:05');
+      expect(formatDuration(125)).toBe('2:05');
+      expect(formatDuration(185)).toBe('3:05');
+    });
+
+    it('should pad single digit seconds with zero', () => {
+      expect(formatDuration(61)).toBe('1:01');
+      expect(formatDuration(121)).toBe('2:01');
+    });
+
+    it('should format long durations', () => {
+      expect(formatDuration(600)).toBe('10:00');
+      expect(formatDuration(3600)).toBe('60:00');
+      expect(formatDuration(3665)).toBe('61:05');
+    });
+
+    it('should handle decimal seconds by flooring', () => {
+      expect(formatDuration(65.7)).toBe('1:05');
+      expect(formatDuration(125.9)).toBe('2:05');
+    });
+
+    it('should format typical song durations', () => {
+      expect(formatDuration(180)).toBe('3:00'); // 3 minutes
+      expect(formatDuration(225)).toBe('3:45'); // 3:45
+      expect(formatDuration(270)).toBe('4:30'); // 4:30
+    });
+  });
+
+  describe('formatTime', () => {
+    it('should format zero as 0:00.0', () => {
+      expect(formatTime(0)).toBe('0:00.0');
+    });
+
+    it('should format null/undefined as 0:00.0', () => {
+      expect(formatTime(null)).toBe('0:00.0');
+      expect(formatTime(undefined)).toBe('0:00.0');
+    });
+
+    it('should format NaN as 0:00.0', () => {
+      expect(formatTime(NaN)).toBe('0:00.0');
+    });
+
+    it('should format seconds less than 1 minute with tenths', () => {
+      expect(formatTime(5.0)).toBe('0:05.0');
+      expect(formatTime(5.5)).toBe('0:05.5');
+      expect(formatTime(5.9)).toBe('0:05.9');
+    });
+
+    it('should format exactly 1 minute', () => {
+      expect(formatTime(60)).toBe('1:00.0');
+    });
+
+    it('should format minutes, seconds, and tenths', () => {
+      expect(formatTime(65.5)).toBe('1:05.5');
+      expect(formatTime(125.7)).toBe('2:05.7');
+    });
+
+    it('should pad single digit seconds with zero', () => {
+      expect(formatTime(61.5)).toBe('1:01.5');
+      expect(formatTime(121.2)).toBe('2:01.2');
+    });
+
+    it('should extract tenths of seconds', () => {
+      expect(formatTime(1.1)).toBe('0:01.1');
+      expect(formatTime(1.5)).toBe('0:01.5');
+      expect(formatTime(1.9)).toBe('0:01.9');
+    });
+
+    it('should floor tenths (not round)', () => {
+      expect(formatTime(1.19)).toBe('0:01.1');
+      expect(formatTime(1.99)).toBe('0:01.9');
+    });
+
+    it('should handle long durations', () => {
+      expect(formatTime(3665.5)).toBe('61:05.5');
+    });
+  });
+
+  describe('formatFileSize', () => {
+    it('should format zero bytes', () => {
+      expect(formatFileSize(0)).toBe('0 B');
+    });
+
+    it('should format bytes (< 1 KB)', () => {
+      expect(formatFileSize(1)).toBe('1 B');
+      expect(formatFileSize(500)).toBe('500 B');
+      expect(formatFileSize(1023)).toBe('1023 B');
+    });
+
+    it('should format kilobytes', () => {
+      expect(formatFileSize(1024)).toBe('1 KB');
+      expect(formatFileSize(2048)).toBe('2 KB');
+      expect(formatFileSize(1536)).toBe('1.5 KB');
+      expect(formatFileSize(10240)).toBe('10 KB');
+    });
+
+    it('should format megabytes', () => {
+      expect(formatFileSize(1048576)).toBe('1 MB'); // 1024 * 1024
+      expect(formatFileSize(2097152)).toBe('2 MB');
+      expect(formatFileSize(5242880)).toBe('5 MB');
+      expect(formatFileSize(10485760)).toBe('10 MB');
+    });
+
+    it('should format gigabytes', () => {
+      expect(formatFileSize(1073741824)).toBe('1 GB'); // 1024^3
+      expect(formatFileSize(2147483648)).toBe('2 GB');
+      expect(formatFileSize(5368709120)).toBe('5 GB');
+    });
+
+    it('should round to 1 decimal place', () => {
+      expect(formatFileSize(1536)).toBe('1.5 KB');
+      expect(formatFileSize(1587200)).toBe('1.5 MB');
+      expect(formatFileSize(1610612736)).toBe('1.5 GB');
+    });
+
+    it('should handle fractional sizes', () => {
+      expect(formatFileSize(1126)).toBe('1.1 KB');
+      expect(formatFileSize(1152921)).toBe('1.1 MB');
+    });
+
+    it('should format typical audio file sizes', () => {
+      expect(formatFileSize(3145728)).toBe('3 MB'); // ~3 MB MP3
+      expect(formatFileSize(10485760)).toBe('10 MB'); // ~10 MB M4A file
+      expect(formatFileSize(52428800)).toBe('50 MB'); // ~50 MB high quality
+    });
+  });
+
+  describe('integration scenarios', () => {
+    it('should format a complete song info', () => {
+      const duration = formatDuration(225); // 3:45
+      const position = formatTime(125.5); // 2:05.5
+      const size = formatFileSize(5242880); // 5 MB
+      const icon = getFormatIcon('m4a-stems');
+
+      expect(duration).toBe('3:45');
+      expect(position).toBe('2:05.5');
+      expect(size).toBe('5 MB');
+      expect(icon).toBe('⚡');
+    });
+
+    it('should handle edge cases consistently', () => {
+      // All functions should handle null/undefined/0 gracefully
+      expect(formatDuration(0)).toBe('-');
+      expect(formatTime(0)).toBe('0:00.0');
+      expect(formatFileSize(0)).toBe('0 B');
+      expect(getFormatIcon('')).toBe('🎵');
+    });
+  });
+});

package/src/shared/hooks/useAppState.js

@@ -0,0 +1,97 @@
+/**
+ * useAppState - React hook for subscribing to AppState changes
+ *
+ * This hook subscribes to state changes for a specific domain via the Bridge
+ * and automatically re-renders when that state changes.
+ *
+ * Usage:
+ *   const mixerState = useAppState('mixer');
+ *   const queueState = useAppState('queue');
+ *   const playbackState = useAppState('playback');
+ *
+ * The bridge handles the platform-specific subscription mechanism:
+ * - ElectronBridge: IPC listeners
+ * - WebBridge: Socket.IO listeners
+ */
+
+import { useState, useEffect } from 'react';
+import { useBridge } from '../context/BridgeContext.jsx';
+
+export function useAppState(domain, initialState = null) {
+  const bridge = useBridge();
+  const [state, setState] = useState(initialState);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    // Fetch initial state
+    const fetchInitialState = async () => {
+      try {
+        let initialData;
+
+        // Fetch initial state based on domain
+        switch (domain) {
+          case 'mixer':
+            initialData = await bridge.getMixerState();
+            break;
+          case 'queue':
+            initialData = await bridge.getQueue();
+            break;
+          case 'playback':
+            initialData = await bridge.getPlaybackState();
+            break;
+          case 'effects':
+            initialData = await bridge.getEffects();
+            break;
+          case 'preferences':
+            initialData = await bridge.getPreferences();
+            break;
+          case 'requests':
+            initialData = await bridge.getRequests();
+            break;
+          default:
+            console.warn(`No initial fetch method for domain: ${domain}`);
+            initialData = null;
+        }
+
+        if (mounted) {
+          setState(initialData);
+          setLoading(false);
+        }
+      } catch (err) {
+        console.error(`Error fetching initial ${domain} state:`, err);
+        if (mounted) {
+          setError(err);
+          setLoading(false);
+        }
+      }
+    };
+
+    fetchInitialState();
+
+    // Subscribe to updates
+    const unsubscribe = bridge.onStateChange(domain, (newState) => {
+      if (mounted) {
+        setState(newState);
+      }
+    });
+
+    // Cleanup
+    return () => {
+      mounted = false;
+      unsubscribe();
+    };
+  }, [domain, bridge]);
+
+  return { state, loading, error };
+}
+
+/**
+ * Simplified version that just returns the state (no loading/error)
+ */
+export function useAppStateSimple(domain, initialState = null) {
+  const { state } = useAppState(domain, initialState);
+  return state;
+}