Trakt to Org-mode Converter

Convert your Trakt.tv watch history and media library into Emacs org-mode files with tables for easy tracking and management.

Features

• Movies tracking: All watched movies and watchlist items in a single table
• Shows tracking: TV shows with episode progress, completion status, and watchlist
• Collection tracking: Media you own (separate from watch history)
• TMDB integration: Fetches total episode counts to calculate show completion
• Deduplication: Personal lists automatically exclude items already tracked elsewhere
• Caching: TMDB API responses are cached to avoid repeated requests

Prerequisites

• Python 3.11+
• uv package manager
• Trakt.tv data export (JSON files)
• TMDB API key (free, for show completion tracking)

Installation

1. Clone this repository:

   git clone <repo-url>
   cd project-trakt
   

2. Install dependencies:

   uv sync
   

3. Get a TMDB API key:

   • Create an account at themoviedb.org
   • Go to Settings > API > Create > Developer
   • Copy the "API Read Access Token" (the long JWT token)

4. Create a .env file with your API key:

   echo 'TMDB_API_KEY=your_token_here' > .env
   

Data Export from Trakt

1. Go to trakt.tv/users/me/settings
2. Scroll to "Export Data" and request an export
3. Download and extract the ZIP file
4. Place the extracted folder in this directory as tabtwo/ (or update DATA_DIR in convert.py)

The expected structure:

tabtwo/
├── watched/
│   ├── watched-movies.json
│   ├── watched-shows.json
│   └── history-*.json
├── collection/
│   ├── collection-movies.json
│   └── collection-shows.json
├── lists/
│   ├── watchlist.json
│   └── list-*.json
└── ...

Usage

Run the converter:

uv run convert.py

Output files are generated in the org/ directory.

Output Files

movies.org

All movies (watched + watchlist) in a single table:

Column	Description
Name	Movie title
IMDB	Link to IMDB page
Last Watched	Date last watched (empty for watchlist)
Status	Watched or Watchlist

Example:

| Name              | IMDB | Last Watched | Status    |
|-------------------+------+--------------+-----------|
| Blade             | IMDB | 2019-09-24   | Watched   |
| Gone Girl         | IMDB |              | Watchlist |

shows.org

All TV shows (watched + watchlist) with progress tracking:

Column	Description
Name	Show title
IMDB	Link to IMDB page
Last Episode	Last watched episode (S01E05 format)
Progress	Episodes watched / total (e.g., 45/100)
Status	Completion status (see below)

Status values:

• Complete - Watched all episodes
• Watching - Show still airing, more episodes to come
• Dropped - Show ended/canceled but not finished watching
• Watchlist - Haven't started watching yet

Example:

| Name          | IMDB | Last Episode | Progress | Status    |
|---------------+------+--------------+----------+-----------|
| Breaking Bad  | IMDB | S05E16       | 62/62    | Complete  |
| Black Mirror  | IMDB | S06E01       | 22/32    | Watching  |
| 30 Rock       | IMDB | S04E22       | 80/138   | Dropped   |
| True Detective| IMDB | S00E00       |          | Watchlist |

collection.org

Media you own (physical or digital):

Column	Description
Name	Title
IMDB	Link to IMDB page
Type	movie or show

Configuration

Environment Variables

Variable	Description
TMDB_API_KEY	TMDB API Read Access Token (JWT)

The API key can be set in .env (recommended) or passed directly:

TMDB_API_KEY="..." uv run convert.py

Paths

Edit these constants in convert.py if needed:

DATA_DIR = Path("tabtwo")      # Trakt export directory
OUT_DIR = Path("org")          # Output directory for org files
CACHE_FILE = Path(".tmdb_cache.json")  # TMDB response cache

Caching

TMDB API responses are cached in .tmdb_cache.json to:

• Speed up subsequent runs
• Avoid hitting API rate limits
• Work offline after initial fetch

Delete this file to force a fresh fetch from TMDB.

Using with Emacs

Open any .org file in Emacs and the tables will be automatically formatted. Useful keybindings:

Key	Action
TAB	Re-align table / move to next cell
S-TAB	Move to previous cell
C-c |	Convert region to table
M-up/down	Move row up/down
C-c C-c	Re-align table

You can also add custom column views, sorting, and filtering using org-mode's built-in features.

Project Structure

project-trakt/
├── convert.py          # Main conversion script
├── pyproject.toml      # Python project config
├── .env                # TMDB API key (git-ignored)
├── .tmdb_cache.json    # TMDB response cache (git-ignored)
├── tabtwo/             # Trakt data export
│   ├── watched/
│   ├── collection/
│   ├── lists/
│   └── ...
└── org/                # Generated org-mode files
    ├── movies.org
    ├── shows.org
    └── collection.org

License

MIT