From 1453c53d3914534035b28007e03d6acf83f7f9de Mon Sep 17 00:00:00 2001 From: Vic Wong Date: Wed, 1 Jan 2025 23:41:58 -0800 Subject: [PATCH] docs: simplify README, deprecate unused files --- docs/README.md | 74 ++++++++------------- pikaraoke/lib/omxclient.py | 2 + pikaraoke/lib/vlcclient.py | 1 + scripts/README.md | 124 ------------------------------------ scripts/how-to-image.md | 11 ---- scripts/pikaraoke.bat | 13 ---- scripts/pikaraoke.sh | 14 ---- scripts/prepare_pi_image.sh | 33 ---------- scripts/requirements.txt | 13 ---- scripts/setup-windows.bat | 32 ---------- scripts/setup.sh | 51 --------------- 11 files changed, 29 insertions(+), 339 deletions(-) delete mode 100644 scripts/README.md delete mode 100644 scripts/how-to-image.md delete mode 100755 scripts/pikaraoke.bat delete mode 100755 scripts/pikaraoke.sh delete mode 100755 scripts/prepare_pi_image.sh delete mode 100644 scripts/requirements.txt delete mode 100755 scripts/setup-windows.bat delete mode 100755 scripts/setup.sh diff --git a/docs/README.md b/docs/README.md index 1cbce700..92cec96b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,16 +21,16 @@ If you want to support this project with a little monetary tip, it's much apprec | **Feature** | **Description** | | --------------------------- | ------------------------------------------------------------- | | Web Interface | Multiple users can queue tracks from their smartphones | -| Player/Splash Screen | Connection QR code and "Next up" display | -| Searching/Browsing | Browse a local song library | +| Player/Splash Screen | Connection QR code and song queue metadata | +| Searching/Browsing | Search and rowse a local song library | | Adding New Songs | Add new songs from Youtube | -| mp3 + cdg Support | Includes compressed .zip bundles | +| mp3 + cdg Support | CDG file support, supports compressed .zip bundles | | Playback Controls | Pause, Skip, Restart, and volume control | -| File Management | Advanced editing of downloaded file names | | Queue Management | Manage the song queue and change the order | | Key Change / Pitch Shifting | Adjust the pitch of songs | +| File Management | Advanced editing of downloaded file names | | Admin Mode | Lock down features with admin mode | -| Headless Mode | Run a dedicated server and stream pikaraoke to remote browser | +| Headless Mode | Run a dedicated pikaraoke server and stream to remote browser | ## Supported Devices / OS / Platforms @@ -43,11 +43,21 @@ If you want to support this project with a little monetary tip, it's much apprec - Linux - Docker - [See official Dockerhub repo](https://hub.docker.com/repository/docker/vicwomg/pikaraoke) -## Get Started +## Docker instructions + +For Docker users, you can get going with one command. The deployed images includes everything you need to run in headless mode: + +```sh +docker run vicwomg/pikaraoke:latest +``` + +## Native installation ### Install required programs -Pikaraoke requires Python 3.9 or greater. You can check your current version by running `python --version`. [Python downloads](https://www.python.org/downloads/) +Pikaraoke requires Python 3.9 or greater. You can check your current version by running `python --version`. + +[Python downloads](https://www.python.org/downloads/) #### Raspberry Pi OS / Linux distros with `apt`: @@ -57,51 +67,23 @@ sudo apt-get install chromium-browser -y sudo apt-get install chromium-chromedriver -y ``` +Chromium/Chromdriver is optional if you're running with the `--headless` option. + #### Windows / OSX / Linux: - FFmpeg 6.0 or greater: [FFmpeg downloads](https://ffmpeg.org/download.html) - Chrome Browser: [Chrome](http://google.com/chrome) (only required for headed mode) -### Install pikaraoke - -#### Create a virtual environment (optional) - -Using a virtual environment (venv) is recommended to prevent conflicts with other global python packages. - -You may find it more convenient to skip these steps, which allows you to launch pikaraoke without activating a venv first, but you run the risk of package conflicts. - -If you don't install a lot of python projects with pip, that skipping venv is probably be fine. The choice is yours. See [the python documentation](https://docs.python.org/3/library/venv.html) for more details on venv. +### Install pikaraoke via pip -Raspberry Pi/Linux/OSX: - -```sh -# Create a .venv directory in the homedir -python -m venv ~/.venv -# Activate your virtual environment -source ~/.venv/bin/activate -``` - -Windows (Powershell terminal): - -```batch -:: Create a venv in Windows in your homedir -cd $HOME -python -m venv .venv -.venv\Scripts\activate -``` - -You should see a "(venv)" prefix in your terminal prompt if the venv is successfully activated. - -#### Install pikaraoke via pip - -Next, install pikaraoke from PyPi on the host into your venv: +Globally or within a virtual env: ```sh # Install pikaraoke from PyPi pip install pikaraoke ``` -Note: if you did not use a venv, you may need to add the `--break-system-packages` parameter to ignore the warning and install pikaraoke and its dependencies globally. +Note: if you did not use a venv, you may need to add the `--break-system-packages` parameter to ignore the warning and install pikaraoke and its dependencies globally. You may experience package conflicts if you have other python programs installed. ### Run @@ -114,8 +96,7 @@ pikaraoke This will start pikaraoke in headed mode, and open Chrome browser with the splash screen. You can then connect to the QR code via your mobile device and start downloading and queueing songs. -Virtual env users: note that if you close your terminal between launches, you'll need to run: -`source ~/.venv/bin/activate` or `.venv\Scripts\activate` (windows) before launching pikaraoke again. +Virtual env users: note that if you close your terminal between launches, you'll need to reactivate your venv before running pikaraoke. ### More Options @@ -154,11 +135,8 @@ poetry run pikaraoke See the [Pikaraoke development guide](https://github.com/vicwomg/pikaraoke/wiki/Pikaraoke-development-guide) for more details. -#### Run from repository (legacy) - -See [README](../scripts/README.md) for how to install pikaraoke cloning this repo and using the -scripts. This is a legacy method and may no longer work. - -## Troubleshooting +## Troubleshooting and guides See the [TROUBLESHOOTING wiki](https://github.com/vicwomg/pikaraoke/wiki/FAQ-&-Troubleshooting) for help with issues. + +There are also some great guides [on the wiki](https://github.com/vicwomg/pikaraoke/wiki/) to running pikaraoke in all manner of bizarre places including Android, Chromecast, and embedded TVs! diff --git a/pikaraoke/lib/omxclient.py b/pikaraoke/lib/omxclient.py index f0aa706f..fe7785bc 100644 --- a/pikaraoke/lib/omxclient.py +++ b/pikaraoke/lib/omxclient.py @@ -3,6 +3,8 @@ import subprocess import time +# This is a legacy class for interacting with raspberry pi's OMXPlayer to play back the video. It is no longer in use. All playback is handled by the browser + class OMXClient: def __init__(self, path=None, adev=None, dual_screen=False, volume_offset=None): diff --git a/pikaraoke/lib/vlcclient.py b/pikaraoke/lib/vlcclient.py index b3a69b19..8405ef9b 100644 --- a/pikaraoke/lib/vlcclient.py +++ b/pikaraoke/lib/vlcclient.py @@ -29,6 +29,7 @@ def get_default_vlc_path(platform): return "/usr/bin/vlc" +# This is a legacy class for interacting with VLC to play back the video. It is no longer in use. All playback is handled by the browser class VLCClient: def __init__(self, port=5002, path=None, qrcode=None, url=None): # HTTP remote control server diff --git a/scripts/README.md b/scripts/README.md deleted file mode 100644 index c2bbac9e..00000000 --- a/scripts/README.md +++ /dev/null @@ -1,124 +0,0 @@ -## Installation - -### General dependencies installation - -Install git, if you haven't already. -(on raspberry pi: `sudo apt-get update; sudo apt-get install git`) - -Install python3/pip3 -(usually raspberry pi OS already has it, run `python3 --version` to check): https://www.python.org/downloads/ -Python >= 3.8 is necessary - -Clone this repo: - -``` -git clone https://github.com/vicwomg/pikaraoke.git -cd pikaraoke -``` - -If you plan to run the splash screen in auto-launch headed mode, you also need to install Chrome browser. On raspberry pi, Chromium should be installed already, which also works fine. - -### Raspberry pi / Linux / OSX - -Run the setup script to install dependencies and set up the python env: - -``` -./setup.sh -``` - -If you're on a raspberry pi or debian system the setup script should have handled installing ffmpeg via apt. - -If you're on OSX or another Linux distro, manually install the latest stable version FFMPEG 6.0 or greater from here: https://ffmpeg.org/download.html . Do not install experimental snapshot builds. - -On Ubuntu, apt seemed to keep installing an old 4.X version of ffmpeg. I found better luck grabbing a pre-built version of ffmpeg 6.0+ and manually copying it to /usr/bin/. Pre-built releases were obtained from this repo: https://github.com/BtbN/FFmpeg-Builds/releases - -### Windows - -Manually install ffmpeg 6.0 or greater https://ffmpeg.org/download.html - -Run the setup script to install python dependencies: - -``` -setup-windows.bat -``` - -Windows firewall may initially block connections to port 5555 and 5556. Be sure to allow these. It should prompt the first time you run pikaraoke and launch a song. Otherwise, configure it manually in the security settings. - -## Launch - -cd to the pikaraoke directory and run: - -`./pikaraoke.sh` (linux/osx/pi) or `pikaraoke.bat` (windows) - -The app should launch and show the PiKaraoke splash screen and a QR code and a URL. Using a device connected to the same wifi network as the Pi, scan this QR code or enter the URL into a browser. You are now connected! You can start exploring the UI and adding/queuing new songs directly from YouTube. - -If you'd like to manually open the splash screen/player or open it on a separate computer's web browser, run `./pikaraoke.sh --headless` to suppress the launch of the splash screen. Then point your browser the the URL it tells you. - -For more options, run `./pikaraoke.sh --help` - -## Auto-start PiKaraoke - -This is optional, but you may want to make your raspberry pi a dedicated karaoke device. - -``` -mkdir /home/pi/.config/autostart -nano /home/pi/.config/autostart/pikaraoke.desktop -``` - -Add this to the file, assuming you installed to /home/pi/pikaraoke, change the Exec path accordingly if not - -``` -[Desktop Entry] -Type=Application -Name=Pikaraoke -Exec=/home/pi/pikaraoke/pikaraoke.sh -``` - -Restart and it should auto-launch on your next boot. - -If you want to kill the pikaraoke process, you can do so from the PiKaraoke Web UI under: `Info > Quit pikaraoke`. Or you can ssh in and run `sudo killall python` or something similar. - -Note that if your wifi/network is inactive pikaraoke will error out 10 seconds after being launched. This is to prevent the app from hijacking your ability to login to repair the connection. - -## Usage - -May not be up to date, run `python3 app.py --help` for the latest: - -``` -usage: app.py [-h] [-p PORT] [-d DOWNLOAD_PATH] [-y YOUTUBEDL_PATH] [-v VOLUME] [-s SPLASH_DELAY] [-t SCREENSAVER_TIMEOUT] - [-l LOG_LEVEL] [--hide-url] [--prefer-ip] [--hide-raspiwifi-instructions] [--hide-splash-screen] [--dual-screen] [--high-quality] - [--logo-path LOGO_PATH] [-u URL] [--hide-overlay] [--admin-password ADMIN_PASSWORD] [--window-size WIDTH,HEIGHT] - -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 - Desired path for downloaded songs. (default: ~/pikaraoke-songs) - -y YOUTUBEDL_PATH, --youtubedl-path YOUTUBEDL_PATH - Path of youtube-dl. (default: /Users/vic/coding/pikaraoke/.venv/bin/yt-dlp) - -v VOLUME, --volume VOLUME - Set initial player volume. A value between 0 and 1. (default: 0.85) - -s SPLASH_DELAY, --splash-delay SPLASH_DELAY - Delay during splash screen between songs (in secs). (default: 3 ) - -t SCREENSAVER_TIMEOUT, --screensaver-timeout SCREENSAVER_TIMEOUT - Delay before the screensaver begins (in secs). (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-raspiwifi-instructions - Hide RaspiWiFi setup instructions 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. Note: requires ffmpeg and may cause CPU, download speed, and other performance issues - --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 - --hide-overlay Hide overlay that shows on top of video with pikaraoke QR code and IP - --admin-password ADMIN_PASSWORD - Administrator password, for locking down certain features of the web UI such as queue editing, player controls, song editing, - and system shutdown. If unspecified, everyone is an admin. - --window-size WIDTH,HEIGHT - Explicitly set the width and height of the splash screen, where the WIDTH and HEIGHT values are specified in pixels. -``` diff --git a/scripts/how-to-image.md b/scripts/how-to-image.md deleted file mode 100644 index 96086f58..00000000 --- a/scripts/how-to-image.md +++ /dev/null @@ -1,11 +0,0 @@ -## Preliminary steps - -- Get the image in good working order on the smallest SD card possible (Raspbian Lite on a 4GB card) -- On the source pi, boot it up the script in this directory and pay attention that the output matches the expected text -- Remove SD card and plug into computer - -## Creating a pi image in OSX - -- Determine the path of SD card `diskutil list` -- Run dd, replacing the if param with the device path of the SD card `sudo dd bs=4m if=/dev/disk5 of=pikaraoke.img` -- Zip the image file, it should clock in under 1.5GB if all goes well diff --git a/scripts/pikaraoke.bat b/scripts/pikaraoke.bat deleted file mode 100755 index 99962b99..00000000 --- a/scripts/pikaraoke.bat +++ /dev/null @@ -1,13 +0,0 @@ -@echo off - -:: cd to the directory of the script -cd /D "%~dp0" - -:: Activate the virtual environment -call .venv\Scripts\activate - -:: Pass remaining arguments to the command -shift - -:: Run the command with the remaining arguments -python app.py %* \ No newline at end of file diff --git a/scripts/pikaraoke.sh b/scripts/pikaraoke.sh deleted file mode 100755 index 5b395c1a..00000000 --- a/scripts/pikaraoke.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/bash -cd "$(dirname "$0")" -source .venv/bin/activate - -if [[ -n "$SSH_CLIENT" || -n "$SSH_TTY" ]]; then - if [[ "$DISPLAY" != ":0.0" ]]; then - echo "Warning: Running remotely via SSH. Setting DISPLAY=:0.0 to run on host display" - export DISPLAY=:0.0 - else - echo "DISPLAY is correctly set for SSH session." - fi -fi - -python3 app.py $@ diff --git a/scripts/prepare_pi_image.sh b/scripts/prepare_pi_image.sh deleted file mode 100755 index 4d02f380..00000000 --- a/scripts/prepare_pi_image.sh +++ /dev/null @@ -1,33 +0,0 @@ -#!/bin/sh - -read -p "This will clean a pikaraoke install to make it ready for image deployment. Proceed? (y/n): " REPLY -if [ $REPLY = "y" ] - then - -echo -echo "*** Ensure we're on the latest master..." -cd ~/pikaraoke -git checkout master -git pull - -echo "*** Clearing the songs dir ***" -sudo rm -rf /usr/lib/pikaraoke - -echo "*** Removing WPA supplicant saved wifi settings ***" -sudo rm -rf /etc/wpa_supplicant/wpa_supplicant.conf - -echo "*** Double-checking /usr/share/alsa/alsa.conf" -cat /usr/share/alsa/alsa.conf | grep "defaults.ctl.card " -cat /usr/share/alsa/alsa.conf | grep "defaults.pcm.card " -echo "^ the above values should be set to 0, not 1" - -echo "*** Double-checking /etc/rc.local expecting to see a line about launching pikaraoke:" -cat /etc/rc.local | grep pikaraoke - -echo "*** Double-checking we have a wpa_supplicant example file in /boot" -ls -la /boot/wpa_supplicant.conf.example - -echo "*** Expecting hostname to be 'pikaraoke'" -hostname - -fi diff --git a/scripts/requirements.txt b/scripts/requirements.txt deleted file mode 100644 index 37333cf7..00000000 --- a/scripts/requirements.txt +++ /dev/null @@ -1,13 +0,0 @@ -Babel==2.9.1 -CherryPy -ffmpeg-python -Flask==2.2.5 -Flask-Babel==2.0.0 -flask-paginate==2021.10.29 -jinja2==3.0.3 # Avoid escape issue: https://github.com/sphinx-doc/sphinx/issues/10289 -psutil -qrcode -requests -selenium==4.21.0 -unidecode -yt-dlp diff --git a/scripts/setup-windows.bat b/scripts/setup-windows.bat deleted file mode 100755 index d8d51c15..00000000 --- a/scripts/setup-windows.bat +++ /dev/null @@ -1,32 +0,0 @@ -@echo off - -:start -echo Are you sure you want to setup PiKaraoke? (y/n): -set /p confirm= - -if /i "%confirm%" == "y" goto setup -if /i "%confirm%" == "n" goto end - -:setup - -echo -echo "*** PULLING LATEST PIKARAOKE CODE ***." -git pull - -echo -echo "*** CREATING PYTHON VIRTUAL ENVIRONMENT ***" -python3 -m venv .venv -call .venv\Scripts\activate - -echo -echo "*** INSTALLING PYTHON DEPENDENCIES ***" -pip install -r requirements.txt - -echo -echo "*** DONE ***" -echo "Run PiKaraoke with: ./pikaraoke.bat " -echo - -:end - - diff --git a/scripts/setup.sh b/scripts/setup.sh deleted file mode 100755 index 602077be..00000000 --- a/scripts/setup.sh +++ /dev/null @@ -1,51 +0,0 @@ -#!/bin/bash - -read -p "Are you sure you want to setup PiKaraoke? (y/n): " REPLY -if [ $REPLY = "y" ] - then - -## setup stuff -echo -echo "*** PULLING LATEST PIKARAOKE CODE ***." -git pull -if [ $? -ne 0 ]; then echo "ERROR: 'git pull' failed with error code: $?"; exit 1; fi -echo - -if [[ $(cat /etc/os-release | grep ^ID= | grep -i 'debian\|raspbian') != "" ]] || [[ $(cat /etc/os-release | grep ^ID_LIKE= | grep -i 'debian') != "" ]]; then - echo "Client is a Debian-based system. Installing binaries"; - echo - echo "*** RUNNING APT-GET UPDATE ***" - sudo apt-get update --allow-releaseinfo-change - if [ $? -ne 0 ]; then echo "ERROR: 'apt-get update' failed with error code: $?"; exit 1; fi - - echo - echo "*** INSTALLING REQUIRED BINARIES ***" - sudo apt-get install ffmpeg -y - sudo apt-get install chromium-browser -y - sudo apt-get install chromium-chromedriver -y - if [ $? -ne 0 ]; then echo "ERROR: Binary dependency installation failed with error code: $?"; exit 1; fi -else - echo "Client is not Debian-based. Skipping binary installation. Please install ffmpeg and chrome manually."; -fi - -echo -echo "*** CREATING PYTHON VIRTUAL ENVIRONMENT ***" -python3 -m venv .venv -source .venv/bin/activate - -echo -echo "*** INSTALLING PYTHON DEPENDENCIES ***" -pip3 install -r requirements.txt -if [ $? -ne 0 ]; then echo "ERROR: Python requirements.txt installation failed with error code: $?"; exit 1; fi - -echo -echo "*** DONE ***" -echo "Run PiKaraoke with: ./pikaraoke.sh " -echo - -# end setup stuff - -else -echo "bye." - -fi