{"id":27883308,"url":"https://github.com/mxmehl/home-stream","last_synced_at":"2025-06-28T20:07:34.659Z","repository":{"id":285625738,"uuid":"958798625","full_name":"mxmehl/home-stream","owner":"mxmehl","description":"A web-based browser and streaming interface for local media files. Supports in-browser playback, HTTP Basic Auth streaming (e.g. VLC), and user-based login with permanent stream URLs","archived":false,"fork":false,"pushed_at":"2025-06-18T16:46:10.000Z","size":478,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-18T17:42:44.293Z","etag":null,"topics":["flask","media","music","python","stream","video"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxmehl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-01T19:26:57.000Z","updated_at":"2025-06-18T16:46:12.000Z","dependencies_parsed_at":"2025-04-01T19:52:08.094Z","dependency_job_id":"72e64516-35ac-4db6-ab6e-e7e0d8ec3d8e","html_url":"https://github.com/mxmehl/home-stream","commit_stats":null,"previous_names":["mxmehl/home-stream"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/mxmehl/home-stream","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Fhome-stream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Fhome-stream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Fhome-stream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Fhome-stream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxmehl","download_url":"https://codeload.github.com/mxmehl/home-stream/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Fhome-stream/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260605254,"owners_count":23035318,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flask","media","music","python","stream","video"],"created_at":"2025-05-05T06:14:48.363Z","updated_at":"2025-06-28T20:07:34.628Z","avatar_url":"https://github.com/mxmehl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2025 Max Mehl \u003chttps://mehl.mx\u003e\n\nSPDX-License-Identifier: GPL-3.0-only\n--\u003e\n\n# Home Stream\n\n[![Test suites](https://github.com/mxmehl/home-stream/actions/workflows/test.yaml/badge.svg)](https://github.com/mxmehl/home-stream/actions/workflows/test.yaml)\n[![REUSE status](https://api.reuse.software/badge/github.com/mxmehl/home-stream)](https://api.reuse.software/info/github.com/mxmehl/home-stream)\n[![The latest version of this application can be found on PyPI.](https://img.shields.io/pypi/v/home-stream.svg)](https://pypi.org/project/home-stream/)\n[![Information on what versions of Python this application supports can be found on PyPI.](https://img.shields.io/pypi/pyversions/home-stream.svg)](https://pypi.org/project/home-stream/)\n\nA web-based browser and streaming interface for local media files. Supports in-browser playback, HTTP Basic Auth streaming (e.g. VLC), and user-based login with permanent stream URLs.\n\n## Features\n\n- Browse local folders and media files\n- Secure user login\n- In-browser audio/video player (if supported by your browser)\n- HTTP Basic Auth fallback for external players (VLC, mpv, etc.) using authenticated links\n- Lightweight and dependency-minimal Python Flask app\n\n## Installation\n\nMinimum Python version: 3.10\n\n### Install and run via pipx (Recommended)\n\n[pipx](hhttps://pipx.pypa.io/) makes installing and running Python programs easier and avoids conflicts with other packages. Install it with\n\n```sh\npip3 install pipx\n```\n\nThe following one-liner both installs and runs this program from [PyPI](https://pypi.org/project/home-stream/):\n\n```sh\npipx run home-stream\n```\n\nIf you want to be able to use the application without prepending it with `pipx run` every time, install it globally like so:\n\n```sh\npipx install home-stream\n```\n\nThe application will then be available in `~/.local/bin`, which must be added to your `$PATH`. So make sure that `~/.local/bin` is in your `$PATH`. On Windows, the required path for your environment may look like `%USERPROFILE%\\AppData\\Roaming\\Python\\Python310\\Scripts`, depending on the Python version you have installed. Recent pipx versions allow you to do this via `pipx ensurepath`.\n\nTo upgrade the application to the newest available version, run this command:\n\n```sh\npipx upgrade home-stream\n```\n\n### Other installation methods\n\nYou may also use pure `pip` or `poetry` to install this package.\n\n## Configuration\n\nCreate a `config.yaml` file in the project root. You can derive your configuration from [`config.sample.yaml`](./config.sample.yaml).\n\nPasswords must be **bcrypt-hashed**. You can generate them using Python:\n\n```python\nimport bcrypt\nprint(bcrypt.hashpw(b\"your-password\", bcrypt.gensalt()).decode())\n```\n\nor by using online tools like [bcrypt-generator.com](https://bcrypt-generator.com/), although not recommended for production passwords.\n\n## Usage\n\nStart the app (session login + streaming):\n\n```bash\nhome-stream -c config.yaml  # uses Flask development server\n```\n\nLog in via browser, by default on [localhost:8000](http://localhost:8000). Browse and play media, or copy permanent stream URLs.\n\n### Production Webserver\n\nFor productive use, you should use a proper webserver. Streaming many and large chunks of files may trigger issues with apps like gunicorn, so uWSGI is officially supported.\n\nFor a quick start, run `poetry run uwsgi --ini uwsgi.ini`. Using the docker image [`ghcr.io/mxmehl/home-stream`](https://github.com/mxmehl/home-stream/pkgs/container/home-stream) you would have everything contained into one container, ready to be use locally or behind a reverse proxy. Note that depending on your use-cases, you may want to reconfigure some uwsgi settings. This currently would need to be done manually.\n\n### Usage Scenarios\n\nThe application is mainly designed with the use-case of running it on a NAS or home server with direct media access to allow accessing your media files remotely.\n\nFor this, you may put this application behind a reverse proxy or make it accessible via a VPN connection.\n\nOf course, you can also use it purely locally, although there are probably better tools to administrate your media files.\n\n## License\n\nThis project is licensed under the terms of the **GPL-3.0-only** license, but contains elements under different licenses.\n\nThe project is [REUSE compliant](https://reuse.software), so licensing and copyright information is available for every single file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxmehl%2Fhome-stream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxmehl%2Fhome-stream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxmehl%2Fhome-stream/lists"}