pikaraoke 1.15.3

Youtube-based Karaoke machine for Raspberry Pi, OSX, Windows, and Linux

PiKaraoke

PiKaraoke is a "KTV"-style karaoke song search and queueing system. It connects to your TV, and shows a QR code for computers and smartphones to connect to a web interface. From there, multiple users can seamlessly search your local track library, queue up songs, add an endless selection of new karaoke tracks from YouTube, and more. Works on Raspberry Pi, OSX, Windows, and Linux!

Pikaraoke is independently developed and maintained. If you want to support this project with a little monetary tip, it's much appreciated:

Table of Contents

• Features
• Supported Devices / OS
• Get Started
• Screenshots
• Developing pikaraoke
• Troubleshooting

Features

Feature	Description
Web Interface	Multiple users can queue tracks from their smartphones
Player/Splash Screen	Connection QR code and song queue metadata
Searching/Browsing	Search and rowse a local song library
Adding New Songs	Add new songs from Youtube
mp3 + cdg Support	CDG file support, supports compressed .zip bundles
Playback Controls	Pause, Skip, Restart, and volume control
Queue Management	Manage the song queue and change the order
Key Change / Pitch Shifting	Adjust the pitch of songs
File Management	Advanced editing of downloaded file names
Admin Mode	Lock down features with admin mode
Headless Mode	Run a dedicated pikaraoke server and stream to remote browser

Supported Devices / OS / Platforms

• Raspberry Pi
  • Requires a Raspberry Pi Model 3 or higher
  • Bookworm Desktop OS required for standalone/headed mode
  • For Pi 3: overclocking is recommended for smoother playback
• OSX
• Windows
• Linux

Native installation

Requirements

• Python 3.10 or greater (You can check your current version by running python --version): Python downloads
• FFmpeg: FFmpeg downloads
• Chrome browser (recommended, though Edge, Safari and Firefox will work with the --headless option)
• A js runtime installed to your PATH (such as Node, Deno, Bun, QuickJS), this is a requirement as of yt-dlp 2025.11.12 otherwise some downloads may not work: https://github.com/yt-dlp/yt-dlp/wiki/EJS . Deno is probably easiest: https://deno.com/

Specific install instructions for Raspberry Pi OS / Linux distros with apt:

sudo apt-get install ffmpeg -y
sudo apt-get install chromium -y
sudo apt-get install chromium-driver -y
sudo curl -fsSL https://deno.land/x/install/install.sh | sh

Chromium/Chromdriver is optional if you're running with the --headless option.

Windows

You may want to try the install script by @lvmasterrj: https://github.com/lvmasterrj/win-pikaraoke-installer

Install pikaraoke via pip

Globally or within a virtual env:

# Install pikaraoke from PyPi
pip install pikaraoke

Note: Some OS install pip as pip3. if you did not use a venv, you may need to add the --break-system-packages parameter to ignore the warning and install pikaraoke and its dependencies globally. You may experience package conflicts if you have other python programs installed.

Run

Pikaraoke is now installed in the $PATH with the command line interface pikaraoke. Start by calling the pikaraoke command.

pikaraoke

This will start pikaraoke in headed mode, and open Chrome browser with the splash screen. You can then connect to the QR code via your mobile device and start downloading and queueing songs.

Virtual env users: note that if you close your terminal between launches, you'll need to reactivate your venv before running pikaraoke.

Upgrading

To upgrade to the latest version of pikaraoke, run:

pip install pikaraoke --upgrade

More Options

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

Docker instructions

For Docker users, you can get going with one command. The deployed images includes everything you need to run in headless mode:

docker run vicwomg/pikaraoke:latest

For more information, see official Dockerhub repo

Screenshots

Developing pikaraoke

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

• Install poetry: Poetry
• Git clone this repo

From the pikaraoke directory:

# install dependencies
poetry install

# Run pikaraoke from the local codebase
poetry run pikaraoke

If you don't want to install poetry, you can alternately install pikaraoke directly from the source code root:

pip install .

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!