From d856cb81d8b1f4f5caf3689487f7bfef4183d0fb Mon Sep 17 00:00:00 2001 From: Andy Date: Fri, 18 Jul 2025 01:11:44 +0000 Subject: [PATCH] refactor: streamline README by removing outdated service and legal information and moved it directly to the WIKI --- README.md | 175 ------------------------------------------------------ 1 file changed, 175 deletions(-) diff --git a/README.md b/README.md index 1f38677..098000d 100644 --- a/README.md +++ b/README.md @@ -70,184 +70,12 @@ For comprehensive setup guides, configuration options, and advanced usage: The WIKI contains detailed information on: -- Installation and dependencies - Service configuration -- Authentication setup - DRM configuration - Advanced features and troubleshooting -> [!WARNING] -> Only create or use services for platforms you have the legal right to access. - For guidance on creating services, see our [WIKI documentation](https://github.com/unshackle-dl/unshackle/wiki). -## License - -This software is licensed under the [GNU General Public License, Version 3.0](LICENSE). - -**⚖️ Legal Notice**: Use unshackle responsibly and only with content you have the legal right to access and download. - -## Services - -unshackle doesn't include any services by default. You must create your own services for the platforms you have legal access to. - -Unlike similar project's such as [youtube-dl], unshackle does not currently come with any Services. You must develop your -own Services and only use unshackle with Services you have the legal right to do so. - -> [!NOTE] -> If you made a Service for unshackle 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 -> unshackle repository as they both use the [Unlicense license] therefore direct reading and porting of their code would be -> legal. - -### Service Tags - -Service tags generally follow these rules: - -- Tag can 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 we 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 unshackle 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 ` and then `cd` into it. -3. `git remote add upstream https://github.com/unshackle-dl/unshackle` -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](https://desktop.github.com). - -> [!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 -Drive, a non-fork repository with just services, and more. - -1. Use any Cloud Source that gives you a pseudo-directory to access the Service files like a normal drive. E.g., rclone, - Google Drive Desktop (aka File Stream), Air Drive, CloudPool, etc. -2. Create a `services` directory somewhere in it and have all your services within it. -3. [Symlink](https://en.wikipedia.org/wiki/Symbolic_link) the `services` directory to the `/unshackle` folder. You should - end up with `/unshackle/services` folder containing services, not `/unshackle/services/services`. - -You have to make sure the original folder keeps receiving and downloading/streaming those changes. You must also make -sure that the version of unshackle you have locally is supported by the Service code. - -> [!NOTE] -> If you're using a cloud source that downloads the file once it gets opened, you don't have to worry as those will -> automatically download. Python importing the files triggers the download to begin. However, it may cause a delay on -> startup. - -## Cookies & Credentials - -unshackle can authenticate with Services using Cookies and/or Credentials. Credentials are stored in the config, and -Cookies are stored in the data directory which can be found by running `unshackle env info`. - -To add a Credential to a Service, take a look at the [Credentials Config](CONFIG.md#credentials-dictstr-strlistdict) -for information on setting up one or more credentials per-service. You can add one or more Credential per-service and -use `-p/--profile` to choose which Credential to use. - -To add a Cookie to a Service, use a Cookie file extension to make a `cookies.txt` file and move it into the Cookies -directory. You must rename the `cookies.txt` file to that of the Service tag (case-sensitive), e.g., `NF.txt`. You can -also place it in a Service Cookie folder, e.g., `/Cookies/NF/default.txt` or `/Cookies/NF/.txt`. - -You can add multiple Cookies to the `/Cookies/NF/` folder with their own unique name and then use `-p/--profile` to -choose which one to use. E.g., `/Cookies/NF/sam.txt` and then use it with `--profile sam`. If you make a Service Cookie -folder without a `.txt` or `default.txt`, but with another file, then no Cookies will be loaded unless you use -`-p/--profile` like shown. This allows you to opt in to authentication at whim. - -> - If your Service does not require Authentication, then do not define any Credential or Cookie for that Service. -> - You can use both Cookies and Credentials at the same time, so long as your Service takes and uses both. -> - If you are using profiles, then make sure you use the same name on the Credential name and Cookie file name when -> using `-p/--profile`. -> [!WARNING] -> Profile names are case-sensitive and unique per-service. They have no arbitrary character or length limit, but for -> convenience sake we don't recommend using any special characters as your terminal may get confused. - -### Cookie file format and Extensions - -Cookies must be in the standard Netscape cookies file format. -Recommended Cookie exporter extensions: - -- Firefox: "[Export Cookies]" by `Rotem Dan` -- Chromium: "[Open Cookies.txt]" by `Ninh Pham` - -Any other extension that exports to the standard Netscape format should theoretically work. - -## Widevine Provisions - -A Widevine Provision is needed for acquiring licenses containing decryption keys for DRM-protected content. -They are not needed if you will be using unshackle on DRM-free services. Please do not ask for any widevine Device Files, -Keys, or Provisions as they cannot be provided. - -unshackle only supports `.WVD` files (widevine Device Files). However, if you have the Provision RSA Private Key and -Device Client Identification Blob as blob files (e.g., `device_private_key` and `device_client_id_blob`), then you can -convert them to a `.WVD` file by running `pywidevine create-device --help`. - -Once you have `.WVD` files, place them in the WVDs directory which can be found by calling `uv run unshackle env info`. -You can then set in your config which WVD (by filename only) to use by default with `uv run unshackle cfg cdm.default wvd_name`. -From here you can then set which WVD to use for each specific service. It's best to use the lowest security-level -provision where possible. - -An alternative would be using a pywidevine Serve-compliant CDM API. Of course, you would need to know someone who is -serving one, and they would need to give you access. Take a look at the [remote_cdm](CONFIG.md#remotecdm-listdict) -config option for setup information. For further information on it see the pywidevine repository. - -## PlayReady Device (PRD) Provisions - -Similarly, a PlayReady Device file (.PRD) is needed for acquiring licenses and decryption keys for PlayReady DRM-protected content. -PRD files are not required for DRM-free services. unshackle only supports `.PRD` files (PlayReady Device Files). - -To create or manage PRD files, use the built-in CLI commands: - -- `uv run unshackle prd new` — Create a new PRD file from device keys and certificates -- `uv run unshackle prd reprovision` — Reprovision an existing PRD file with new keys -- `uv run unshackle prd test` — Test a PRD file against the Microsoft PlayReady demo server - -Once you have `.PRD` files, place them in the `PRDs/` directory (see `uv run unshackle env info` for the path). -You can set the default PRD file in your config with `uv run unshackle cfg cdm.default prd_name`. -Service-specific PRD files can also be set in the config, just like Widevine. -For best compatibility, use the lowest security-level PRD file available. - -Do not ask for PRD device files, keys, or provisions as they cannot be provided. Only use PRD files for services you have the legal right to access. - ## End User License Agreement unshackle and it's community pages should be treated with the same kindness as other projects. @@ -271,6 +99,3 @@ You can find a copy of the license in the LICENSE file in the root folder. [Export Cookies]: https://addons.mozilla.org/addon/export-cookies-txt [Open Cookies.txt]: https://chrome.google.com/webstore/detail/gdocmgbfkjnnpapoeobnolbbkoibbcif -[Unlicense license]: https://choosealicense.com/licenses/unlicense -[youtube-dl]: https://github.com/ytdl-org/youtube-dl -[yt-dlp]: https://github.com/yt-dlp/yt-dlp