Streama: a self hosted streaming server for your own video files

What Streama solves, and who it is actually for

The README opens with the problem in plain terms: a large shelf of shows and movies, and no good way to organise the digitised copies. Streama answers that with a web application that presents your own video files as a browsable catalogue with cover art, seasons, episodes and a watch position. It is not a source of content. Nothing in the repository fetches media; the media comes from you, either uploaded through the admin panel or referenced from a local directory you already have mounted.

The intended user is someone running their own hardware who wants the Netflix interaction model over files they own. The README describes the player as heavily inspired by Netflix, with a next episode button, an episode and season browser, volume control, play and pause, and fullscreen. The episode browser is called out specifically: it shows every episode that has been added, including ones with no video file, which appear greyed out. That detail matters because it means the catalogue can be built ahead of the files.

It is the wrong tool for anyone who wants a hosted service, a mobile app as the primary client, or a system that acquires media for them. It is also a poor fit if you have no interest in metadata curation, because the whole admin workflow is built around pulling information and images from theMovieDatabase.org.

How Streama works: Grails, AngularJS and theMovieDb

The repository layout tells you most of the architecture. There is a grails-app directory and a gradle wrapper, so the server side is Grails on the JVM, with build.gradle and gradle.properties at the top level. There is a bower.json and a src directory, and the README describes the player as HTML5-based, so the client is a browser application. The primary language listed for the repository is JavaScript, which reflects how much of the interface lives in the front end.

The data flow has three inputs. First, settings: an upload directory, a theMovieDb API key, and optionally a different base URL for remote hosting. Second, metadata: the admin panel uses the theMovieDatabase.org API to auto-fill episodes, shows and movies with information and images, which the README says eases the user's role in adding content. Third, files: either uploaded by drag and drop, or referenced through the local file feature.

Resume tracking is described as a periodic database update that runs only while a video is playing, recording which video is being watched and how far. That is why the dashboard can show recently watched shows and movies with progress, and why a movie or episode with no video files will not appear on the dashboard at all. The catalogue and the playable set are two different things, and only the playable set reaches the dashboard.

Installing Streama and setting it up for the first time

The README does not carry installation steps inline. It points to a single page, Installation and first-time setup, under docs.streama-project.com/getting-started/installing/, and it lists stable and beta builds on the GitHub releases page. The repository also contains a docker directory and a .dockerignore, so a container path exists in the tree, but the README text provided does not document the commands, so treat the docs page as the authority rather than copying anything from a blog post.

The first real use is the settings page. On first run the application redirects you there, and you enter the upload directory, your theMovieDb.org API key, and a base URL if you are hosting remotely. The README is explicit that you must validate each value before saving. Validation for the API key calls theMovieDb.org to check it is valid; validation for the upload directory checks that the application has read and write permission on it.

After the settings validate, the next step is adding content. Creating a TV show pulls the show and its first-season episodes from theMovieDb, and uploading a file for an episode is drag and drop. If you would rather not upload, define a local directory in settings and use the local file browser from any movie or TV show, or the bulk-create feature, which the README notes does not require the TV show to exist beforehand.

The local file path is the feature that decides your setup

Uploading every file is the obvious workflow, and it is the one the admin panel is built around. The local file feature is the one that changes how you would deploy Streama. You define a local directory, and the README gives the author's own example: a directory containing symlinks to mounted drives. From there you can pick files individually through the local file browser, reachable from any movie or TV show wherever you would otherwise upload, or use bulk-create from file.

This matters because it separates the storage question from the application. If your library already lives on a NAS or a set of mounts, the local directory is a pointer, not a copy. The constraint is that the directory must be defined in settings first, and, given that the upload directory is validated for read and write access, you should expect the same class of permission check to matter for anything the application touches on disk. A directory the Streama process cannot read is a directory the browser will not show you.

The bulk-create path is also the answer to a common objection about manual cataloguing. The README states that the TV show does not have to be present in order to use it, which means you can point Streama at a directory of episodes and let it create the structure rather than building the show by hand first.

Where Streama falls short, by its own documentation

The README is unusually candid about gaps, and they are worth taking at face value. The player is HTML5-based and, in the README's words, has only really been tested in Chrome. If your household watches in Safari, Firefox or on a television browser, you are outside the tested path.

Subtitles are not there. The README says that a feature to add subtitles and to switch between video files, for instance between different quality uploads, will come later down the road. If subtitle support is a requirement for your library, Streama as documented does not meet it, and no amount of configuration will add it.

The dashboard has a rule that surprises people: a movie or episode with no video files does not show up there. The episode browser deliberately shows greyed-out episodes without files, but the dashboard does not. So a carefully built catalogue of unwatched, un-ripped content is invisible on the page most users open first.

Finally, the dependency on theMovieDb.org is structural, not cosmetic. The API key is validated against that service at setup time, and the admin panel leans on it to auto-fill shows, movies and episodes. If you want a catalogue with no external metadata service involved, the admin workflow as described is not designed for you.

Streama compared with a plain file server or a media front end

The obvious alternative is not another media server. It is a plain file share plus a video player, or a lightweight web front end over a directory listing. The difference in approach is where the state lives. A file server has no notion of a season, no watch position, and no cover art; the browser is a directory listing and the player is whatever the client provides. Streama moves that state into an application database, which is exactly what makes continue-watching and the episode browser possible, and exactly what makes the setup heavier.

That trade-off is the honest way to choose. If all you need is to play a file from another room, a share and a player cost you nothing to maintain. Streama earns its complexity only when you want the catalogue behaviour: metadata and images pulled from theMovieDb, episodes grouped by season, greyed-out entries for content you have not added yet, and a resume point that survives closing the tab. The README's own framing, your own personal Netflix, is a statement about the interface, not about the storage.

A second comparison is against uploading into a hosted platform. Streama keeps the files on your hardware and the catalogue in your database, with no upload to a third party beyond the metadata requests to theMovieDb. If data locality is the reason you are self hosting, Streama's local file feature is the part that lets you keep it.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-08-09. Releases are not on a fixed cadence: v1.11.0 arrived on 2026-01-02, v1.10.6 on 2025-12-18, and v1.10.5 on 2023-10-29, which is a gap of more than two years between v1.10.5 and the next tagged release. Anyone planning an upgrade path should read the CHANGELOG.md in the repository rather than assume a schedule, because the tag history does not show one.

The upgrade cost is tied to the stack. A Grails application with a Gradle build and a Bower-managed front end means your deployment has to account for the JVM side and the built client assets, and the docker directory is the place to look if you want the container route. Before upgrading, check whether your database schema and your settings still validate, since the settings page performs live checks against theMovieDb and against the upload directory.

The licence is MIT, per the repository's LICENSE.md and the licence badge in the README. In practical terms that is a permissive licence, which is relevant because Streama is a server you run yourself rather than a service you subscribe to. It says nothing about the terms of theMovieDb's API, which you accept separately when you register for a key. That is not legal advice; read both texts if the distinction matters to you.

Editorial conclusion

Adopt Streama if you already hold a local library of movie and TV files and want a browser player with resume tracking, and you are willing to run a Grails application and supply a theMovieDb API key. Do not adopt it if you need a managed service, a mobile-first client, or subtitle support, since the README states subtitle switching is a future feature and the player is HTML5-based and has only really been tested in Chrome. Before committing, verify that the upload directory passes the read/write validation in the settings page and that your deployment path matches the installation page at docs.streama-project.com.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. streamaserver/streama on GitHub