Create Python Package

docs/README.md

@@ -0,0 +1,97 @@
+# PiKaraoke
+
+PiKaraoke is a "KTV"-style karaoke song search and queueing system. It connects to your TV, and shows a QR code for computers and smartphones to connect to a web interface. From there, multiple users can seamlessly search your local track library, queue up songs, add an endless selection of new karaoke tracks from YouTube, and more. Works on Raspberry Pi, OSX, Windows, and Linux!
+
+If you want to support this project with a little monetary tip, it's much appreciated: <br/>
+<a href="https://www.buymeacoffee.com/vicwomg" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>
+
+## Table of Contents
+
+- [Features](#features)
+- [Supported Devices / OS](#supported-devices--os)
+- [Get Started](#get-started)
+  - [Install](#install)
+  - [Run](#run)
+  - [More Options](#more-options)
+- [Screenshots](#screenshots)
+  - [TV](#tv)
+  - [Web interface](#web-interface)
+- [Troubleshooting](#troubleshooting)
+- [Install from Repo](#install-from-repository-legacy)
+
+## Features
+
+| **Feature**                            | **Description**                                      |
+|----------------------------------------|------------------------------------------------------|
+| Web Interface                          | Multiple users can queue tracks                     |
+| Player/Splash Screen                   | Connection QR code and "Next up" display             |
+| Searching/Browsing                     | Browse a local song library                         |
+| Adding New Songs                       | Add new songs from Youtube                          |
+| mp3 + cdg Support                      | Includes compressed .zip bundles                    |
+| Playback Controls                      | Pause, Skip, Restart, and volume control            |
+| File Name Editing                      | Advanced editing of downloaded file names           |
+| Queue Management                       | Manage the song queue                               |
+| Key Change / Pitch Shifting            | Adjust the pitch of songs                           |
+| Admin Mode                             | Lock down features with admin mode                  |
+
+## Supported Devices / OS
+
+| **Device/OS**                         | **Details**                                                                                   |
+|---------------------------------------|-----------------------------------------------------------------------------------------------|
+| Raspberry Pi 3 and above              | Suitable, but anything below Pi 3 will likely be too slow.                                    |
+| Raspberry Pi Desktop OS (headed)      | Should be used if running with a display, as it requires a browser.                           |
+| 32-bit Bullseye OS (recommended for Pi 3) | Recommended OS for Pi 3.                                                                      |
+| 64-bit Bookworm OS (recommended for Pi 4 and above) | Fine for Pi 4 and above.                                                             |
+| Raspberry Pi 3 High-Res Video Playback | Pi 3 might struggle with high-res video playback, but overclocking can help.                  |
+| Disable Screen Blanking               | Disable "screen blanking" in `raspi-config` to prevent the display from turning off when idle.|
+| Modern Mac, PCs, and Linux            | Works fine on modern devices.                                                                 |
+
+## Get Started
+
+### Install
+
+Install pikaraoke from PyPi on the host.
+
+```sh
+# Setup a virtual environment (optional) (recommended)
+python -m venv venv
+source venv/bin/activate
+
+# Install pikaraoke from PyPi
+pip install pikaraoke
+```
+
+### Run
+
+Pikaraoke is now installed in `$PATH` with the command line interface `pikaraoke`. Start is by
+calling the pikaraoke command.
+
+```sh
+# Run pikaraoke
+pikaraoke
+```
+
+### More Options
+
+See the help command `pikaraoke --help` for available options.
+
+## Screenshots
+
+<div style="display: flex">
+<img width="250" alt="pikaraoke-nowplaying" src="https://user-images.githubusercontent.com/4107190/95813193-2cd5c180-0ccc-11eb-89f4-11a69676dc6f.png">
+<img width="250" alt="pikaraoke-queue" src="https://user-images.githubusercontent.com/4107190/95813195-2d6e5800-0ccc-11eb-8f00-1369350a8a1c.png">
+<img width="250"  alt="pikaraoke-browse" src="https://user-images.githubusercontent.com/4107190/95813182-27787700-0ccc-11eb-82c8-fde7f0a631c1.png">
+<img width="250"  alt="pikaraoke-search1" src="https://user-images.githubusercontent.com/4107190/95813197-2e06ee80-0ccc-11eb-9bf9-ddb24d988332.png">
+<img width="250"  alt="pikaraoke-search2" src="https://user-images.githubusercontent.com/4107190/95813190-2ba49480-0ccc-11eb-84e3-f902cbd489a2.png">
+</div>
+<img width="400" alt="pikaraoke-tv2" src="https://user-images.githubusercontent.com/4107190/95813564-019fa200-0ccd-11eb-95e1-57a002c357a3.png">
+  </p>
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for help with issues.
+
+## Install 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.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,96 @@
+## Troubleshooting
+
+### How do I update pikaraoke to the latest version?
+
+Simply run the setup script again. CD the pikaraoke directory and run: `./setup.sh` (linux/osx/rpi) `setup-windows.bat` (windows)
+
+### I'm not hearing audio out of the headphone jack
+
+By default the raspbian outputs to HDMI audio when it's available. Pikaraoke tries to output to both HDMI and headphone, but if it doesn't work you may need to to force it to the headphone jack. This is definitely the case when using VLC. To do so, change following setting on the pi:
+`sudo raspi-config`
+Advanced Options > Audio > Force 3.5mm (headphone)
+
+See: https://www.raspberrypi.org/documentation/configuration/audio-config.md
+
+If you're still having issues with hearing audio, it has been reported this helps on raspberry pi 4 devices:
+
+`sudo nano /usr/share/alsa/alsa.conf`
+
+Scroll down and change defaults.ctl.card and defaults.pcm.card to "1"
+
+```
+defaults.ctl.card 1
+defaults.pcm.card 1
+```
+
+Note this value might be different in older versions of Raspbian or if you have external audio hardware. See source article for details: https://raspberrypi.stackexchange.com/a/39942
+
+### Songs aren't downloading!
+
+Make sure youtube-dl is up to date, old versions have higher failure rates due to security changes in Youtube. You can see your current version installed by navigating to `Info > System Info > Youtube-dl version`. The version number is usually the date it was released. If this is older than a couple of months, chances are it will need an update.
+
+You can update youtube-dl directly from the web UI. Go to `Info > Update Youtube-dl`
+
+### Downloads are slow!
+
+youtube-dl is very CPU intensive, especially for single-core devices like the pi models zero and less-than 2. The more simultaneous downloads there are, the longer they will take. Try to limit it to 1-2 at a time. Pi 3 can handle quite a bit more.
+
+### I brought my pikaraoke to a friend's house and it can't connect to their network. How do I change wifi connection without ssh?
+
+These are my preferred ways to do it, but they might require either a USB keyboard or a computer with an SD Card reader.
+
+- _USB Keyboard_: plug in a USB keyboard to the pi. After it boots up, log in and run "sudo raspi-config" and configure wifi through the Network Options section. If the desktop UI is installed, you can also run "startx" and configure wifi from the Raspbian GUI. You can also manually edit /etc/wpa_supplicant/wpa_supplicant.conf as desribed below.
+- _SD Card Reader_: Remove the pi's SD card and open it on another computer with an SD card reader. It should mount as a disk drive. On the BOOT partition, add a plaintext file named "wpa_supplicant.conf" and put the following in it:
+
+```
+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
+}
+```
+
+Add the SD card back to the pi and start it up. On boot, Raspbian should automatically add the wpa_supplicant.conf file to the correct location and connect to wifi.
+
+Finally, this package can set up your pi as a self-configuring wireless access point, but hasn't been updated in a while https://github.com/jasbur/RaspiWiFi
+
+### Can I run PiKaraoke without a wifi/network connection?
+
+Yes, but you can only access your existing library and won't be able to download new songs.
+
+If you run your pi as a wifi access point, your browser can connect to that access point, and it should work. See: https://www.raspberrypi.org/documentation/configuration/wireless/access-point.md
+
+You can also try this: https://github.com/jasbur/RaspiWiFi (used for configuring wifi connections headless). While it's in AP mode, you can connect to the pi as an AP and connect directly to it at http://10.0.0.1:5555
+
+### Where do I plug in a microphone?
+
+The pi doesn't have a hardware audio input. Technically, you should be able to run a microphone through it with a USB sound card attached to the pi (or USB microphone), but the latency is generally not usable.
+
+Ideally, you'd have a mixer and amplifier that you could run the line out of the pi to, as well as the microphones. I used this affordable wireless microphone set from amazon: https://amzn.to/2OXKXdc (affiliate link) It has a line-in so you can also run PiKaraoke into the mix, and output to an amplifier.
+
+### How do I change song pitch/key?
+
+While a song is playing, the home screen of the web interface will show a transpose slider. Slide it up or down based on your preference and press the "ok" button to restart the song in the given key.
+
+### How do I add cdg or mp3+cdg zip files?
+
+You'll need to add them manually by copying them to the root of your download folder. Run `pikaraoke.sh --help` and look under DOWNLOAD_PATH to find out what the default folder is, or specify your own. Only cdg/mp3 pairs and .zip files are supported.
+
+### My mp3/cdg file is not playing
+
+CDG files must have an mp3 file with a exact matching file name. They can also be bundled together in a single zip file, but the filenames in the zip must still match. They must also be placed in the root of the download directory and not stashed away in sub-directories.
+
+### I'm getting this ChromeDriver error on launch: "session not created: DevToolsActivePort file doesn't exist"
+
+Are you trying to launch over SSH? That probably indicates that chromedriver doesn't know which display to launch the browser on. If so, you may need to specify the native display of the remote device using this command: `DISPLAY=:0.0 ./pikaraoke.sh`. Note that Pikaraoke 1.2.1 and newer should do this for you.
+
+You can alternately run headless if you launch the splash screen manually on a separate machine: `./pikaraoke.sh --headless`
+
+### How do I dismiss the Splash confirmation screen on an in-TV browser? (like a Samsung TV with web browsing)
+
+The splash confirmation screen is an unfortunate necessity due to modern browser permissions disabling video autoplay. A single interaction will enable it, and the confirmation screen serves as this interaction. Hopefully your TV has a way to click the button on the screen with the remote or otherwise.
+
+If you want to try without confirmation, you can add a parameter to the end of the splash screen URL "confirm=false". Ex: `http://pikaraoke.local:5555/splash.html?confirm=false` but there's no guarantee that videos will play; it depends on the embedded browser implementation.

pikaraoke/__init__.py

@@ -0,0 +1,13 @@
+from pikaraoke.constants import VERSION
+from pikaraoke.karaoke import Karaoke
+from pikaraoke.lib.get_platform import get_platform
+
+__version__ = VERSION
+PACKAGE = __package__
+
+__all__ = [
+    "VERSION",
+    "PACKAGE",
+    Karaoke.__name__,
+    get_platform.__name__,
+]

app.py → pikaraoke/app.py

@@ -12,7 +12,9 @@
 
 import cherrypy
 import flask_babel
+import karaoke
 import psutil
+from constants import LANGUAGES, VERSION
 from flask import (
     Flask,
     flash,
@@ -25,6 +27,7 @@
 )
 from flask_babel import Babel
 from flask_paginate import Pagination, get_page_parameter
+from lib.get_platform import get_platform, is_raspberry_pi
 from selenium import webdriver
 from selenium.webdriver.chrome.options import Options
 from selenium.webdriver.chrome.service import Service
@@ -33,10 +36,6 @@
 from selenium.webdriver.support import expected_conditions as EC
 from selenium.webdriver.support.ui import WebDriverWait
 
-import karaoke
-from constants import LANGUAGES, VERSION
-from lib.get_platform import get_platform, is_raspberry_pi
-
 try:
     from urllib.parse import quote, unquote
 except ImportError:

karaoke.py → pikaraoke/karaoke.py

@@ -14,8 +14,6 @@
 
 import ffmpeg
 import qrcode
-from unidecode import unidecode
-
 from lib.file_resolver import FileResolver
 from lib.get_platform import (
     get_ffmpeg_version,
@@ -24,6 +22,7 @@
     is_raspberry_pi,
     supports_hardware_h264_encoding,
 )
+from unidecode import unidecode
 
 
 # Support function for reading  lines from ffmpeg stderr without blocking

lib/vlcclient.py → pikaraoke/lib/vlcclient.py

@@ -12,7 +12,6 @@
 from threading import Timer
 
 import requests
-
 from lib.get_platform import get_platform, is_raspberry_pi
 
 

pyproject.toml

@@ -0,0 +1,31 @@
+[tool.poetry]
+name = "pikaraoke"
+version = "1.0.0"
+description = "Youtube-based Karaoke machine for Raspberry Pi, OSX, Windows, and Linux"
+authors = ["Marius <[email protected]>"]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+CherryPy = "18.10.0"
+Flask = "2.2.5"
+qrcode = "7.4.2"
+psutil = "6.0.0"
+unidecode = "1.3.8"
+requests = "2.32.3"
+flask-paginate = "2021.10.29"
+jinja2 = "3.0.3"  # Avoid escape issue: https://github.com/sphinx-doc/sphinx/issues/10289
+Babel = "2.9.1"
+Flask-Babel = "2.0.0"
+selenium = "4.21.0"
+ffmpeg-python = "0.2.0"
+yt-dlp = "2024.7.9"
+
+[tool.poetry.dev-dependencies]
+pytest = "^6.2.5"
+
+[tool.poetry.scripts]
+pikaraoke = "pikaraoke.app:main"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"