Setting up the machine

Everything on this page is set when PiKaraoke starts, so it needs access to the machine PiKaraoke runs on. The common cases are answered first; the full list of flags follows.

Common setups

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.

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 PiKaraoke run in headless/server-only mode?

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

Can I run multiple "rooms" on the same machine?

Yes. Run multiple PiKaraoke instances on different ports, each 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 room by navigating to its 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.

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

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.

Is there an API?

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

Command line options

Run pikaraoke --help to see the options for the version you have installed.

The snapshot below is from version 1.23.0, kept here so the flags are searchable. Regenerate it when it drifts too far from the current release.

usage: pikaraoke [OPTIONS]

options:
  -h, --help            show this help message and exit

General:
  --config-file-path CONFIG_FILE_PATH
                        Path to a config file to load settings from. CLI arguments override and persist to this file. (default: config.ini)
  -l, --log-level LOG_LEVEL
                        Logging level int value (DEBUG: 10, INFO: 20, WARNING: 30, ERROR: 40, CRITICAL: 50). (default: 20)
  --preferred-language PREFERRED_LANGUAGE
                        Set the preferred language for the web interface. This will persist across restarts. Available codes: en, de_DE, es_VE, fi_FI, fr_FR, id_ID,it_IT, ja_JP, ko_KR, nl_NL, nb_NO, pt_BR, ru_RU, th_TH, zh_Hans_CN,
                        zh_Hant_TW
  --enable-swagger      Enable Swagger API documentation at /apidocs.
  --dolphly             Enable top-secret DOLPHLY mode.

Server and network:
  -p, --port PORT       Desired http port (default: 5555)
  -u, --url URL         Override the displayed IP address with a supplied URL. This argument should include port, if necessary
  --base-path BASE_PATH
                        URL path prefix for reverse proxy deployments (e.g., /karaoke). Requires a reverse proxy to handle the path routing; PiKaraoke only generates correct URLs with this prefix.
  --prefer-hostname     Use the local hostname instead of the IP as the connection URL. Use at your discretion: mDNS is not guaranteed to work on all LAN configurations. (default: False)
  --admin-password [ADMIN_PASSWORD]
                        Administrator password for the web UI: player controls, song editing, shutdown. Saved when passed, so it also resets a forgotten one; pass it with no value to clear it. Unset, everyone is an admin.

Song library and downloads:
  -d, --download-path DOWNLOAD_PATH [DOWNLOAD_PATH ...]
                        Desired path for downloaded songs. (default: ~\pikaraoke-songs)
  --youtubedl-proxy YOUTUBEDL_PROXY
                        Proxy server to use for yt-dlp, in case blocked by a firewall
  --ytdl-args YTDL_ARGS
                        Additional arguments to pass to yt-dlp, as a single string. Attach the value with an equals sign, or its leading dashes are read as PiKaraoke arguments (Example: --ytdl-args="--sleep-requests 1.5")
  --skip-youtubedl-upgrade, --skip-ytdl-upgrade
                        Skip automatic yt-dlp upgrade check on startup.
  --high-quality        Download higher quality video. May cause CPU, download speed, and other performance issues
  --enable-folder-browsing
                        Let users browse the song library by the folders it is stored in. Adds a Folders view to the Songs page when the library has subdirectories.

Splash screen:
  --hide-splash-screen, --headless
                        Headless mode. Don't launch the splash screen/player on the pikaraoke server
  --window-size WINDOW_SIZE
                        Desired window geometry in pixels for headed mode, specified as width,height (Example: --window-size 800,600). Only works on Chromium browsers. Disables kiosk fullscreen mode. This can be used to open a windowed
                        mode splash screen and move it to an external monitor where it can be fullscreened from the menu or a keyboard shortcut (F11 key, or control+cmd+f on Mac).
  --external-monitor    Experimental: Launch the splash screen on an external monitor by positioning window at x=2000. Useful for dual-monitor setups. Only works on Chromium browsers and possibly only windows.
  --logo-path LOGO_PATH [LOGO_PATH ...]
                        Path to a custom logo image file for the splash screen. Recommended dimensions ~ 2048x1024px
  --hide-url            Hide URL and QR code from the splash screen.
  --hide-session-name   Hide the karaoke session name shown under the splash screen logo.
  --hide-logo           Hide the logo in the centre of the splash screen.
  --hide-overlay        Hide all overlays that show on top of video, including current/next song, pikaraoke QR code and IP
  --hide-notifications  Hide notifications from the splash screen.
  --show-splash-clock   Show the digital clock on the splash screen.
  -s, --splash-delay SPLASH_DELAY
                        Delay during splash screen between songs (in secs). (default: 2)
  -t, --screensaver-timeout SCREENSAVER_TIMEOUT
                        Delay before the screensaver begins (in secs). Set to 0 to disable screensaver. (default: 300)
  --keep-awake          Prevent the host machine from sleeping while PiKaraoke is running. Especially useful when headless, where no local player window keeps the system awake.

Background music and video:
  --bg-music-path BG_MUSIC_PATH [BG_MUSIC_PATH ...]
                        Path to a custom directory for the splash screen background music. Directory must contain mp3 files which will be randomized in a playlist.
  --bg-video-path BG_VIDEO_PATH [BG_VIDEO_PATH ...]
                        Path to a custom background video for the splash screen. Either a single mp4, m4v or webm file, or a directory of them, one of which is picked at random each time the splash screen returns.
  --disable-bg-music    Disable background music on splash screen
  --disable-bg-video    Disable background video on splash screen
  --bg-music-volume BG_MUSIC_VOLUME
                        Set the volume of background music on splash screen. A value between 0 and 1. (default: 0.3)

Playback and audio:
  -v, --volume VOLUME   Set initial player volume. A value between 0 and 1. (default: 0.85)
  -n, --normalize-audio
                        Normalize volume. May cause performance issues on slower devices
  -c, --complete-transcode-before-play
                        Wait for ffmpeg video transcoding to fully complete before playback begins. Transcoding occurs when you have normalization on, play a cdg file, or change key. May improve performance and browser compatibility
                        (Safari, Firefox), but will significantly increase the delay before playback begins. On modern hardware, the delay is likely negligible.
  -b, --buffer-size BUFFER_SIZE
                        Buffer size for transcoded video (in kilobytes). Increase if you experience songs cutting off early. Higher size will transcode more of the file before streaming it to the client. This will increase the delay
                        before playback begins. This value is ignored if --complete-transcode-before-play was specified. (default: 150)
  --avsync AVSYNC       Use avsync (in seconds) if the audio and video streams are out of sync. (negative = advances audio | positive = delays audio) (default: 0)
  --cdg-pixel-scaling   Enable CDG pixel scaling to improve video rendering of CDG files. This may increase CPU usage and may cause performance issues on slower devices.
  --streaming-format {hls,mp4}
                        Video streaming format: 'hls' (HLS with fMP4 segments) or 'mp4' (pushes mp4 directly to the browser - legacy format that might work better on some configurations). (default: hls)
  --enable-mic-passthrough
                        Enable experimental server-side microphone passthrough so singers can hear themselves through the karaoke speakers.

Queue:
  --limit-user-songs-by LIMIT_USER_SONGS_BY
                        Limit the number of songs a user can add to queue. User name 'Pikaraoke' is always unlimited (default: 0 = unlimited)
  --disable-score       Disable the score screen after each song