# 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!
Pikaraoke is independently developed and maintained. If you want to support this project with a little monetary tip, it's much appreciated: <br/><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 song queue metadata |
| Searching/Browsing | Search and rowse a local song library |
| Adding New Songs | Add new songs from Youtube |
| mp3 + cdg Support | CDG file support, supports compressed .zip bundles |
| Playback Controls | Pause, Skip, Restart, and volume control |
| 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 pikaraoke server and stream to remote browser |
## Supported Devices / OS / Platforms
- 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
## Native installation
### Requirements
- Python 3.9 or greater (You can check your current version by running `python --version`): [Python downloads](https://www.python.org/downloads/)
- FFmpeg: [FFmpeg downloads](https://ffmpeg.org/download.html)
- Chrome browser (recommended, though Safari and Firefox will work with the `--complete-transcode-before-play` option)
#### Specific install instructions for 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
```
Chromium/Chromdriver is optional if you're running with the `--headless` option.
### Install pikaraoke via pip
Globally or within a virtual env:
```sh
# Install pikaraoke from PyPi
pip install pikaraoke
```
Note: Some OS install `pip` as `pip3`. 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
Pikaraoke is now installed in the `$PATH` with the command line interface `pikaraoke`. Start by calling the pikaraoke command.
```sh
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 reactivate your venv before running pikaraoke.
### Upgrading
To upgrade to the latest version of pikaraoke, run:
```sh
pip install pikaraoke --upgrade
```
### More Options
See the help command `pikaraoke --help` for available options.
## 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
```
For more information, [see official Dockerhub repo](https://hub.docker.com/repository/docker/vicwomg/pikaraoke)
## 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
```
If you don't want to install poetry, you can alternately install pikaraoke directly from the source code root:
```sh
pip install .
```
See the [Pikaraoke development guide](https://github.com/vicwomg/pikaraoke/wiki/Pikaraoke-development-guide) for more details.
## 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!
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/9f/20/d9c9212874a0b0c9665b5d54c1da488f9286b7cc61af2cea6c9c13e127d7/pikaraoke-1.11.0.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\nPikaraoke is independently developed and maintained. If you want to support this project with a little monetary tip, it's much appreciated: <br/><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 song queue metadata |\n| Searching/Browsing | Search and rowse a local song library |\n| Adding New Songs | Add new songs from Youtube |\n| mp3 + cdg Support | CDG file support, supports compressed .zip bundles |\n| Playback Controls | Pause, Skip, Restart, and volume control |\n| Queue Management | Manage the song queue and change the order |\n| Key Change / Pitch Shifting | Adjust the pitch of songs |\n| File Management | Advanced editing of downloaded file names |\n| Admin Mode | Lock down features with admin mode |\n| Headless Mode | Run a dedicated pikaraoke server and stream to remote browser |\n\n## Supported Devices / OS / Platforms\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## Native installation\n\n### Requirements\n\n- Python 3.9 or greater (You can check your current version by running `python --version`): [Python downloads](https://www.python.org/downloads/)\n- FFmpeg: [FFmpeg downloads](https://ffmpeg.org/download.html)\n- Chrome browser (recommended, though Safari and Firefox will work with the `--complete-transcode-before-play` option)\n\n#### Specific install instructions for 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\nChromium/Chromdriver is optional if you're running with the `--headless` option.\n\n### Install pikaraoke via pip\n\nGlobally or within a virtual env:\n\n```sh\n# Install pikaraoke from PyPi\npip install pikaraoke\n```\n\nNote: Some OS install `pip` as `pip3`. 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.\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\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 reactivate your venv before running pikaraoke.\n\n### Upgrading\n\nTo upgrade to the latest version of pikaraoke, run:\n\n```sh\npip install pikaraoke --upgrade\n```\n\n### More Options\n\nSee the help command `pikaraoke --help` for available options.\n\n## Docker instructions\n\nFor Docker users, you can get going with one command. The deployed images includes everything you need to run in headless mode:\n\n```sh\ndocker run vicwomg/pikaraoke:latest\n```\n\nFor more information, [see official Dockerhub repo](https://hub.docker.com/repository/docker/vicwomg/pikaraoke)\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\nIf you don't want to install poetry, you can alternately install pikaraoke directly from the source code root:\n\n```sh\npip install .\n```\n\nSee the [Pikaraoke development guide](https://github.com/vicwomg/pikaraoke/wiki/Pikaraoke-development-guide) for more details.\n\n## Troubleshooting and guides\n\nSee the [TROUBLESHOOTING wiki](https://github.com/vicwomg/pikaraoke/wiki/FAQ-&-Troubleshooting) for help with issues.\n\nThere 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!\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Youtube-based Karaoke machine for Raspberry Pi, OSX, Windows, and Linux",
"version": "1.11.0",
"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": null,
"digests": {
"blake2b_256": "d6e67cb68a5d96abe1f5f0442a612aafa401e59b0af86282350a557d428bcfd8",
"md5": "ad240bd235f03f4ca2bf38949740895c",
"sha256": "b33854d98e93ae2dbe564cc8ed3a1a0faf4fa8671c7fffc73a312c23041b6af3"
},
"downloads": -1,
"filename": "pikaraoke-1.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad240bd235f03f4ca2bf38949740895c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 7826528,
"upload_time": "2025-02-08T17:22:06",
"upload_time_iso_8601": "2025-02-08T17:22:06.066382Z",
"url": "https://files.pythonhosted.org/packages/d6/e6/7cb68a5d96abe1f5f0442a612aafa401e59b0af86282350a557d428bcfd8/pikaraoke-1.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f20d9c9212874a0b0c9665b5d54c1da488f9286b7cc61af2cea6c9c13e127d7",
"md5": "7d110f9d7a18b2c35de80a406a04f2be",
"sha256": "715c5c8ee08ddd7fa2097de8e58641e64c7861e64c99ae4489ca8616aa535af8"
},
"downloads": -1,
"filename": "pikaraoke-1.11.0.tar.gz",
"has_sig": false,
"md5_digest": "7d110f9d7a18b2c35de80a406a04f2be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 7734721,
"upload_time": "2025-02-08T17:22:09",
"upload_time_iso_8601": "2025-02-08T17:22:09.674547Z",
"url": "https://files.pythonhosted.org/packages/9f/20/d9c9212874a0b0c9665b5d54c1da488f9286b7cc61af2cea6c9c13e127d7/pikaraoke-1.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-08 17:22:09",
"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
