Chicago Watch Order for Kodi

This folder contains a small script that builds a Kodi-friendly .m3u playlist for the Chicago crossover watch order.

Recommended approach

Use a basic Kodi playlist in .m3u format. Kodi supports video playlists that point directly at episode files, which is the simplest way to force a custom cross-show order.

What the script expects

1. A folder that contains the episode files for Chicago Fire, Chicago Med, and Chicago P.D.
2. Optionally, a local CSV/TSV order source.

If --order-source is not provided, the script uses chronolists by default. Use --order-source fandom, --order-source tvmaze, or pass a local CSV/TSV file path if desired.

The watch order is cached in .cache/chicago_watch_order.json so repeated runs do not repeatedly fetch remote sources.

The spreadsheet can match files in either of these ways:

• Direct filename match with a path, file, filename, or basename column.
• Episode metadata match with show, season, and episode columns.

Example CSV:

air_order,show,season,episode,title,air_date
1,Chicago Fire,1,1,Pilot,2012-10-10
2,Chicago PD,1,1,Stepping Stone,2014-01-08
3,Chicago Med,1,1,Derailed,2015-11-17

Usage

Virtual environment (recommended)

Create and populate a local virtual environment once:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

For each new shell session, activate it before running commands:

source .venv/bin/activate

Run:

source .venv/bin/activate
python generate_kodi_playlist.py /path/to/videos /path/to/chicago-watch-order.m3u

Common examples:

# Your current setup: output playlist paths relative to mnt (default behavior)
python3 generate_kodi_playlist.py mnt chicago_watch_order.m3u

# Prefix playlist paths for another machine (example MediaPC path)
python3 generate_kodi_playlist.py mnt chicago_watch_order.m3u --path-prefix /srv/media

# Force refresh of order cache from source
python3 generate_kodi_playlist.py mnt chicago_watch_order.m3u --refresh-cache

# Use Fandom explicitly
python3 generate_kodi_playlist.py mnt chicago_watch_order.m3u --order-source fandom

# Use TVmaze and keep its source sequence as primary ordering
python3 generate_kodi_playlist.py mnt chicago_watch_order.m3u --order-source tvmaze --tvmaze-prefer-source-order

# Use a local CSV/TSV file as primary source
python3 generate_kodi_playlist.py mnt chicago_watch_order.m3u --order-source /path/to/watch-order.csv

If rows do not match local files, the script prints unmatched rows so you can rename files or adjust matching.

Linting (strict)

This repo uses Ruff as a strict Python linter.

Run lint:

ruff check .

Auto-fix safe issues:

ruff check . --fix

If ruff is missing on macOS with Homebrew Python, install with:

brew install ruff

Using it in Kodi

On macOS, copy the generated playlist into:

~/Library/Application Support/Kodi/userdata/playlists/video/

Then open it in Kodi from the video playlists area, or browse to the file directly.

Other workable options

1. Queue and save inside Kodi. This works, but it is manual and painful for a long interleaved order.
2. Build a .strm or .nfo driven library workflow. This is more complex and is only worth it if you want deep library customization.
3. Rename or symlink files into a new folder with numeric prefixes like 0001 - Chicago Fire S01E01.mkv, then browse that folder in Kodi sorted by filename. This is often the most robust alternative if you do not want playlists.

Notes

• Playlist entries are written relative to the video_root you pass.
• Use --path-prefix if Kodi needs a mount-specific root path.
• If your spreadsheet is .xlsx, export it to CSV first, then run the script.
• The script recognizes common S01E02 and 1x02 filename patterns.