PiKaraoke

PiKaraoke is a cross-platform karaoke server that brings the professional "KTV" experience to your home. It transforms your computer or Raspberry Pi into a dedicated karaoke station with a full-screen player and an instant web interface. Guests can join by simply scanning a QR code—no app downloads required—to browse your local library, manage the queue, and access countless karaoke hits from YouTube.

• 📱 Instant Mobile Remote: Search and queue songs from any smartphone—just scan and sing.
• 📺 Dedicated Player: High-performance splash screen that can be opened on any web browser for a true karaoke room feel.
• 🌐 YouTube & Local Media: Play your own files or access more from the web.
• 🎹 Live Pitch Shifting: Adjust the key of any song to match your vocal range.
• 🛠️ Admin Control: Manage the queue and settings via a password-protected admin mode.
• 🎯 Hyper-accurate vocal performance scoring system: (not really, it's random. But kind of fun!)
• 🐧 Lightweight & Versatile: Runs anywhere from a basic Raspberry Pi to a high-end PC.

Love PiKaraoke? This project is independently maintained and free for everyone to enjoy. If PiKaraoke has made your parties better and you'd like to help keep the project alive and growing, feel free to buy me a coffee!

Table of Contents

• Supported Devices / OS / Platforms
• Quick Install
• Manual Installation
• Usage
• Docker
• Screenshots
• Developing pikaraoke
• Troubleshooting

Supported Devices / OS / Platforms

• OSX
• Windows
• Linux
• Raspberry Pi 4 or higher (Pi3 works ok with overclocking)

Quick Install

For a streamlined installation that handles all dependencies (uv, ffmpeg, deno) and installs PiKaraoke, run the following in your terminal:

Linux & macOS

curl -fsSL https://raw.githubusercontent.com/vicwomg/pikaraoke/master/build_scripts/install/install.sh | bash

Windows (installer)

Download PiKaraoke-<version>-setup.exe from the latest release and run it. It adds Start Menu and desktop shortcuts.

Windows shows a blue "Windows protected your PC" screen because the installer is unsigned. Click More info, then Run anyway.

To uninstall, use Settings > Apps.

Windows (PowerShell)

irm https://raw.githubusercontent.com/vicwomg/pikaraoke/master/build_scripts/install/install.ps1 | iex

To uninstall, swap install.ps1 for uninstall.ps1.

After installation, you can launch pikaraoke from the command line with pikaraoke or from a desktop shortcut. Re-running the above command will update a previous pikaraoke installation to the latest version.

Uninstalling removes the pikaraoke package and its shortcuts. Your songs, settings, ffmpeg, deno and uv are left in place.

Manual installation (advanced users)

Prerequisites

• A modern web browser (Chrome/Chromium/Edge recommended)
• Python 3.10 or greater: Python downloads
• FFmpeg (preferably a build with lib-rubberband for transposing): FFmpeg downloads
• A js runtime installed to your PATH. Node.js is most common, Deno is probably easiest for non-developers.

Install the pikaraoke package

We recommend installing pikaraoke via uv.

uv tool install pikaraoke

You may alternately use the standard python pip install pikaraoke installer if you are familiar with virtual environments or you are not concerned with global package isolation.

Usage

Run pikaraoke from the command line with:

pikaraoke

Launches the player in "headed" mode via your default browser. Scan the QR code to connect mobile remotes. Use pikaraoke --headless to run as a background server for external browsers.

See the help command pikaraoke --help for available options.

To upgrade to the latest version of pikaraoke, run:

uv tool upgrade pikaraoke

Docker instructions

Run PiKaraoke in Docker using the command below. Note the requirements for port mapping, LAN IP specification, and persistent volume mounts (set to ~/.pikaraoke in the example for simplicity):

docker run -p 5555:5555 \
  -e TZ=Europe/London \
  -v ~/pikaraoke-songs:/app/pikaraoke-songs \
  -v ~/.pikaraoke:/home/pikaraoke/.pikaraoke \
  vicwomg/pikaraoke:latest \
  -u http://<YOUR_LAN_IP>:5555

Set TZ to your own timezone, taken from the "TZ identifier" column of the tz database list.

For more information and a configurable docker-compose example, see official Dockerhub repo

To run under a path prefix (e.g., /karaoke), add --base-path /your-path and set -u to the public origin. Example: --base-path /karaoke -u https://example.com. PiKaraoke will generate links under /karaoke automatically. For reverse proxy setups, the proxy must forward both HTTP and WebSocket traffic for that path to PiKaraoke. Path-based nginx-proxy setups typically also need VIRTUAL_PATH=/karaoke with VIRTUAL_DEST=/.

Screenshots

Developing pikaraoke

The Pikaraoke project utilizes uv for dependency management and local development.

• Install uv
• Git clone this repo

From the pikaraoke directory:

# install dependencies and run pikaraoke from local code
uv run pikaraoke

See the Pikaraoke development guide for more details.

Troubleshooting and guides

See the TROUBLESHOOTING wiki for help with issues.

There are also some great guides on the wiki to running pikaraoke in all manner of bizarre places including Android, Chromecast, and embedded TVs!