iSubRip is a Python command-line tool for downloading subtitles from Apple TV movie URLs.
- Scrape subtitles from Apple TV and iTunes movies you own or have rented.
- Retrieve the expected streaming release date (if available) for unreleased movies.
- Utilize asynchronous downloading to speed up the download of chunked subtitles.
- Automatically convert subtitles to SubRip (SRT) format.
- Fix right-to-left (RTL) alignment in RTL language subtitles automatically.
- Configure settings such as download folder, preferred languages, and toggling features.
Note
Apple previously allowed Apple TV master playlists to be fetched without account entitlement. They are now restricted to Apple Accounts that own or have rented the movie. See Issue #103 for more context.
pip install isubripisubrip [--dsid DSID] <URL> [URL...]Owned or rented content requires an Apple DSID. See Apple DSID for setup instructions.
Tip
Run isubrip --help for all command-line options.
A TOML configuration file is optional.
iSubRip looks for the configuration file in the following location, based on your operating system:
- Windows:
%USERPROFILE%\.isubrip\config.toml - Linux / macOS:
$HOME/.isubrip/config.toml
- Windows:
C:\Users\Michael\.isubrip\config.toml - Linux:
/home/Michael/.isubrip/config.toml - macOS:
/Users/Michael/.isubrip/config.toml
[downloads]
folder = "C:\\Subtitles\\AppleTV"
languages = ["en-US", "fr-FR", "he"]
zip = false
[subtitles]
convert-to-srt = true
fix-rtl = true
[subtitles.webvtt]
subrip-alignment-conversion = true
[scrapers.appletv]
dsid = "1234567890"Tip
An example config with details and explanations for all available settings can be found here.
Apple requires account entitlement before HLS manifests of paid content can be loaded. A DSID identifies the Apple account that owns or has rented the title.
Important
Support for locating or acquiring a DSID will not be provided. Please do not open issues requesting help with DSID acquisition.
Apple does not provide a documented way for third-party tools to look up a DSID. You can try the following steps to find your DSID:
- Sign in to Apple TV's Billing page using the Apple Account that owns or has rented the movie. If prompted to add a payment method, you can skip it; no billing changes are required.
- Open ph2.tv.apple.com/settings.
- Locate the
dsIdkey and copy its numeric value from the JSON response.
Configure the DSID using one of the following methods. If multiple methods are configured, --dsid overrides the
ISUBRIP_DSID environment variable, which overrides config.toml.
The configuration file is recommended for regular use:
[scrapers.appletv]
dsid = "1234567890"You can instead use an environment variable:
# Linux / macOS
export ISUBRIP_DSID="1234567890"
# Windows PowerShell
$env:ISUBRIP_DSID = "1234567890"For a one-off run, you can use the command-line flag:
isubrip --dsid 1234567890 <URL>Warning
The DSID is a numeric Apple account identifier. It is not a password or authentication cookie, but it is persistent, tied to your account, and should not be shared publicly.
Command-line arguments may be saved in shell history or visible to other local processes. It is safer to configure the DSID using the environment variable or the configuration file.
- If the response from ph2.tv.apple.com/settings contains
"message": "Sign-In Required", make sure you authenticated on the Apple TV Billing page, even if you are already signed in on the main Apple TV website. - Confirm that the DSID belongs to the Apple account that owns the movie or has an active rental.
- An Apple HTTP 404 with a configured DSID can mean that the account is not entitled to that title, the rental expired, or Apple changed the manifest access flow.
Log files are created for each run in the following paths, depending on your operating system:
Windows: %USERPROFILE%\.isubrip\logs
Linux / macOS: $HOME/.isubrip/logs
Log rotation (deletion of old files once a certain number of files is reached) can be configured in the configuration file using the general.log-rotation-size setting. The default value is 15.
For more details, see the example configuration.
The changelog for the latest, and all previous versions, can be found here.
This project is open-source but currently lacks the infrastructure to fully support external contributions.
If you wish to contribute, please open an issue first to discuss your proposed changes to avoid working on something that might not be accepted.
If you find this project helpful, please consider supporting it by:
- 🌟 Starring the repository
- 💖 Sponsoring the project
By using iSubRip, you agree to the following terms:
- Disclaimer of Affiliation: iSubRip is an independent, open-source project. It is not affiliated with, endorsed by, or in any way officially connected to Apple Inc., iTunes, or Apple TV.
- Educational Purpose: This tool is developed and provided for educational and research purposes only. It demonstrates techniques for accessing and processing subtitle data from HLS playlists for Apple TV / iTunes content the user is entitled to access.
- User Responsibility and Compliance: Any use of iSubRip is solely at the user's own risk and discretion. Users are responsible for ensuring that their use of the tool complies with all applicable laws, regulations, and terms of service of the content providers. This includes adhering to local, state, national, and international laws and regulations.
- Limitation of Liability: The developers of iSubRip shall not be held responsible for any legal consequences arising from the use of this tool. This includes, but is not limited to, claims of copyright infringement, intellectual property violations, or breaches of terms of service of content providers. Users assume all risks associated with acquiring and using subtitle data through this tool.
By using iSubRip, you acknowledge that you have read, understood, and agree to be bound by this agreement's terms and conditions.
This project is licensed under the MIT License. For more details, see the LICENSE file.