emby-tools

A collection of useful Python tools and scripts to make managing and analyzing your Emby media server easier.

Tools Included

1. emby-gui.py — Emby Batch Editor (GUI)

A modern, dark-themed graphical interface built with CustomTkinter that lets you browse, filter, and batch-edit items in your Emby library.

Key Features:

• Connect to any Emby server using URL, API key, and User ID
• Powerful quick filters:
  • All fully viewed items
  • Items without actors
  • Items in progress
• Search by title, folder name, or filename
• Table view with optional posters, play count, actors, and tags
• Batch add actors (with optional character role) to multiple selected items at once
• Batch add tags (multiple tags) to multiple selected items at once
• Double-click any item to open it directly in the Emby web UI
• Saves your connection settings locally for convenience (~/.emby-batch-editor.json)

2. emby_top_actors.py — Emby Top Statistics (CLI)

A command-line tool that scans your watched items and generates insightful statistics, weighted by actual play count (if you watched something 5 times, it counts 5×).

Outputs:

• Top Actors
• Top Genres
• Top Tags
• Most played Movies / Episodes / Videos
• Most common Tag Combinations

Supports filtering to only plays from the last X days.

Requirements

• Python 3.8+
• An Emby server with API access enabled

Install Dependencies

pip install -r requirements.txt

requirements.txt includes:

• customtkinter (modern GUI)
• requests (Emby API)
• pillow (poster images)
• certifi, urllib3, etc.

Installation

git clone https://gitea.oisec.net/cliff/emby-tools.git
cd emby-tools
pip install -r requirements.txt

Usage

GUI — Emby Batch Editor

python emby-gui.py

1. Enter your Emby Server URL (example: http://emby:8096 or https://emby.yourdomain.com)
2. Paste your API Key
3. Enter your User ID (a GUID)
4. Click Test Connection
5. Click Load Libraries
6. Use the quick filter buttons or the search bar
7. Select one or more items in the table
8. Use the "Add Actor" panel on the right to batch-apply changes

Tip: You can find your API key in Emby Dashboard → API Keys.
Your User ID is visible in your user profile or via the /Users API endpoint.

CLI — Top Statistics

python emby_top_actors.py --url http://your-emby-server:8096 --api-key YOUR_API_KEY --user-id YOUR_USER_ID

Available options:

• --url Emby server base URL
• --api-key Your Emby API key
• --user-id User GUID
• --top N Number of top entries to show per category (default: 10)
• --days D Only consider plays from the last D days

Examples:

# Show top 15 for all time
python emby_top_actors.py --url http://127.0.0.1:8096 --api-key abc123def456 --user-id 8f3e2d1c-9b0a-4e5f-8c7d-1a2b3c4d5e6f --top 15

# Only last 30 days
python emby_top_actors.py --url http://emby:8096 --api-key abc123def456 --user-id 8f3e2d1c-9b0a-4e5f-8c7d-1a2b3c4d5e6f --days 30

How to Get Your API Key and User ID

1. Log into the Emby web interface as an administrator.
2. Go to Dashboard → API Keys → Create a new key (give it a descriptive name).
3. For the User ID, go to Users in the dashboard or call the API endpoint GET /Users (the GUID is in the response).

Configuration

The GUI automatically saves your last connection details to ~/.emby-batch-editor.json so you don’t have to re-enter them every time.

License

Beer-Ware License
Cliff Albert wrote this file. As long as you retain this notice you can do whatever you want with this stuff. If we meet some day, and you think this stuff is worth it, you can buy me a beer in return.

See the LICENSE file for the full text.

---

Made with ❤️ for the Emby community by Cliff Albert.

Contributions, ideas, and bug reports are very welcome!