Skip to content
Guts444Public

About

Local-first Windows IPTV player with native libmpv playback, saved sources, favorites, recents, and startup resume.

Resources

Stars

10 stars

Watchers

0 watching

Forks

Repository files navigation

Onyx

Onyx is a local-first Windows IPTV player built with Tauri, React, TypeScript, and native libmpv playback.

It is meant for people who already have their own playlists, Xtream accounts, and XMLTV guide URLs, and want a desktop app that can keep large libraries usable without pushing their data through a cloud account.

Windows is the primary supported platform.

Download

Download from the Microsoft Store

Install the supported Store release from the Microsoft Store. The Store handles installation and future updates automatically.

Standalone MSI and NSIS installers remain available from GitHub Releases.

Release builds include the native playback dependencies. You do not need Node.js, Rust, or the mpv DLLs unless you are building Onyx from source.

Onyx uses the system Microsoft Edge WebView2 runtime. Windows 11 and current Windows 10 installs normally include it already, so the installer does not download or run the WebView2 bootstrapper.

Getting Started

New to Onyx? Read the complete User Guide.

  1. Open Settings > Sources.
  2. Import a local .m3u / .m3u8 file, or add an M3U URL or Xtream profile and select Load Now.
  3. Open Live TV, optionally search above the group list, select a group, then left-click a channel in the TV guide. For Xtream providers, open Movies or TV Shows, search above the vertical group list, then browse details, seasons, and episodes.
  4. Right-click a channel to manage Favorites or assign an EPG listing.
  5. Double-click the mini player to open the resizable window, or use its Fullscreen button. In fullscreen, Esc or a double-click drops into the window; once windowed, Esc returns to the guide and the window comes back to its previous size.

The in-app User Guide button above Settings contains this quick start and direct links to Sources and EPG settings.

For guide data, add an XMLTV URL under Settings > EPG, apply it, and select Update Now before manually matching channels.

What Onyx Does

  • Loads local .m3u / .m3u8 files, remote M3U URLs, and Xtream Live TV, Movies, and TV Shows.
  • Saves source profiles so you can reload a provider without re-entering the same details.
  • Keeps the main navigation, searchable group list, and TV guide visible together while browsing large libraries.
  • Lets you search and independently hide noisy Live TV, Movies, and TV Shows groups under Settings > Library.
  • Loads one or more XMLTV EPG guides.
  • Caches guide data locally for matching and now/next programme display.
  • Supports manual EPG matching when automatic matching is not enough.
  • Plays streams through native libmpv.
  • Recovers from stalls and drops on its own: a stream that stops opening or stops progressing is retried up to five times, with waits growing from 3 seconds to a minute and a visible countdown plus Retry now; when the ladder is spent Onyx reports the failure and offers Reload. A retried movie or episode resumes where it stopped.
  • Opens movies and episodes in the resizable player window with idle-hiding controls, click-to-pause/resume, 30-second skips, seeking, detected resolution, subtitles, mute, volume, a Fullscreen switch and one Quit action through native libmpv.
  • Stats in either player shows codec, resolution, frame rate, hardware decoding, cache, dropped frames, and recovery state, with a Copy button for bug reports that never includes a stream URL or credential.
  • Double-click switches a movie or episode between the window and fullscreen at any time. The window works down to 480 x 270; Esc leaves fullscreen and, once windowed, quits back to the title with its position saved.
  • Live TV has the same windowed mode: double-click the mini player or use its Windowed or Fullscreen button, and the fullscreen player offers Windowed and Guide. Esc or Guide returns to the guide while the channel keeps playing; the guide's mini player keeps Stop. Its buttons appear on hover, for five seconds after playback starts, and on keyboard focus. Changing views never reopens the stream, and returning to the guide restores the previous window size.
  • Remembers where each movie and episode stopped, offers Resume from m:ss or Start over, and keeps that progress across restarts.
  • Coming back to Live resumes the channel that was playing when you left, unless you stopped it.
  • Lets automatic resume start in the window (the default for new installs), in fullscreen, or in the mini-player under Settings > General.

Large Library Behavior

Onyx is built around large IPTV libraries. Recent startup and browsing work focuses on cases with tens of thousands of playlist channels and many EPG programmes:

  • cached playlists can appear immediately while saved remote sources refresh later
  • startup EPG refreshes are delayed until cached guide directories have loaded
  • multiple startup EPG refreshes are staggered instead of launched all at once
  • the channel shelf renders large groups incrementally instead of trying to mount every visible channel card in one pass
  • VOD categories are fetched only when opened, one concrete category at a time; complete provider-wide catalogs never enter the Live TV startup path
  • A provider category is capped at 20,000 valid titles; if that safety limit is reached, Onyx displays an explicit truncation notice instead of presenting the count as complete
  • EPG now/next lookup uses faster indexed programme searches

Privacy And Storage

Onyx has no cloud backend, analytics, telemetry, or account sync. Playlist, guide, playback, and settings data stay on the local machine except for direct requests to the source and guide URLs supplied by the user.

Local app state is stored by Tauri in the app local data directory. This includes credential-free source metadata, guide settings, favorites, recents, hidden groups, playback session data, volume, and credential-free playlist snapshots.

Xtream passwords, remote M3U URLs, and EPG URLs are stored separately in Windows Credential Manager through the Rust keyring integration. Persisted state and cache identities do not use those URLs. At startup, Onyx hydrates the secrets into memory and migrates compatible legacy source, channel, cache, and EPG-mapping references to URL-free identifiers before safely rewriting them.

