devine

Features

• 🚀 Seamless Installation via pip

• 🎥 Movie, Episode, and Song Service Frameworks

• 🛠️ Built-in DASH and HLS Parsers

• 🔒 Widevine DRM integration via pywidevine

• 💾 Local & Remote DRM Key-vaults

• 🌍 Local & Remote Widevine CDMs

• 👥 Multi-profile Authentication per-service with Credentials and/or Cookies

• 🤖 Automatic P2P filename structure with Group Tag

• ⚙️ YAML for Configuration

• ❤️ Fully Open-Source! Pull Requests Welcome

Installation

$ pip install devine

[!NOTE] If pip gives you a warning about a path not being in your PATH environment variable then promptly add that path then close all open command prompt/terminal windows, or devine won't work as it will not be found.

Voilà 🎉 — You now have the devine package installed!
A command-line interface is now available, try devine --help.

Dependencies

The following is a list of programs that need to be installed by you manually.

• CCExtractor for extracting Closed Caption data like EIA-608 from video streams and converting as SRT.
• FFmpeg (and ffprobe) for repacking/remuxing streams on specific services, and evaluating stream data.
• MKVToolNix v54+ for muxing individual streams to an .mkv file.
• shaka-packager for decrypting CENC-CTR and CENC-CBCS video and audio streams.
• (optional) aria2(c) to use as a downloader.

[!TIP] You should install these from a Package Repository if you can; including winget/chocolatey on Windows. They will automatically add the binary's path to your PATH environment variable and will be easier to update in the future.

[!IMPORTANT] Most of these dependencies are portable utilities and therefore do not use installers. If you do not install them from a package repository like winget/choco/pacman then make sure you put them in your current working directory, in Devine's installation directory, or the binary's path into your PATH environment variable. If you do not do this then Devine will not be able to find the binaries.

Usage

First, take a look at devine --help for a full help document, listing all commands available and giving you more information on what can be done with Devine.

Here's a checklist on what I recommend getting started with, in no particular order,

• Add Services, these will be used in devine dl.
• Add Profiles, these are your cookies and credentials.
• Add Widevine Provisions, also known as CDMs, these are used for DRM-protected content.
• Set your Group Tag, the text at the end of the final filename, e.g., devine cfg tag NOGRP for ...-NOGRP.
• Set Up a Local Key Vault, take a look at the Key Vaults Config.

And here's some more advanced things you could take a look at,

• Setting default Headers that the Request Session uses.
• Setting default Profiles and CDM Provisions to use for services.
• NordVPN and Hola Proxy Providers for automatic proxies.
• Hosting and/or Using Remote Key Vaults.
• Serving and/or Using Remote CDM Provisions.

Documentation on the config is available in the CONFIG.md file, it has a lot of handy settings.
If you start to get sick of putting something in your CLI call, then I recommend taking a look at it!

Services

Unlike similar project's such as youtube-dl, Devine does not currently come with any Services. You must develop your own Services and only use Devine with Services you have the legal right to do so.

[!NOTE] If you made a Service for Devine that does not use Widevine or any other DRM systems, feel free to make a Pull Request and make your service available to others. Any Service on youtube-dl (or yt-dlp) would be able to be added to the Devine repository as they both use the Unlicense license therefore direct reading and porting of their code would be legal.

Creating a Service

[!WARNING] Only create or use Service Code with Services you have full legal right to do so.

A Service consists of a folder with an __init__.py file. The file must contain a class of the same name as the folder. The class must inherit the Service class and implement all the abstracted methods. It must finally implement a new method named cli where you define CLI arguments.

