From e3125dfd3c0a555a28db780f95f8e010816490b0 Mon Sep 17 00:00:00 2001 From: Sp5rky Date: Thu, 17 Jul 2025 18:54:39 -0600 Subject: [PATCH] Created Services (markdown) --- Services.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 Services.md diff --git a/Services.md b/Services.md new file mode 100644 index 0000000..1ae712d --- /dev/null +++ b/Services.md @@ -0,0 +1,87 @@ +## 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. \ No newline at end of file