App-state and EPG-cache writes are size-bounded, serialized, and atomically replaced with validated recovery backups. If a primary is corrupt, Onyx can recover a safe backup; invalid or credential-bearing legacy artifacts are quarantined or securely discarded according to their contents. A failed migration or credential-store operation keeps existing saved data rather than committing a partial change.

Security Notes

  • Playlist metadata is treated as untrusted text and rendered without HTML injection.
  • Stream URLs are normalized and restricted to supported protocols or local file paths.
  • Remote playlist and XMLTV guide imports are fetched in Rust to avoid browser CORS limitations and to enforce size limits.
  • Xtream passwords and remote M3U/EPG URLs are stored in Windows Credential Manager rather than browser storage, app-state JSON, or EPG cache JSON.
  • Persisted state uses URL-free source/cache identifiers and rejects credential-bearing playlist state at the backend boundary.
  • Production uses a restrictive CSP and a minimum Tauri IPC capability set; development has a separate identity, data directory, credential namespace, and explicit localhost-only CSP additions.
  • No shell execution is driven by playlist data.

Screenshots

Home

Onyx home screen

Settings

Library EPG Sources
Onyx library settings Onyx EPG settings Onyx saved sources

On-demand library

Movies Group visibility In-app guide
Onyx Movies browser Onyx movie group visibility settings Onyx in-app guide describing Movies and TV Shows

Build From Source

The supported Windows x86-64 build is intentionally reproducible. Required versions are:

  • Node.js 24.18.x (.nvmrc pins 24.18.0)
  • npm 11.16.x (package.json pins npm@11.16.0)
  • Rust 1.95.x with x86_64-pc-windows-msvc, rustfmt, and clippy (rust-toolchain.toml pins 1.95.0)
  • the normal Tauri Windows prerequisites

The npm manifest and package-lock.json are authoritative for JavaScript dependencies; use npm only and install the exact lockfile graph:

npm ci

Do not generate or commit a pnpm lockfile. Before building, run the pinned prerequisite and native-binary checks:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check-toolchain.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-native-deps.ps1

The required src-tauri/lib/libmpv-wrapper.dll and libmpv-2.dll are described in src-tauri/lib/SOURCES.md. That file contains fixed release URLs, archive hashes, extracted DLL hashes, and the fetch/replacement procedure. Fetch only those pinned archives, verify each archive hash before extraction, verify the extracted DLL hash against both SOURCES.md and src-tauri/lib/SHA256SUMS, then run scripts/verify-native-deps.ps1. Do not use a latest release URL or tauri-plugin-libmpv-api setup-lib for release inputs.

Start isolated development mode:

npm run tauri:dev

Or double-click Start Onyx Dev.cmd. Development uses the com.guts444.onyx.dev identifier, Onyx Dev product/title, a development-only CSP overlay, separate local app data, and separate OS credential-store service names. It cannot read or overwrite production state or credentials.

If you only run npm run dev, the app opens in a browser preview and native playback is disabled.

Validate a release candidate without packaging:

npm ci
npm test
npm run check
npm run build
npm audit
cargo test --manifest-path src-tauri/Cargo.toml --locked --target x86_64-pc-windows-msvc
cargo fmt --manifest-path src-tauri/Cargo.toml --all -- --check
cargo clippy --manifest-path src-tauri/Cargo.toml --locked --target x86_64-pc-windows-msvc --all-targets -- -D warnings
cargo audit --file src-tauri/Cargo.lock

Only after those checks and native provenance verification pass, build all Windows release formats with Build Onyx Release.cmd or:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-release.ps1

The unified release command verifies synchronized metadata and immutable native inputs, then produces MSI, NSIS, and Store MSIX artifacts with checksums under src-tauri/target/release/bundle.

Microsoft Store Package

The Store uses the reserved identity Guts444.Onyx-IPTV. Build the x64 MSIX after the normal release prerequisites and native-dependency checks:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-store-msix.ps1

The script performs a locked Tauri release build, maps the app version to a Store-valid four-part package version, assembles the native libmpv payload, and writes the package plus checksum under src-tauri/target/release/bundle/store.

Microsoft Store package versions cannot begin with zero and reserve their fourth component. Onyx therefore maps SemVer major.minor.patch to Store (major + 1).minor.patch.0; for example, Onyx 0.5.9 becomes Store package 1.5.9.0.

Store listing copy, certification notes, the manifest template, and noncredentialed certification fixtures live under store/. The MSIX does not need a CA-trusted signature for Partner Center upload; Microsoft re-signs it after certification.

The complete version-bump, tagged GitHub release, and Partner Center update routine is documented in docs/releasing.md.

Disclaimer

Onyx is a client application for loading and playing user-supplied playlists, streams, guide URLs, and related credentials. It does not provide channels, playlists, stream URLs, guide data, or service access.

Users are responsible for ensuring they are authorized to use any playlists, streams, Xtream accounts, credentials, EPG URLs, and other third-party services or content loaded by Onyx, and that their use complies with applicable law and the terms of the relevant provider.

Onyx is not affiliated with, endorsed by, or responsible for third-party content or services loaded by users.

Donations

If you enjoy Onyx, donations help support continued fixes and improvements.

Bitcoin:

3LYX3oEDCzz5S7oQjPmYQYi7ZGoA5XpCdM

Ethereum:

0x1246dFAf32E435d79689852A3304ca384A73c1cb

Solana:

Aqm2mLHikyZ5guTf7pKcaXjNXG69ifrDRY2324h79ony

Thank you for the support.

License

This project is licensed under the MIT License.

About

Local-first Windows IPTV player with native libmpv playback, saved sources, favorites, recents, and startup resume.

Resources

Stars

10 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages