View on GitHub

PyKaraoke-NG

A free, open-source karaoke player for Linux, Windows, and macOS

PyKaraoke NG Tauri Migration - Quick Start Guide

← Back to Home Developer Guide

What Was Built

This migration introduces a Tauri-based architecture that separates the Python karaoke engine from the UI, replacing wxPython with a modern web-based interface.

New Components

  1. pykbackend.py - Headless Python backend service
    • Manages playback, library, playlists
    • JSON-based command API
    • Event-driven state updates
    • NO wxPython dependencies
  2. tauri-app/ - Desktop application shell
    • Rust-based native wrapper (Tauri)
    • Web frontend (HTML/CSS/JS)
    • IPC bridge between frontend and Python
    • Cross-platform (Windows, macOS, Linux)
  3. ARCHITECTURE.md - Complete architecture documentation
    • System design diagrams
    • Communication protocol specs
    • Migration strategy
    • Development guidelines

Quick Start

Option 1: Run Backend Standalone (Testing)

# Test the backend API
python3 pykbackend.py

# In another terminal, send commands:
echo '{"action":"get_state","params":{}}' | python3 pykbackend.py

Option 2: Run Full Tauri App

# Prerequisites: Rust toolchain must be installed
# Install if needed: https://rustup.rs/

cd tauri-app

# Development mode (hot reload)
cargo tauri dev

# Production build
cargo tauri build

Option 3: Run Tests

# Test the backend API
pytest tests/test_backend_api.py -v

Project Structure

pykaraoke-ng/
├── pykbackend.py              # NEW: Headless Python backend
├── ARCHITECTURE.md            # NEW: Architecture documentation
├── tauri-app/                 # NEW: Tauri application
│   ├── README.md             # Tauri-specific docs
│   ├── src/                  # Frontend (HTML/CSS/JS)
│   │   ├── index.html        # Main UI
│   │   ├── styles.css        # Styling  
│   │   └── app.js            # Frontend logic
│   └── src-tauri/            # Rust backend
│       ├── Cargo.toml        # Rust dependencies
│       ├── tauri.conf.json   # Tauri config
│       └── src/
│           └── main.rs       # Tauri application
├── pykaraoke.py              # EXISTING: Original wxPython GUI
├── pykplayer.py              # EXISTING: Player base class
├── pykmanager.py             # EXISTING: Manager (used by backend)
├── pykdb.py                  # EXISTING: Database (used by backend)
├── pycdg.py                  # EXISTING: CDG player
├── pykar.py                  # EXISTING: MIDI/KAR player
└── pympg.py                  # EXISTING: MPEG player

API Examples

Send Commands

Commands are JSON objects sent to the backend:

// Play command
{"action": "play", "params": {"playlist_index": 0}}

// Search library
{"action": "search_songs", "params": {"query": "Beatles"}}

// Adjust volume
{"action": "set_volume", "params": {"volume": 0.75}}

// Get current state
{"action": "get_state", "params": {}}

Receive Events

Backend emits events when state changes:

{
  "type": "event",
  "event": {
    "type": "state_changed",
    "timestamp": 1706745678.123,
    "data": {
      "playback_state": "playing",
      "current_song": {
        "title": "Hey Jude",
        "artist": "The Beatles",
        "filename": "hey_jude.cdg"
      },
      "position_ms": 45000,
      "duration_ms": 240000,
      "volume": 0.75
    }
  }
}

Key Features

Backend API (pykbackend.py)

✅ Playback control (play, pause, stop, next, previous)
✅ Volume control
✅ Playlist management (add, remove, clear)
✅ Library search
✅ Song database integration
✅ Event emission (state changes, song finished, errors)
✅ JSON command interface
✅ Headless operation (no UI dependencies)

Frontend UI

✅ Modern web-based interface
✅ Player controls with progress bar
✅ Library browser with search
✅ Playlist management
✅ Volume control
✅ Real-time state updates
✅ Responsive design

Tauri Shell

✅ Python subprocess management
✅ IPC message routing
✅ Event forwarding
✅ Cross-platform support
✅ Native OS integration

Migration Status

✅ Completed

🔄 In Progress / TODO

Development Workflow

1. Modify Backend Logic

Edit pykbackend.py → Restart Tauri app or backend process

2. Update Frontend

Edit files in tauri-app/src/ → Auto-reload in dev mode

3. Change Rust Code

Edit tauri-app/src-tauri/src/main.rs → Rebuild with cargo tauri dev

4. Test Changes

# Run backend tests
pytest tests/test_backend_api.py

# Run full app
cd tauri-app && cargo tauri dev

Comparison: Old vs New

Aspect wxPython (Old) Tauri (New)
UI Framework wxPython Web (HTML/CSS/JS)
Architecture Monolithic Decoupled (frontend/backend)
Testing Difficult (UI coupled) Easy (API testable)
Cross-platform Limited Excellent
UI Modernization Hard to update Easy with web tech
Bundle Size ~50MB ~3-5MB
Performance Good Excellent
Development Python only Python + Rust + Web
Distribution Platform installers Single binary

Next Steps

  1. Test the backend: Run python3 pykbackend.py and send test commands
  2. Build Tauri app: Run cd tauri-app && cargo tauri dev
  3. Review architecture: Read ARCHITECTURE.md for full details
  4. Contribute: Pick a TODO item and implement it
  5. Report issues: File bugs or feature requests

FAQ

Q: Does this replace the original pykaraoke.py?
A: Yes! The legacy wxPython GUI has been removed. Use the modern Tauri-based interface instead.

Q: Can I run just the backend?
A: Yes! Run python3 pykbackend.py for headless operation.

Q: What dependencies are needed?
A: Backend needs pygame, pygame, numpy. Tauri needs Rust toolchain.

Q: How do I build for distribution?
A: Run cd tauri-app && cargo tauri build to create installers.

Q: Can I use React/Vue instead of vanilla JS?
A: Yes! The frontend is framework-agnostic. Just replace tauri-app/src/.

Q: Is WebSocket supported?
A: Not yet, but it’s planned. Currently uses stdio for IPC.

Resources

License

LGPL-2.1-or-later (same as PyKaraoke)