1. Make a new folder within /devine/services. The folder name you choose will be what's known as the Service Tag. This "tag" is used in the final output filename of downloaded files, for various code-checks, lookup keys in key-vault databases, and more.
2. Within the new folder create an __init__.py file and write a class inheriting the Service class. It must be named the exact same as the folder. It is case-sensitive.
3. Implement all the methods of the Service class you are inheriting that are marked as abstract.
4. Define CLI arguments by implementing a cli method. This method must be static (i.e. @staticmethod). For example to implement the bare minimum to receive a Title ID of sorts:

   @staticmethod
   @click.command(name="YT", short_help="https://youtube.com", help=__doc__)
   @click.argument("title", type=str)
   @click.pass_context
   def cli(ctx, **kwargs):
       return YT(ctx, **kwargs)
   

   You must implement this cli method, even if you do not want or need any CLI arguments. It is required for the core CLI functionality to be able to find and call the class.
5. Accept the CLI arguments by overriding the constructor (the __init__() method):

   def __init__(self, ctx, title):
       self.title = title
       super().__init__(ctx)  # important
       # ... the title is now available across all methods by calling self.title
   

[!NOTE]

• All methods of your class inherited from Service marked as abstract (@abstractmethod) MUST be implemented by your class.
• When overriding any method (e.g., __init__() method) you MUST super call it, e.g., super().__init__() at the top of the override. This does not apply to any abstract methods, as they are unimplemented.
• If preparing your Requests Session with global headers or such, then you should override the get_session method, then modify self.session. Do not manually make self.session from scratch.

[!TIP]

1. To make web requests use the self.session class instance variable, e.g. self.session.get(url).
2. If you make a config.yaml file next to your __init__.py, you can access it with self.config.
3. You can include any arbitrary file within your Service folder for use by your Service. For example TLS certificate files, or other python files with helper functions and classes.

Service Tags

Service tags generally follow these rules:

• Tag must be between 2-4 characters long, consisting of just [A-Z0-9i]{2,4}.
  • Lower-case i is only used for select services. Specifically BBC iPlayer and iTunes.
• If the Service's commercial name has a + or Plus, the last character should be a P. E.g., ATVP for Apple TV+, DSCP for Discovery+, DSNP for Disney+, and PMTP for Paramount+.

These rules are not exhaustive and should only be used as a guide. You don't strictly have to follow these rules, but I recommend doing so for consistency.

Sharing Services

Sending and receiving zipped Service folders is quite cumbersome. Let's explore alternative routes to collaborating on Service Code.

[!WARNING] Please be careful with who you trust and what you run. The users you collaborate with on Service code could update it with malicious code that you would run via devine on the next call.

Forking

If you are collaborating with a team on multiple services then forking the project is the best way to go.

1. Create a new Private GitHub Repository without README, .gitignore, or LICENSE files. Note: Do NOT use the GitHub Fork button, or you will not be able to make the repository private.
2. git clone <your repo url here> and then cd into it.
3. git remote add upstream https://github.com/devine-dl/devine
4. git remote set-url --push upstream DISABLE
5. git fetch upstream
6. git pull upstream master
7. (optionally) Hard reset to the latest stable version by tag. E.g., git reset --hard v1.0.0.

Now commit your Services or other changes to your forked repository.
Once committed all your other team members can easily pull changes as well as push new changes.

When a new update comes out you can easily rebase your fork to that commit to update.

1. git fetch upstream
2. git rebase upstream/master

However, please make sure you look at changes between each version before rebasing and resolve any breaking changes and deprecations when rebasing to a new version.

If you are new to git then take a look at GitHub Desktop.

[!TIP] A huge benefit with this method is that you can also sync dependencies by your own Services as well! Just use poetry to add or modify dependencies appropriately and commit the changed poetry.lock. However, if the core project also has dependency changes your poetry.lock changes will conflict and you will need to learn how to do conflict resolution/rebasing. It is worth it though!

Symlinking

This is a great option for those who wish to do something like the forking method, but may not care what changes happened or when and just want changes synced across a team.

This also opens up the ways you can host or collaborate on Service code. As long as you can receive a directory that updates with just the services within it, then you're good to go. Options could include an FTP server, Shared Google D