TheChosenDownloader

This project contains the tools to download all episodes of The Chosen (TV show) as mkv's in any available language and video quality.

Version 2.0 of this project simplifies the process by having just one script to do all the work.

Unfortunately, The Chosen still keeps their latest season "under lock and key" which in this case means that to download Season 5 you need to obtain a viewer token from the official site to gain access to the downloads. Instructions for that are below.

Usage Instructions

1. Install dependencies

   • Make sure you have Python 3.7+ installed.
   • Install required Python packages:

     pip install -r requirements.txt

   • You also need yt-dlp and ffmpeg installed and available in your PATH.

2. Prepare your CSV file

   • The default input file is urls.csv. It should contain columns: url, season, episode, title.

3. Run the script

   • Basic usage:

     python3 download.py

   • For a dry run (shows what would be downloaded, checks URLs):

     python3 download.py --dry-run

   • To specify options (see python3 download.py --help for all options):

     python3 download.py -s 1,2 -a en,es --subtitle-language en,es -v 1080p -f mkv -o downloads/

   • To filter by specific episodes (requires season to be specified):

     python3 download.py -s 1 -e 1,2,3

   • Multi-audio and subtitle selection:

     • You can specify multiple audio or subtitle languages using a comma-separated list (e.g., -a en,es --subtitle-language en,es).
     • If you select more than one audio or subtitle track, it is recommended to use -f mkv for proper multi-track playback.

   • Descriptive audio flag:

     • By default, the script will select the standard audio track for a language (e.g., English) and avoid tracks labeled as "Audio Description".
     • To select descriptive audio tracks ("Audio Description") when available, use the --descriptive-audio flag:

       python3 download.py -a en --descriptive-audio

     • If both standard and descriptive tracks exist, the flag ensures the descriptive track is chosen.

4. Viewer Token

   • If you encounter a 403 Forbidden error, the script will create a file called viewer-token.txt in the project directory.
   • You must obtain your viewer token and paste it into this file.
   • The script will automatically retry URLs using your token.

How to Obtain Your Viewer Token

Note: This step must be done manually until the login protocol for The Chosen's watch site is reverse-engineered.

Follow these steps to obtain your viewer token:

1. Create an account on watch.thechosen.tv and log in.
2. Navigate to any episode's watch page (season 5 is recommended).
3. Open your browser's developer tools:
   • On Chrome: Right-click the page and select Inspect.
4. Go to the Network tab in developer tools.
   • Reload the page to capture all network requests.
5. Look for a request to hls.m3u8 or stream.m3u8.
   • The request URL will look like: hls.m3u8?viewerToken=XYZ
6. Copy the viewer token:
   • The value after viewerToken= (a long string of characters).
7. Paste the token into the viewer-token.txt file in your project directory.

Once you have added your token, rerun the script. The script will use your token to access protected streams.