### Pikaraoke Autostart Desktop Entry with Parameters (Global Install)

Source: https://github.com/vicwomg/pikaraoke/wiki/Auto‐launching-pikaraoke

Example of a .desktop file entry for globally installed Pikaraoke, including optional command-line parameters for customization.

```ini
Exec=pikaraoke -l10 --headless --normalize-audio
```

--------------------------------

### Install Dependencies and Run Pikaraoke

Source: https://github.com/vicwomg/pikaraoke/wiki/Pikaraoke-development-guide

Use 'uv run pikaraoke' to install all project dependencies and start the Pikaraoke application from the local codebase.

```bash
uv run pikaraoke
```

--------------------------------

### Enable and Start systemd Service

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Reload systemd to recognize the new service, enable it to start on boot, and start it immediately.

```bash
sudo systemctl daemon-reload
sudo systemctl enable startx.service
```

--------------------------------

### Manual PiKaraoke Installation Steps

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Alternative method for installing PiKaraoke, involving manual installation of ffmpeg, uv, and then PiKaraoke itself.

```bash
# Install ffmpeg
sudo apt-get install ffmpeg -y

# Install uv
curl -fsSL https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# Install pikaraoke
uv tool install pikaraoke
```

--------------------------------

### Install PiKaraoke with One-Line Installer

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Use the provided curl command to download and execute the PiKaraoke installation script.

```bash
curl -fsSL https://raw.githubusercontent.com/vicwomg/pikaraoke/master/build_scripts/install/install.sh | bash
```

--------------------------------

### Install PulseAudio Utilities

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Install PulseAudio utilities to manage system volume. This is necessary before setting the default volume.

```bash
sudo apt install pulseaudio -y
```

--------------------------------

### Launch Pikaraoke Server

Source: https://github.com/vicwomg/pikaraoke/wiki/Android:-run-pikaraoke-server-using-termux

Start the Pikaraoke server after installation. This command will run the server in headless mode on Android.

```bash
pikaraoke
```

--------------------------------

### Install Python, FFmpeg, and Binutils

Source: https://github.com/vicwomg/pikaraoke/wiki/Android:-run-pikaraoke-server-using-termux

Install necessary dependencies for Pikaraoke, including Python, FFmpeg for media processing, and binutils.

```bash
pkg install python ffmpeg binutils-is-llvm
```

--------------------------------

### Pikaraoke Autostart Desktop Entry (Global Install)

Source: https://github.com/vicwomg/pikaraoke/wiki/Auto‐launching-pikaraoke

This is the content for the .desktop file when Pikaraoke is installed globally. It specifies the application to run.

```ini
[Desktop Entry]
Type=Application
Name=Pikaraoke
Exec=pikaraoke
```

--------------------------------

### Install Samba File Sharing

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Install Samba and configure it to share the karaoke song directory. This allows easy transfer of music files from a library computer.

```bash
sudo apt-get install samba samba-common-bin
```

```bash
sudo nano /etc/samba/smb.conf
```

```text
[karaoke]
comment = Shared folder
path = /home/pi/pikaraoke-songs/
browseable = yes
writeable = yes
only guest = no
force user = pi **<-- This will be the user you configured in the OS that you have been signing in as**
create mask = 0777
directory mask = 0777
public = yes
guest ok = yes
```

--------------------------------

### Configure Kiosk Mode Startup Script

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Create and configure the .xinitrc file to disable screen blanking, start Openbox, run PiKaraoke headless, and launch Chromium in kiosk mode.

```bash
cat << 'EOF' > ~/.xinitrc
#!/bin/sh
xset -dpms
xset s off
xset s noblank

export PATH="$HOME/.local/bin:$PATH"

# Start Openbox window manager
openbox-session &

# Start PiKaraoke server in the background (headless = no auto-browser)
pikaraoke --headless &

# Wait for the server to start
sleep 5

# Launch Chromium in kiosk mode pointing at PiKaraoke splash screen
chromium --kiosk --noerrdialogs --disable-infobars --no-first-run \
    --disable-session-crashed-bubble --disable-features=TranslateUI \
    --autoplay-policy=no-user-gesture-required \
    --disable-gpu-compositing --disable-dev-shm-usage \
    http://localhost:5555/splash
EOF

chmod +x ~/.xinitrc
```

--------------------------------

### Install ffmpeg

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Install the ffmpeg package, which is a dependency for PiKaraoke to handle audio and video processing.

```bash
sudo apt-get install ffmpeg -y
```

--------------------------------

### Enable PiKaraoke Systemd Service

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Enable the PiKaraoke service to start automatically on system boot.

