NZB-DAV Kodi Addon

A Kodi 21 (Omega) player/resolver add-on that streams Usenet media through TMDBHelper. You browse a movie or TV episode in TMDBHelper, NZB-DAV searches your indexers, you pick a release, and NZB-DAV streams it through nzbdav or InfiniDysk — with a progress bar, seeking, and automatic recovery when a source goes bad. No manual NZB handling required. An optional download-first NZBGet backend is also available.

This add-on provides software, not content. You bring your own indexers (NZBHydra2, Prowlarr, or direct Newznab), your own nzbdav, InfiniDysk, or NZBGet server, and your own Usenet provider.

📖 Full documentation

This README is the short version. The complete guide — every setting, every feature, and a technical breakdown of how it all works — lives at:

👉 appz4fun.github.io/nzbdavkodi

There you'll find getting-started walkthroughs, a complete settings reference, feature guides, and a technical "how it works" section with architecture diagrams.

How it works

flowchart LR
    A[TMDBHelper] -->|movie / episode| B[NZB-DAV Addon]
    B -->|Newznab / native search| C[NZBHydra2 / Prowlarr /<br/>direct indexers]
    C -->|results| B
    B -->|you pick a result| D{Filter & rank}
    D -->|submit NZB| E[nzbdav]
    E -->|poll status| B
    E -->|WebDAV| F[Local stream proxy]
    F -->|range requests, gap recovery| G[Kodi player]

Loading

nzbdav (or InfiniDysk) handles both fetching and serving over WebDAV — no separate download client needed. A background stream proxy adds seeking, on-the-fly remuxing, and mid-playback source switching. With the optional NZBGet backend, NZBGet downloads the whole file first and Kodi plays it from an SMB share or a local/mounted folder.

Requirements

Component	Description
Kodi 21 (Omega)	Or later
InfiniDysk (recommended) or nzbdav	Running and reachable (submission API + WebDAV). InfiniDysk is the maintained nzbdav fork and uses the same settings
NZBGet (optional, instead of nzbdav)	JSON-RPC API plus a completed folder Kodi can read
NZBHydra2, Prowlarr, or direct Newznab indexers	At least one search provider
TMDBHelper	To browse titles and trigger playback
ffmpeg (recommended)	Enables the optional remux tiers; without it the proxy uses pass-through

See Prerequisites for details.

Installation

From the Appz4Fun Kodi repository (recommended)

NZB-DAV is distributed through the Appz4Fun Kodi repository, which delivers automatic updates on one of two channels:

Channel	Repository add-on	NZB-DAV today
Stable	repository.appz4fun.stable	1.2.3
Beta	repository.appz4fun.beta	2.0.0-beta.2 (pre-releases included)

1. Open appz4fun.github.io/Appz4Fun-Kodi-Repo and download the channel zip (for example repository.appz4fun.stable-1.0.1.zip).
2. In Kodi: Settings → System → Add-ons → enable Unknown sources.
3. Settings → Add-ons → Install from zip file → select the channel zip.
4. Settings → Add-ons → Install from repository → Appz4Fun Repository (or Appz4Fun Repository (Beta)) → Video add-ons → install NZB-DAV. Future updates on that channel install automatically.

Kodi only updates a third-party add-on from the repository it was installed from, so to switch channels (or move an existing install onto the new repository), install the other repository zip, then open NZB-DAV's add-on info page → Versions and pick the version listed under that repository. See Beta channel and beta features for what the beta adds and how to switch.

Upgrading from the old repository? NZB-DAV used to be distributed from the NZB-DAV Repository add-on (repository.nzbdav) at https://appz4fun.github.io/nzbdavkodi/. That URL now hosts this project's documentation, not add-on metadata, so installs made from it no longer update. Install an Appz4Fun repository zip as above, reinstall NZB-DAV from it through Versions (settings are kept), then remove the old nzbdav file-manager source and the old NZB-DAV Repository add-on.

Manual install

Download plugin.video.nzbdav-<version>.zip from the releases page (releases marked Pre-release are beta builds), then Settings → Add-ons → Install from zip file. Manual installs don't auto-update.

Full steps: Install the add-on.

Quick setup

