jellycodec 0.1.0

Jellyfin Codec Analyzer — analyze video codecs in your Jellyfin library

Jellyfin Codec Analyzer

A small command-line tool to analyze video codecs in a Jellyfin media library. It queries the Jellyfin server, inspects media stream information for movies and episodes, and summarizes codecs, counts, and sizes. The tool also supports an interactive mode to explore and export results.

The primary intended use of this tool is to find your biggest files using inefficient codecs and replace or re-encode them to save space or bandwith.

Key features

• Analyze video codecs across your Jellyfin library
• Show counts, total sizes, and percentages per codec
• List files grouped by codec and optionally filter by codec
• Save summary or per-file lists to CSV or JSON
• Interactive TUI-style mode for quick exploration

Requirements

• Python 3.8+
• requests (for HTTP requests to Jellyfin)
• python-dotenv (optional — automatically loads .env file if installed)

Install dependencies (recommended inside a virtualenv):

pip install -r requirements.txt
# Or install packages individually:
# pip install requests python-dotenv

Configuration

The script reads the Jellyfin server URL and API key from environment variables or command-line flags. Create a .env file in the same directory (optional) with the following values:

JELLYFIN_SERVER=http://localhost:8096
JELLYFIN_API_KEY=your_api_key_here

If python-dotenv is available the script will automatically load .env on startup and print a notice to stderr.

Usage

Run the analyzer directly:

python jellycodec.py -s http://your-server:8096 -k YOUR_API_KEY

Common options:

• -s, --server: Jellyfin server URL (or set JELLYFIN_SERVER env var)
• -k, --api-key: Jellyfin API key (or set JELLYFIN_API_KEY env var)
• -i, --interactive: Run in interactive mode (menu-driven)
• -l, --list-files: List all files grouped by codec
• -c, --codec: Filter listed files by codec (use with -l)
• -o, --output: Save codec summary to a file
• -d, --detailed: Show percentages and detailed output

Examples:

• Analyze library and print summary:

python jellycodec.py -s http://localhost:8096 -k ABCDEFGHIJK

• Run interactive mode (recommended for exploring and exporting):

python jellycodec.py -i -s http://localhost:8096 -k ABCDEFGHIJK

• List files for a specific codec:

python jellycodec.py -l -c "HEVC (H.265)" -s http://localhost:8096 -k ABCDEFGHIJK

• Save codec summary to codecs.txt:

python jellycodec.py -o codecs.txt -d -s http://localhost:8096 -k ABCDEFGHIJK

Interactive mode

When launched with -i, the script fetches all movie/episode items once and provides a simple menu where you can:

• View codec statistics (counts, total size)
• View detailed statistics with percentages
• List files grouped by codec
• List files for a selected codec
• Export file lists (CSV or JSON)

The interactive flow is useful when you want to quickly inspect which files use a particular codec and export results for further analysis.

Output and exports

• Summary output shows total videos analyzed and aggregated size (human-readable).
• File lists can be saved in CSV (recommended) or JSON formats.
• The script attempts to use MediaSources entry to determine file sizes; when size information is missing the size will be reported as Unknown.

Notes & Error Handling

• The script performs basic HTTP error handling (401/403/404/500 and connection/timeouts) and prints helpful guidance to stderr.
• Ensure the API key has sufficient permissions to read library items.
• The tool requests the Items endpoint with Recursive=true and IncludeItemTypes=Movie,Episode to fetch media streams.

Development & Contributing

Contributions and improvements welcome. Open an issue or submit a pull request with fixes or enhancements (e.g., support for additional item types, more robust size detection, or unit tests).

License

This repository does not include a license file. Add a license of choice if you intend to share publicly.

---

File: jellycodec.py