```bash
sudo systemctl enable pikaraoke.service
```

--------------------------------

### Install PiKaraoke using uv

Source: https://github.com/vicwomg/pikaraoke/blob/master/docs/README.md

Installs the pikaraoke package using the uv package manager. This is the recommended method for advanced users.

```shell
uv tool install pikaraoke
```

--------------------------------

### Install ARGON Utilities

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Download and install the ARGON utilities script for managing the remote control and fan. After installation, configure the desired parameters.

```bash
wget https://download.argon40.com/argon1.sh
```

```bash
sudo chmod 700 argon1.sh
```

```bash
sudo ./argon1.sh
```

```bash
sudo argon-config
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/vicwomg/pikaraoke/wiki/Pikaraoke-development-guide

Configure the project to automatically run pre-commit hooks on every commit.

```bash
pre-commit install --config code_quality/.pre-commit-config.yaml
```

--------------------------------

### Install Kiosk Dependencies

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Install essential packages for a minimal X11 session and a web browser required for PiKaraoke's UI.

```bash
sudo apt-get install --no-install-recommends xserver-xorg xinit openbox chromium -y
```

--------------------------------

### Install PiKaraoke on Windows (PowerShell)

Source: https://github.com/vicwomg/pikaraoke/blob/master/docs/README.md

Installs PiKaraoke and its dependencies using a PowerShell command. Re-running this command updates an existing installation.

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

--------------------------------

### Create systemd Service for Auto-Start

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Define a systemd service to automatically start the X server and PiKaraoke on boot. Ensure 'pi' is replaced with your actual username.

```bash
sudo tee /etc/systemd/system/startx.service > /dev/null << EOF
[Unit]
Description=Start X at boot
After=network.target

[Service]
User=pi
Group=pi
Type=simple
Environment=DISPLAY=:0
Environment=XAUTHORITY=/home/pi/.Xauthority
ExecStart=/usr/bin/startx
WorkingDirectory=/home/pi
StandardInput=tty
StandardOutput=journal
StandardError=journal
TTYPath=/dev/tty1

