Free and open source karaoke software for playing and creating stem-based karaoke files from your own music

Loukai is a free, open source karaoke software that runs locally on your computer to play and create karaoke files from your own music. Built on M4A Stems (MPEG-4 multi-track audio), it uses industry-standard formats compatible with DJ software, giving you full control over your personal karaoke library.

Key highlights:

• Open Format: Built on NI Stems — no vendor lock-in, works with Traktor, Mixxx, and other DJ software
• Create Your Own: Built-in Creator processes your audio files into stem-separated karaoke with AI-transcribed lyrics
• Play Anywhere: Cross-platform desktop app (Linux, Windows, macOS) with web remote control
• Fully Open Source: AGPL-3.0 licensed — inspect, modify, and contribute

• M4A Stems Format (Primary): Built on NI Stems with karaoke extensions
  • Compatible with DJ software (Traktor, Mixxx) via standard NI Stems metadata
  • Smaller file sizes than legacy formats
  • Embedded lyrics with word-level timing in custom atoms
• Real-Time Stem Control: Individual volume, mute, and solo controls for vocals, drums, bass, and other stems
• Legacy Format Support: CDG/MP3 pairs
• Dual Output Routing: Independent PA and IEM (in-ear monitor) outputs with per-stem routing
• High-Quality Audio: Web Audio API with real-time processing and pitch correction
• Auto-Tune System: Real-time pitch correction for microphone input
  • AudioWorklet processing (< 5ms latency)
  • Autocorrelation pitch detection (80-800 Hz vocal range)
  • Musical key support (12 major keys with scale snapping)
  • Adjustable strength and speed parameters
  • Phase vocoder architecture prepared for future enhancement
• Queue Management: Add, remove, reorder songs with drag-and-drop

• Butterchurn Integration: 200+ Milkdrop-style audio-reactive visualizations
• CDG Graphics: Classic karaoke graphics rendering with full format support
• Canvas Window: Dedicated fullscreen window for visuals with multi-monitor support
• Lyric Display: Real-time synchronized lyrics with customizable styling
• QR Code Display: Scannable QR code on canvas for easy mobile device connection (configurable)
• Queue Display: "Next up" overlay showing upcoming 1-3 songs with singer names (configurable)
• Singer Identification: Color-coded singer names (yellow for guests, white for KJ)

• Fast Library Scanning: Automatic metadata extraction from thousands of songs
• M4A Stems Native: Optimized for MPEG-4 multi-track audio with full metadata support
• Legacy Format Support: Also reads CDG/MP3 pairs
• Smart Search: Fuzzy search across titles, artists, and albums
• Alphabet Navigation: Quick filtering by first letter
• Pagination: Efficient handling of large libraries (tested with 23K+ songs)

• Remote Control: Full player control from any device on the network
• Song Requests: Allow singers to browse and request songs remotely
• Request Management: Approve/reject song requests with real-time notifications
• QR Code Access: Scan QR code from canvas for instant mobile connection
• WebRTC Streaming: Stream audio and video to remote devices (optional)
• Multi-Device Sync: Real-time state synchronization via Socket.IO

• Advanced Mixer: Per-stem gain control, routing, and effects
• Preset Management: Save and load mixer presets
• Lyrics Editor: Edit lyrics line-by-line with timing adjustments
• Song Metadata Editor: Update title, artist, album, and other metadata

• Modern Stack: React 19, Vite 7, Electron 38
• Comprehensive Testing: 52% code coverage with Vitest
• ESLint + Prettier: Automated code formatting and linting
• Pre-commit Hooks: Husky + lint-staged for quality assurance
• Hot Module Replacement: Fast development with Vite HMR

• Node.js 18+ (LTS recommended)
• npm 9+ or yarn 1.22+
• Git

# Clone the repository
git clone https://github.com/monteslu/loukai.git
cd loukai

# Install dependencies
npm install

# Start the Electron app in dev mode with hot reload
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests with UI
npm run test:ui

# Lint code
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

# Build all assets (renderer + web)
npm run build:all

# Build for Linux (AppImage x64/ARM64 + Flatpak x64/ARM64)
npm run build:linux

# Build for Windows (NSIS installer x64)
npm run build:win

# Build for macOS (DMG x64 + ARM64)
npm run build:mac

Build Output:

Build Requirements:

• Linux builds: Requires flatpak-builder and Flatpak runtimes (24.08)

  # Install flatpak-builder
  sudo apt-get install flatpak-builder flatpak
  
  # Add Flathub repository
  flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
  
  # Install required runtimes
  flatpak install --user -y flathub \
    org.electronjs.Electron2.BaseApp/x86_64/24.08 \
    org.freedesktop.Platform/x86_64/24.08 \
    org.freedesktop.Sdk/x86_64/24.08 \
    org.electronjs.Electron2.BaseApp/aarch64/24.08 \
    org.freedesktop.Platform/aarch64/24.08 \
    org.freedesktop.Sdk/aarch64/24.08

• ARM64 builds: x64 hosts use QEMU for cross-compilation

  • AppImages: Built via QEMU (supported out of the box)
  • Flatpak: Requires ARM64 runtimes (installed above)

• macOS builds: Both Intel and Apple Silicon DMGs built simultaneously

• Windows builds: x64 NSIS installer with auto-updater support

# Start the app (after building)
npm start

Loukai is built with a multi-process architecture:

• Audio Engine: Native audio processing with dual outputs
• Library Scanner: Metadata extraction and caching
• Web Server: Express 5 REST API + Socket.IO
• State Management: Centralized app state with event emitters
• File System: M4A/CDG file parsing and manipulation
• IPC Handlers: Communication bridge to renderer

• React 19: Modern UI with concurrent features
• Vite 7: Lightning-fast builds and HMR
• Tailwind CSS: Utility-first styling with dark mode
• Web Audio API: Real-time audio processing
• Butterchurn: Audio visualization engine
• Socket.IO Client: Real-time updates from main process

• Standalone Web UI: Accessible from any device
• Socket.IO: Real-time bidirectional communication
• Responsive Design: Mobile-friendly interface
• Authentication: Session-based login with bcrypt
• WebRTC: Optional audio/video streaming

Flatpak Configuration:

• Runtime: org.freedesktop.Platform 24.08
• SDK: org.freedesktop.Sdk 24.08
• Base: org.electronjs.Electron2.BaseApp 24.08
• Permissions: Wayland, X11, Audio, Network, Home filesystem

GitHub Actions CI:

• Automated builds for all platforms
• Multi-architecture support (x64, ARM64)
• Automatic releases on version tags

Industry-standard MPEG-4 multi-track audio - the modern karaoke format:

• ✅ DJ Software Compatible: Works with Traktor, Mixxx, and other NI Stems-compatible software
• ✅ Smaller Files: 30-50% smaller than ZIP-based formats due to MPEG-4 compression
• ✅ Better Metadata: Native MP4 atoms for rich metadata (title, artist, album art, BPM, key)
• ✅ Karaoke Extensions: Custom atoms for lyrics with word-level timing
• ✅ Single File: No unpacking required - instant playback
• ✅ Dual Purpose: Same file works for both DJing and karaoke

• Multi-track audio: Master + 4 stems (drums, bass, other, vocals)
• NI Stems atom: stem - standard metadata for DJ software compatibility
• Karaoke atom: kara (lyrics with word-level timing)
• File extension: .stem.m4a or .m4a

Full specification: docs/m4a_format.md

Use the built-in Creator tab in Loukai:

1. Open Loukai and go to the Creator tab
2. Drop your audio file (MP3, FLAC, WAV, etc.)
3. The Creator will:
   • Separate audio into stems using Demucs (AI stem separation)
   • Transcribe lyrics using Whisper (AI speech recognition)
   • Detect musical key using CREPE
   • Package everything into a .stem.m4a file

Output: Artist - Title.stem.m4a saved to your songs folder

Classic karaoke format with graphics - widely available but limited features:

• MP3 + CDG pairs: song.mp3 + song.cdg
• Limitations: No stem separation, basic graphics, no metadata

Configure audio devices in the Mixer tab:

• PA Output: Main speakers/sound system
• IEM Output: Stage monitors/headphones
• Input Device: Microphone for vocal processing

Access in the Server tab:

• Port: Default 3069
• Server Name: Custom server name for identification
• Authentication: Enable/disable login
• Requests: Allow remote song requests
• Max Requests: Limit requests per user
• Show QR Code: Display QR code on canvas for easy mobile access (on by default)
• Display Queue: Show upcoming songs on canvas (on by default)

All settings are automatically saved to:

• Linux: ~/.config/loukai/
• Windows: %APPDATA%\loukai\
• macOS: ~/Library/Application Support/loukai/

