# Sovereign > Sovereign is a self-hosted media server for streaming locally stored movies and TV series to any device over a network. ## Documentation - [Introduction](https://sovereign.watch/docs/introduction/): Sovereign is a self-hosted media server for streaming locally stored movies and TV series to multiple clients over a network - similar in purpose to Plex, Jellyfin, or Emby. - [Getting Started](https://sovereign.watch/docs/getting-started/): Sovereign hasn't had its first release yet, so there's nothing to download and no download links anywhere on this site. ## Configuration - [Overview](https://sovereign.watch/docs/configuration/overview/): You configure Sovereign's server through environment variables on the container. There's no settings page for them in the app. Values that aren't sensitive go in your compose file or manifest, and sensitive ones go in through your platform's secret mechanism. - [System Requirements](https://sovereign.watch/docs/configuration/system-requirements/): What you need to run Sovereign depends far more on how often it has to re-encode a title than on how many people are watching. The specs on this page size a server for five users. - [Docker Compose](https://sovereign.watch/docs/configuration/docker-compose/): This page runs Sovereign with Docker Compose. All configuration lives in two files: compose.yaml (non-sensitive, safe to commit) and sovereign.env (sensitive, never committed). - [Docker](https://sovereign.watch/docs/configuration/docker/): This page runs Sovereign with plain docker run. Docker Compose and Kubernetes have pages of their own. - [Kubernetes](https://sovereign.watch/docs/configuration/kubernetes/): On Kubernetes, every sensitive setting lives in a Secret resource and reaches the Deployment through secretKeyRef, so no sensitive values appear in the Deployment manifest itself. - [Production Hardening](https://sovereign.watch/docs/configuration/production-hardening/): Sovereign starts with no secrets configured: it generates the ones it needs on first run, so a first run works with nothing but a media path. Every one of those values is then written to your data volume and read back on each start, so a restart changes nothing. - [File System Layout](https://sovereign.watch/docs/configuration/file-system/): Everything Sovereign creates lives under a single directory, /sovereign-data, mounted from a volume you provide. Knowing what each directory holds, and how long its contents last, tells you what to back up, what's safe to delete, and what to size your storage for. - [NFS Media Storage](https://sovereign.watch/docs/configuration/nfs-media-storage/): NFS is a common way to hand Sovereign a media library that lives on a NAS rather than on the server itself. The mount options you choose decide whether a slow or unreachable share degrades gracefully or leaves playback and scans stuck until it comes back. Here's a starting set, and what each option buys you. - [Filesystem Media Sources](https://sovereign.watch/docs/configuration/filesystem-media-sources/): A filesystem media source is a directory of media files Sovereign scans itself, with no Radarr or Sonarr in front of it. Sovereign reads the title's identity from the folder and file names, looks it up on TMDb for its artwork and metadata, and imports the files exactly as it would an Arr one. A source holds either films or television, set by its MediaType. This page covers how to configure a source and how to name your files so each one is found. - [Playback Decisions](https://sovereign.watch/docs/configuration/playback-decisions/): Every time a title starts, Sovereign walks the same fixed sequence of steps to decide whether to send the file as it is (Direct Play), repackage it with some audio converted (Remux), or re-encode the video (Transcode). Its checks don't all fall the same way when they have nothing to go on: some let the copy through, and some refuse it. - [Transcoding](https://sovereign.watch/docs/configuration/transcoding/): Sovereign re-encodes as little as possible. Every time a title starts, it compares the source file against what the client says it can decode and picks the cheapest delivery that will play. It also records reasons for that choice, every way the stream differs from the file, and they're the first thing to check when a stream is heavier than you expected. - [Video Quality](https://sovereign.watch/docs/configuration/video-quality/): The Video Quality settings control how much visual detail Sovereign preserves when it has to transcode a stream, and the peak bandwidth that transcode is allowed to use. Together they let you trade picture quality against bandwidth and hardware load. - [Authentication](https://sovereign.watch/docs/configuration/authentication/): This page covers how to configure sign-in and the security model behind it, from how users authenticate to how media links are protected. - [Remote Access](https://sovereign.watch/docs/configuration/remote-access/): Putting an access layer in front of your Sovereign server means a request has to prove who sent it, or which network it came from, before it reaches the server at all. This page covers the two kinds in common use, what each one changes for the clients, and the bypass the Roku channel needs for artwork. - [Email](https://sovereign.watch/docs/configuration/email/): Sovereign can send email over SMTP, and uses it to tell administrators when something needs their attention. It's off by default, and stays off until you give it a server to send through. ## Metadata - [Overview](https://sovereign.watch/docs/metadata/overview/): For the media in your library, Sovereign generates three kinds of derived metadata: trickplay thumbnails, media images, and subtitle tracks. Background workers inside the server produce the thumbnails, the images and the image-based subtitle tracks; text subtitles are written by the stream you're watching. - [Trickplay Thumbnails](https://sovereign.watch/docs/metadata/trickplay/): Trickplay thumbnails are the seek previews: the small image that appears when you hover over or drag the playback scrubber. They belong to a specific media file, so each version of a title (e.g. different quality encodes) has its own set of sprites. - [Media Images](https://sovereign.watch/docs/metadata/media-images/): Media images (posters, backdrops, logos and similar artwork) come from your configured library managers during the library sync, and Sovereign downloads and converts them on demand: Radarr supplies movie artwork, Sonarr supplies TV series, season, and episode artwork, and cast/crew headshots come from TMDb. Titles imported from a filesystem media source take all of their artwork from TMDb. Unlike trickplay and subtitles, images belong to the media item itself (a movie or TV series) rather than any individual file, so all versions of a title share the same artwork. - [Subtitles](https://sovereign.watch/docs/metadata/subtitles/): Sovereign carries both kinds of embedded subtitle track through to the player, and they take different routes to get there. Text tracks (SRT, ASS/SSA) become native HLS subtitle tracks that any HLS-capable player discovers, lists and renders like broadcast captions. Image-based tracks (PGS, VOBSUB, DVB) carry pixels rather than words, so an HLS player can't render them and HLS can't carry them at all; those are turned into one image per caption and drawn over the video by the client itself. ## Hardware Acceleration - [Overview](https://sovereign.watch/docs/hardware-acceleration/overview/): Sovereign automatically uses GPU hardware codecs when they're available to the container. Detection and selection need no configuration; you only need to expose your GPU device to the container in the way your platform requires. - [NVIDIA](https://sovereign.watch/docs/hardware-acceleration/nvidia/): NVIDIA acceleration uses NVENC for hardware encoding and CUVID for hardware decoding. The NVIDIA Container Toolkit has to be installed on the host before you can expose a GPU to the container. - [Intel QSV](https://sovereign.watch/docs/hardware-acceleration/qsv/): Intel Quick Sync Video (QSV) is Intel's proprietary hardware video acceleration API, built on top of the Intel Media SDK (now oneVPL). QSV is Intel-only. The QSV runtime in the Sovereign image supports Tiger Lake (11th-generation Core) and newer Intel GPUs, integrated or discrete, including Alder Lake-N, Iris Xe and Arc. An older Intel iGPU fails the QSV probe; from Broadwell onwards it still transcodes on the GPU through VAAPI. - [VAAPI](https://sovereign.watch/docs/hardware-acceleration/vaapi/): VA-API (Video Acceleration API) is a Linux-only hardware acceleration interface supported by Intel and AMD GPUs. Sovereign uses VAAPI for a full hardware pipeline: decode and encode share the same device context, so there's no round trip through the CPU between stages. A downscale runs on the GPU too. Because every step has to run there, a transcode that needs a step VAAPI doesn't do on the GPU (padding the frame for a strict decoder, or deinterlacing an SDR source, where the software filter gives a cleaner picture) goes to the next option instead: Quick Sync on Intel, or the CPU. ## Licensing - [Overview](https://sovereign.watch/docs/licensing/overview/): Sovereign runs on your own hardware and keeps running whether or not it holds a license. An unlicensed server plays everything a licensed one plays, but it shows a licensing notice, and it can't use user backups, which need a purchased license. - [Pricing](https://sovereign.watch/docs/licensing/pricing/): Each license covers one server, and you buy it from that server's System > License page, as described in Getting a License. These are the plans on sale right now: - [Getting a License](https://sovereign.watch/docs/licensing/getting-a-license/): Everything about licensing a server happens on the server itself, in System > License: a free trial, a purchase, and managing the subscription afterwards. There's no account to create and nothing to sign in to. - [Moving a License](https://sovereign.watch/docs/licensing/moving/): A license belongs to one server at a time, and moving it happens on the servers involved, in System > License. With the old server still running, a transfer code does it. With the old server gone, the email address you paid with does. - [Your License Data](https://sovereign.watch/docs/licensing/your-data/): Export Your Data on a server's License page downloads everything the licensing service holds about the license that server holds, as a single JSON file. It holds the records we keep about that license, and the rest of this page lists what's left out and why. ## Troubleshooting - [Overview](https://sovereign.watch/docs/troubleshooting/overview/): When an app shows an error, the code under the message is the quickest way in. Error Codes lists every code with its likely cause and what to do. - [Error Codes](https://sovereign.watch/docs/troubleshooting/error-codes/): When something goes wrong, every Sovereign app shows a short sentence and a code beneath it, such as Error PLAY-201. This page lists every code, what usually causes it and what you can do about it. ## Interface - [Overview](https://sovereign.watch/docs/interface/overview/): Sovereign serves its library to more than one kind of client. They all talk to the same server, so your library, watch progress, favorites, and account settings follow you between them. - [Overview](https://sovereign.watch/docs/interface/web/overview/): The web interface is what you get by browsing to your Sovereign server. It's where you browse and stream your library and run the server, and this section covers each of its pages. - [Home](https://sovereign.watch/docs/interface/web/home/): The home page is your landing spot after signing in. It shows what's new and what's airing across your library. - [Library](https://sovereign.watch/docs/interface/web/movies/library/): The movies library lists every movie in your collection as a poster grid. The tabs across the top (Movies, Trending, New Releases, Collections, and Genres) switch between different ways of browsing your movies. - [Movie Details](https://sovereign.watch/docs/interface/web/movies/movie-details/): The movie details page shows everything Sovereign knows about a title, and is the starting point for playback. - [Collections](https://sovereign.watch/docs/interface/web/movies/collections/): Collections group the movies in your library by film series, so a trilogy and its sequels sit together. Open the list from the Collections tab of the movies library. - [Genres](https://sovereign.watch/docs/interface/web/movies/genres/): The Genres tab of the movies library breaks the catalog down by genre. - [Library](https://sovereign.watch/docs/interface/web/tv-series/library/): The TV series library lists every show in your collection as a poster grid, with the same browsing tools as the movies library: an alphabet jump bar, infinite scrolling, and a Filters panel for searching by title and narrowing by genre, a range of years, and content rating. - [Series Details](https://sovereign.watch/docs/interface/web/tv-series/series-details/): The series details page has a show's artwork, metadata, and full episode list. - [Episode Details](https://sovereign.watch/docs/interface/web/tv-series/episode-details/): The episode details page is the TV equivalent of the movie details page. - [Library](https://sovereign.watch/docs/interface/web/people/library/): The people library lists everyone credited on a movie in your collection, as a grid of headshots with the number of movies each appears in. Only movie credits count, so your TV series don't add anyone here. The chips across the top switch between All, Actors and Directors. - [Person Details](https://sovereign.watch/docs/interface/web/people/person-details/): A person's page carries their headshot and biography above their filmography, split by what they did on each film. - [Favorites](https://sovereign.watch/docs/interface/web/favorites/): Favorites collects the movies, TV series, and collections you've starred. - [Search](https://sovereign.watch/docs/interface/web/search/): The Search page finds anything in the library from a single term. Open it from the magnifying glass on the navigation rail. - [Video Player](https://sovereign.watch/docs/interface/web/video-player/): Pressing Play anywhere in the interface opens the full-screen video player. - [User Settings](https://sovereign.watch/docs/interface/web/user-settings/): Open the account menu (your avatar at the foot of the rail, or in the top-right corner on a phone) and choose User Settings to manage your account and see your own activity and device details. The page has six tabs: Profile, Preferences, Stats, Activity, Client Profile, and Privacy. - [Device Pairing](https://sovereign.watch/docs/interface/web/device-pairing/): The Pair a Device page signs a TV or other remote-control device in to your account by having you type a short code, so you never have to spell out a password with a D-pad. - [Overview](https://sovereign.watch/docs/interface/web/admin/overview/): The Overview page of Admin Settings is the server dashboard. The queue status updates live, so you can watch background work as it happens, and a connection indicator beside it confirms live updates are flowing. - [Active Streams](https://sovereign.watch/docs/interface/web/admin/active-streams/): The Active Streams page shows everyone currently streaming media from the server, live. - [Analytics](https://sovereign.watch/docs/interface/web/admin/analytics/): The Analytics page summarizes how the server is being used and what the library contains. A window selector (7, 30, or 90 days) scopes the usage sections. - [Activity Logs](https://sovereign.watch/docs/interface/web/admin/activity-logs/): The Activity Logs page records user-level events such as logins, logouts, and media playback, so you can audit who did what, and when. - [Media Sources](https://sovereign.watch/docs/interface/web/admin/media-sources/): The Media Sources page lists every media source registered with Sovereign (your Radarr and Sonarr instances, and any directories Sovereign scans itself) along with their current health. - [Jobs](https://sovereign.watch/docs/interface/web/admin/jobs/): The Jobs page lists every scheduled background job on the server and its recent run history. - [Playback Simulator](https://sovereign.watch/docs/interface/web/admin/playback-simulator/): The Playback Simulator page tells you whether a device would direct play a title before anyone presses play, by working out the decision a real start would make without starting a stream. - [Users](https://sovereign.watch/docs/interface/web/admin/users/): The Users page is where you manage every account on the server. - [Clients](https://sovereign.watch/docs/interface/web/admin/clients/): The Clients page lists every device that has connected to this server, who signed in on it, and what it can play. - [Client Errors](https://sovereign.watch/docs/interface/web/admin/client-errors/): The Client Errors page collects problems the web, Roku and Android clients ran into, so a viewer saying "it didn't work" turns into something you can act on. - [Configuration](https://sovereign.watch/docs/interface/web/admin/configuration/): The Configuration page lists the server's current runtime settings in a single table, sorted by environment variable name. Each row names the variable exactly as you'd set it, so you can copy it straight into your compose file or environment. - [Email](https://sovereign.watch/docs/interface/web/admin/email/): The Email page shows the SMTP relay this server sends through, lets you prove it works with a test message, and lists every message the server has sent. It sits under System in the admin menu. - [GPU / Codecs](https://sovereign.watch/docs/interface/web/admin/gpu-capabilities/): The GPU Capabilities page (GPU / Codecs in the admin menu) reports the results of the hardware-acceleration probe that runs at server startup: which encoders, decoders and filters your GPU can run, which complete encode paths work end to end, and the software path a transcode falls back to. - [FFmpeg](https://sovereign.watch/docs/interface/web/admin/ffmpeg/): The FFmpeg page describes the FFmpeg build this server ships with and everything compiled into it. It sits under System in the admin menu, beside GPU / Codecs. - [Logs](https://sovereign.watch/docs/interface/web/admin/logs/): The Logs page shows the server's log output as it happens, along with the log files it has kept, for troubleshooting. - [License](https://sovereign.watch/docs/interface/web/admin/license/): The License page shows the license this server holds and is where you start a trial, buy a license, or move one here. It sits under System in the admin menu, beside Backup & Restore. - [Backup & Restore](https://sovereign.watch/docs/interface/web/admin/backup/): The Backup & Restore page exports this server's accounts and license to a single archive, and restores one. It sits under System in the admin menu, beside License, because a backup carries the license as well as the users. - [Overview](https://sovereign.watch/docs/interface/roku/overview/): The Roku channel brings your Sovereign library to the TV. It mirrors the web interface's look and feel, and everything on your account (watch progress, favorites, preferences) follows you between the two. - [Home](https://sovereign.watch/docs/interface/roku/home/): The Home screen is your landing spot after the channel starts. It shows what's new and what you're in the middle of watching. - [Library](https://sovereign.watch/docs/interface/roku/movies/library/): The Movies library lists every movie in your collection as a poster grid. The tabs on the title row switch between ways of browsing the catalog: All, Trending, New Releases, and Collections. - [Movie Details](https://sovereign.watch/docs/interface/roku/movies/movie-details/): The Movie Details screen shows everything Sovereign knows about a title, and it's where playback starts. - [Collections](https://sovereign.watch/docs/interface/roku/movies/collections/): The Collections tab of the Movies library groups movies into their film series, each card showing the collection artwork and how many of its movies you have. - [Genres](https://sovereign.watch/docs/interface/roku/movies/genres/): On the channel, you browse movies by genre from the Genres row of the filter pane. The Movies library has no separate Genres tab. - [Library](https://sovereign.watch/docs/interface/roku/tv-series/library/): The TV Series library lists every series in your collection as a poster grid, with each card showing the series poster, name, and first-air date. - [Series Details](https://sovereign.watch/docs/interface/roku/tv-series/series-details/): The Series Details screen shows the series poster, genres, synopsis, and metadata, with the episode browser below. - [Episode Details](https://sovereign.watch/docs/interface/roku/tv-series/episode-details/): The Episode Details screen shows a single episode: its still, season and episode number, air date, runtime, and synopsis, with the name of its series above the title. - [Favorites](https://sovereign.watch/docs/interface/roku/favorites/): The Favorites screen collects everything you've starred, with tabs for Movies, TV Series, and Collections. - [Video Player](https://sovereign.watch/docs/interface/roku/video-player/): Pressing Play anywhere in the channel opens the full-screen video player. The overlay appears when you pause or press OK, and hides itself while you watch. - [Account](https://sovereign.watch/docs/interface/roku/account/): The Account screen opens from your avatar at the foot of the rail. It covers your profile and preferences on the device. - [Overview](https://sovereign.watch/docs/interface/android/overview/): The Android apps bring your Sovereign library to phones, tablets and Android-based TVs. Like the Roku channel, they cover browsing, playback, favorites and your own account, and everything on your account follows you between clients. - [Browsing](https://sovereign.watch/docs/interface/android/browsing/): The Android apps share one set of library screens. The TV apps lay them out for the remote and the Mobile app for touch, but the content of each screen is the same. - [Video Player](https://sovereign.watch/docs/interface/android/video-player/): Pressing Play anywhere in the Android apps opens the full-screen video player. The controls appear when you need them and hide while you watch. - [Account](https://sovereign.watch/docs/interface/android/account/): The Account screen holds your profile, playback preferences, viewing statistics, recent activity and version details. Open it from your avatar: at the foot of the rail on the TV apps, or at the top right of any screen on Mobile. ## Legal - [Privacy Policy](https://sovereign.watch/docs/privacy-policy/): This policy covers the three services Sovereign Media LLC runs for Sovereign, the licensing service, the metadata service and the download service, and this documentation site. It also describes what the self-hosted Sovereign software stores and sends, which we don't receive. - [Terms of Use](https://sovereign.watch/docs/terms-of-use/): These terms are an agreement between you and Sovereign Media LLC ("we", "us"), which runs the Sovereign licensing service and publishes the official Sovereign client applications. They cover your use of the client applications for web, Roku, Android, Google TV and Fire TV, and of the licensing service at account.sovereign.watch, including any trial or license you obtain from it.