[Install]
WantedBy=multi-user.target
EOF
```

--------------------------------

### Commit Message Examples

Source: https://github.com/vicwomg/pikaraoke/wiki/Pikaraoke-development-guide

Examples of commit messages following the commitlint format, indicating the type of change.

```bash
build: update npm dependency
```

```bash
ci: add circleci configuration file
```

```bash
docs: fix typo in foo.md and bar.md
```

```bash
perf: optimize database query for faster response times
```

```bash
feat: allow provided config object to extend other configs
```

```bash
fix: resolve issue with incorrect data rendering
```

```bash
refactor: reorganize code structure for better readability
```

```bash
style: format code according to Prettier standards
```

```bash
test: add unit tests for user authentication
```

--------------------------------

### Install Pikaraoke via Pip

Source: https://github.com/vicwomg/pikaraoke/wiki/Android:-run-pikaraoke-server-using-termux

Install the Pikaraoke package using pip. This command assumes Python is already installed.

```bash
pip install pikaraoke
```

--------------------------------

### Run Pikaraoke Headless

Source: https://github.com/vicwomg/pikaraoke/wiki/Troubleshooting

Launch Pikaraoke in headless mode if you manually start the splash screen on a separate machine.

```bash
pikaraoke --headless
```

--------------------------------

### Pikaraoke Autostart Desktop Entry (Virtual Environment)

Source: https://github.com/vicwomg/pikaraoke/wiki/Auto‐launching-pikaraoke

This .desktop file entry is used when Pikaraoke is installed in a virtual environment. It points to the wrapper script that handles environment activation.

```ini
[Desktop Entry]
Type=Application
Name=Pikaraoke
Exec=/home/pi/launch-pikaraoke-venv.sh
```

--------------------------------

### Verify PiKaraoke Installation

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Check if the 'pikaraoke' command is recognized after installation.

```bash
pikaraoke --help
```

--------------------------------

### Apply Environment Changes

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Source the bashrc file to apply changes made by the installer, such as updated PATH.

```bash
source ~/.bashrc
```

--------------------------------

### Translate Simple String with %s Placeholder

Source: https://github.com/vicwomg/pikaraoke/wiki/Translation-help-needed!

Example of translating a string containing a %s placeholder, which should be left as is. This format is common for dynamic content.

```po
#. Message shown after the download is completed and queued
#: karaoke.py:376
#, python-format
msgid "Downloaded and queued: %s"
msgstr "成功添加歌曲： %s"
```

--------------------------------

### Configure WiFi on Raspberry Pi via SD Card

Source: https://github.com/vicwomg/pikaraoke/wiki/Troubleshooting

Manually configure WiFi settings by creating a wpa_supplicant.conf file on the SD card's boot partition. This is useful for headless setup.

```text
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=<Your 2-letter country code, ex. US>
network={
  ssid="<the wifi ap ssid name>"
  psk="<the wifi password>"
  key_mgmt=WPA-PSK
}
```

--------------------------------

### Update and Upgrade OS

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Run these commands to update the package list and upgrade installed packages on your Raspberry Pi. A reboot is required after the upgrade.

```bash
sudo apt-get update && sudo apt-get upgrade -y
sudo reboot
```

--------------------------------

### Modal for Video Preview

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/search.html

Handles opening a modal to display a video preview. It makes an AJAX call to get the stream URL and sets up the video player. Includes logic to unlock autoplay on iOS/mobile.

```javascript
$("#search-results").on("click", ".img-wrapper", function () {
    const modal = document.getElementById("modal-js-example");
    const modalVideo = document.getElementById("modal-video");
    const modalContent = modal.querySelector(".modal-content");
    const videoUrl = $(this).data("url");
    modal.classList.add("is-active");
    modalContent.classList.add("is-loading");
    // Unlock autoplay on iOS/mobile: briefly play the empty video element
    // synchronously inside the click handler so Safari associates it with
    // a user gesture. Without this, the async AJAX callback's .play() is blocked.
    modalVideo.play().then(function () {
        modalVideo.pause();
    }).catch(function () {});
    const closeButton = modal.querySelector(".modal-close");
    closeButton.focus();
    // Remove the spinner when the video starts playing or errors — not when
    // the AJAX returns, since the video still has to buffer after src is set.
    const stopLoading = function () {
        modalContent.classList.remove("is-loading");
    };
    modalVideo.addEventListener("playing", stopLoading, { once: true });
    modalVideo.addEventListener("error", stopLoading, { once: true });
    const closeModal = function () {
        modal.classList.remove("is-active");
        modalContent.classList.remove("is-loading");
        modalVideo.pause();
        modalVideo.src = "";
    };
    closeButton.onclick = closeModal;
    modal.querySelector(".modal-background").onclick = closeModal;
    $.ajax({
        url: "{{ url_for('search.preview') }}" + "?url=" + encodeURIComponent(videoUrl),
        type: "get",
        success: function (data) {
            if (modal.classList.contains("is-active")) {
                modalVideo.src = data.stream_url;
                modalVideo.load();
                modalVideo.play().catch(function () {});
            }
        },
        error: function () {
            closeModal();
        },
    });
});
```

--------------------------------

### Create Pikaraoke Autostart Directory and File

Source: https://github.com/vicwomg/pikaraoke/wiki/Auto‐launching-pikaraoke

This command sequence creates the necessary directory for autostart applications and an empty .desktop file for Pikaraoke.

```sh
## Create an autostart launcher
mkdir ~/.config/autostart
touch ~/.config/autostart/pikaraoke.desktop
```

--------------------------------

### Initialize Volume, Socket, and Load Now Playing

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/home.html

Sets the initial volume, ensures the WebSocket connection is established, and loads the current 'now playing' information when the page loads.

```javascript
var volume = {{ volume|default(0.85) }};
// Ensure global socket exists
if (typeof window.socket === 'undefined') {
    window.socket = io();
}
function loadNowPlaying() {
    console.log("Loading now playing data");
    $.get('{{ url_for("now_playing.now_playing") }}', function (data) {
        handleNowPlaying(JSON.parse(data));
    });
}
```

--------------------------------

### Create Karaoke Song Directories and Set Permissions

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Create directories for organizing karaoke songs (CDG and YT) and set world-writable permissions for ease of access. These directories will be used by Pikaraoke for downloaded songs.

```bash
mkdir /home/pi/pikaraoke-songs/CDG
```

```bash
mkdir /home/pi/pikaraoke-songs/YT
```

```bash
sudo chmod 0777 /home/pi/pikaraoke-songs/CDG
```

```bash
sudo chmod 0777 /home/pi/pikaraoke-songs/YT
```

```bash
sudo chmod 0777 /home/pi/pikaraoke-songs/
```

--------------------------------

### Initialize UI Controls and Event Listeners

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/home.html

Sets up event listeners for UI elements like sliders, buttons, and WebSocket events. Includes debouncing for volume changes.

```javascript
$(function () {
    $(".control-box").hide();
    var slider = document.getElementById("transpose");
    var output = document.getElementById("semitones-label");
    if (slider && output) {
        output.innerHTML = getSemitonesLabel(slider.value);
        // Update the current slider value (each time you drag the slider handle)
        slider.oninput = function () {
            output.innerHTML = getSemitonesLabel(slider.value);
        };
    }
    $("#volume-slider").on( "input", debounce(function (event) {
        const value = this.value;
        $.get("/volume/" + value);
    }, 500)
    );
    $("#submit-transpose").click(function () {
        var value;
        if (slider) {
            value = slider.value;
        } else {
            value = 0;
        }
        r = confirm(window.translations.confirmTranspose.replace("SEMITONE_LABEL", getSemitonesLabel(value)));
        if (r) {
            $.get("/transpose/" + value);
        }
        slider.value = 0;
        output.innerHTML = getSemitonesLabel(slider.value);
    });
    $("#pause-resume").click(function () {
        $.get("/pause");
        togglePausePlayButton();
    });
    $("#vol-up").click(function () {
        $.get("/vol_up");
    });
    $("#vol-down").click(function () {
        $.get("/vol_down");
    });
    $("#restart").click(function () {
        r = confirm(window.translations.confirmRestartTrack);
        if (r) {
            $.get("/restart");
        }
    });
    $("#skip").click(function () {
        r = confirm( // {# MSG: Confirmation message when clicking a button to skip a track. #}
            `{{ _("Are you sure you want to skip this track? If you didn't add this song, ask permission first!") }}
`
        );
        if (r) {
            $.get("/skip");
        }
    });
    $("#semitones-info").click(function () {
        showNotification(
            window.translations.semitonesInfo,
            "is-info",
            10000
        );
    });
    function togglePausePlayButton() {
        if ($("#pause-resume").hasClass("icon-pause")) {
            $("#pause-resume").removeClass("icon-pause");
            $("#pause-resume").addClass("icon-play");
        } else {
            $("#pause-resume").removeClass("icon-play");
            $("#pause-resume").addClass("icon-pause");
        }
    }
    //for first time load of splash screen
    loadNowPlaying();
    //for pushed updates to now playing state
    window.socket.on("now_playing", (np) => handleNowPlaying(np));
    document.addEventListener("visibilitychange", function () {
        console.log("on visibility change");
        if (document.visibilityState === "visible") {
            loadNowPlaying();
            console.log(window.socket);
            if (!window.socket.connected) {
                console.log("Reconnecting socket...");
                window.socket = io();
                window.socket.on("now_playing", (np) => handleNowPlaying(np));
            }
        }
    });
});
```

--------------------------------

### Upgrade Pikaraoke with pip/pipx

Source: https://github.com/vicwomg/pikaraoke/wiki/Troubleshooting

Upgrade Pikaraoke using pip or pipx if you installed it with these package managers.

```bash
pip(x) install pikaraoke --upgrade
```

--------------------------------

### Set Master Volume and Store ALSA Settings

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Set the master volume to a desired level (e.g., 70%) and then store the ALSA settings to make them persistent.

```bash
amixer set Master 70%
```

```bash
sudo alsactl store
```

--------------------------------

### Update Package Repositories

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Update the package list and upgrade installed packages on your Raspberry Pi OS.

```bash
sudo apt update
sudo apt upgrade -y
```

--------------------------------

### Get User Cookie

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/base.html

Retrieves the value of the 'user' cookie. Returns the username if set, otherwise undefined.

```javascript
function getUserCookie() {
  return Cookies.get("user");
}
```

--------------------------------

### Initialize a New Language Translation

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/_TRANSLATION.md

Command to create a new empty `.po` file for a new language locale.

```shell
$ pybabel init -i messages.pot -d translations -l $NEW_LOCALE
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/vicwomg/pikaraoke/blob/master/CLAUDE.md

