| Name | webp3 JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Music player web app |
| upload_time | 2024-06-07 11:38:05 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3 |
| license | None |
| keywords |
audio
html5
music
player
server
web
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# What is WebP3? (use case)
WebP3 is a humble web-app (server) to play your audio files remotely.
Typically, you host WebP3 on your personal home machine (or server) where your music files sit, and you can then listen to the music remotely at your workplace or on a handheld device in your browser.
It's designed for personal use.
No, there aren't any user-data-exploiting/social features and no, it's not hosted on some million-dollars cloud, it's hosted on your machine or your server.
## Design
WebP3 exposes a tree of folders and files that can be browsed through the web interface.
A few root directories are specified on the command-line to run WebP3, and all the content under those roots is simply exposed on the web interface, as there are no fine-grained permissions.
An HTML5 player allows to play the audio files from a requested dir.
It is designed to serve trees where a folder is an album (or contains other folders). ID3 is not necessary as it's not used.
### Audio format support
WebP3 solely relies on HTML5's `<audio>` tag. So, audio file format support (like MP3) depends on your viewing browser and OS.
### JSON
When `application/json` mimetype is present in the `Accept` HTTP header, the listing of the browsed directory is returned in JSON format.
### M3U
When `audio/x-mpegurl` mimetype is present in the `Accept` HTTP header, or if the URL ends with `?m3u`, the listing of files the browsed directory is returned in M3U playlist format.
Thus, the URL can be given to an audio player like VLC.
## Usage
### Podman/Docker
WebP3 can be run as a container:
podman run --rm -d \
-e WEBP3_BASE_URL=https://your.example/webp3/ \
-v /path/to/some/files:/media:ro \
-p 8000:8000 \
registry.gitlab.com/hydrargyrum/webp3
If you want to have several music directories that are not under the same parent dir, add several volumes to `/media` subdirectories:
podman run --rm -d -v /path/to/some/files:/media/first:ro -v /another/folder/to/share:/media/second:ro -p 8000:8000 registry.gitlab.com/hydrargyrum/webp3
### Standalone server
First, run something like:
webp3.py -p 8000 music=/path/to/some/files music2=/another/folder/to/share
The command will not terminate, the files are served as long as WebP3 is running.
Open <http://localhost:8000> to see (and play!) the music.
There will be 2 roots, /music and /music2, serving respectively the full content of /path/to/some/files and /another/folder/to/share.
Command-line flags:
-p PORT
WebP3 will listen on port (default: 8000)
#### Single root
If it's not needed to have multiple roots, it's possible to run instead
webp3.py -p 8000 --single-root /path/to/some/files
### WSGI
WebP3 can be set up to run as a WSGI app, for example to be served by an existing Apache instance.
When using WSGI, the mappings that were passed on command-line should now be placed in a `webp3.conf` file, with one `NAME=PATH` entry per line.
Using the documented script in the `apache` folder, the installation is as follows:
* the WebP3 code and WSGI is typically in a path like /usr/lib/python3/dist-packages/webp3
* the Apache configuration is in /etc/apache2/sites-available/webp3.conf
* the WebP3 config indicating the locations of the music files is at /etc/webp3.conf
Using an Apache instance to run the WebP3 WSGI allows:
* HTTPS
* serving the music tree under an URL prefix
If not using the default location, the config file can be passed in env variable `WEBP3_CONF`.
## Dependencies
WebP3 is written in Python 3 and uses:
* [Bottle web framework](https://bottlepy.org/)
* [Mako templates](https://www.makotemplates.org/)
## Security
WebP3 does not write files. However, it gives access to all files and folders contained in directories specified in its configuration.
Therefore, directory containing sensitive data should not be put in its configuration.
WebP3 does not have by itself any authentication mechanism to restrict access to its content.
If this is desired a proxy should be used, or access can be configured in an existing WSGI server (like Apache).
WebP3 reads files with the process' permissions. For example, if using WSGI, WebP3 will likely read files with the `www-data` user's permissions.
WebP3 does not follow symlinks.
## Install
On [PyPI](https://pypi.org/project/webp3/):
pipx install webp3
## License
WebP3 is licensed under the [do What The Fuck you want Public License v2](https://wtfpl.net).
Raw data
{
"_id": null,
"home_page": null,
"name": "webp3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "audio, html5, music, player, server, web",
"author": null,
"author_email": "Hg <dev@indigo.re>",
"download_url": "https://files.pythonhosted.org/packages/c2/6d/ac0008728846fbec9e411b0a5a18e006a7133751e41f1a5d77f10922d965/webp3-1.1.0.tar.gz",
"platform": null,
"description": "# What is WebP3? (use case)\n\nWebP3 is a humble web-app (server) to play your audio files remotely.\n\nTypically, you host WebP3 on your personal home machine (or server) where your music files sit, and you can then listen to the music remotely at your workplace or on a handheld device in your browser.\nIt's designed for personal use.\n\nNo, there aren't any user-data-exploiting/social features and no, it's not hosted on some million-dollars cloud, it's hosted on your machine or your server.\n\n## Design\n\nWebP3 exposes a tree of folders and files that can be browsed through the web interface.\nA few root directories are specified on the command-line to run WebP3, and all the content under those roots is simply exposed on the web interface, as there are no fine-grained permissions.\n\nAn HTML5 player allows to play the audio files from a requested dir.\n\nIt is designed to serve trees where a folder is an album (or contains other folders). ID3 is not necessary as it's not used.\n\n\n\n### Audio format support\n\nWebP3 solely relies on HTML5's `<audio>` tag. So, audio file format support (like MP3) depends on your viewing browser and OS.\n\n### JSON\n\nWhen `application/json` mimetype is present in the `Accept` HTTP header, the listing of the browsed directory is returned in JSON format.\n\n### M3U\n\nWhen `audio/x-mpegurl` mimetype is present in the `Accept` HTTP header, or if the URL ends with `?m3u`, the listing of files the browsed directory is returned in M3U playlist format.\nThus, the URL can be given to an audio player like VLC.\n\n## Usage\n\n### Podman/Docker\n\nWebP3 can be run as a container:\n\n podman run --rm -d \\\n -e WEBP3_BASE_URL=https://your.example/webp3/ \\\n -v /path/to/some/files:/media:ro \\\n -p 8000:8000 \\\n registry.gitlab.com/hydrargyrum/webp3\n\nIf you want to have several music directories that are not under the same parent dir, add several volumes to `/media` subdirectories:\n\n podman run --rm -d -v /path/to/some/files:/media/first:ro -v /another/folder/to/share:/media/second:ro -p 8000:8000 registry.gitlab.com/hydrargyrum/webp3\n\n### Standalone server\n\nFirst, run something like:\n\n\twebp3.py -p 8000 music=/path/to/some/files music2=/another/folder/to/share\n\nThe command will not terminate, the files are served as long as WebP3 is running.\n\nOpen <http://localhost:8000> to see (and play!) the music.\n\nThere will be 2 roots, /music and /music2, serving respectively the full content of /path/to/some/files and /another/folder/to/share.\n\nCommand-line flags:\n\n\t-p PORT\n\nWebP3 will listen on port (default: 8000)\n\n#### Single root\n\nIf it's not needed to have multiple roots, it's possible to run instead\n\n webp3.py -p 8000 --single-root /path/to/some/files\n\n### WSGI\n\nWebP3 can be set up to run as a WSGI app, for example to be served by an existing Apache instance.\nWhen using WSGI, the mappings that were passed on command-line should now be placed in a `webp3.conf` file, with one `NAME=PATH` entry per line.\n\nUsing the documented script in the `apache` folder, the installation is as follows:\n\n* the WebP3 code and WSGI is typically in a path like /usr/lib/python3/dist-packages/webp3\n* the Apache configuration is in /etc/apache2/sites-available/webp3.conf\n* the WebP3 config indicating the locations of the music files is at /etc/webp3.conf\n\nUsing an Apache instance to run the WebP3 WSGI allows:\n\n* HTTPS\n* serving the music tree under an URL prefix\n\nIf not using the default location, the config file can be passed in env variable `WEBP3_CONF`.\n\n## Dependencies\n\nWebP3 is written in Python 3 and uses:\n\n* [Bottle web framework](https://bottlepy.org/)\n* [Mako templates](https://www.makotemplates.org/)\n\n## Security\n\nWebP3 does not write files. However, it gives access to all files and folders contained in directories specified in its configuration.\nTherefore, directory containing sensitive data should not be put in its configuration.\n\nWebP3 does not have by itself any authentication mechanism to restrict access to its content.\nIf this is desired a proxy should be used, or access can be configured in an existing WSGI server (like Apache).\n\nWebP3 reads files with the process' permissions. For example, if using WSGI, WebP3 will likely read files with the `www-data` user's permissions.\nWebP3 does not follow symlinks.\n\n## Install\n\nOn [PyPI](https://pypi.org/project/webp3/):\n\n\tpipx install webp3\n\n## License\n\nWebP3 is licensed under the [do What The Fuck you want Public License v2](https://wtfpl.net).\n",
"bugtrack_url": null,
"license": null,
"summary": "Music player web app",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://gitlab.com/hydrargyrum/webp3"
},
"split_keywords": [
"audio",
" html5",
" music",
" player",
" server",
" web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea6b25866a40f99fe189e0906a5bdac2398cca2a4a9d42cecfa0579c52a192b1",
"md5": "d10d628a67f49a7536823aa516f35363",
"sha256": "7473f1eb999c40cb9d53f4b163bab5f82badb5e2af20dccaf5ce4a5dcc7c5bf3"
},
"downloads": -1,
"filename": "webp3-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d10d628a67f49a7536823aa516f35363",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 17504,
"upload_time": "2024-06-07T11:38:03",
"upload_time_iso_8601": "2024-06-07T11:38:03.373114Z",
"url": "https://files.pythonhosted.org/packages/ea/6b/25866a40f99fe189e0906a5bdac2398cca2a4a9d42cecfa0579c52a192b1/webp3-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c26dac0008728846fbec9e411b0a5a18e006a7133751e41f1a5d77f10922d965",
"md5": "864f441154549bf2bff616f2dbe72ae6",
"sha256": "c7e3bc14b67e04dd47507b37b7fb97f52123e6edcad6894924b685c8a049d1f9"
},
"downloads": -1,
"filename": "webp3-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "864f441154549bf2bff616f2dbe72ae6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 13001,
"upload_time": "2024-06-07T11:38:05",
"upload_time_iso_8601": "2024-06-07T11:38:05.547510Z",
"url": "https://files.pythonhosted.org/packages/c2/6d/ac0008728846fbec9e411b0a5a18e006a7133751e41f1a5d77f10922d965/webp3-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-07 11:38:05",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "hydrargyrum",
"gitlab_project": "webp3",
"lcname": "webp3"
}
