UsenetFlix

UsenetFlix is a Kodi video plugin that lets you browse a local folder containing NZB files as if they were movies. You can send these NZB files directly to SABnzbd for downloading — all without leaving Kodi.

---

Features

• Browse .nzb files in a user-configured folder, presented as movie entries.
• Parses movie title and year from NZB filenames.
• Fetches and caches metadata (title, year, plot, poster) from TMDb.
• Uses local posters if present (e.g. movie.jpg → movie.nzb).
• Falls back to TMDb poster (if available), or to a default poster bundled with the plugin.
• Only fetches TMDb metadata for new entries or entries missing a poster, avoiding unnecessary lookups.
• Sends NZB files to SABnzbd via its API with automatic category detection.
• Supports filename-based category mapping (e.g. my.movie.4k.nzb → 4k).
• Autopopulates category mapping from SABnzbd or a text file if not defined.
• API keys and category mapping can be loaded from .txt files in the NZB folder.
• Displays helpful prompts if API keys are missing (can be disabled).
• Metadata is stored in a local SQLite database.
• Auto-cleans the database (removing orphaned entries) on startup (configurable).
• Manual “Clean Database” option available in the Kodi UI.
• Admin tools available in the Kodi UI (only visible when enabled in settings).
• [Test SABnzbd-connection] option available from the UI.
• Marking of files already sent to SABnzbd (status: sent).
• Uses a bundled fallback poster when no other artwork is available.
• Fully compatible with Kodi 21+ on platforms like Vero V, Windows, Linux, etc.

---

File Format Support

UsenetFlix currently supports .nzb files only.
Compressed formats like .nzb.gz or .zip are not supported at this time.

---

Installation