Execute pre-commit checks using uv and a specified configuration file to ensure code quality across all files.

```bash
# Run pre-commit checks
uv run pre-commit run --config code_quality/.pre-commit-config.yaml --all-files
```

--------------------------------

### Connect to WebSocket Server

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/base.html

Establishes a WebSocket connection using Socket.IO and logs connection/disconnection events to the console. Assumes Socket.IO client is available.

```javascript
function connectSocket() {
  window.socket = io();
  window.socket.on('connect', function() {
    console.log('Socket connected');
  });
  window.socket.on('disconnect', function() {
    console.log('Socket disconnected');
  });
}
```

--------------------------------

### Translate String with Newlines and HTML

Source: https://github.com/vicwomg/pikaraoke/wiki/Translation-help-needed!

Example demonstrating how to translate strings that include newlines and embedded HTML. Preserve the formatting and HTML structure.

```po
#. Link which will let the user log into admin mode.
#: templates/info.html:348
#, python-format
msgid "\n    Enable admin mode: <a href=\"%(login_url)s\">Log in</a>\n  "
msgstr "\n    开启管理员模式: <a href=\"%(login_url)s\">登入</a>\n  "
```

--------------------------------

### Initialize Queue Page

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/queue.html

Initializes the queue page by fetching initial data and setting up event listeners for modal backgrounds and queue/now-playing options buttons.

