cliff/emby-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: Home
Pages
Home
2 Home
Cliff Albert edited this page 2026-05-13 06:03:35 +00:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

emby-tools is a small collection of Python scripts designed to simplify common tasks when managing an Emby media server. The tools focus on batch editing metadata and generating useful statistics from your personal media library.

The project is hosted on the oisec Gitea instance: https://gitea.oisec.net/cliff/emby-tools

== Features ==

  • Modern graphical batch editor with dark theme
  • Powerful filtering of library items (fully watched, missing actors, in progress, etc.)
  • Bulk adding of actors (with optional character names) to multiple items at once
  • Direct links from the GUI to open items in the Emby web interface
  • Command-line tool for generating weighted statistics based on actual play counts
  • Automatic saving of connection settings

== Included Tools ==

=== emby-gui.py – Emby Batch Editor (GUI) ===

A user-friendly graphical application built with '''CustomTkinter'''. It allows you to:

  • Connect to any Emby server using URL, API key and User ID
  • Browse your libraries with quick filters: ** All fully viewed items ** Items without any actors ** Items currently in progress
  • Search by title, folder or filename
  • View table with optional posters, play count, actors and tags
  • Select multiple items and batch-add actors + character roles
  • Double-click any row to open the item directly in Emby

The GUI automatically saves your last connection details to ~/.emby-batch-editor.json.

=== emby_top_actors.py – Top Statistics (CLI) ===

A command-line script that analyzes your '''watched''' content and produces statistics weighted by how many times you actually played each item.

It generates rankings for:

  • Top actors
  • Top genres
  • Top tags
  • Most played movies / episodes / videos
  • Most common tag combinations

You can limit the analysis to plays from the last ''N'' days.

== Requirements ==

  • Python 3.8 or higher
  • An Emby server with API access enabled

=== Python dependencies ===

The following packages are required (listed in ''requirements.txt''):

  • customtkinter
  • requests
  • pillow
  • certifi, urllib3, etc.

Install them with:

pip install -r requirements.txt

== Installation ==

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

== Usage ==

Running the GUI

python emby-gui.py
  • Enter your Emby server URL (e.g. http://emby:8096 or https://emby.example.com)
  • Paste your API key (create one in Emby Dashboard → API Keys)
  • Enter your User ID (GUID)
  • Click '''Test Connection''' then '''Load Libraries'''
  • Use the filters or search, select items, and batch-edit actors on the right panel

Running the CLI statistics tool

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

Useful options:

  • --top 15 – show top 15 entries per category
  • --days 30 – only include plays from the last 30 days

== How to obtain API Key and User ID ==

  • Log into your Emby web dashboard as administrator
  • Go to '''Dashboard → API Keys''' and create a new key
  • For the User ID, check your user profile or query the /Users endpoint

== License ==

The project uses the '''Beerware''' license. In short: do whatever you want with the code; if we ever meet and you find it useful, you can buy the author a beer.

Full text is available in the https://gitea.oisec.net/cliff/emby-tools/src/branch/main/LICENSE

== Author ==

== External links ==