Merge pull request #365 from mariugul/feat/create-python-package

Create Python Package

.gitignore

@@ -2,7 +2,9 @@
 *.swp
 .vscode/
 .venv/
+.venv*
 __pycache__/
+dist/
 songs/
 qrcode.png
 .DS_Store

docs/README.md

@@ -0,0 +1,110 @@
+# 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 from their smartphones        |
+| 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 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                                     |
+| Admin Mode                  | Lock down features with admin mode                            |
+| Headless Mode               | Run a dedicated server and stream pikaraoke to remote browser |
+
+## Supported Devices / OS
+
+- Raspberry Pi
+  - Requires a Raspberry Pi Model 3 or higher
+  - Bullseye/Bookworm Desktop OS required for standalone/headed mode
+  - For Pi 3: 32-bit Bullseye OS and overclocking is recommended for smoother playback.
+- OSX
+- Windows
+- Linux
+
+## Get Started
+
+### Install required programs
+
+Raspberry Pi OS / Debian-based distros:
+
+```
+sudo apt-get install ffmpeg -y
+sudo apt-get install chromium-browser -y
+sudo apt-get install chromium-chromedriver -y
+```
+
+Windows / OSX / Linux:
+
+- Python 3.9 or greater: https://www.python.org/downloads/
+- FFmpeg 6.0 or greater: https://ffmpeg.org/download.html
+- Chrome Browser: http://google.com/chrome (only required for headed mode)
+
+### Install pikaraoke
+
+Optional: create a virtual environment. Recommended if you might have conflicting python programs installed. Probably not a concern for many users. (See: https://docs.python.org/3/library/venv.html)
+
+Install pikaraoke from PyPi on the host:
+
+```sh
+# Install pikaraoke from PyPi
+pip install pikaraoke
+```
+
+### Run
+
+Pikaraoke is now installed in `$PATH` with the command line interface `pikaraoke`. Start 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 and may no longer work.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,107 @@
+## Troubleshooting
+
+### How do I update pikaraoke to the latest version?
+
+`pip install --upgrade pikaraoke`
+
+### I'm not hearing audio out of the headphone jack (rpi)
+
+See: https://www.raspberrypi.com/documentation/computers/configuration.html#change-audio-output
+
+### How to auto-start PiKaraoke (rpi)
+
+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/scripts/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.
+
+### How to keep the screen from turning off when idle (rpi)
+
+Disable "screen blanking" in raspi-config: https://www.raspberrypi.com/documentation/computers/configuration.html#display-options
+
+### 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? (rpi)
+
+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 configure wifi using the GUI wizard (right-click the wifi icon in the top right). 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 --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`.
+
+You can alternately run headless if you launch the splash screen manually on a separate machine: `pikaraoke --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

@@ -33,9 +33,9 @@
 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
+from pikaraoke import karaoke
+from pikaraoke.constants import LANGUAGES, VERSION
+from pikaraoke.lib.get_platform import get_platform, is_raspberry_pi
 
 try:
     from urllib.parse import quote, unquote
@@ -686,12 +686,6 @@ def expand_fs():
 signal.signal(signal.SIGTERM, lambda signum, stack_frame: k.stop())
 
 
-def get_default_youtube_dl_path(platform):
-    if platform == "windows":
-        return os.path.join(os.path.dirname(__file__), ".venv\\Scripts\\yt-dlp.exe")
-    return os.path.join(os.path.dirname(__file__), ".venv/bin/yt-dlp")
-
-
 def get_default_dl_dir(platform):
     if raspberry_pi:
         return "~/pikaraoke-songs"
@@ -709,7 +703,7 @@ def get_default_dl_dir(platform):
             return "~/pikaraoke-songs"
 
 
-if __name__ == "__main__":
+def main():
     platform = get_platform()
     default_port = 5555
     default_ffmpeg_port = 5556
@@ -720,7 +714,7 @@ def get_default_dl_dir(platform):
     default_prefer_hostname = False
 
     default_dl_dir = get_default_dl_dir(platform)
-    default_youtubedl_path = get_default_youtube_dl_path(platform)
+    default_youtubedl_path = "yt-dlp"
 
     # parse CLI args
     parser = argparse.ArgumentParser()
@@ -865,11 +859,6 @@ def get_default_dl_dir(platform):
     app.jinja_env.globals.update(filename_from_path=filename_from_path)
     app.jinja_env.globals.update(url_escape=quote)
 
-    # check if required binaries exist
-    if not os.path.isfile(args.youtubedl_path):
-        print("Youtube-dl path not found! " + args.youtubedl_path)
-        sys.exit(1)
-
     # setup/create download directory if necessary
     dl_path = os.path.expanduser(arg_path_parse(args.download_path))
     if not dl_path.endswith("/"):
@@ -907,6 +896,7 @@ def get_default_dl_dir(platform):
         ffmpeg_url=args.ffmpeg_url,
         prefer_hostname=args.prefer_hostname,
     )
+    k.upgrade_youtubedl()
 
     # Start the CherryPy WSGI web server
     cherrypy.tree.graft(app, "/")
@@ -954,3 +944,7 @@ def get_default_dl_dir(platform):
     cherrypy.engine.exit()
 
     sys.exit()
+
+
+if __name__ == "__main__":
+    main()

karaoke.py → pikaraoke/karaoke.py

@@ -16,8 +16,8 @@
 import qrcode
 from unidecode import unidecode
 
-from lib.file_resolver import FileResolver
-from lib.get_platform import (
+from pikaraoke.lib.file_resolver import FileResolver
+from pikaraoke.lib.get_platform import (
     get_ffmpeg_version,
     get_os_version,
     get_platform,

lib/file_resolver.py → pikaraoke/lib/file_resolver.py

@@ -3,7 +3,7 @@
 import shutil
 import zipfile
 
-from lib.get_platform import get_platform
+from pikaraoke.lib.get_platform import get_platform
 
 
 # Processes a given file path and determines the file format and file path, extracting zips into cdg + mp3 if necessary.

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

@@ -13,7 +13,7 @@
 
 import requests
 
-from lib.get_platform import get_platform, is_raspberry_pi
+from pikaraoke.lib.get_platform import get_platform, is_raspberry_pi
 
 
 def get_default_vlc_path(platform):

pikaraoke/setup_apt.py

@@ -0,0 +1,24 @@
+import subprocess
+
+
+def run_command(command):
+    result = subprocess.run(command, shell=True, text=True)
+    if result.returncode != 0:
+        raise Exception(f"ERROR: '{command}' failed with error code: {result.returncode}")
+
+
+# Create an alias function for apt
+def apt(command):
+    run_command(f"sudo apt-get {command}")
+
+
+def main():
+    print("*** INSTALLING REQUIRED BINARIES ***")
+    apt("update --allow-releaseinfo-change")
+    apt("install ffmpeg -y")
+    apt("install chromium-browser -y")
+    apt("install chromium-chromedriver -y")
+
+
+if __name__ == "__main__":
+    main()