homehost: A Self-Hosted Media Streamer That Depends on Filename Metadata

The Problem homehost Solves Is Metadata, Not Streaming

Serving files over a home network is a solved problem. What is not solved is turning a directory of video files into a browsable catalogue with posters, genres, popularity rankings and search. homehost attacks that second problem. The README describes it as made for streaming your media collection within the home network, and the feature list is short: movies, TV shows, music. The interesting part is what sits behind those three words. The server exposes routes such as /api/movies/most_popular, /api/movies/highest_rated, /api/movies/genres and /api/music/albums/recently_added. Those are catalogue queries, not file listings. The intended user is someone who already has a local library and wants a Netflix-shaped interface over it, on a machine that stays inside the LAN. The topics list confirms the scope: self-hosted, streaming, tmdb, spotify, node, react. It is not a downloader, not a torrent client, and not a remote-access platform.

Filename Conventions Are the Metadata Layer

This is the design decision that determines whether homehost is usable for you. The README specifies exact naming conventions per media type. Movies follow <movies_path> with an optional subdirectory and a file named <movie_file_name <TMDb-movie-ID>> with an .mp4 or .mkv extension. TV shows follow a directory named <tv_show_directory_name <TMDb-tv-show-ID>> containing files named S<season_number>E<episode_number> episode_file_name. Music follows an album directory named <album_directory_name <Spotify-album-ID>> containing tracks named with an optional disc number and a track number. The TMDb or Spotify identifier is not a hint. It is the join key between your filesystem and the external API that supplies artwork, genres and popularity. There is one escape hatch: tracks not found on Spotify can be placed in a directory titled Unknown Album without disc or track numbers. That is the only documented path for media that has no external ID, and it applies to music only. The README also states that each media item must be in a unique location and cannot share the same directory path. This is a hard constraint, not a preference, and it means you cannot point two entries at one folder.

Setup: Two Env Files, One Migration, One Start Command

Installation is a single command, npm run install-packages. Configuration is split across two .env files. The client file packages/client/.env needs REACT_APP_HOMEHOST_BASE, REACT_APP_IMAGE_BASE and REACT_APP_IMDB_BASE. The server file packages/server/.env needs TMDB_KEY, SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, MOVIES_PATH, TV_PATH, MUSIC_PATH, DATABASE_URL and CLIENT_BASE_URL. The README gives concrete values for all of these, including DATABASE_URL = 'file:./data/media.db' and CLIENT_BASE_URL = 'http://localhost:3000'. Database setup is npm run db:migrate, which the README says creates migrations from the schema, applies them and generates the database client. After that, homehost scans the media paths and adds the files to the database. That scan is asynchronous, and the README tells you to wait for the job to finish generating metadata and saving. A separate command, npm run db:browse, opens a browser view at http://localhost:5555 for inspecting the data, and npm run db:clear wipes it. Running the app is npm run start, with server on port 5000 and client on port 3000, or npm run start:prod with a default port of 5000. While running, the README states that homehost continuously saves and retrieves information for any media that was added, moved or removed. That continuous reconciliation is the part worth understanding before you trust it with a large library.

Where homehost Breaks Down

The naming convention is the failure mode. Any file that does not carry a TMDb or Spotify ID in the expected position will not resolve to metadata, and the README offers no documented fallback for movies or TV, only the Unknown Album directory for music. If your library was assembled by a download client that writes release-group names, you are looking at a rename pass across the entire collection before homehost is useful. The second constraint is the uniqueness rule. Media cannot share directory paths, which rules out symlink-heavy layouts where the same file is exposed under multiple logical names. Third, the README says development works best in Chrome and lists Desktop, iOS and Android as coming, which is a plain statement that the client is a browser app without native clients today. Fourth, the setup requires two external API credentials before the app will show you anything. If you object to sending your library's identifiers to TMDb and Spotify, this is the wrong tool. The README does not describe an offline metadata mode. The release history also matters: the most recent release listed is 1.9.2 from October 2022, while the last push is dated 2026. The gap between tagged releases and commits is something to check yourself rather than assume.

How It Differs From a General-Purpose Media Server

The obvious comparison is Jellyfin, which is the reference open source media server. The difference is where metadata comes from. Jellyfin and similar servers attempt to match your files against metadata providers using fuzzy title parsing, folder structure heuristics and manual correction in the admin UI, and they let you override a wrong match. homehost inverts this. The identifier is written into the path by you, so matching is exact by construction and there is no reconciliation UI described in the README. That removes an entire class of ambiguity and removes the correction workflow along with it. The second difference is scope. A general media server typically handles live TV, DVR, transcoding profiles and user accounts. homehost's documented routes are catalogue and playback paths: /movies/:id, /tv/:tv_show_id/:season_number/:episode_number, /music/:album_id/:disc_number/:track_number, plus search endpoints /api/watch/search and /api/listen/search and a /api/watch/billboard route. Nothing in the README describes transcoding, user accounts or remote access. If you want those, the identifier-in-filename approach is not the trade-off you are making; you are choosing a different category of tool.

Licence and Maintenance Cost

homehost is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive and imposes no copyleft obligation on your own code. Two things sit outside the licence and deserve separate attention. The first is the README's disclaimer, which is a fair-use statement about images and a takedown commitment, and which states plainly that you may not use the service for any illegal or unauthorized purpose and must not violate copyright or trademark law in your jurisdiction. That is a statement about your obligations as the operator of the library, not a grant of rights over the media. The second is the dependency on TMDb and Spotify APIs. Their terms govern your use of their endpoints, and the README directs you to request authorization from each. A licence review of homehost itself tells you nothing about whether your use of those APIs is permitted. On maintenance: the repository is not archived, and the last push is recent relative to the release tags. Upgrading means re-running npm run db:migrate when the schema changes, and because the database is a local SQLite file at the path you set in DATABASE_URL, a migration failure is recoverable by restoring that file. npm run db:clear exists if you would rather rebuild from a rescan.

Who Should Adopt homehost

Adopt it if you control your filenames and are willing to enforce the conventions. The payoff is a catalogue that is correct by construction rather than correct by heuristics. Adopt it if your library is movies, TV and music and you do not need live TV, DVR or transcoding profiles. Adopt it if you are comfortable creating TMDb and Spotify API credentials and putting those keys in packages/server/.env. Do not adopt it if your collection is large and inconsistently named, because the rename work scales linearly with library size and the README documents no bulk-matching tool. Do not adopt it if you need remote access outside the home network, since nothing in the supplied material describes authentication or exposure beyond the LAN. Do not adopt it if you want a native mobile client today. The first thing to verify is small: create one movie directory and one music album directory following the naming rules exactly, run npm run db:migrate, wait for the scan to finish, then open npm run db:browse at http://localhost:5555 and confirm the rows carry the metadata you expect. If that works, the rest of the library is a naming exercise. If it does not, the problem is in the filenames, and no amount of configuration will fix it.

Editorial conclusion

Adopt homehost if your media is already organised with TMDb and Spotify IDs in folder and file names and you want a browser UI over a home network without a large media server stack. Do not adopt it if your library uses arbitrary filenames or if you need remote access, since the README describes a home-network tool with no authentication layer mentioned. Before committing, verify that npm run db:migrate completes against a small test directory and that the async metadata job finishes, because that job is the point at which the filename convention either works or fails.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. ridhwaans/homehost on GitHub