FAQ

Connecting & Access

How do singers connect to the karaoke session?

Singers connect by opening the PiKaraoke web interface in any browser on the same network. The URL is shown on the splash screen (typically http://<your-ip>:5555). You can also scan the QR code displayed on the splash screen for instant access on mobile devices. Multiple singers can connect simultaneously from different devices -- phones, tablets, or laptops.

What does the QR code on the splash screen do?

The QR code links directly to the PiKaraoke web interface URL. Point any phone camera at the TV screen to open the karaoke interface instantly -- no app install needed. You can hide the QR code via the --hide-url flag or the "Hide URL" preference on the Info page.

Does PiKaraoke support multiple languages?

Yes. The web interface is available in 16 languages: English, German, Spanish, Finnish, French, Indonesian, Italian, Japanese, Korean, Dutch, Norwegian, Brazilian Portuguese, Russian, Thai, Chinese (Simplified), and Chinese (Traditional). The admin can change the language on the Info page under "Language settings". A restart is required for the change to take effect.

Songs & Library

How do I find and download karaoke songs?

Use the Search page in the web interface to search YouTube for karaoke tracks. You can toggle the "karaoke" filter to narrow results. Preview videos before downloading, and optionally check "add to queue" to queue the song automatically after download. You can also paste a YouTube URL directly into the search bar.

What file formats does PiKaraoke support?

PiKaraoke supports these file formats:

• Video: MP4, WebM, MKV, AVI, MOV
• Audio: MP3 (requires a companion CDG file for lyrics)
• Karaoke-specific: CDG (MP3+CDG pairs), ZIP (containing MP3+CDG pairs), ASS subtitles (companion to MP4 files)

Are MP3/CDG files supported?

Yes. PiKaraoke supports CDG karaoke files natively. To add them, copy your MP3+CDG file pairs (or ZIP files containing them) into the download folder. Both files must share the same base filename (e.g., Song.mp3 and Song.cdg). Run pikaraoke --help to see the default download folder location for your platform, or use --download-path to specify a custom one.

Are MP4 files with ASS subtitles supported?

Yes. Place the .ass subtitle file in the same directory as the .mp4 file with a matching base filename (e.g., Song.mp4 and Song.ass). PiKaraoke will detect the subtitle file automatically and burn it into the video during playback.

Where are my downloaded songs stored?

Songs are stored in the download directory, which defaults to ~/pikaraoke-songs on most platforms (or ~\pikaraoke-songs on Windows). You can change this with the --download-path command-line flag. The current path is shown on the Info page in the web interface.

How should I name my karaoke files for best results?

PiKaraoke extracts artist and title information from filenames. For best results, use a hyphen with spaces as the separator:

Artist - Title.mp4 or Title - Artist.mp4

Both orderings work — PiKaraoke detects which is which. This is the same format most YouTube karaoke tracks already use, so songs downloaded through PiKaraoke's search will typically work out of the box.

• Use - (space-dash-space) as the separator. This is the standard format and the most reliable.
• YouTube IDs are handled automatically. The ID suffix (e.g. ---dQw4w9WgXcQ or [dQw4w9WgXcQ]) is stripped from display names.
• If there's no separator, PiKaraoke will attempt to look up the artist via an online service, but a well-formatted filename is faster and more reliable.
• Subdirectories are supported. You can organize songs into folders under your download path (set with -d / --download-path). PiKaraoke scans all subdirectories automatically.

Does PiKaraoke support high-quality video downloads?

Yes. When enabled by the admin on the Info page, PiKaraoke downloads higher-quality video (up to 1080p) instead of the default lower resolution. This uses more disk space and may impact performance on lower-spec devices.

Playback & Audio

Does PiKaraoke support pitch/key changing?

Yes. While a song is playing, the home screen shows a transpose control. Adjust the number of semitones up or down and confirm to restart the song in the new key. This feature requires FFmpeg built with the librubberband library.

Does PiKaraoke support audio normalization?

Yes. When enabled by the admin, this applies loudness normalization so that songs play at a consistent volume. Note that normalization is CPU-intensive and may cause performance issues on lower-spec devices like the Raspberry Pi.

What is the difference between HLS and MP4 streaming modes?

PiKaraoke supports two streaming formats, selectable via --streaming-format:

• HLS (default) -- HTTP Live Streaming with fragmented MP4 segments. Better compatibility and smoother streaming experience for most setups.
• MP4 (legacy) -- Pushes the MP4 file directly to the browser. May work better on some edge-case configurations where HLS has issues.

Does PiKaraoke show a score after each song?

Yes. After each song finishes, PiKaraoke displays a score screen with a random phrase based on the score range (low, mid, or high). The admin can customize these phrases on the Info page, or disable the score screen entirely.

Splash Screen

Can I customize the splash screen?

Yes. The splash screen shown on the TV between songs is highly configurable. The admin can toggle these options on the Info page:

• Background video -- a looping video shown while waiting for the next song (or provide a custom one with --bg-video-path)
• Background music -- randomized MP3 playlist during idle time (or provide a custom directory with --bg-music-path)
• Screensaver -- activates after a configurable idle timeout (default 5 minutes, set to 0 to disable)
• Digital clock -- optional clock overlay
• Now playing / up next overlays -- can be hidden if preferred
• Splash delay -- configurable pause in seconds before the next song starts

Can I use a custom logo on the splash screen?

Yes. Launch with --logo-path <path-to-image> to display a custom logo image on the splash screen instead of the default PiKaraoke logo.

Does the splash screen support UI scaling?

Yes. Append ?scale=<value> to the splash screen URL (e.g., http://<your-ip>:5555/splash?scale=1.5) to scale all overlay elements -- logo, now playing info, QR code, score screen, notifications, and clock. This is useful when the splash screen is displayed on a very large or very small screen where the default element sizes don't look right. A value of 1 is the default; values greater than 1 make elements larger, and values less than 1 make them smaller.

Queue Features

Does PiKaraoke support round-robin (fair) queuing?

Yes. When enabled by the admin, the queue interleaves songs so that singers take turns in rounds rather than having one person dominate the queue. Songs are ordered by the round each singer falls into.

Does PiKaraoke prevent duplicate songs in the queue?

Yes. If a song is already in the queue, attempting to add it again will be rejected. This applies to both manual additions and the "add random" feature.

Administration & Control

Does PiKaraoke support admin password protection?

Yes. Launch with --admin-password <password> to require authentication for admin-level actions. Protected actions include editing the queue order, controlling playback, managing files, changing preferences, updating yt-dlp, and shutting down the system. Singers can still search, download, and add songs to the queue without logging in.

Can the admin limit how many songs each singer can queue?

Yes. Set the "Limit User Songs By" preference to a number greater than 0. For example, setting it to 2 means each singer can have at most 2 songs in the queue at a time. A value of 0 (the default) means unlimited.

How do I enable fair queue or other queue settings?

Open the Info page and toggle "Fair Queue" under preferences. The admin can also enable it at startup with --enable-fair-queue. Other queue-related settings like per-singer song limits are configured on the same page.

Can I rename or delete songs from the web interface?

Yes. The Files page lets you browse, rename, and delete songs. There is also a Batch Renamer that can suggest cleaner filenames using Last.fm metadata. Deleting a song also removes its companion files (CDG, ASS). These operations require admin access if a password is set.

How do I change preferences and settings?

Open the Info page in the web interface. The preferences section lets you toggle options like audio normalization, high-quality downloads, fair queue, splash screen settings, volume, and more. Changes are saved to config.ini and persist across restarts. Most preferences can also be set via command-line flags (run pikaraoke --help to see them all).

Can PiKaraoke run in headless/server-only mode?

Yes. Launch with --headless (or --hide-splash-screen) to skip the splash screen/player window entirely. PiKaraoke will run as a web server only, which is useful when running on a remote machine, in Docker, or when you don't need a dedicated TV display.

How do I update yt-dlp when downloads stop working?

YouTube occasionally changes its systems, which can break downloads. To update yt-dlp, go to the Info page and click the "Update yt-dlp" button (requires admin access if a password is set). You can also update manually by running pip install --upgrade yt-dlp in your terminal.

Can I run multiple "rooms" or separate karaoke sessions on the same machine?

Yes. Run multiple PiKaraoke instances on different ports, each operating as an independent room with its own queue and library. Launch in headless mode with distinct ports:

pikaraoke --headless -p 5555 &
pikaraoke --headless -p 6666 &

Singers connect to a specific room by navigating to the corresponding port (e.g., http://<your-ip>:5555 or http://<your-ip>:6666). Each instance runs completely separately. Open the splash screen for a room at its /splash path (e.g., http://<your-ip>:5555/splash).