pikaraoke 1.18.1

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!

Features: dedicated player/splash screen, mobile-friendly web interface, song searching/browsing, adding new songs from YouTube, mp3 + cdg support, playback controls, queue management, key change / pitch shifting, filename management, admin mode, headless mode

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

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

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

Quick Install

For a streamlined installation that handles all dependencies (python, pipx, ffmpeg, deno, yt-dlp) 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 (PowerShell)

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

After installation, you can launch pikaraoke from the command line with pikaraoke or from a desktop shortcut (if specified).

You can rerun the above command to update a previous installation also.

Manual installation (advanced)

Prerequisites

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

Install pikaraoke via pipx

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

pipx install pikaraoke

Run pikaraoke with:

pikaraoke

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

Upgrading

To upgrade to the latest version of pikaraoke, run:

pipx upgrade pikaraoke

More Options

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

Docker instructions

For Docker users, you can get going with one command. Note that for best results you should map the port, supply your actual LAN IP, and set some persistence volumes for songs and settings (for simplicity, this example sets them to ~):

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

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

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
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!