home-stream 0.3.0

Browser and streaming interface for local media files

Home Stream

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.

Features

• Browse local folders and media files
• Secure user login
• In-browser audio/video player (if supported by your browser)
• HTTP Basic Auth fallback for external players (VLC, mpv, etc.) using authenticated links
• Lightweight and dependency-minimal Python Flask app

Installation

Minimum Python version: 3.10

Install and run via pipx (Recommended)

pipx makes installing and running Python programs easier and avoids conflicts with other packages. Install it with

pip3 install pipx

The following one-liner both installs and runs this program from PyPI:

pipx run home-stream

If you want to be able to use the application without prepending it with pipx run every time, install it globally like so:

pipx install home-stream

The 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.

To upgrade the application to the newest available version, run this command:

pipx upgrade home-stream

Other installation methods

You may also use pure pip or poetry to install this package.

Configuration

Create a config.yaml file in the project root. You can derive your configuration from config.sample.yaml.

Passwords must be bcrypt-hashed. You can generate them using Python:

import bcrypt
print(bcrypt.hashpw(b"your-password", bcrypt.gensalt()).decode())

or by using online tools like bcrypt-generator.com, although not recommended for production passwords.

Usage

Start the app (session login + streaming):

home-stream -c config.yaml  # uses Flask development server

Log in via browser, by default on localhost:8000. Browse and play media, or copy permanent stream URLs.

For productive use, consider using uWSGI. However, note that streaming many and large chunks of files may trigger issues with apps like gunicorn. It is planned for this project to document practical solutions soon.

Usage Scenarios

The 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.

For this, you may put this application behind a reverse proxy or make it accessible via a VPN connection. This application and the documentation does not help to set this up.

Of course, you can also use it purely locally, although there are probably better tools to administrate your media files.

License

This project is licensed under the terms of the GPL-3.0-only license, but contains elements under different licenses.