```javascript
$(function() {
  window.queuePage_getDownloads();
  window.queuePage_getQueue();
  // Close modals on background click
  $('.modal-background').click(function() {
    window.closeSongOptions();
    window.closeNowPlayingOptions();
  });
  // Queue song options button (for queued songs)
  $(document).on('click', '.queue-song-options-btn', function(e) {
    e.preventDefault();
    var $btn = $(this);
    var index = parseInt($btn.data('index'), 10);
    var file = decodeURIComponent($btn.data('file'));
    var title = decodeURIComponent($btn.data('title'));
    openSongOptions(index, file, title);
  });
  // Now-playing options button
  $(document).on('click', '.now-playing-options-btn', function(e) {
    e.preventDefault();
    openNowPlayingOptions();
  });
  // Playback controls handler (still
```

--------------------------------

### Update Termux Packages

Source: https://github.com/vicwomg/pikaraoke/wiki/Android:-run-pikaraoke-server-using-termux

Update and upgrade all installed packages in Termux. Ensure the app remains open and in the foreground during this process to avoid network interruptions.

```bash
pkg update && pkg upgrade
```

--------------------------------

### Execute Playback Action

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/queue.html

Executes a playback action (e.g., play, pause) via an AJAX GET request and closes the now playing options modal.

```javascript
window.executePlaybackAction = function(action) {
  $.get('/' + action);
  window.closeNowPlayingOptions();
};
```

--------------------------------

### Document Ready Initialization

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/base.html

Executes initialization code once the DOM is fully loaded. Includes connecting to the socket, setting up notification close buttons, handling active navigation links, and displaying the current user.

```javascript
$(function () {
  connectSocket();
  $("#notification-close").click(function () {
    $(".notification").hide();
  });
  $("#notification-alt").hide()
  // Navbar burger menu is handled by spa-navigation.js
  // handle highlighting current nav bar location
  var currentPath = window.location.pathname;
  if (currentPath == "/") {
    $("#home").addClass("is-active")
  }
  if (currentPath == "/queue") {
    $("#queue").addClass("is-active")
  }
  if (currentPath == "/search") {
    $("#search").addClass("is-active")
  }
  if (currentPath == "/browse") {
    $("#browse").addClass("is-active")
  }
  if (currentPath == "/info") {
    $("#info").addClass("is-active")
  }
  // handle auto-close flash notifications
  setTimeout(function() {
    $("#notification").fadeOut()
  }, 3000);
  // handle current user display
  var currentUser = Cookies.get("user");
  if (currentUser) {
    $("#current-user span").text(currentUser)
    $("#current-user").removeClass("is-hidden");
  };
  // Username change handler is now in spa-navigation.js
});
```

--------------------------------

### Automated Translation Workflow Commands

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/_TRANSLATION.md

Commands to manage the translation cycle, including installation, full cycle execution, and specific steps like extraction or translation.

```shell
# Install translation dependencies
uv sync --group translations

# Full cycle: extract, update, auto-translate, compile
python build_scripts/update_translations.py

# Extract + update .po files only (no auto-translation)
python build_scripts/update_translations.py --extract-po-only

# Translate + compile only (skip extract/update, useful for retrying)
python build_scripts/update_translations.py --translate-only

# Full cycle but keep obsolete (#~) entries in .po files
python build_scripts/update_translations.py --keep-obsolete
```

--------------------------------

### Configure ALSA Defaults

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Edit the ALSA configuration file to set the default audio card, device, and subdevice. Ensure these match the output from 'aplay -l'.

```bash
sudo nano /usr/share/alsa/alsa.conf
```

```text
defaults.ctl.card 2
defaults.pcm.card 2
defaults.pcm.device 0
defaults.pcm.subdevice 0
```

--------------------------------

### Check FFmpeg for librubberband

Source: https://github.com/vicwomg/pikaraoke/wiki/Troubleshooting

Verify if your FFmpeg installation includes the librubberband library, which is required for pitch shifting functionality. The output will show 'rubberband' if it's present.

```bash
ffmpeg -filters | grep rubberband
```

--------------------------------

### Create Pikaraoke Virtual Environment Wrapper Script

