<p align="center">
<img src="https://raw.githubusercontent.com/christofsteel/syng/refs/heads/main/resources/icons/hicolor/512x512/apps/rocks.syng.Syng.png"
height="130">
_Easily host karaoke events_
<p align="center">
[](https://matrix.to/#/#syng:matrix.org)
[](https://floss.social/@syng)
[](https://pypi.org/project/syng/)
[](https://flathub.org/apps/rocks.syng.Syng)
[](https://www.gnu.org/licenses/agpl-3.0.en.html)
[](https://syng.rocks)
[](https://git.k-fortytwo.de/christofsteel/syng2)
**Syng** is an all-in-one karaoke software, consisting of a *backend server*, a *web frontend* and a *playback client*.
Karaoke performers can search a library using the web frontend, and add songs to the queue.
The playback client retrieves songs from the backend server and plays them in order.
You can play songs from **YouTube**, an **S3** storage or simply share local **files**.
The playback client uses [mpv](https://mpv.io/) for playback and can therefore play a variety of file formats, such as `mp3+cdg`, `webm`, `mp4`, ...
Join our [matrix room](https://matrix.to/#/#syng:matrix.org) or follow us on [mastodon](https://floss.social/@syng) for update notifications and support.
# Screenshots
<img src="https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng.png" alt="Main Window" height=200/> <img src="https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_advanced.png" alt="Main Window (Advanced)" height=200/>
<img src="https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_web2.png" alt="Web Interface" height=200/><img src="https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_mobile_search.png" alt="Web Interface on Mobile" height=200/>
<img src="https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_player_next_up.png" alt="Player (next up)" height=200/> <img src="https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_player_song.png" alt="Player playing a song" height=200/>
# Client
[](https://flathub.org/apps/rocks.syng.Syng)
To host a karaoke event, you only need to use the playback client. You can use the publicly available instance at https://syng.rocks as your server.
## Installation
### Linux
The preferred way to install the client is via [Flathub](https://flathub.org/apps/rocks.syng.Syng).
Alternatively Syng can be installed via the _Python Package Index_ (PyPI). When installing the client it is mandatory to include the `client` flag:
pip install 'syng[client]'
This installs both the playback client (`syng client`) and a configuration GUI (`syng gui`).
**Note:** When installing via PyPI, you need to have [mpv](https://mpv.io/) installed on the playback client, and the `mpv` binary must be in your `PATH`.
### Windows
Windows support is experimental, but you can download the current version from [Releases](https://github.com/christofsteel/syng/releases). No installation necessary, you can just run the `exe`.
## Configuration
You can host karaoke events using the default configuration. But if you need more advanced configuration, you can either configure Syng using the GUI or via a text editor by editing `~/.config/syng/config.yaml`. There are the following settings:
* `server`: URL of the server to connect to.
* `room`: The room code for your karaoke event. Can be chosen arbitrarily, but must be unique. Unused rooms will be deleted after some time. _Note:_ Everyone, that has access to the room code can join the karaoke event.
* `secret`: The admin password for your karaoke event. If you want to reconnect with a playback client to a room, these must match. Additionally, this unlocks admin capabilities to a web client, when given under "Advanced" in the web client.
* `waiting_room_policy`: One of `none`, `optional`, `forced`. When a performer wants to be added to the playback queue, but has already a song queued, they can be added to the _waiting room_. `none` disables this behavior and performers can have multiple songs in the queue, `optional` gives the performer a notification, and they can decide for themselves, and `forced` puts them in the waiting room every time. Once the current song of a performer leaves the queue, the song from the waiting room will be added to the queue.
* `last_song`: `none` or a time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). When a song is added to the queue, and its ending time exceeds this value, it is rejected.
* `preview_duration`: Before every song, there is a short slide for the next performer. This sets how long it is shown in seconds.
* `key`: If the server, you want to connect to is in _private_ or _restricted_ mode, this will authorize the client. Private server reject unauthorized playback clients, restricted servers limit the searching to be _client only_.
* `buffer_in_advance`: How many songs should be buffered in advanced.
* `qr_box_size`: The size of one box (think pixel) of the QR Code in the playback window.
* `qr_position`: Position of the QR Code in the playback window. One of `bottom-left`, `bottom-right`, `top-left`, `top-right`.
* `show_advanced`: Show advanced options in the configuration GUI.
In addition to the general config, has its own configuration under the `sources` key of the configuration.
### YouTube
Configuration is done under `sources` → `youtube` with the following settings:
* `enabled`: `true` or `false`.
* `channels`: list of YouTube channels. If this is a nonempty list, Syng will only search these channels, otherwise YouTube will be searched as a whole.
* `tmp_dir`: YouTube videos will be downloaded before playback. This sets the directory, where YouTube videos are stored.
* `max_res`: Maximum resolution of a video.
* `start_streaming`: `true` or `false`. If `true`, videos will be streamed directly using `mpv`, if the video is not cached beforehand. Otherwise, Syng waits for the video to be downloaded.
### S3
Configuration is done under `sources` → `s3` with the following settings:
* `enabled`: `true` or `false`.
* `extensions`: List of extensions to be searched. For karaoke songs, that separate audio and video (e.g. CDG files), you can use `mp3+cdg` to signify, that the audio part is a `mp3` file and the video is a `cdg` file. For karaoke songs, that do not separate this (e.g. mp4 files), you can simply use `mp4`.
* `endpoint`: Endpoint of the s3.
* `access_key` Access key for the s3.
* `secret_key`: Secret key for the s3.
* `secure`: If `true` uses `ssl`, otherwise not.
* `bucket`: Bucket for the karaoke files.
* `index_file`: Cache file, that contains the filenames of the karaoke files in the s3.
* `tmp_dir`: Temporary download directory of the karaoke files.
### Files
Configuration is done under `sources` → `files` with the following settings:
* `enabled`: `true` or `false`.
* `extensions`: List of extensions to be searched. For karaoke songs, that separate audio and video (e.g. CDG files), you can use `mp3+cdg` to signify, that the audio part is a `mp3` file and the video is a `cdg` file. For karaoke songs, that do not separate this (e.g. mp4 files), you can simply use `mp4`.
* `dir`: Directory, where the karaoke files are stored.
### Default configuration
```
config:
key: ''
last_song: null
preview_duration: 3
room: <Random room code>
secret: <Random secret>
server: https://syng.rocks
waiting_room_policy: none
show_advanced: false
buffer_in_advance: 2
qr_box_size: 5
qr_position: bottom-right
sources:
files:
dir: .
enabled: false
extensions:
- mp3+cdg
s3:
access_key: ''
bucket: ''
enabled: false
endpoint: ''
extensions:
- mp3+cdg
index_file: ${XDG_CACHE_DIR}/syng/s3-index
secret_key: ''
secure: true
tmp_dir: ${XDG_CACHE_DIR}/syng
youtube:
channels: []
enabled: true
start_streaming: false
max_res: 720
tmp_dir: ${XDG_CACHE_DIR}/syng
```
# Server
If you want to host your own Syng server, you can do that, but you can also use the publicly available Syng instance at https://syng.rocks.
## Python Package Index
You can install the server via pip:
pip install 'syng[server]'
and then run via:
syng server
## Docker
Alternatively you can run the server using docker. It listens on port 8080 and reads a key file at `/app/keys.txt` when configured as private or restricted.
docker run --rm -v /path/to/your/keys.txt:/app/keys.txt -p 8080:8080 ghcr.io/christofsteel/syng -H 0.0.0.0
## Configuration
Configuration is done via command line arguments, see `syng server --help` for an overview.
## Public, Restricted, Private and keys.txt
Syng can run in three modes: public, restricted and private. This restricts which playback clients can start an event and what capabilities the event has.
This has no bearing on the web clients. Every web client, that has access to the room code can join the event.
Authorization is done via an entry in the `keys.txt`
- Public means, that there are no restrictions. Every playback client can start an event and has support for all features
- Restricted means, that every playback client can start an event, but server side searching is limited to authorized clients. For unauthorized clients, a search request is forwarded to the playback client, that handles that search.
- Private means, that only authorized clients can start an event.
The `keys.txt` file is a simple text file holding one `sha256` encrypted password per line. Passwords are stored as their hex value and only the first 64 characters per line are read by the server. You can use the rest to add comments.
To add a key to the file, you can simply use `echo -n "PASSWORD" | sha256sum | cut -d ' ' -f 1 >> keys.txt`.
Raw data
{
"_id": null,
"home_page": "https://syng.rocks",
"name": "syng",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "karaoke, youtube, web, audio, video, player, qt",
"author": "Christoph Stahl",
"author_email": "christoph.stahl@tu-dortmund.de",
"download_url": "https://files.pythonhosted.org/packages/29/94/a1807f74824fdd6a705d295a6008a9c3da01e1799762ee6933d8280ae68c/syng-2.1.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/christofsteel/syng/refs/heads/main/resources/icons/hicolor/512x512/apps/rocks.syng.Syng.png\"\n height=\"130\">\n\n_Easily host karaoke events_\n<p align=\"center\">\n\n[](https://matrix.to/#/#syng:matrix.org)\n[](https://floss.social/@syng)\n[](https://pypi.org/project/syng/)\n[](https://flathub.org/apps/rocks.syng.Syng)\n[](https://www.gnu.org/licenses/agpl-3.0.en.html)\n[](https://syng.rocks)\n[](https://git.k-fortytwo.de/christofsteel/syng2)\n\n\n**Syng** is an all-in-one karaoke software, consisting of a *backend server*, a *web frontend* and a *playback client*.\nKaraoke performers can search a library using the web frontend, and add songs to the queue.\nThe playback client retrieves songs from the backend server and plays them in order.\n\nYou can play songs from **YouTube**, an **S3** storage or simply share local **files**.\n\nThe playback client uses [mpv](https://mpv.io/) for playback and can therefore play a variety of file formats, such as `mp3+cdg`, `webm`, `mp4`, ...\n\nJoin our [matrix room](https://matrix.to/#/#syng:matrix.org) or follow us on [mastodon](https://floss.social/@syng) for update notifications and support.\n\n# Screenshots\n<img src=\"https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng.png\" alt=\"Main Window\" height=200/> <img src=\"https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_advanced.png\" alt=\"Main Window (Advanced)\" height=200/>\n\n<img src=\"https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_web2.png\" alt=\"Web Interface\" height=200/><img src=\"https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_mobile_search.png\" alt=\"Web Interface on Mobile\" height=200/> \n\n<img src=\"https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_player_next_up.png\" alt=\"Player (next up)\" height=200/> <img src=\"https://raw.githubusercontent.com/christofsteel/syng/94e0d9c0b77579ed256bf74412a20da314dd7166/resources/screenshots/syng_player_song.png\" alt=\"Player playing a song\" height=200/>\n\n# Client\n\n[](https://flathub.org/apps/rocks.syng.Syng)\n\nTo host a karaoke event, you only need to use the playback client. You can use the publicly available instance at https://syng.rocks as your server.\n\n## Installation\n\n### Linux\n\nThe preferred way to install the client is via [Flathub](https://flathub.org/apps/rocks.syng.Syng).\n\nAlternatively Syng can be installed via the _Python Package Index_ (PyPI). When installing the client it is mandatory to include the `client` flag:\n\n pip install 'syng[client]'\n\nThis installs both the playback client (`syng client`) and a configuration GUI (`syng gui`). \n\n**Note:** When installing via PyPI, you need to have [mpv](https://mpv.io/) installed on the playback client, and the `mpv` binary must be in your `PATH`.\n\n### Windows\n\nWindows support is experimental, but you can download the current version from [Releases](https://github.com/christofsteel/syng/releases). No installation necessary, you can just run the `exe`.\n\n\n## Configuration\n\nYou can host karaoke events using the default configuration. But if you need more advanced configuration, you can either configure Syng using the GUI or via a text editor by editing `~/.config/syng/config.yaml`. There are the following settings:\n\n * `server`: URL of the server to connect to.\n * `room`: The room code for your karaoke event. Can be chosen arbitrarily, but must be unique. Unused rooms will be deleted after some time. _Note:_ Everyone, that has access to the room code can join the karaoke event.\n * `secret`: The admin password for your karaoke event. If you want to reconnect with a playback client to a room, these must match. Additionally, this unlocks admin capabilities to a web client, when given under \"Advanced\" in the web client.\n * `waiting_room_policy`: One of `none`, `optional`, `forced`. When a performer wants to be added to the playback queue, but has already a song queued, they can be added to the _waiting room_. `none` disables this behavior and performers can have multiple songs in the queue, `optional` gives the performer a notification, and they can decide for themselves, and `forced` puts them in the waiting room every time. Once the current song of a performer leaves the queue, the song from the waiting room will be added to the queue.\n * `last_song`: `none` or a time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). When a song is added to the queue, and its ending time exceeds this value, it is rejected.\n * `preview_duration`: Before every song, there is a short slide for the next performer. This sets how long it is shown in seconds.\n * `key`: If the server, you want to connect to is in _private_ or _restricted_ mode, this will authorize the client. Private server reject unauthorized playback clients, restricted servers limit the searching to be _client only_.\n * `buffer_in_advance`: How many songs should be buffered in advanced.\n * `qr_box_size`: The size of one box (think pixel) of the QR Code in the playback window.\n * `qr_position`: Position of the QR Code in the playback window. One of `bottom-left`, `bottom-right`, `top-left`, `top-right`.\n * `show_advanced`: Show advanced options in the configuration GUI.\n\nIn addition to the general config, has its own configuration under the `sources` key of the configuration.\n\n### YouTube\n\nConfiguration is done under `sources` \u2192 `youtube` with the following settings:\n\n * `enabled`: `true` or `false`.\n * `channels`: list of YouTube channels. If this is a nonempty list, Syng will only search these channels, otherwise YouTube will be searched as a whole.\n * `tmp_dir`: YouTube videos will be downloaded before playback. This sets the directory, where YouTube videos are stored.\n * `max_res`: Maximum resolution of a video.\n * `start_streaming`: `true` or `false`. If `true`, videos will be streamed directly using `mpv`, if the video is not cached beforehand. Otherwise, Syng waits for the video to be downloaded. \n\n### S3\n\nConfiguration is done under `sources` \u2192 `s3` with the following settings:\n\n * `enabled`: `true` or `false`.\n * `extensions`: List of extensions to be searched. For karaoke songs, that separate audio and video (e.g. CDG files), you can use `mp3+cdg` to signify, that the audio part is a `mp3` file and the video is a `cdg` file. For karaoke songs, that do not separate this (e.g. mp4 files), you can simply use `mp4`.\n * `endpoint`: Endpoint of the s3.\n * `access_key` Access key for the s3.\n * `secret_key`: Secret key for the s3.\n * `secure`: If `true` uses `ssl`, otherwise not.\n * `bucket`: Bucket for the karaoke files.\n * `index_file`: Cache file, that contains the filenames of the karaoke files in the s3.\n * `tmp_dir`: Temporary download directory of the karaoke files.\n\n### Files\n\nConfiguration is done under `sources` \u2192 `files` with the following settings:\n\n * `enabled`: `true` or `false`.\n * `extensions`: List of extensions to be searched. For karaoke songs, that separate audio and video (e.g. CDG files), you can use `mp3+cdg` to signify, that the audio part is a `mp3` file and the video is a `cdg` file. For karaoke songs, that do not separate this (e.g. mp4 files), you can simply use `mp4`.\n * `dir`: Directory, where the karaoke files are stored. \n\n### Default configuration\n\n```\nconfig:\n key: ''\n last_song: null\n preview_duration: 3\n room: <Random room code>\n secret: <Random secret>\n server: https://syng.rocks\n waiting_room_policy: none\n show_advanced: false\n buffer_in_advance: 2\n qr_box_size: 5\n qr_position: bottom-right\n \nsources:\n files:\n dir: .\n enabled: false\n extensions:\n - mp3+cdg\n s3:\n access_key: ''\n bucket: ''\n enabled: false\n endpoint: ''\n extensions:\n - mp3+cdg\n index_file: ${XDG_CACHE_DIR}/syng/s3-index\n secret_key: ''\n secure: true\n tmp_dir: ${XDG_CACHE_DIR}/syng\n youtube:\n channels: []\n enabled: true\n start_streaming: false\n max_res: 720\n tmp_dir: ${XDG_CACHE_DIR}/syng\n```\n\n# Server\n\nIf you want to host your own Syng server, you can do that, but you can also use the publicly available Syng instance at https://syng.rocks.\n\n## Python Package Index\n\nYou can install the server via pip:\n\n pip install 'syng[server]'\n\nand then run via:\n\n syng server\n\n## Docker\n\nAlternatively you can run the server using docker. It listens on port 8080 and reads a key file at `/app/keys.txt` when configured as private or restricted.\n\n docker run --rm -v /path/to/your/keys.txt:/app/keys.txt -p 8080:8080 ghcr.io/christofsteel/syng -H 0.0.0.0\n\n## Configuration\n\nConfiguration is done via command line arguments, see `syng server --help` for an overview. \n\n## Public, Restricted, Private and keys.txt\n\nSyng can run in three modes: public, restricted and private. This restricts which playback clients can start an event and what capabilities the event has.\nThis has no bearing on the web clients. Every web client, that has access to the room code can join the event. \nAuthorization is done via an entry in the `keys.txt`\n\n - Public means, that there are no restrictions. Every playback client can start an event and has support for all features\n - Restricted means, that every playback client can start an event, but server side searching is limited to authorized clients. For unauthorized clients, a search request is forwarded to the playback client, that handles that search.\n - Private means, that only authorized clients can start an event.\n\nThe `keys.txt` file is a simple text file holding one `sha256` encrypted password per line. Passwords are stored as their hex value and only the first 64 characters per line are read by the server. You can use the rest to add comments.\nTo add a key to the file, you can simply use `echo -n \"PASSWORD\" | sha256sum | cut -d ' ' -f 1 >> keys.txt`.\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Easily host karaoke events",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://syng.rocks",
"Repository": "https://github.com/christofsteel/syng"
},
"split_keywords": [
"karaoke",
" youtube",
" web",
" audio",
" video",
" player",
" qt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0cb4825a934525942f8d23338c22e0b1226f4ca33afea59f880b7a9a49a00bc6",
"md5": "36818122053599d9fb2ef73a6eeff49a",
"sha256": "d1a5ad155034ff7e162cdea3345c1f1e9de50b6430b13f29d52a5a69846a8789"
},
"downloads": -1,
"filename": "syng-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36818122053599d9fb2ef73a6eeff49a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 1599736,
"upload_time": "2024-11-21T18:30:32",
"upload_time_iso_8601": "2024-11-21T18:30:32.362261Z",
"url": "https://files.pythonhosted.org/packages/0c/b4/825a934525942f8d23338c22e0b1226f4ca33afea59f880b7a9a49a00bc6/syng-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2994a1807f74824fdd6a705d295a6008a9c3da01e1799762ee6933d8280ae68c",
"md5": "dcc44213a43585077674b5c2bf3db289",
"sha256": "e71fc8a2618c568c903eba284bd68cdfa78ca1e1c4b2f2a7d03cb6734f619ea8"
},
"downloads": -1,
"filename": "syng-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "dcc44213a43585077674b5c2bf3db289",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 1586104,
"upload_time": "2024-11-21T18:30:35",
"upload_time_iso_8601": "2024-11-21T18:30:35.534481Z",
"url": "https://files.pythonhosted.org/packages/29/94/a1807f74824fdd6a705d295a6008a9c3da01e1799762ee6933d8280ae68c/syng-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-21 18:30:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "christofsteel",
"github_project": "syng",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "syng"
}
JSON