1. Open My add-ons → Video add-ons → NZB-DAV → Configure and enter your nzbdav URL + API key and WebDAV credentials (InfiniDysk uses the same fields). Use the Test actions. To use NZBGet instead, fill in the NZBGet tab and enable Use NZBGet instead of nzbdav for playback.
2. Enable a search provider and test it. NZBHydra2 is recommended over entering each indexer's API on the Indexers tab: it's easier to manage and highly configurable, and results still show which indexer they came from.
3. On the Player Installation tab, select Install TMDBHelper Player.
4. Restart Kodi (or run TMDBHelper Players → Update players), then set Default player (Movies) and Default player (TV Shows) to NZB-DAV.
5. Play a title from TMDBHelper.

Full walkthrough: Configure connections · Set up TMDBHelper · Play your first title.

Key features

• Multi-provider search across NZBHydra2, Prowlarr, and direct Newznab indexers, merged and de-duplicated. Optional TVDB-aware TV search resolves a show's id for more accurate episode results.
• Quality filtering and ranking by resolution, HDR, audio, codec, language, release group, size, and keywords. Default-enabled Other / Unknown options prevent unrecognized formats from disappearing. Relevance ranks resolution first, then HDR, Hybrid REMUX / REMUX, and three editable TRaSH remux group tiers.
• Exact season-pack playback and reuse: completed multi-episode downloads play the requested episode instead of the largest file, then appear as an already-downloaded pack for later episodes from that same backend job.
• A local stream proxy that preserves seeking, rewrites tail-moov MP4s in pure Python, recovers from missing articles, and offers optional Matroska remux and fMP4 HLS tiers for large or Dolby Vision files.
• Self-healing fallback streams that switch to a verified (same length, matching sampled fingerprints) alternate release mid-playback without stopping or rewinding.
• Optional NZBGet backend (beta) as an alternative to nzbdav, playing from an SMB share or a local/mounted folder, with Smart Duplicates failover to a same-release backup when a download turns out unrepairable.

Each feature is documented in full under Features.

Troubleshooting

If NZB-DAV doesn't appear in TMDBHelper, no results show, or playback fails, see the Troubleshooting guide. See CHANGELOG.md for release notes.

Development

Requires uv (runs the pinned test/lint toolchain) and just. Addon runtime code stays Python 3.8+ and pure Python.

just test          # Run the default unit test suite
just lint          # ruff + black + pylint + vermin
just lint-fix      # Auto-fix lint/format issues
just ci            # lint + test + the Python 3.8 compile check CI runs
just release       # Build plugin.video.nzbdav-<version>.zip
just ship          # Test, then build the release zip
just docs          # Build the documentation site into ./site (strict)
just docs-serve    # Serve the docs site locally with live reload

Contributor orientation: AGENTS.md · architecture and internals: How it works and docs/proxy-architecture.md.

Project structure

repo/plugin.video.nzbdav/     # The Kodi add-on (installed via zip)
  addon.xml                   # Add-on manifest
  addon.py / service.py       # Entry point + background service (stream proxy)
  resources/
    settings.xml              # Kodi settings UI
    lib/                      # Runtime modules (router, search, resolver, proxy, ...)
    language/                 # Localization
docs-site/                    # MkDocs documentation source (GitHub Pages)
mkdocs.yml                    # Docs site config
docs/                         # Contributor deep-dives (proxy internals, DV/HLS notes)
scripts/                      # Addon zip build + PR-review helpers
tests/                        # pytest suite (Kodi mocks in conftest.py)
.github/workflows/            # ci.yml, release.yml, pages.yml (docs), security scans

Releasing

1. Bump version in repo/plugin.video.nzbdav/addon.xml.
2. Update CHANGELOG.md and repo/plugin.video.nzbdav/changelog.txt.
3. Run just lint and just test.
4. Commit, then tag and push: git tag vX.Y.Z && git push origin main vX.Y.Z.

The Release workflow builds the zip and creates a GitHub Release, then notifies the Appz4Fun Kodi repository to rebuild and republish. Pre-release tags (any tag with a hyphen, such as v2.0.0-beta.3) are published to the Beta channel only. Note that Kodi ranks 2.0.0-beta.N above 2.0.0, so beta users auto-update only to a higher base version; see AGENTS.md.

Compatibility

Platform	Supported
Kodi	21 (Omega) and later
Python	3.8+
OS	CoreELEC, LibreELEC, OSMC, Windows, macOS, Linux
Architecture	ARM64 (aarch64), x86-64
Dependencies	None — all vendored, no pip required

License

GPLv3 — see LICENSE for details.