Source: https://github.com/vicwomg/pikaraoke/wiki/Auto‐launching-pikaraoke

Commands to create and make executable a shell script that will activate a Python virtual environment before launching Pikaraoke.

```sh
# Create a pikaraoke wrapper script
touch ~/launch-pikaraoke-venv.sh
chmod +x ~/launch-pikaraoke-venv.sh
nano ~/launch-pikaraoke-venv.sh
```

--------------------------------

### Docker Compose for PiKaraoke

Source: https://github.com/vicwomg/pikaraoke/wiki/Reverse-Proxy-Domain-Setup-with-Docker

Defines the PiKaraoke service within a Docker Compose setup, including image, container name, command, volumes, restart policy, and port mapping.

```yaml
pikaraoke:
  image: vicwomg/pikaraoke:latest
  container_name: PiKaraoke
  command: --url https://[domain_name]
  volumes:
    [volume information here]
  restart: unless-stopped
  ports:
    - "5555:5555"
```

--------------------------------

### Initialize WebSocket and Queue State

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/queue.html

Ensures a global WebSocket connection exists and initializes the queue page state if it hasn't been set up yet. This includes defining the structure for queue and now playing data.

```javascript
var isAdmin = JSON.parse('{{ admin | tojson }}');

function escape(str) {
  return encodeURIComponent(str);
}

if (typeof window.socket === 'undefined') {
  window.socket = io();
}

if (typeof window.queuePageState === 'undefined') {
  window.queuePageState = {
    queue: [],
    previousQueue: null,
    nowPlaying: null,
    previousNowPlaying: null
  };
}
```

--------------------------------

### Initiate and Manage Library Synchronization

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/info.html

Handles the 'Sync Now' button click event. Disables the button and adds a loading indicator. It also listens for SocketIO events to manage the button's state during and after synchronization.

```javascript
// Sync Now button
$("#sync-library-btn").click(function() {
  var $btn = $(this);
  $btn.addClass("is-loading").prop("disabled", true);
  $.getJSON("{{ url_for('admin.sync_library') }}", function(data) {
    if (data.status !== "already_syncing") return; // stays disabled -- sync_finished will re-enable
  }).fail(function() {
    $btn.removeClass("is-loading").prop("disabled", false);
  });
});

// SocketIO: manage Sync Now button state
window.socket.on("sync_started", function() {
  $("#sync-library-btn").addClass("is-loading").prop("disabled", true);
});

window.socket.on("sync_finished", function() {
  $("#sync-library-btn").removeClass("is-loading").prop("disabled", false);
  $.getJSON("{{ url_for('admin.library_stats') }}", fu
```

--------------------------------

### Translate String with Embedded JS Function Call

Source: https://github.com/vicwomg/pikaraoke/wiki/Translation-help-needed!

Example of translating text surrounding an embedded JavaScript function call. Do not translate function names or HTML attributes within tags.

```po
#. Prompt for interaction in order to enable video autoplay.
#: templates/splash.html:629
msgid "Due to limititations with browser permissions, you must interact\n      with the page once before it allows autoplay of videos. Pikaraoke "
      "will not\n      play otherwise. Click the button below to\n      <a onClick=\"handleConfirmation()\">confirm</a> ."
msgstr "Devido a limitações nas permissões do navegador, você deve interagir com "
"a página uma vez antes que ela permita a reprodução automática de vídeos.""
" Pikaraokê não jogue de outra forma. Clique no botão abaixo para       "
" <a onClick=\"handleConfirmation()\">confirmar</a> ."
```

--------------------------------

### Run Multiple PiKaraoke Instances

Source: https://github.com/vicwomg/pikaraoke/wiki/FAQ

Launch multiple independent PiKaraoke instances on different ports to create separate karaoke rooms. Each instance operates with its own queue and library.

```bash
pikaraoke --headless -p 5555 &
pikaraoke --headless -p 6666 &
```

--------------------------------

### Initialize Selectize for Song Search

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/search.html

Initializes the Selectize library for the song search input. Configures fields, options, and event handlers for user interaction, including search term tracking and input validation.

```javascript
var $select = $("#song\_to\_add").selectize({
    valueField: "path",
    labelField: "fileName",
    searchField: ["fileName"],
    optgroupField: "type",
    optgroups: [
        { value: "autocomplete", label: '{{ \_("Available songs in local library") }}' },
    ],
    createOnBlur: true,
    openOnFocus: false,
    createFilter: function (input) {
        return input.length >= 2;
    },
    onInitialize: function () {
        var that = this;
        bindSearchTextboxTracking(this);
        this.$control.on("click", function () {
            that.ignoreFocusOpen = true;
            setTimeout(function () {
                that.ignoreFocusOpen = false;
            }, 50);
        });
    },
    onFocus: function () {
        if ($(window).width() <= 500 && $(window).height() <= 740) {
            document.getElementById("search-field").scrollIntoView();
        }
        if (!this.ignoreFocusOpen) {
            this.open();
        }
    },
    onBlur: function () {
        this.setTextboxValue(getRestorableSearchTerm(this));
    },
    onChange: function (id) {
        if (!id) {
            $("#add-queue-link").attr("disabled", "true");
            $("#search-link").attr("disabled", "true");
            $("#add-queue-link").hide();
            $("#search-link").show();
        } else {
            $("#add-queue-link").removeAttr("disabled");
            $("#search-link").removeAttr("disabled");
            $("#add-queue-link").show();
            $("#search-link").hide();
        }
    },
    onType: function (text) {
        if (!text) {
            console.log("no text");
            $("#search-link").attr("disabled", "true");
            {# $("#add-queue-link").show(); $("#search-link").hide(); #}
        } else {
            console.log("has text: " + text);
            $("#search-link").removeAttr("disabled");
            $("#add-queue-link").hide();
            $("#search-link").show();
        }
    },
    render: {
        option: function (item, escape) {
            return (
                '<div class="row">' +
                '<div class="col-icon"><i class="icon icon-music has-text-info"></i></div>' +
                '<div class="col-text">' + escape(item.fileName) + '</div>' +
                '</div>'
            );
        },
        optgroup_header: function (data, escape) {
            return '<div class="optgroup-header">' + escape(data.label) + '</div>';
        },
    },
    load: function (query, callback) {
        if (query.length < 2) return callback;
        $.ajax({
            url: "{{ url\_for('search.autocomplete') }}" + "?q=" + query,
            type: "get",
            success: function (data) {
                callback(data);
            },
        });
    },
});
```

--------------------------------

### Tidy Filename

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/edit.html

When the 'Auto-format' button is clicked, this snippet makes an AJAX call to the '/metadata/tidy-name' endpoint to get a tidied version of the filename. If a tidied name is returned, it updates the input field.

```javascript
$(function () {
    $('#remove-karaoke').click(function (e) {
        var filename = $('#new_file_name').val();
        if (!$.trim(filename)) return;
        $.getJSON('/metadata/tidy-name', { filename: filename }, function (data) {
            if (data.tidied) {
                $('#new_file_name').val(data.tidied);
            }
        });
    });
});
```

--------------------------------

### Add Local Bin to PATH

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Troubleshooting step: Ensure the ~/.local/bin directory, where user-installed executables are often placed, is included in your system's PATH environment variable.

```bash
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Create and Configure PiKaraoke Systemd Service

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

This configuration sets up PiKaraoke to run as a systemd service. It specifies the working directory, execution command with options for headless operation, download path, volume, and quality. The service runs as root and restarts automatically if it fails.

```bash
[Unit]
Description=pikaraoke
After=multi-user.target

[Service]
WorkingDirectory=/home/pi/.venv/
Type=simple
ExecStart=/home/pi/.venv/bin/python /home/pi/.venv/bin/pikaraoke --headless  --download-path /home/pi/pikaraoke-songs --volume 0.75 --high-quality
User=root
Group=root
Environment="PATH=$PATH:/home/pi/.venv/bin:/home/pi/.venv/lib/python3.11/site-packages:/usr/bin:/usr/sbin"
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Handle Playback Button Clicks

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/templates/queue.html

Attaches a click event listener to playback buttons to trigger actions via AJAX GET requests. Ensure the buttons have a 'data-action' attribute specifying the action to perform.

```javascript
$(document).on('click', '.playback-btn', function(e) {
  e.preventDefault();
  var action = $(this).data('action');
  $.get('/' + action);
});
```

--------------------------------

### Manual Rebuilding with Pybabel

Source: https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/_TRANSLATION.md

Manual steps to extract, update, and compile translation files using the `pybabel` command-line tool.

```shell
$ pybabel extract -F babel.cfg -o messages.pot --add-comments="MSG:" --strip-comment-tags  --sort-by-file .
$ pybabel update -i messages.pot -d translations
# Update any translations/**/messages.po files
$ pybabel compile -d translations/
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/vicwomg/pikaraoke/wiki/Pikaraoke-development-guide

Execute all pre-commit hooks to ensure code quality before committing. This command can auto-fix many issues.

```bash
uv run pre-commit run --config code_quality/.pre-commit-config.yaml --all-files
```

--------------------------------

### Configure Default Kiosk Page

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

Modify the FullPageOS configuration file to set the PiKaraoke splash page as the default Kiosk page. This ensures PiKaraoke launches automatically on boot.

```bash
sudo nano /boot/firmware/fullpageos.txt
http://localhost:5555/splash?confirm=false
```

--------------------------------

### Configure Default Audio Output

Source: https://github.com/vicwomg/pikaraoke/wiki/Rpi-OS-Lite-Installation

Set the default audio output device by specifying the card number in the .asoundrc file. Replace '0' with your device's card number.

```bash
cat << EOF > ~/.asoundrc
pcm.!default {
    type hw
    card 0
}

ctl.!default {
    type hw
    card 0
}
EOF
```

--------------------------------

### Check Pikaraoke Service Status and Logs

Source: https://github.com/vicwomg/pikaraoke/wiki/FullPageOS-with-pikaraoke-(Oct-2024)

If Pikaraoke fails to load, use these commands to check the service status and view logs for troubleshooting. This helps identify the root cause of the issue.

```bash
sudo service pikaraoke status
```

```bash
journalctl -u pikaraoke.service
```

--------------------------------

### Pikaraoke Command Line Usage

Source: https://github.com/vicwomg/pikaraoke/wiki/Home

This snippet displays the general usage and available options for the Pikaraoke command-line interface. It lists all possible arguments for configuring the application.

```bash
usage: pikaraoke [-h] [-p PORT] [-d DOWNLOAD_PATH [DOWNLOAD_PATH ...]] [--youtubedl-proxy YOUTUBEDL_PROXY]
                 [--ytdl-args YTDL_ARGS] [-v VOLUME] [-n] [-s SPLASH_DELAY] [-t SCREENSAVER_TIMEOUT] [-l LOG_LEVEL]
                 [--hide-url] [--prefer-hostname] [--hide-overlay] [--hide-notifications] [--hide-splash-screen]
                 [--high-quality] [-c] [-b BUFFER_SIZE] [--logo-path LOGO_PATH [LOGO_PATH ...]] [-u URL]
                 [--window-size WINDOW_SIZE] [--external-monitor] [--admin-password ADMIN_PASSWORD] [--disable-bg-music]
                 [--bg-music-volume BG_MUSIC_VOLUME] [--bg-music-path BG_MUSIC_PATH [BG_MUSIC_PATH ...]]
                 [--bg-video-path BG_VIDEO_PATH [BG_VIDEO_PATH ...]] [--disable-bg-video] [--disable-score]
                 [--limit-user-songs-by LIMIT_USER_SONGS_BY] [--avsync AVSYNC] [--config-file-path CONFIG_FILE_PATH]
                 [--cdg-pixel-scaling] [--streaming-format {hls,mp4}] [--preferred-language PREFERRED_LANGUAGE]
                 [--enable-swagger] [--dolphly]

options:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  Desired http port (default: 5555)
  -d DOWNLOAD_PATH [DOWNLOAD_PATH ...], --download-path DOWNLOAD_PATH [DOWNLOAD_PATH ...]
                        Desired path for downloaded songs. (default: ~/pikaraoke-songs)
  --youtubedl-proxy YOUTUBEDL_PROXY
                        Proxy server to use for youtube-dl, in case blocked by a firewall
  --ytdl-args YTDL_ARGS
                        Additional arguments to pass to youtube-dl/yt-dlp (as a single string)
  -v VOLUME, --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 (default: False)
  -s SPLASH_DELAY, --splash-delay SPLASH_DELAY
                        Delay during splash screen between songs (in secs). (default: 2 )
  -t SCREENSAVER_TIMEOUT, --screensaver-timeout SCREENSAVER_TIMEOUT
                        Delay before the screensaver begins (in secs). Set to 0 to disable screensaver. (default: 300 )
  -l LOG_LEVEL, --log-level LOG_LEVEL
                        Logging level int value (DEBUG: 10, INFO: 20, WARNING: 30, ERROR: 40, CRITICAL: 50). (default: 20 )
  --hide-url            Hide URL and QR code from the splash screen.
  --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. Defaults to False
  --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.
  --hide-splash-screen, --headless
                        Headless mode. Don't launch the splash screen/player on the pikaraoke server
  --high-quality        Download higher quality video. May cause CPU, download speed, and other performance issues
  -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
                        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 is: 150
  --logo-path LOGO_PATH [LOGO_PATH ...]
                        Path to a custom logo image file for the splash screen. Recommended dimensions ~ 2048x1024px
  -u URL, --url URL     Override the displayed IP address with a supplied URL. This argument should include port, if
                        necessary
  --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.

```