# PiKaraoke
[](https://conventionalcommits.org)
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)
- [Screenshots](#screenshots)
- [Developing pikaraoke](#developing-pikaraoke)
- [Troubleshooting](#troubleshooting)
## 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
- Bookworm Desktop OS required for standalone/headed mode
- For Pi 3: overclocking is recommended for smoother playback
- OSX
- Windows
- Linux
## Get Started
### 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/)
#### Raspberry Pi OS / Linux distros with `apt`:
```
sudo apt-get install ffmpeg -y
sudo apt-get install chromium-browser -y
sudo apt-get install chromium-chromedriver -y
```
#### 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.
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:
```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.
### Run
Pikaraoke is now installed in the `$PATH` with the command line interface `pikaraoke`. Start by calling the pikaraoke command.
```sh
# Run pikaraoke
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.
### 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>
## Developing pikaraoke
The Pikaraoke project utilizes Poetry for dependency management and local development.
- Install poetry: [Poetry](https://python-poetry.org/docs/#installation)
- Git clone this repo
From the pikaraoke directory:
```sh
# install dependencies
poetry install
```
```sh
# Run pikaraoke from the local codebase
poetry run pikaraoke
```
#### 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
See the [TROUBLESHOOTING wiki](https://github.com/vicwomg/pikaraoke/wiki/FAQ-&-Troubleshooting) for help with issues.
Raw data
{
"_id": null,
"home_page": "https://github.com/vicwomg/pikaraoke",
"name": "pikaraoke",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "karaoke, ktv, video, audio, youtube, raspberry-pi, osx, windows, linux",
"author": "Vic Wong",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f2/d4/10ee7c73d95b09ae04d6af26e921de20e8f949db6dc11770697dff160ce2/pikaraoke-1.5.1.tar.gz",
"platform": null,
"description": "# PiKaraoke\n\n[](https://conventionalcommits.org)\n\nPiKaraoke 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!\n\nIf you want to support this project with a little monetary tip, it's much appreciated: <br/>\n<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>\n\n## Table of Contents\n\n- [Features](#features)\n- [Supported Devices / OS](#supported-devices--os)\n- [Get Started](#get-started)\n- [Screenshots](#screenshots)\n- [Developing pikaraoke](#developing-pikaraoke)\n- [Troubleshooting](#troubleshooting)\n\n## Features\n\n| **Feature** | **Description** |\n| --------------------------- | ------------------------------------------------------------- |\n| Web Interface | Multiple users can queue tracks from their smartphones |\n| Player/Splash Screen | Connection QR code and \"Next up\" display |\n| Searching/Browsing | Browse a local song library |\n| Adding New Songs | Add new songs from Youtube |\n| mp3 + cdg Support | Includes compressed .zip bundles |\n| Playback Controls | Pause, Skip, Restart, and volume control |\n| File Management | Advanced editing of downloaded file names |\n| Queue Management | Manage the song queue and change the order |\n| Key Change / Pitch Shifting | Adjust the pitch of songs |\n| Admin Mode | Lock down features with admin mode |\n| Headless Mode | Run a dedicated server and stream pikaraoke to remote browser |\n\n## Supported Devices / OS\n\n- Raspberry Pi\n - Requires a Raspberry Pi Model 3 or higher\n - Bookworm Desktop OS required for standalone/headed mode\n - For Pi 3: overclocking is recommended for smoother playback\n- OSX\n- Windows\n- Linux\n\n## Get Started\n\n### Install required programs\n\nPikaraoke requires Python 3.9 or greater. You can check your current version by running `python --version`. [Python downloads](https://www.python.org/downloads/)\n\n#### Raspberry Pi OS / Linux distros with `apt`:\n\n```\nsudo apt-get install ffmpeg -y\nsudo apt-get install chromium-browser -y\nsudo apt-get install chromium-chromedriver -y\n```\n\n#### Windows / OSX / Linux:\n\n- FFmpeg 6.0 or greater: [FFmpeg downloads](https://ffmpeg.org/download.html)\n- Chrome Browser: [Chrome](http://google.com/chrome) (only required for headed mode)\n\n### Install pikaraoke\n\n#### Create a virtual environment (optional)\n\nUsing a virtual environment (venv) is recommended to prevent conflicts with other global python packages.\n\nYou 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.\n\nIf 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.\n\nRaspberry Pi/Linux/OSX:\n\n```sh\n# Create a .venv directory in the homedir\npython -m venv ~/.venv\n# Activate your virtual environment\nsource ~/.venv/bin/activate\n```\n\nWindows (Powershell terminal):\n\n```batch\n:: Create a venv in Windows in your homedir\ncd $HOME\npython -m venv .venv\n.venv\\Scripts\\activate\n```\n\nYou should see a \"(venv)\" prefix in your terminal prompt if the venv is successfully activated.\n\n#### Install pikaraoke via pip\n\nNext, install pikaraoke from PyPi on the host into your venv:\n\n```sh\n# Install pikaraoke from PyPi\npip install pikaraoke\n```\n\nNote: 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.\n\n### Run\n\nPikaraoke is now installed in the `$PATH` with the command line interface `pikaraoke`. Start by calling the pikaraoke command.\n\n```sh\n# Run pikaraoke\npikaraoke\n```\n\nThis 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.\n\nVirtual env users: note that if you close your terminal between launches, you'll need to run:\n`source ~/.venv/bin/activate` or `.venv\\Scripts\\activate` (windows) before launching pikaraoke again.\n\n### More Options\n\nSee the help command `pikaraoke --help` for available options.\n\n## Screenshots\n\n<div style=\"display: flex\">\n<img width=\"250\" alt=\"pikaraoke-nowplaying\" src=\"https://user-images.githubusercontent.com/4107190/95813193-2cd5c180-0ccc-11eb-89f4-11a69676dc6f.png\">\n<img width=\"250\" alt=\"pikaraoke-queue\" src=\"https://user-images.githubusercontent.com/4107190/95813195-2d6e5800-0ccc-11eb-8f00-1369350a8a1c.png\">\n<img width=\"250\" alt=\"pikaraoke-browse\" src=\"https://user-images.githubusercontent.com/4107190/95813182-27787700-0ccc-11eb-82c8-fde7f0a631c1.png\">\n<img width=\"250\" alt=\"pikaraoke-search1\" src=\"https://user-images.githubusercontent.com/4107190/95813197-2e06ee80-0ccc-11eb-9bf9-ddb24d988332.png\">\n<img width=\"250\" alt=\"pikaraoke-search2\" src=\"https://user-images.githubusercontent.com/4107190/95813190-2ba49480-0ccc-11eb-84e3-f902cbd489a2.png\">\n</div>\n<img width=\"400\" alt=\"pikaraoke-tv2\" src=\"https://user-images.githubusercontent.com/4107190/95813564-019fa200-0ccd-11eb-95e1-57a002c357a3.png\">\n </p>\n\n## Developing pikaraoke\n\nThe Pikaraoke project utilizes Poetry for dependency management and local development.\n\n- Install poetry: [Poetry](https://python-poetry.org/docs/#installation)\n- Git clone this repo\n\nFrom the pikaraoke directory:\n\n```sh\n# install dependencies\npoetry install\n```\n\n```sh\n# Run pikaraoke from the local codebase\npoetry run pikaraoke\n```\n\n#### Run from repository (legacy)\n\nSee [README](../scripts/README.md) for how to install pikaraoke cloning this repo and using the\nscripts. This is a legacy method and may no longer work.\n\n## Troubleshooting\n\nSee the [TROUBLESHOOTING wiki](https://github.com/vicwomg/pikaraoke/wiki/FAQ-&-Troubleshooting) for help with issues.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Youtube-based Karaoke machine for Raspberry Pi, OSX, Windows, and Linux",
"version": "1.5.1",
"project_urls": {
"Homepage": "https://github.com/vicwomg/pikaraoke",
"Repository": "https://github.com/vicwomg/pikaraoke"
},
"split_keywords": [
"karaoke",
" ktv",
" video",
" audio",
" youtube",
" raspberry-pi",
" osx",
" windows",
" linux"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd99e8c4559a278ed2ce6f5c65e6be62b2722e9668ab8db4d4d4a08330246cfb",
"md5": "bf2c6eaa8cef12d866a27690b8c4fb2b",
"sha256": "ddbfe2df6a0265c1d690c02e370cb33ae26b79db3322bb9841350b81a337d0eb"
},
"downloads": -1,
"filename": "pikaraoke-1.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf2c6eaa8cef12d866a27690b8c4fb2b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 755040,
"upload_time": "2024-09-23T18:42:49",
"upload_time_iso_8601": "2024-09-23T18:42:49.010512Z",
"url": "https://files.pythonhosted.org/packages/dd/99/e8c4559a278ed2ce6f5c65e6be62b2722e9668ab8db4d4d4a08330246cfb/pikaraoke-1.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2d410ee7c73d95b09ae04d6af26e921de20e8f949db6dc11770697dff160ce2",
"md5": "32931aa209bf3c67d61e728196897f42",
"sha256": "ddad1087b518da42b8b6d360b336b8f61361d7ddf43c66c383a11fb38d615f23"
},
"downloads": -1,
"filename": "pikaraoke-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "32931aa209bf3c67d61e728196897f42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 716626,
"upload_time": "2024-09-23T18:42:51",
"upload_time_iso_8601": "2024-09-23T18:42:51.013935Z",
"url": "https://files.pythonhosted.org/packages/f2/d4/10ee7c73d95b09ae04d6af26e921de20e8f949db6dc11770697dff160ce2/pikaraoke-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 18:42:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vicwomg",
"github_project": "pikaraoke",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pikaraoke"
}
JSON
