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.

3. emby_yamtrack_sync.py — Emby → Yamtrack Sync (CLI)

Sync your Emby play history into Yamtrack (self-hosted media tracker).

Modes:

• csv (recommended for history) — exports a Yamtrack-compatible CSV with real LastPlayedDate values. Upload it in Yamtrack → Import Data.
• webhook — POSTs synthetic Emby playback.stop events to Yamtrack’s Emby webhook URL. Good for automated / incremental sync (state file skips already-sent items).
• both — write CSV and push webhooks.

Items need external provider IDs in Emby (TMDB / IMDb / TVDB) so Yamtrack can match metadata. Home videos and unmatched items are skipped.

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

CLI — Emby → Yamtrack Sync

# Historical import: generate a Yamtrack CSV (preserves Emby play dates)
python emby_yamtrack_sync.py \
  --emby-url http://your-emby-server:8096 \
  --emby-api-key YOUR_API_KEY \
  --emby-user-id YOUR_USER_ID \
  --mode csv \
  --output emby-history.csv

# Only last 90 days
python emby_yamtrack_sync.py \
  --emby-url http://emby:8096 \
  --emby-api-key YOUR_API_KEY \
  --emby-user-id YOUR_USER_ID \
  --mode csv --days 90 -o recent.csv

# Incremental push to Yamtrack's Emby webhook
python emby_yamtrack_sync.py \
  --emby-url http://emby:8096 \
  --emby-api-key YOUR_API_KEY \
  --emby-user-id YOUR_USER_ID \
  --mode webhook \
  --yamtrack-url https://yamtrack.example.com \
  --yamtrack-token YOUR_YAMTRACK_WEBHOOK_TOKEN

# Preview without writing/sending
python emby_yamtrack_sync.py ... --mode webhook --dry-run -v

CSV import steps in Yamtrack:

1. Run the tool with --mode csv
2. Open Yamtrack → Import Data → Yamtrack CSV
3. Upload the generated file (choose new or overwrite)

Webhook token: In Yamtrack, open your Emby integration / webhook settings. The URL looks like
https://your-yamtrack/webhook/emby/<token> — pass that <token> as --yamtrack-token.

Useful options:

Flag	Description
--mode csv|webhook|both	Output mode (default: csv)
--days N	Only plays from the last N days
--limit N	Cap number of items processed
--state-file PATH	Incremental state for webhook mode (default: ~/.emby-yamtrack-sync-state.json)
--full	Ignore state and re-send everything
--delay SEC	Pause between webhook POSTs (default: 0.25)
--dry-run	Print actions without writing/sending
-v	Verbose per-item logging

Note: Webhook mode stamps watch dates as the time of the sync (Yamtrack’s handler uses “now”). Use csv mode when you care about historical play dates.

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!