README
¶
Beyond the static library.
One self-hosted binary that speaks the Plex Media Server protocol—combining a rich metadata catalogue, zero-FUSE Usenet streaming, and a Home screen that learns every viewer's taste.
Stop babysitting a nine-container stack of scanners, symlink farms, FUSE mounts, request portals, and YAML overlay scripts.
Ether is an independent, self-hosted media server written in pure Go (CGO_ENABLED=0) that connects directly to official Plex client apps—Apple TV, iOS, Android TV, Smart TVs, and Plex Web. Instead of requiring pre-extracted local files on a hard drive or brittle virtual filesystem mounts, Ether pairs a TMDB-backed metadata catalogue with your own Usenet providers and Newznab indexers, shapes every shelf around the individual viewer, and resolves and streams media on demand the moment someone presses Play.
No external request portal. No waiting for a full archive extraction or library scan. Open your existing client app, browse or search, and play.
Why Ether Feels Different
1. Native Catalogue & Metadata Engine
Traditional setups force viewers into a separate web portal to queue jobs and wait for a filesystem scan before an item can be browsed. Ether serves metadata, artwork, franchises, and smart collections natively to your client apps—complete with verified plex:// cloud identities, UltraBlurColors, clearLogos, cast/crew, custom episode ordering (DVD, absolute, story arc), and optional IMDb, Rotten Tomatoes, Metacritic, and Letterboxd poster badges.
2. Zero-FUSE, Zero-Download Streaming Engine
When a viewer hits Play, Ether queries your configured indexers, ranks candidates against your quality profiles and custom formats, verifies article health over NNTP (including mid-file BODY yEnc probes), and opens the stream in seconds:
- Direct byte-offset indexing across Usenet: Maps byte ranges straight to NNTP article IDs across plain posts and store-mode RAR4, RAR5, and 7z multi-volume archives in memory—without extracting to disk or mounting FUSE.
- Instant 4K seeking: Jumping to
01:00:00reads the container's MP4stss/sidxor MatroskaCueskeyframe index and fetches only the exact articles for that timestamp over warm, priority-scheduled NNTP connection pools. - Self-healing mid-stream failover: If articles are missing mid-stream, Ether automatically switches to an alternate source, aligns the playhead by timestamp (accounting for keyframe cues, subtitle dialogue timing, and 25 fps PAL speedup), and transitions playback without dropping the viewer's session.
3. A Home Screen That Actually Learns Each Viewer
Standard media servers show the same static shelves to every account. Ether runs a Netflix-style contextual personalization engine behind /hubs:
- Per-viewer taste models: Learns signed affinities across genres, keywords, directors, actors, decades, franchises, and languages from completions, rewatches, early abandons, ratings, Trakt history, and impression fatigue.
- Contextual bandit row ranking: Uses Thompson sampling blended with device class, time of day, and weekday/weekend session habits (Short on Time lifts on weeknight phones; long-form features and franchises lift on weekend evening TVs) with Maximal Marginal Relevance (MMR) diversity so one franchise never floods a row.
- Home Designer & Collection Studio: Pin, schedule, or restrict rows globally or per viewer with live preview, and build rule-driven or Trakt/Letterboxd/MDBList-backed collections that mix movies and TV in a single shelf.
4. Built for Every Device and Player Quirk
- Play Version picker: Detail pages expose distinct release tiers—Automatic, 4K Dolby Vision / HDR10, 1080p High Compatibility, or Director's / Extended Cut—right inside the client's native Play Version menu.
- Descriptive & natural search: Search "90s thrillers under 100 mins" or "cozy rainy-day sci-fi" inside the native search bar; Ether returns matching titles plus an instant generated collection you can save by rating it.
- Adaptive HLS & MPEG-DASH transcoding: Hardware-accelerated encoding (
VideoToolbox,NVENC,QuickSync,VAAPI), on-demand ABR ladders, goodput-steered VBV reservoirs, and a VBR spike governor for copy streams. - Skip Intro, Skip Credits & Trickplay: Container chapters, TheIntroDB lookup, piecewise subtitle auto-sync, and progressive
.bifscrubbing thumbnails generated on the fly. - Cinema Trailers & pre-warming: While a trailer plays—or as an episode nears its credits—Ether resolves and pre-warms the feature or next episode in the background so playback starts in sub-second time.
- Live TV & Virtual Channels: Assemble 24/7 virtual broadcast channels from your collections and genres, or proxy M3U playlists and XMLTV guides directly into the native Live TV grid.
One Binary vs. The Multi-Container Stack
| Capability | Traditional Stack | Ether |
|---|---|---|
| Client Protocol & Server API | Plex Media Server | Built in (internal/plex, internal/plextv) |
| Release Selection & Profiles | Radarr + Sonarr | Built in (internal/resolver, on-demand at Play) |
| Indexer Management | Prowlarr | Built in (internal/newznab, automatic service-limit handling) |
| Usenet Streaming & Archive Indexing | SABnzbd / NZBGet / AltMount + rclone FUSE | Built in (internal/usenet, internal/stream, internal/archive) |
| Catalogue & Watchlist Sync | Overseerr / Jellyseerr | Built in (internal/catalog, internal/watchlist) |
| Collections & Poster Overlays | Kometa (PMM) | Built in (internal/collections, internal/overlays) |
| Personalized Home Rows | Not supported | Built in (internal/personalize taste & bandit engine) |
| Virtual Live TV Channels | ErsatzTV / Tunarr / Threadfin | Built in (internal/livetv) |
| Analytics & Notifications | Tautulli + Notifiarr | Built in (internal/stats, internal/notify) |
Quick Start
Download the macOS app, Windows installer, or Linux packages from the Releases page. Docker images are published to ghcr.io/braedonsaunders/ether. Check the release notes for platform requirements and signing status.
Docker
docker run -d --name ether --restart unless-stopped \
--network host \
-v /path/to/config:/config \
-v /path/to/cache:/cache \
ghcr.io/braedonsaunders/ether:latest
Build from Source
CGO_ENABLED=0 go build -o ether ./cmd/ether
./ether
Once Ether is running, open http://localhost:32400/ether/ to sign in, add your personal TMDB API key, Usenet providers, and Newznab indexers, and configure viewer access. Ether supports both automatic *.plex.direct TLS certificates and custom HTTPS domains behind your own reverse proxy.
See the Installation Guide, the User Guide, and the Product & Architecture Specification.
Support
For a bug report, include your Ether version, operating system, client app and version, what you did, and what happened. Remove credentials and personal details from any logs you attach.
Legal, Trademarks and Services
Ether is an independent, clean-room open-source software project. It ships no media content, no Usenet providers, no indexers, no site definitions, no accounts, and no embedded third-party API keys. Owners supply their own accounts and credentials and are solely responsible for the content they access and compliance with applicable laws and service terms.
"Plex" is a registered trademark of Plex, Inc. "TMDB" and "The Movie Database" are trademarks of their respective owners. Ether is not affiliated with, sponsored by, or endorsed by Plex, Inc. or TMDB. All third-party product and service names are used solely to describe protocol interoperability. See LEGAL.md.
Licensed under the GNU General Public License v3.0. Third-party notices.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ether
command
Command ether runs the Ether server: a Plex Media Server-compatible front end over a TMDB catalogue, streaming from Usenet on demand.
|
Command ether runs the Ether server: a Plex Media Server-compatible front end over a TMDB catalogue, streaming from Usenet on demand. |
|
ether-livebench
command
Command ether-livebench measures time-to-playable against real services: it resolves a title over the owner's indexers and Usenet providers, opens it, reads the first bytes, seeks, and probes it.
|
Command ether-livebench measures time-to-playable against real services: it resolves a title over the owner's indexers and Usenet providers, opens it, reads the first bytes, seeks, and probes it. |
|
ether-release-sign
command
Command ether-release-sign manages Ether's release-signing keys and signs update manifests.
|
Command ether-release-sign manages Ether's release-signing keys and signs update manifests. |
|
ether-tray
command
Command ether-tray is Ether's tray / menu-bar companion: it shows server status, opens the web UI, starts/stops the service, checks the signed update feed (notify only: the server installs updates itself) and can launch at login.
|
Command ether-tray is Ether's tray / menu-bar companion: it shows server status, opens the web UI, starts/stops the service, checks the signed update feed (notify only: the server installs updates itself) and can launch at login. |
|
pmsdiff
command
pmsdiff records and compares Plex Media Server HTTP responses.
|
pmsdiff records and compares Plex Media Server HTTP responses. |
|
internal
|
|
|
admin
Package admin is Ether's owner-facing HTTP surface: the JSON API under /ether/api/ and the embedded React SPA (setup wizard, dashboard, settings, logs, resolver traces) served under /ether/.
|
Package admin is Ether's owner-facing HTTP surface: the JSON API under /ether/api/ and the embedded React SPA (setup wizard, dashboard, settings, logs, resolver traces) served under /ether/. |
|
app
Package app wires Ether's components into one running server: the Plex front end and the owner UI on one port, and the background services (catalogue sync, plex.tv registration, prefetch, LAN discovery) behind it.
|
Package app wires Ether's components into one running server: the Plex front end and the owner UI on one port, and the background services (catalogue sync, plex.tv registration, prefetch, LAN discovery) behind it. |
|
archive
Package archive reads the headers of RAR (4.x and 5.x) and 7z archives and maps each inner file onto byte ranges (extents) of the archive volumes, so that store-mode (uncompressed, unencrypted) members can be streamed straight out of the volumes without extracting anything.
|
Package archive reads the headers of RAR (4.x and 5.x) and 7z archives and maps each inner file onto byte ranges (extents) of the archive volumes, so that store-mode (uncompressed, unencrypted) members can be streamed straight out of the volumes without extracting anything. |
|
archive/archivetest
Package archivetest builds small RAR 4.x / RAR 5.0 archives (and Copy-mode 7z archives) for tests.
|
Package archivetest builds small RAR 4.x / RAR 5.0 archives (and Copy-mode 7z archives) for tests. |
|
artwork
Package artwork serves and makes Ether's artwork: a caching proxy for TMDB images (memory LRU over a disk cache) and a pure-Go poster generator for collections (collage and backdrop treatments with the title set in the Go fonts).
|
Package artwork serves and makes Ether's artwork: a caching proxy for TMDB images (memory LRU over a disk cache) and a pure-Go poster generator for collections (collage and backdrop treatments with the title set in the Go fonts). |
|
auth
Package auth implements core.Auth: it maps the X-Plex-Token a Plex app presents to an Ether user, and keeps the users table with per-user settings (stream limit, content rating cap, languages, sections).
|
Package auth implements core.Auth: it maps the X-Plex-Token a Plex app presents to an Ether user, and keeps the users table with per-user settings (stream limit, content rating cap, languages, sections). |
|
backup
Package backup creates integrity-checked, portable snapshots without copying live WAL files.
|
Package backup creates integrity-checked, portable snapshots without copying live WAL files. |
|
cardigann
Package cardigann runs owner-supplied indexer definitions written in the Cardigann YAML format (the format Prowlarr and Jackett use for their built-in sites).
|
Package cardigann runs owner-supplied indexer definitions written in the Cardigann YAML format (the format Prowlarr and Jackett use for their built-in sites). |
|
catalog
Package catalog implements core.Catalog: a SQLite mirror of a filtered TMDB slice plus on-demand fetches for anything else.
|
Package catalog implements core.Catalog: a SQLite mirror of a filtered TMDB slice plus on-demand fetches for anything else. |
|
cluster
Package cluster is Ether's multi-node runtime: node identity, liveness heartbeats, leader election and a small cross-node event bus.
|
Package cluster is Ether's multi-node runtime: node identity, liveness heartbeats, leader election and a small cross-node event bus. |
|
clusterbus
Package clusterbus is the small surface components use to take part in a cluster: publishing and receiving events on the cluster bus, knowing their own node ID and which nodes are alive, and dropping in-memory caches when another node writes the shared database (Invalidator).
|
Package clusterbus is the small surface components use to take part in a cluster: publishing and receiving events on the cluster bus, knowing their own node ID and which nodes are alive, and dropping in-memory caches when another node writes the shared database (Invalidator). |
|
clusterconfig
Package clusterconfig keeps the settings and identity material that the nodes of an Ether cluster share in the owner's PostgreSQL database:
|
Package clusterconfig keeps the settings and identity material that the nodes of an Ether cluster share in the owner's PostgreSQL database: |
|
collections
Package collections is Ether's collection engine.
|
Package collections is Ether's collection engine. |
|
config
Package config is Ether's owner-editable settings, stored as JSON in the data directory.
|
Package config is Ether's owner-editable settings, stored as JSON in the data directory. |
|
core
Package core holds the domain types and the interfaces between Ether's components.
|
Package core holds the domain types and the interfaces between Ether's components. |
|
debrid
Package debrid streams torrent releases through owner-configured debrid services (Real-Debrid, TorBox, AllDebrid, Premiumize).
|
Package debrid streams torrent releases through owner-configured debrid services (Real-Debrid, TorBox, AllDebrid, Premiumize). |
|
episodeorder
Package episodeorder provides presentation-only TV ordering.
|
Package episodeorder provides presentation-only TV ordering. |
|
extras
Package extras lists and resolves trailers and other clips attached to catalogue titles (Plex "Extras" and Cinema Trailers).
|
Package extras lists and resolves trailers and other clips attached to catalogue titles (Plex "Extras" and Cinema Trailers). |
|
faillog
Package faillog logs a repeating background failure (a heartbeat or sync loop that cannot reach the database) without flooding the log: the first failure is logged at WARN, later ones are summarised at most once per interval, and the recovery is logged once at INFO.
|
Package faillog logs a repeating background failure (a heartbeat or sync loop that cannot reach the database) without flooding the log: the first failure is logged at WARN, later ones are summarised at most once per interval, and the recovery is logged once at INFO. |
|
invites
Package invites implements expiring invitations with account-bound redemption.
|
Package invites implements expiring invitations with account-bound redemption. |
|
livetv
Package livetv implements owner-defined virtual channels and IPTV playout.
|
Package livetv implements owner-defined virtual channels and IPTV playout. |
|
llm
Package llm is an optional OpenAI-compatible chat client (Ollama, LM Studio, OpenAI, …) used for natural-language recommendation rows: "more like this" for a title and themed rows from a user's history ("Slow-burn sci-fi with a twist").
|
Package llm is an optional OpenAI-compatible chat client (Ollama, LM Studio, OpenAI, …) used for natural-language recommendation rows: "more like this" for a title and themed rows from a user's history ("Slow-burn sci-fi with a twist"). |
|
logfile
Package logfile provides Ether's on-disk logs: a size-rotated log file (stderr is discarded under a Windows service and unrotated under launchd) and the crash log that receives fatal runtime traces.
|
Package logfile provides Ether's on-disk logs: a size-rotated log file (stderr is discarded under a Windows service and unrotated under launchd) and the crash log that receives fatal runtime traces. |
|
markers
Package markers supplies release-duration-specific skip ranges.
|
Package markers supplies release-duration-specific skip ranges. |
|
migrate
Package migrate performs read-only PMS discovery and reviewed, idempotent local imports.
|
Package migrate performs read-only PMS discovery and reviewed, idempotent local imports. |
|
newznab
Package newznab implements core.Indexer against Newznab-compatible Usenet indexers, with per-indexer daily budgets and a result cache.
|
Package newznab implements core.Indexer against Newznab-compatible Usenet indexers, with per-indexer daily budgets and a result cache. |
|
notify
Package notify provides durable, rule-filtered owner notifications.
|
Package notify provides durable, rule-filtered owner notifications. |
|
nzb
Package nzb parses NZB documents: the XML index of a Usenet post that lists every file, its newsgroups and the message IDs of its segments (articles).
|
Package nzb parses NZB documents: the XML index of a Usenet post that lists every file, its newsgroups and the message IDs of its segments (articles). |
|
overlays
Package overlays creates truthful, versioned poster variants in pure Go.
|
Package overlays creates truthful, versioned poster variants in pure Go. |
|
par2
Package par2 parses the metadata packets of PAR2 2.0 files.
|
Package par2 parses the metadata packets of PAR2 2.0 files. |
|
par2/par2test
Package par2test builds PAR2 2.0 metadata packets and index files for tests.
|
Package par2test builds PAR2 2.0 metadata packets and index files for tests. |
|
personalize
Package personalize is Ether's Netflix-style personalization engine.
|
Package personalize is Ether's Netflix-style personalization engine. |
|
playback
Package playback implements core.Playback: it binds a user, a client and a title to a resolved, open release, enforces stream limits, serves the source to clients (direct play) and to ffmpeg (a loopback HTTP server), fails over to another release mid-stream when articles go missing, and protects the releases of live and in-progress titles in the segment cache.
|
Package playback implements core.Playback: it binds a user, a client and a title to a resolved, open release, enforces stream limits, serves the source to clients (direct play) and to ffmpeg (a loopback HTTP server), fails over to another release mid-stream when articles go missing, and protects the releases of live and in-progress titles in the segment cache. |
|
plex
Package plex is Ether's Plex Media Server front end: the HTTP API that official Plex apps (Web, iOS, Apple TV, Android, TVs) talk to.
|
Package plex is Ether's Plex Media Server front end: the HTTP API that official Plex apps (Web, iOS, Apple TV, Android, TVs) talk to. |
|
plex/model
Package model holds the Plex Media Server response models and the encoder that renders one model as either PMS-style XML or PMS-style JSON.
|
Package model holds the Plex Media Server response models and the encoder that renders one model as either PMS-style XML or PMS-style JSON. |
|
plexguid
Package plexguid maps verified external identities through Plex's metadata provider.
|
Package plexguid maps verified external identities through Plex's metadata provider. |
|
plextv
Package plextv is Ether's plex.tv client: PIN sign-in, server claim, connection publishing, resources, shared users and their server access tokens, and plex.direct certificates.
|
Package plextv is Ether's plex.tv client: PIN sign-in, server claim, connection publishing, resources, shared users and their server access tokens, and plex.direct certificates. |
|
pmsconform
Package pmsconform captures and compares the HTTP surface exposed by Plex Media Servers.
|
Package pmsconform captures and compares the HTTP surface exposed by Plex Media Servers. |
|
prefetch
Package prefetch warms the segment cache in the background so the next episode and the resume point of in-progress titles start instantly.
|
Package prefetch warms the segment cache in the background so the next episode and the resume point of in-progress titles start instantly. |
|
ratings
Package ratings caches licensed, owner-keyed rating data.
|
Package ratings caches licensed, owner-keyed rating data. |
|
recommend
Package recommend supplies detail-page related rows.
|
Package recommend supplies detail-page related rows. |
|
releaseparse
Package releaseparse parses scene and P2P release names into core.ReleaseInfo.
|
Package releaseparse parses scene and P2P release names into core.ReleaseInfo. |
|
remote
Package remote handles Ether's network presence: LAN address enumeration, WAN IP detection, Plex connection URIs (plain IP and *.plex.direct), UPnP IGD and NAT-PMP port mapping, GDM LAN discovery and reachability probes.
|
Package remote handles Ether's network presence: LAN address enumeration, WAN IP detection, Plex connection URIs (plain IP and *.plex.direct), UPnP IGD and NAT-PMP port mapping, GDM LAN discovery and reachability probes. |
|
resolver
Package resolver implements core.Resolver: it turns a catalogue title plus client capabilities into a health-checked release.
|
Package resolver implements core.Resolver: it turns a catalogue title plus client capabilities into a health-checked release. |
|
safety
Package safety persists owner policy and enforces it at Plex request boundaries.
|
Package safety persists owner policy and enforces it at Plex request boundaries. |
|
segcache
Package segcache is Ether's on-disk cache of decoded Usenet segments.
|
Package segcache is Ether's on-disk cache of decoded Usenet segments. |
|
service
Package service runs Ether as an operating-system service: systemd on Linux, launchd on macOS and the Service Control Manager on Windows, via github.com/kardianos/service.
|
Package service runs Ether as an operating-system service: systemd on Linux, launchd on macOS and the Service Control Manager on Windows, via github.com/kardianos/service. |
|
spike
Package spike serves a handful of local video files as a Plex library so the Plex front end (internal/plex) can be tested against official Plex apps before the Usenet engine exists.
|
Package spike serves a handful of local video files as a Plex library so the Plex front end (internal/plex) can be tested against official Plex apps before the Usenet engine exists. |
|
spike/cmd/ether-spike
command
Command ether-spike serves local video files through Ether's Plex front end, for testing official Plex apps (and pmsdiff) before the Usenet engine is wired in.
|
Command ether-spike serves local video files through Ether's Plex front end, for testing official Plex apps (and pmsdiff) before the Usenet engine is wired in. |
|
state
Package state implements per-user watch state and playlists over SQLite: core.State and core.Playlists.
|
Package state implements per-user watch state and playlists over SQLite: core.State and core.Playlists. |
|
stats
Package stats records owner analytics from observed playback and provider data.
|
Package stats records owner analytics from observed playback and provider data. |
|
store
Package store opens Ether's database and applies each component's migrations.
|
Package store opens Ether's database and applies each component's migrations. |
|
stream
Package stream is Ether's stream engine: it turns an NZB into a seekable core.MediaSource without writing the full file anywhere.
|
Package stream is Ether's stream engine: it turns an NZB into a seekable core.MediaSource without writing the full file anywhere. |
|
subtitles
Package subtitles fetches missing subtitle languages from OpenSubtitles and serves them as external (sidecar) tracks.
|
Package subtitles fetches missing subtitle languages from OpenSubtitles and serves them as external (sidecar) tracks. |
|
tmdb
Package tmdb is a TMDB API v3 client with rate limiting, retries, request coalescing and an ETag/TTL response cache.
|
Package tmdb is a TMDB API v3 client with rate limiting, retries, request coalescing and an ETag/TTL response cache. |
|
trackprefs
Package trackprefs persists viewer stream policy and show-specific choices.
|
Package trackprefs persists viewer stream policy and show-specific choices. |
|
trakt
Package trakt is the optional per-user Trakt integration: OAuth device flow sign-in, scrobbling Ether watch events to Trakt, and pulling Trakt history / recommendations / watchlist back in as recommendation sources.
|
Package trakt is the optional per-user Trakt integration: OAuth device flow sign-in, scrobbling Ether watch events to Trakt, and pulling Trakt history / recommendations / watchlist back in as recommendation sources. |
|
transcode
Package transcode wraps Ether's bundled ffmpeg: discovery, hardware encoder detection, probing, the direct play / remux / transcode decision and HLS and MPEG-DASH sessions.
|
Package transcode wraps Ether's bundled ffmpeg: discovery, hardware encoder detection, probing, the direct play / remux / transcode decision and HLS and MPEG-DASH sessions. |
|
updater
Package updater implements Ether's signed self-update feed.
|
Package updater implements Ether's signed self-update feed. |
|
usenet
Package usenet is Ether's Usenet layer: an NNTP client, per-provider connection pools with priority scheduling and circuit breakers, and a multi-provider fetcher that implements core.ArticleFetcher with primary-first ordering and backfill from block accounts.
|
Package usenet is Ether's Usenet layer: an NNTP client, per-provider connection pools with priority scheduling and circuit breakers, and a multi-provider fetcher that implements core.ArticleFetcher with primary-first ordering and backfill from block accounts. |
|
usenet/nntptest
Package nntptest provides an in-memory NNTP server for tests across Ether: articles keyed by message-id (yEnc-encoded on the way in), optional AUTHINFO, TLS, missing articles, latency, a connection limit and fault injection, plus Post, which uploads files as multipart yEnc segments and returns a matching NZB document.
|
Package nntptest provides an in-memory NNTP server for tests across Ether: articles keyed by message-id (yEnc-encoded on the way in), optional AUTHINFO, TLS, missing articles, latency, a connection limit and fault injection, plus Post, which uploads files as multipart yEnc segments and returns a matching NZB document. |
|
watchlist
Package watchlist ingests authorized viewers' watchlists and lazily checks their release availability.
|
Package watchlist ingests authorized viewers' watchlists and lazily checks their release availability. |
|
yenc
Package yenc implements the yEnc binary encoding used for Usenet binary posts (http://www.yenc.org/yenc-draft.1.3.txt): a fast streaming decoder with =ybegin/=ypart/=yend parsing and CRC32 verification, and an encoder used by tests and the fake NNTP server.
|
Package yenc implements the yEnc binary encoding used for Usenet binary posts (http://www.yenc.org/yenc-draft.1.3.txt): a fast streaming decoder with =ybegin/=ypart/=yend parsing and CRC32 verification, and an encoder used by tests and the fake NNTP server. |
Click to show internal directories.
Click to hide internal directories.