1. Set Songs Folder: Settings tab → Browse for your karaoke library (M4A files recommended)
2. Scan Library: Click "Scan Library" to index all songs
3. Search & Play: Use the Library tab to find and play songs

Tip: For best results, use .stem.m4a files created with the built-in Creator. M4A files load faster and take less disk space than legacy formats.

1. Load Song: Double-click a song or add to queue
2. Adjust Mixer: Control stem volumes in the Mixer tab
3. Enable Effects: Choose visual effects in the Effects tab
4. Open Canvas: Project visuals to a second screen

1. Enable Web Server: Settings → Server → Enable
2. Set Password: Configure authentication credentials
3. Share URL: Give singers the URL (shown in Server tab)
4. QR Code: Singers can scan the QR code from the canvas for instant access
5. Manage Requests: Approve/reject requests in the Requests tab

The karaoke canvas shows helpful information when not playing:

• QR Code (bottom left): Scannable code for mobile device access

  • Toggle: Server tab → "Show QR Code" checkbox
  • Only visible when not playing

• Queue Display (bottom right): Shows upcoming songs

  • Toggle: Server tab → "Display Queue" checkbox
  • Displays "Next up:" with 1-3 upcoming songs
  • Singer names shown in yellow (guests) or white (KJ)
  • Only visible when not playing and queue has items

Loukai has comprehensive test coverage using Vitest:

# Run all tests
npm test

# Run tests once (CI mode)
npm run test:run

# Run with coverage report
npm run test:coverage

# Interactive test UI
npm run test:ui

Current Coverage: 283 tests

See PHASE2-SUMMARY.md for detailed testing information.

loukai/
├── src/
│   ├── main/              # Electron main process
│   │   ├── main.js        # Entry point
│   │   ├── appState.js    # Centralized state
│   │   ├── audioEngine.js # Audio processing
│   │   ├── webServer.js   # Express + Socket.IO
│   │   └── handlers/      # IPC handlers
│   │       └── autotuneHandlers.js  # Auto-tune IPC
│   ├── renderer/          # Electron renderer (React)
│   │   ├── components/    # React components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── js/            # Audio engine (vanilla JS)
│   │   │   ├── autoTuneWorklet.js  # Auto-tune processor
│   │   │   └── playerController.js # Unified control
│   │   └── vite.config.js # Renderer build config
│   ├── web/               # Web admin interface
│   │   ├── App.jsx        # Web admin root
│   │   ├── components/    # Web-specific components
│   │   └── vite.config.js # Web build config
│   ├── shared/            # Shared code (renderer + web)
│   │   ├── components/    # Reusable React components
│   │   ├── services/      # Business logic
│   │   └── utils/         # Utility functions
│   ├── native/            # Native modules
│   │   └── autotune.js    # Auto-tune utilities
│   └── test/              # Test setup
│       └── setup.js       # Vitest config
├── static/                # Static assets
├── docs/                  # Documentation
├── coverage/              # Test coverage reports
└── dist/                  # Build output

This project uses ESLint and Prettier for code quality:

# Check linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format all files
npm run format

# Check formatting
npm run format:check

Pre-commit hooks automatically run linting and formatting on staged files.

Create test files next to source files with .test.js extension:

// src/shared/services/myService.test.js
import { describe, it, expect } from 'vitest';
import * as myService from './myService.js';

describe('myService', () => {
  it('should do something', () => {
    const result = myService.doSomething();
    expect(result).toBe(true);
  });
});

See CONTRIBUTING.md for development guidelines.

• Check audio device selection in Mixer tab
• Verify output device permissions (especially on Linux)
• Try switching between PA and IEM outputs

• Ensure songs folder path is correct
• Check file permissions (read access required)
• Supported formats: .m4a (recommended), .stem.m4a, .cdg + .mp3 pairs
• For best performance, use M4A Stems format

• Check firewall settings
• Verify server is enabled in Settings
• Check port is not in use (default: 3000)
• Try accessing via IP address instead of hostname

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear build cache
rm -rf dist/ coverage/
npm run build:all

AGPL-3.0

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

See LICENSE for full text.

• Butterchurn - Audio visualization engine
• CDGraphics - CDG format support
• React - UI framework
• Electron - Desktop framework
• Vite - Build tool

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

Made with ♪ for karaoke enthusiasts