TV Time to RYOT Converter

Convert your exported TV Time data into a RYOT-compatible CompleteExport JSON file.

After the announcement that TV Time was shutting down, I had to find a new app to keep track of the movies and TV shows I’ve watched. I decided to self-host RYOT. This script helped me convert the data I had been entering into TV Time for more than two years into a format that RYOT can understand.

I hope this helps someone else.

What this script does

This script reads exported TV Time data and generates a JSON file that can be imported into RYOT using the Generic JSON importer.

It can use data from:

• TV Time Liberator export
• TV Time GDPR export

The recommended source is TV Time Liberator, because it usually provides richer data, including movies, shows, watched episodes, ratings, favorites and lists.

The GDPR export is supported mainly as a fallback for TV show history.

Features

• Converts watched movies
• Converts watched TV show episodes
• Preserves watched dates when available
• Imports TV Time watchlist items as RYOT collections
• Imports TV Time lists as RYOT collections
• Imports TV Time favorites as RYOT collections
• Imports ratings when available
• Generates a RYOT CompleteExport JSON file
• Supports pretty-printed JSON for manual inspection
• Prints a summary and warnings after conversion

Requirements

• Node.js 18 or newer
• A TV Time export generated with TV Time Liberator and/or TV Time GDPR
• A running RYOT instance

No npm dependencies are required. The script only uses Node.js built-in modules.

Exporting your TV Time data

You can use one or both export methods.

For best results, use TV Time Liberator. You can also request the official TV Time GDPR export as a backup.

Option 1: Export with TV Time Liberator

TV Time Liberator is a community tool/browser extension that exports your TV Time data.

It can export data such as:

• Shows
• Movies
• Watched episodes
• Favorites
• Lists
• Activity history

Steps

1. Install or run TV Time Liberator.
2. Log in to your TV Time account.
3. Run the export.
4. Extract the exported ZIP file.
5. Place the exported files in a directory, for example:

tv-time-export/

The converter looks for these files inside the Liberator export directory:

movies.json
shows.json
lists.json
favorites.json
activity_history.csv

Not all files are strictly required, but the more files you provide, the more complete the generated RYOT import will be.

Recommended project structure:

your-project/
├── convert-tvtime-to-ryot.js
├── tv-time-export/
│   ├── movies.json
│   ├── shows.json
│   ├── lists.json
│   ├── favorites.json
│   └── activity_history.csv
└── gdpr-data/

Option 2: Export with TV Time GDPR

TV Time also provides a GDPR data export portal.

Steps

1. Go to the TV Time GDPR export page.
2. Sign in with your TV Time account.
3. Request or generate your personal data export.
4. Download the export when it is available.
5. Extract the ZIP file.
6. Place the extracted CSV files in a directory, for example:

gdpr-data/

The converter currently uses these GDPR files:

followed_tv_show.csv
seen_episode_latest.csv

The GDPR export is mainly used as a fallback when no TV Time Liberator metadata is available.

Installation

Clone or download this repository:

git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
cd YOUR_REPOSITORY

Make sure the script is executable:

chmod +x convert-tvtime-to-ryot.js

You can run it directly with Node.js:

node convert-tvtime-to-ryot.js

Or, if executable permissions are set:

./convert-tvtime-to-ryot.js

Usage

Default usage

By default, the script expects this structure:

parent-directory/
├── tv-time-export/
├── gdpr-data/
└── repository/
    └── convert-tvtime-to-ryot.js

Default paths used by the script:

../tv-time-export
../gdpr-data
./ryot-complete-export.json

Run:

node convert-tvtime-to-ryot.js

This generates:

ryot-complete-export.json

Custom paths

You can specify the TV Time Liberator directory, the GDPR directory and the output file manually.

node convert-tvtime-to-ryot.js \
  --liberator ./tv-time-export \
  --gdpr ./gdpr-data \
  --output ./ryot-complete-export.json

Pretty JSON output

Use --pretty if you want the generated JSON to be easier to inspect manually:

node convert-tvtime-to-ryot.js \
  --liberator ./tv-time-export \
  --gdpr ./gdpr-data \
  --output ./ryot-complete-export.json \
  --pretty

Help

node convert-tvtime-to-ryot.js --help

Importing into RYOT

The script generates a RYOT CompleteExport JSON file.

To import it into RYOT:

1. Open RYOT.
2. Go to the import section.
3. Choose Generic JSON importer.
4. Upload the generated file:

ryot-complete-export.json

5. Start the import.
6. Review the imported movies, shows, watched episodes and collections.

Depending on your RYOT version and database size, the import may take some time because RYOT needs to fetch and match metadata.

Output example

After running the script, you will see a summary similar to this:

{
  "output": "/path/to/ryot-complete-export.json",
  "summary": {
    "collections": 3,
    "metadata": 250,
    "movies": 80,
    "shows": 170,
    "seen_history": 2300,
    "custom_source_items": 2,
    "warnings": 4
  },
  "warnings": []
}

Warnings

The script may print warnings when some data cannot be matched cleanly.

Common warnings include:

Movie without TVDB exported as custom
Show without TVDB exported as custom
List item not found in metadata
Watchlist item not found in metadata

These warnings do not always mean the import failed. They usually mean that some items could not be matched using a TVDB identifier and were exported as custom metadata instead.

How matching works

When possible, the script uses TVDB identifiers from the TV Time export.

Items with a valid TVDB ID are exported with:

"source": "tvdb"

Items without a valid TVDB ID are exported as:

"source": "custom"

Custom items may require manual cleanup or matching inside RYOT after import.

Data source priority

The script uses the following logic:

1. If TV Time Liberator data exists and contains metadata, it uses Liberator.
2. If Liberator metadata is not available, it tries to build TV show history from the GDPR export.
3. It generates one RYOT CompleteExport JSON file.

For the most complete migration, provide both exports.

Recommended workflow

mkdir tv-time-to-ryot
cd tv-time-to-ryot

# Place the script here
cp /path/to/convert-tvtime-to-ryot.js .

# Place your exports here
mkdir tv-time-export
mkdir gdpr-data

# Copy/extract TV Time Liberator files into ./tv-time-export
# Copy/extract TV Time GDPR files into ./gdpr-data

node convert-tvtime-to-ryot.js \
  --liberator ./tv-time-export \
  --gdpr ./gdpr-data \
  --output ./ryot-complete-export.json \
  --pretty

Then import ryot-complete-export.json into RYOT using the Generic JSON importer.

Limitations

• The script depends on the structure of TV Time Liberator and TV Time GDPR exports.
• Movies are best imported from TV Time Liberator data.
• GDPR fallback support is focused on TV show history.
• Items without TVDB IDs may be imported as custom metadata.
• Some items may need manual cleanup inside RYOT.
• Imports are not guaranteed to be perfect, especially if TV Time data is incomplete or inconsistent.

Privacy

This script runs locally.

It does not send your TV Time data anywhere. Your data is only read from the local export directories and written to the generated RYOT JSON file.

License

MIT

Disclaimer

This project is not affiliated with TV Time, RYOT, or TV Time Liberator.

Use it at your own risk and always keep a backup of your original TV Time exports before importing anything into RYOT.