1. Copy the plugin.video.usenetflix folder into Kodi's addons directory.
2. In Kodi, open the addon settings:
   • Set your NZB folder path.
   • Set your SABnzbd host URL (e.g. http://localhost:8080).
3. Provide API keys:
   • Either place tmdb_api_key.txt and sabnzbd_api_key.txt in your NZB folder (recommended).
   • Example template files (tmdb_api_key.txt.example and sabnzbd_api_key.txt.example) are included in the plugin folder to help you get started.
   • Or enter them manually in the addon settings.
4. (Optional) Add custom category mapping (category_mapping.txt) in the NZB folder.
5. (Optional) Toggle the “Show API Key Help” prompt on/off.
6. Launch the plugin via the Kodi video addons section.

---

Settings

Setting	Description	Default
NZB Path	Path to your local NZB files	(empty)
TMDb API Key	API key for TMDb (for movie metadata)	(empty)
SABnzbd Host	URL to your SABnzbd server	(empty)
SABnzbd API Key	API key for your SABnzbd instance	(empty)
Show API Key Help	Show prompt if API keys are missing	True
Default Category	Category used if no tag is matched	movies
Category Mapping	Tag-to-category mapping (4k:4k,uhd;kids:kids,...)	(empty)
Auto Clean Database	Remove missing files from DB on startup	True
Show Admin Tools	Enables admin UI features (e.g. test SAB, clean DB)	False

---

Poster Support

Posters for each NZB file are resolved in the following order:

1. Local Poster – A .jpg file with the same name as the NZB (e.g. movie.nzb → movie.jpg in the NZB folder).
2. TMDb Poster – If TMDb is enabled and a match is found, only fetched for entries that don't already have a poster.
3. Default Poster – A bundled fallback image: resources/media/default_poster.png.

This logic ensures that previously fetched TMDb posters or local posters are not overwritten, and reduces unnecessary lookups.

---

Automatic Category Mapping

If Category Mapping is empty, UsenetFlix will attempt to populate it automatically:

1. From File – If a category_mapping.txt file exists in the NZB folder (same format as the setting).
2. From SABnzbd – If no file exists, the plugin fetches category names via SABnzbd's API and uses a default mapping (e.g., "UHD" → "2160p").

Example category_mapping.txt:

uhd:2160p,4k
hd:1080p,720p
kids:kids,family
anime:anime,japan

The first matched tag wins. If no match is found, the default category is used.

---

Status Indicators

Files that have been sent to SABnzbd will show a small status indicator (e.g. [*]) in the list.
This helps avoid accidental re-submission and keeps large NZB folders manageable.

---

Admin Tools

When Show Admin Tools is enabled:

• [Refresh database] – Removes entries for missing files and fetches TMDb metadata for new entries.
• [Test SABnzbd-connection] – Quickly check if SABnzbd is reachable.

---

API Key Example Files

To simplify initial setup, you can use the provided example files:

• tmdb_api_key.txt.example → copy to tmdb_api_key.txt and insert your TMDb API key.
• sabnzbd_api_key.txt.example → copy to sabnzbd_api_key.txt and insert your SABnzbd API key.
  You can optionally use the format <api-key>@<host> for SABnzbd (e.g., MYSECRETAPIKEY@192.168.0.10:8080).

These example files are included in the plugin folder as templates to help you get started quickly. Make sure to not commit your real API keys to version control.

---

Database

• Metadata is cached in a local SQLite database:
  ~/.kodi/userdata/addon_data/plugin.video.usenetflix/usenetflix.db
• Auto-clean removes orphaned entries on startup if enabled.
• Status field tracks whether a file has been "sent" to SABnzbd.
• Manual refresh database is available in the UI.
• TMDb metadata and poster URLs are only fetched for new entries or entries missing a poster. This ensures local posters or already fetched TMDb posters are preserved.

---

How to Use

1. Open UsenetFlix in Kodi.
2. Browse .nzb files, shown with metadata and posters.
3. Select an item to send it to SABnzbd.
4. Monitor the download via SABnzbd's web interface.
5. Already sent files are marked visually.

---

Tests

UsenetFlix includes automated tests for its core components to ensure reliability and correctness. The tests cover the following modules:

• NZBFile – Parsing filenames, detecting categories, and cleaning file content.
• NZBManager – Listing .nzb files, ignoring non-NZB files, handling missing directories, and managing errors.
• SABnzbdClient – Building URLs, sending NZB files, handling API responses, and testing connections.
• TMDbClient – Fetching metadata, caching results, and handling errors.

---

Running the Tests

Follow these steps to run the test suite:

1. Create a Python virtual environment (if not already done):

python -m venv .venv

2. Activate the virtual environment

• Windows (PowerShell):

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
.venv\Scripts\Activate.ps1

• Linux / macOS:

source .venv/bin/activate

3. Install test dependencies:

pip install -r requirements-dev.txt

If pytest is not listed in your dev requirements, install it manually:

pip install pytest

4. Run all tests:

pytest -v

The output will indicate which tests passed or failed. All core tests for NZBFile, NZBManager, SABnzbdClient, and TMDbClient are included.

---

Notes

• Tests use mocking to avoid making real HTTP requests to SABnzbd or TMDb.
• Kodi-specific modules (xbmc, xbmcaddon, xbmcvfs) are mocked so tests can run outside Kodi.
• You can extend the test suite by adding new tests under the tests/ directory.

---

Troubleshooting

• No posters or metadata? → Check TMDb API key and internet access.
• NZB files not sending? → Check SABnzbd URL, port, and API key.
• Category not assigned? → Ensure filename contains a mapped tag or define your own mapping.
• Still issues? → Enable Kodi debug log and check [UsenetFlix] entries.

---

License

MIT License – see LICENSE file.

---

Disclaimer

Uses the TMDb API but is not endorsed or certified by TMDb.

Important Notice

UsenetFlix is intended for legal and educational use only. Please respect copyright laws.

If you love movies, please support the film industry by buying your favorite films on Blu-ray or 4K UHD. Physical media is the best and most enjoyable way to watch movies!

---

Maintainer

Maintained by @jlindqv. For questions or contributions, please open an issue on GitHub.

---

Changelog

For a full history of changes and version notes, see the CHANGELOG.

Happy Usenetflixing!