FAQ

A note on page names: the navigation bar reads Home, Queue, Songs, Add New, and a menu holding Rankings, Play History, Sessions and Settings. Older documentation calls these the Files, Search and Info pages respectively.

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 the URL and QR code" preference on the Settings page.

Can I show a different address instead of the detected IP?

Yes. Use --url to override the displayed address entirely -- include the port if you need one. Use --prefer-hostname to show the machine's hostname rather than its IP address; this relies on mDNS, which is not guaranteed to work on every LAN.

Can I run PiKaraoke behind a reverse proxy?

Yes. Use --base-path to serve PiKaraoke under a URL prefix, for example --base-path /karaoke. PiKaraoke generates all its links with that prefix; the reverse proxy still has to do the actual path routing.

Does PiKaraoke support multiple languages?

Yes. The web interface is available in 16 languages: English, German, Spanish (Venezuela), Finnish, French, Indonesian, Italian, Japanese, Korean, Dutch, Norwegian, Brazilian Portuguese, Russian, Thai, Chinese (Simplified), and Chinese (Traditional). Change the language on the Settings page under "Language settings", or set it at startup with --preferred-language. A restart is required for the change to take effect.

Songs & Library

How do I find and download karaoke songs?

Use the Add New page 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.

If a result is already in your library, PiKaraoke offers to queue it rather than downloading a second copy.

How do I search the songs I already have?

Use the Songs page. This searches your local library only, and is separate from the YouTube search on the Add New page. The page also offers A-Z letter jumps, sorting by date added, and a results-per-page control. The per-page choice is stored per device, so one phone changing it does not change what everybody else sees; the server-wide default is set on the Settings page.

Can I browse my library by folder?

Yes, once folder browsing is switched on -- either the "Enable folder browsing" preference on the Settings page or --enable-folder-browsing at startup. A Folders view then appears on the Songs page whenever your library actually has subdirectories, letting you walk the directory structure your songs are stored in. Searching and letter jumps apply within the folder you are in.

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)

CDG and ASS files are companions -- they are picked up alongside a matching MP3 or MP4, not listed as songs in their own right.

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.

If CDG graphics look soft or blocky, enable "CDG pixel scaling" on the Settings page (or --cdg-pixel-scaling). It sharpens the rendering at the cost of some CPU, so it may not suit an older Pi.

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 Settings page.

How does PiKaraoke keep track of my library?

The library is held in a SQLite database (pikaraoke.db) in the platform data directory, alongside config.ini. On startup PiKaraoke reconciles that database against the download directory: the first run does a full scan before the interface is ready, and later runs load instantly and sync in the background. Files that have simply been moved are detected and followed rather than deleted and re-added.

If you add or remove files while PiKaraoke is running, open the Settings page and press Sync Now under Song Library. The same card shows the current song count.

A safety measure worth knowing about: if a scan would delete more than half the library at once -- what happens when a USB drive holding your songs is unplugged -- the sync aborts rather than wiping the database.

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, but kept in the filename so PiKaraoke still knows where the song came from.
• If there's no separator, nothing goes looking for the artist on its own -- the song simply displays under whatever the filename says. Use the song editor's Suggest from iTunes, or the Batch Renamer, to fill the artist in. Naming the file properly in the first place saves the trip.
• Subdirectories are supported. You can organize songs into folders under your download path (set with -d / --download-path). PiKaraoke scans all subdirectories automatically.

Can PiKaraoke tidy up noisy YouTube titles?

Yes. Enable "Enable automatic YouTube title cleanup" on the Settings page and PiKaraoke strips the usual noise -- "Karaoke Version", "HD", "Lyrics On Screen" and similar -- from the titles it displays. This only changes what is shown; the file on disk keeps its name. To change the filenames themselves, use the song editor or the Batch Renamer.

Does PiKaraoke support high-quality video downloads?

Yes. Enable "Download high quality videos" on the Settings page (or --high-quality) and PiKaraoke downloads higher-quality video, up to 1080p, instead of the default lower resolution. Downloads are constrained to H.264 so they remain playable without transcoding. This uses more disk space and may impact performance on lower-spec devices.

A download failed. Does that stall everything else?

No. A failed download is retried automatically, and if it still fails it is reported on the Queue page as an error card with a retry button, while the rest of the queue carries on downloading.

Playback & Audio

Does PiKaraoke support pitch/key changing?

Yes. While a song is playing, the Home page shows a Change Key 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 -- the Settings page reports "missing lib-rubberband" next to the FFmpeg version if yours lacks it.

Does PiKaraoke support audio normalization?

