Skip to content

Commit

Permalink
docs: add description of all configuration options
Browse files Browse the repository at this point in the history
  • Loading branch information
@cecobask
cecobask committed Jan 11, 2025
1 parent 3eb81e0 commit 7bcca02
Show file tree
Hide file tree
Showing 3 changed files with 222 additions and 77 deletions.
201 changes: 195 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,220 @@
[![sync](https://github.com/cecobask/imdb-trakt-sync/actions/workflows/sync.yaml/badge.svg)](https://github.com/cecobask/imdb-trakt-sync/actions/workflows/sync.yaml)
[![quality](https://github.com/cecobask/imdb-trakt-sync/actions/workflows/quality.yaml/badge.svg)](https://github.com/cecobask/imdb-trakt-sync/actions/workflows/quality.yaml)

# imdb-trakt-sync

<img src="./assets/logo.png" alt="logo"/>

Command line application that can sync [IMDb](https://www.imdb.com/) and [Trakt](https://trakt.tv/dashboard) user data - watchlist, lists, ratings and optionally history.
Command line application that can sync [IMDb](https://www.imdb.com/) and [Trakt](https://trakt.tv/dashboard) user data - watchlist, lists, ratings and history.
To achieve its goals the application is using the [Trakt API](https://trakt.docs.apiary.io/) and web scraping.
Keep in mind that this application is performing one-way sync from IMDb to Trakt. This means that any changes made on IMDb will be reflected on Trakt, but not the other way around.

# Configuration

<table>
<tr>
<th>FIELD NAME</th>
<th>DEFAULT VALUE</th>
<th>ALLOWED VALUES</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>IMDB_AUTH</td>
<td>cookies</td>
<td>
credentials<br />
cookies<br />
none
</td>
<td>
Authentication method to be used for IMDb:<br />
<code>credentials</code> => IMDB_EMAIL + IMDB_PASSWORD field required<br />
<code>cookies</code> => IMDB_COOKIEATMAIN + IMDB_COOKIEUBIDMAIN fields required<br />
<code>none</code> => IMDB_LISTS field required
</td>
</tr>
<tr>
<td>IMDB_EMAIL</td>
<td>-</td>
<td>-</td>
<td>IMDb account email address. Only required when IMDB_AUTH => <code>credentials</code></td>
</tr>
<tr>
<td>IMDB_PASSWORD</td>
<td>-</td>
<td>-</td>
<td>IMDb account password. Only required when IMDB_AUTH => <code>credentials</code></td>
</tr>
<tr>
<td>IMDB_COOKIEATMAIN</td>
<td>-</td>
<td>-</td>
<td>
Cookie value only required when IMDB_AUTH => <code>cookies</code>. Get the following cookie information from
your browser:<br />
<code>name: at-main | domain: .imdb.com</code>
</td>
</tr>
<tr>
<td>IMDB_COOKIEUBIDMAIN</td>
<td>-</td>
<td>-</td>
<td>
Cookie value required when IMDB_AUTH => <code>cookies</code>. Get the following cookie information from your
browser:<br />
<code>name: ubid-main | domain: .imdb.com</code>
</td>
</tr>
<tr>
<td>IMDB_LISTS</td>
<td>-</td>
<td>-</td>
<td>
Array of IMDb list IDs that you would like synced to Trakt. If this array is not specified or empty, all
IMDb lists on your account will be synced to Trakt. In order to get the ID of an IMDb list, open it from a
browser - the ID is in the URL with format <code>ls#########</code>. If provided as GitHub secret or
environment variable, define its values as comma-separated list. Keep in mind the <a
href="https://forums.trakt.tv/t/personal-list-updates/10170#limits-3">Trakt list limits</a>!
</td>
</tr>
<tr>
<td>IMDB_TRACE</td>
<td>false</td>
<td>
true<br />
false
</td>
<td>Print tracing logs related to browser activities. Can be useful for debugging purposes</td>
</tr>
<tr>
<td>IMDB_HEADLESS</td>
<td>true</td>
<td>
true<br />
false
</td>
<td>
Whether to run the browser in headless mode or not. Only set this to false when running the syncer locally
</td>
</tr>
<tr>
<td>IMDB_BROWSERPATH</td>
<td>-</td>
<td>-</td>
<td>
The location of your preferred web browser. If you leave this value empty, the syncer will attempt to lookup
common browser locations. You can optionally override its value to use a specific browser
</td>
</tr>
<tr>
<td>SYNC_MODE</td>
<td>dry-run</td>
<td>
full<br />
add-only<br />
dry-run
</td>
<td>
Sync mode to be used when running the application:<br />
<code>full</code> => add Trakt items that don't exist, delete Trakt items that don't exist on IMDb,
update<br />
Trakt items by treating IMDb as the source of truth<br />
<code>add-only</code> => add Trakt items that do not exist, but do not delete anything<br />
<code>dry-run</code> => identify what Trakt items would be added / deleted / updated
</td>
</tr>
<tr>
<td>SYNC_HISTORY</td>
<td>false</td>
<td>
true<br />
false
</td>
<td>Whether to sync history or not. When IMDB_AUTH => <code>none</code>, history sync will be skipped</td>
</tr>
<tr>
<td>SYNC_RATINGS</td>
<td>true</td>
<td>
true<br />
false
</td>
<td>Whether to sync ratings or not. When IMDB_AUTH => <code>none</code>, ratings sync will be skipped</td>
</tr>
<tr>
<td>SYNC_WATCHLIST</td>
<td>true</td>
<td>
true<br />
false
</td>
<td>Whether to sync watchlist or not. When IMDB_AUTH => <code>none</code>, watchlist sync will be skipped</td>
</tr>
<tr>
<td>SYNC_LISTS</td>
<td>true</td>
<td>
true<br />
false
</td>
<td>Whether to sync lists or not. This provides the option to disable syncing of lists</td>
</tr>
<tr>
<td>SYNC_TIMEOUT</td>
<td>15m</td>
<td>-</td>
<td>
Maximum duration to run the syncer. Users with large libraries might have to increase the timeout value
accordingly. Valid time units are: ns, us (or µs), ms, s, m, h
</td>
</tr>
<tr>
<td>TRAKT_CLIENTID</td>
<td>-</td>
<td>-</td>
<td>Trakt app client ID</td>
</tr>
<tr>
<td>TRAKT_CLIENTSECRET</td>
<td>-</td>
<td>-</td>
<td>Trakt app client secret</td>
</tr>
<tr>
<td>TRAKT_EMAIL</td>
<td>-</td>
<td>-</td>
<td>Trakt account email address (do NOT confuse with username)</td>
</tr>
<tr>
<td>TRAKT_PASSWORD</td>
<td>-</td>
<td>-</td>
<td>Trakt account password</td>
</tr>
</table>

# Usage
The application can be setup to run automatically, based on a custom schedule (_default: once every 12 hours_) using **GitHub Actions** or locally on your machine.

The application can be setup to run automatically, based on a custom schedule (_default: once every 12 hours_) using **GitHub Actions**, in a container, or locally on your machine.
Workflow schedules can be tweaked by editing the [.github/workflows/sync.yaml](.github/workflows/sync.yaml) file and committing the changes.
There are 3 possible modes to run this application and more details can be found in the [config.yaml](config.yaml) file.
Please configure the application to suits your needs, by referring to the [Configuration](#configuration) section, before running it.
Follow the relevant section below, based on how you want to use the application.

## Run the application using GitHub Actions

1. [Fork the repository](https://github.com/cecobask/imdb-trakt-sync/fork) to your account
2. Create a [Trakt App](https://trakt.tv/oauth/applications). Use **urn:ietf:wg:oauth:2.0:oob** as redirect uri
3. Configure the application:
- Open your fork repository on GitHub
- Create an individual repository secret for each [configuration](config.yaml) parameter: `Settings` > `Secrets and variables` > `Actions` > `New repository secret`
- The secret names should match the configuration parameter paths (delimited by underscore). For example, to configure your Trakt email, the secret name should be **TRAKT_EMAIL**
- Create an individual repository secret for each [Configuration](#configuration) field you need: `Settings` > `Secrets and variables` > `Actions` > `New repository secret`
4. Allow GitHub Actions on your fork repository: `Settings` > `Actions` > `General` > `Allow all actions and reusable workflows`
5. Enable the **sync** workflow: `Actions` > `Workflows` > `sync` > `Enable workflow`
6. Run the **sync** workflow manually: `Actions` > `Workflows` > `sync` > `Run workflow`
7. From now on, GitHub Actions will automatically trigger the **sync** workflow
7. From now on, GitHub Actions will automatically trigger the **sync** workflow based on your schedule

## Run the application in a Docker container

1. Install [Docker](https://www.docker.com/get-started)
2. Clone the repository: `git clone [email protected]:cecobask/imdb-trakt-sync.git`
3. Create a [Trakt App](https://trakt.tv/oauth/applications). Use **urn:ietf:wg:oauth:2.0:oob** as redirect uri
Expand All @@ -39,6 +227,7 @@ Follow the relevant section below, based on how you want to use the application.
- Run the sync workflow in a Docker container: `make sync-container`

## Run the application locally

1. Install [Git](https://git-scm.com/downloads) and [Go](https://go.dev/doc/install)
2. Clone the repository: `git clone [email protected]:cecobask/imdb-trakt-sync.git`
3. Create a [Trakt App](https://trakt.tv/oauth/applications). Use **urn:ietf:wg:oauth:2.0:oob** as redirect uri
Expand Down
92 changes: 21 additions & 71 deletions config.yaml
View file
Original file line number Diff line number Diff line change
@@ -1,74 +1,24 @@
IMDB:
# Authentication method to be used for IMDb
# The value must be one of the following:
# credentials - dependent fields [IMDB_EMAIL] [IMDB_PASSWORD]
# cookies - dependent fields [IMDB_COOKIEATMAIN] [IMDB_COOKIEUBIDMAIN]
# none - no dependent fields
AUTH: cookies
# IMDb account email address
EMAIL: [email protected]
# IMDb account password
PASSWORD: password123
# The cookies can be used as a fallback if captcha is preventing the authentication flow
# Log into your IMDb account from a web browser, inspect the cookies and retrieve the value of cookie:
# name: at-main | domain: .imdb.com
COOKIEATMAIN: zAta|RHiA67JIrBDPaswIym3GyrTlEuQH-u9yrKP3BUNCHgVyE4oNtUzBYVKlhjjzBiM_Z-GSVnH9rKW3Hf7LdbejovoF6SI4ZmgJcTIUXoA4NVcH1Qahwm0KYCyz95o1gsgby-uQwdU6CoS6MFTnjMkLe1puNiv4uFkvo8mOQulJJeutzYedxiUd0ns9w1X_WeVXPTZWjwisPZMw3EOR6-q9xR4kCEWRW7CmWxU1AEDQbT8ns_AJJD34w1nIQUkuLgBQrvJI_pY
# The cookies can be used as a fallback if captcha is preventing the authentication flow
# Log into your IMDb account from a web browser, inspect the cookies and retrieve the value of cookie:
# name: ubid-main | domain: .imdb.com
COOKIEUBIDMAIN: 301-0710501-5367639
# Array of IMDb lists that you would like synced to Trakt
# If this array is empty, all IMDb lists will be synced to Trakt
# Keep in mind the maximum number of lists you can have in Trakt: https://twitter.com/trakt/status/1536751362943332352
# In order to get the ID of an IMDb list, open it from a browser - the ID is in the URL with format ls#########
LISTS:
- ls000000000
- ls111111111
# Print tracing logs related to browser activities
# Can be useful for debugging purposes
TRACE: false
# Whether to run the browser in headless mode or not
# For local debugging you can set this value to false
# If running via GitHub Actions or other CI the value will always be true
HEADLESS: true
# The location of your preferred web browser
# This browser is going to be used for web scraping
# For local invocations you can override its value to match your own browser path
# Alternatively, if you leave this value empty, the syncer will attempt to lookup common browser locations
BROWSERPATH:
AUTH: cookies
EMAIL: [email protected]
PASSWORD: password123
COOKIEATMAIN: zAta|RHiA67JIrBDPaswIym3GyrTlEuQH-u9yrKP3BUNCHgVyE4oNtUzBYVKlhjjzBiM_Z-GSVnH9rKW3Hf7LdbejovoF6SI4ZmgJcTIUXoA4NVcH1Qahwm0KYCyz95o1gsgby-uQwdU6CoS6MFTnjMkLe1puNiv4uFkvo8mOQulJJeutzYedxiUd0ns9w1X_WeVXPTZWjwisPZMw3EOR6-q9xR4kCEWRW7CmWxU1AEDQbT8ns_AJJD34w1nIQUkuLgBQrvJI_pY
COOKIEUBIDMAIN: 301-0710501-5367639
LISTS:
- ls000000000
- ls111111111
TRACE: false
HEADLESS: true
BROWSERPATH:
SYNC:
# Sync mode to be used when running the application
# The value must be one of the following:
# full - add Trakt items that do not exist, delete Trakt items that do not exist on IMDb, update Trakt items by treating IMDb as the source of truth
# add-only - add Trakt items that do not exist, but do not delete anything
# dry-run - identify what Trakt items would be added / deleted / updated
MODE: dry-run
# Whether to sync history or not. If set to true, history will be synced
# When IMDB_AUTH is none, history will be ignored
HISTORY: false
# Whether to sync ratings or not. If set to true, ratings will be synced
# When IMDB_AUTH is none, ratings will be ignored
RATINGS: true
# Whether to sync watchlist or not. If set to true, watchlist will be synced
# When IMDB_AUTH is none, watchlist will be ignored
WATCHLIST: true
# Whether to sync lists or not. If set to true, lists will be synced
# This provides the option to disable syncing of your lists
LISTS: true
# Maximum duration to run the syncer
# Users with large IMDb/Trakt libraries might have to increase the timeout value accordingly
# Valid time units are: ns, us (or µs), ms, s, m, h
TIMEOUT: 15m
MODE: dry-run
HISTORY: false
RATINGS: true
WATCHLIST: true
LISTS: true
TIMEOUT: 15m
TRAKT:
# Trakt app client ID
# You need to replace this value with your own, the default value is for illustrative purposes only
CLIENTID: 828832482dea6fffa4453f849fe873de8be54791b9acc01f6923098d0a62972d
# Trakt app client secret
# You need to replace this value with your own, the default value is for illustrative purposes only
CLIENTSECRET: bdf9bab88c17f3710a6394607e96cd3a21dee6e5ea0e0236e9ed06e425ed8b6f
# Trakt account email address (not to be confused with username)
# You need to replace this value with your own, the default value is for illustrative purposes only
EMAIL: [email protected]
# Trakt account password
# You need to replace this value with your own, the default value is for illustrative purposes only
PASSWORD: password123
CLIENTID: 828832482dea6fffa4453f849fe873de8be54791b9acc01f6923098d0a62972d
CLIENTSECRET: bdf9bab88c17f3710a6394607e96cd3a21dee6e5ea0e0236e9ed06e425ed8b6f
EMAIL: [email protected]
PASSWORD: password123
6 changes: 6 additions & 0 deletions internal/config/config.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,9 @@ func (c *Config) checkDummies() error {
}

func (c *Config) applyDefaults() {
if c.IMDb.Auth == nil {
c.IMDb.Auth = pointer(IMDbAuthMethodCookies)
}
if c.IMDb.Lists == nil {
c.IMDb.Lists = pointer(make([]string, 0))
}
Expand All @@ -204,6 +207,9 @@ func (c *Config) applyDefaults() {
if c.IMDb.BrowserPath == nil {
c.IMDb.BrowserPath = pointer("")
}
if c.Sync.Mode == nil {
c.Sync.Mode = pointer(SyncModeDryRun)
}
if c.Sync.History == nil {
c.Sync.History = pointer(false)
}
Expand Down

0 comments on commit 7bcca02

Please sign in to comment.