Yes. Enable "Normalize audio volume" on the Settings page (or -n / --normalize-audio) to play songs at a consistent volume. Normalization is CPU-intensive and may cause performance issues on lower-spec devices like the Raspberry Pi.

Can singers hear themselves through the karaoke speakers?

Yes, using experimental server-side microphone passthrough. Start PiKaraoke with --enable-mic-passthrough, then plug a USB or Bluetooth microphone into the machine running PiKaraoke. Detected microphones appear under Audio on the Settings page and on the Home page, where any device in the room can switch them on, set levels, and adjust a latency slider. On Linux there is also an experimental echo cancellation option, which reduces feedback at the cost of some latency.

Passthrough uses PulseAudio or PipeWire on Linux and PortAudio on Windows and macOS. If the Settings page reports that microphone support is unavailable on a Pi, install the missing tools with sudo apt install pulseaudio-utils and restart PiKaraoke.

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.

Songs cut off early, or the audio drifts out of sync. What can I change?

Three settings on the Settings page cover most of this:

• Buffer size (-b / --buffer-size) -- how much video is transcoded before streaming starts. Increase it if songs cut off early; playback will take longer to begin.
• Transcode video completely before playing (-c) -- waits for the whole transcode to finish first. Best browser compatibility, notably Safari and Firefox, at the cost of a longer wait. Buffer size is ignored when this is on.
• A/V sync (--avsync) -- offset in seconds when audio leads or lags the video. Negative advances the audio, positive delays it.

Transcoding only happens when normalization is on, when playing a CDG file, or when the key has been changed.

Does PiKaraoke show a score after each song?

Yes. After each song finishes, PiKaraoke displays a score screen with a random phrase drawn from a low, mid or high band. You can replace the built-in phrases with your own under "Score phrases" on the Settings page, or turn the score screen off entirely with "Disable the score screen after each song" (--disable-score).

Splash Screen

Can I customize the splash screen?

Yes. The splash screen shown on the TV between songs is highly configurable. Toggle these on the Settings 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, with its own volume control (or provide a custom directory with --bg-music-path)
• Screensaver -- activates after a configurable idle timeout (default 300 seconds, set to 0 to disable)
• Digital clock -- optional clock overlay (--show-splash-clock)
• Logo -- can be hidden with --hide-logo
• Session name -- the name of the running session, shown under the logo; hide it with --hide-session-name
• Now playing / up next overlays -- can be hidden if preferred (--hide-overlay)
• Notifications -- can be hidden with --hide-notifications
• 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. Around 2048x1024px works well.

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, session name, now playing and up next, 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.

Can I put the splash screen on a second monitor?

Yes. --window-size 1280,720 opens the player in a window instead of kiosk fullscreen, which you can then drag to another display and fullscreen with F11 (control+cmd+f on Mac). There is also an experimental --external-monitor flag which positions the window at x=2000 for dual-monitor setups. Both only work on Chromium-based browsers.

Queue Features

Does PiKaraoke support round-robin (fair) queuing?

Yes. Enable "Enable fair queue" on the Settings page and new songs are slotted in so that singers take turns in rounds rather than one person dominating the queue.

Ranking is by turns already taken tonight, not by what is left in the queue -- so the song on screen and everything already sung both count against a singer. Someone arriving late can jump ahead by one round to catch up, but no further, so a singer walking in at midnight does not claim every round the room got through before they arrived.

Note that this is a preference only; there is no command-line flag for it.

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.

Can I rename a song that is already in the queue?

Yes. Renaming a song from the Queue page renames the file and updates the queue entry in place, keeping its position, the singer it is attributed to, and any key change already applied.

Can I reorder the queue?

Yes. The Queue page supports drag-and-drop reordering, and songs can be moved to the top, removed, or the whole queue cleared. These are admin actions if an admin password is set.

Sessions, Play History & Rankings

What is a session?

A session is one night of karaoke. Every song played is recorded against a session, which gives you a play log for the evening and a set of rankings. Open the Sessions page to start a session and give it a name -- the name appears under the logo on the splash screen while it runs.

If songs are played with no session open, PiKaraoke quietly opens an unnamed one so nothing is lost. An unnamed session closes itself after six hours of silence, so tonight is never filed under yesterday.

What does the Play History page show?

Every song played, who sang it, and when. You can filter by session, by performer, or by song, sort by any of those columns, and choose whether to include songs that were skipped rather than sung. Anyone in the room can open this page -- it is how a guest finds something they sang last time and queues it up again. Deleting an entry is host-only.

What does the Rankings page show?

Most-played songs and most active performers, either across all time or for one session. Both lists have a row-count selector. Only songs sung through are counted; skipped songs stay on record but do not appear in the charts. Names are matched case-insensitively, so "Mike" and "mike" rank as one person.

Can I export the play history?

Yes. A session can be exported as CSV or as a plain text set list from the Sessions page.

How do I clear the history?

A single session can be cleared from its own row on the Sessions page. To delete everything, use "Reset all history" under Song Library on the Settings page. This deletes every session and every play on record and cannot be undone.

Who can see the session pages?

The Play History page is open to everyone. The Sessions page, the singer directory, and every action that changes history are host-only when an admin password is set.

KJ Mode

What is KJ mode?

KJ mode lets a host queue songs on behalf of singers who are not using their own phone. When it is on, the Add New and Songs pages gain a Queue for singer field, so the song is attributed to whoever is actually going to sing it rather than to the host.

How do I turn KJ mode on?

Append ?kj_mode=true to any page URL -- for example http://<your-ip>:5555/browse?kj_mode=true. It stays on for the rest of that browser tab's session and is invisible to everyone else, so the ordinary singer experience is untouched. Append ?kj_mode=false to turn it off.

KJ mode requires admin access and a running session. If no session is open, the singer field is replaced by a link to the Sessions page -- start one there and the field appears without a reload.

Does it remember singer names?

Yes. The singer field autocompletes from performers already in your play history, so regulars are a couple of keystrokes.

Administration & Control

How do I set an admin password?

Open the Settings page and scroll to the Admin card. Type a password, press Save password, and it takes effect immediately -- no restart and no command-line flag. The device you set it from stays logged in; every other device is logged out and will need the password to get back in.

Because everyone is an admin until a password exists, anyone in the room can reach that card on an unprotected install. Set yours before the guests arrive.

You can also set it at startup with --admin-password <password>. The flag is saved rather than applied for that run only, so you never need to pass it twice.

How do I log in as admin?

Open the Settings page. When a password is set and you are not logged in, an Admin card near the top of the page offers a password field -- enter it and press Login. The admin controls appear on the rest of the page once you are in.

That device stays logged in for 90 days, or until you press Log out on the Settings page, or until the password is changed.

I have forgotten the admin password. How do I get back in?

Restart PiKaraoke with --admin-password <new-password>. The flag overwrites whatever is stored, so it doubles as the reset. The old password cannot be recovered -- only a hash of it is kept.

To remove the password entirely and go back to everyone being an admin, either press Clear password on the Settings page while logged in, or restart with a bare --admin-password and no value after it.

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, or pass --limit-user-songs-by. 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. The name "Pikaraoke" is always exempt.

Can I rename or delete songs from the web interface?

Yes. The Songs page lets you browse, rename, and delete songs. Deleting a song also removes its companion files (CDG, ASS). These operations require admin access if a password is set.

Two tools help with naming, and they draw on different sources:

• The song editor, reached from any song, offers Auto Format, Swap Artist/Title, and Suggest from iTunes, which proposes clean Artist - Title filenames from the iTunes catalogue.
• The Batch Renamer works through the library in bulk and takes its suggestions from Last.fm. For YouTube downloads whose filename already contains an - separator, it tidies what is there rather than querying anything.

The two preferences under Song Library -- iTunes search country, which decides which regional catalogue is queried, and the order of suggested song names (Artist - Title or Title - Artist) -- apply to the song editor's iTunes suggestions. They do not affect the Batch Renamer.

How do I change preferences and settings?

Open the Settings page. The preferences section covers audio normalization, high-quality downloads, fair queue, splash screen settings, volume, folder browsing, title cleanup, and more. Changes are saved to config.ini in the platform data directory and persist across restarts. Most preferences can also be set via command-line flags, and a flag you pass at startup is written back to the config file so the web interface reflects it. 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.

Can I stop the machine going to sleep mid-song?

Yes. Enable "Keep the server awake while PiKaraoke is running" on the Settings page, or pass --keep-awake at startup. This matters most in headless mode, where there is no local player window keeping the system awake.

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 Settings page and use the "YT-DLP update" section (requires admin access if a password is set). You can also update manually by running pip install --upgrade yt-dlp in your terminal.

PiKaraoke checks for a yt-dlp upgrade on startup. If that check is slow or you manage the version yourself, skip it with --skip-youtubedl-upgrade.

Can I pass extra options to yt-dlp?

Yes. --ytdl-args passes additional arguments through as a single string, and --youtubedl-proxy routes downloads via a proxy server if a firewall is in the way.

Is there an API?

Yes. Start PiKaraoke with --enable-swagger and interactive API documentation is served at /apidocs.

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, down to a per-port QR code, so the two do not overwrite each other. Open the splash screen for a room at its /splash path (e.g., http://<your-ip>:5555/splash).

Give each instance its own --config-file-path if you want their preferences kept apart.