Unshackle - Modular Movie, TV, and Music Archival Software

[SummerArk]

Starting a new Unshackle discussion to keep it out of billybanana's Devine thread.

https://github.com/unshackle-dl/unshackle

Discuss away

[billybanana]

Haha, now get ready for all the PM'S you'll get from people thinking you're behind Unshackle. I've lived that Devine life just from starting the thread.

[Tom Saurus]

I might give it a try as long as I can still have Devine installed and working along side it. I also want to try Ozvine and AllHellYes.

[deccavox]

A couple of teething problems but, yes, much much much much easier to install than devine. I'm a great fan of uv and use it with all my scripts now. It makes the installation, installing dependencies and creating venvs a piece of piss. And it's incredibly easy to pass on a complete project to others and they have minimal work to do to get it going (usually just 'uv sync').

I've still to tailor my download settings in the unshackle.yaml file. I've installed it so that everything is completely self contained within its own folder (ie. not global). That's the way I prefer it. I've tested it out on the usual UK channels: ITVX, STV, iplayer, All4, My5, UKTV. Works well. I've done nothing fancy, just downlloaded individual epsisodes so far.

Let's hope that unshackle remains supported by the developer.

PS, did I mention how much easier it is to install than devine and bloody poetry

[ImSp4rky]

A couple of teething problems but, yes, much much much much easier to install than devine. I'm a great fan of uv and use it with all my scripts now. It makes the installation, installing dependencies and creating venvs a piece of piss. And it's incredibly easy to pass on a complete project to others and they have minimal work to do to get it going (usually just 'uv sync')...

I'm happy to try to clean up those teething problems; I want to make the general installation and preparation as seamless as possible. What parts caused issues other than copying services over and renaming the "from devine" to "from unshackle" I've added some additional commands for Windows/Mac/Unix for automating this process https://github.com/unshackle-dl/unshackle/wiki/Migration-from-Devine

Wiki has some initial information, but will be opening it further.

I'm looking to support this for the foreseeable future, as it's my primary tool for archiving my content.

Issues/problems can either be raised on Github or mentioned here and I will raise on your behalf.

[deccavox]

A couple of teething problems but, yes, much much much much easier to install than devine. I'm a great fan of uv and use it with all my scripts now. It makes the installation, installing dependencies and creating venvs a piece of piss. And it's incredibly easy to pass on a complete project to others and they have minimal work to do to get it going (usually just 'uv sync')...

I'm happy to try to clean up those teething problems; I want to make the general installation and preparation as seamless as possible.

My teething problems were my own stupidity. I was transfering some settings from my old devine.yaml to the new unshackle.yaml. My old used indents of 4 spaces. The new uses 2 spaces. Python doesn't like a mixture . Also, I had downloaded yesterday's version from github which didn't cater for srt subs. It does now.

Here's some of my thoughts if you want to add them to your future setup instructions.

I use Windows and the cmd.exe box.

I decided to do a clean install and not migrate my devine to unshackle.

For those who haven't installed uv, I'd recommend using pipx and not pip. uv is young and gets frequent updates. It's easier to update successfully with pipx. Install it globally so it can be used anywhere.

Open a cmd box (anywhere)
Install pipx (if you've never installed it before):

python -m pip install --user pipx

Install uv with pipx:

pipx install uv

In future, to update uv

pipx upgrade uv

With uv, you don't need to activate the venv. Using

uv run ....

at the CL does that. Nice and simple.

I wanted everything to be self contained within the project folder unshackle (ie. not global).

So,
go to the root folder you'll be installing unshackle

git clone https://github.com/unshackle-dl/unshackle.git
cd unshackle
uv sync
uv run unshackle --help

The last line proves it works.

You need to set up the \unshackle\unshackle\unshackle.yaml file.

Because I've made mine to be self contained, my paths:

directories:
  services: D:\unshackle\unshackle\services
  cache: D:\unshackle\cache
  cookies: D:\unshackle\cookies
#  dcsl: DCSL # Device Certificate Status List
  downloads: D:\unshackle\Downloads
  logs: D:\unshackle\Logs
  temp: D:\unshackle\temp
  WVDs: D:\unshackle\unshackle\WVDs

I've not changed commands, services, vaults, fonts

I'll let you sort out the rest of the unshackle.yaml. I'm sure there'll be input from others. I totally deleted the VPN and proxy bits, they're of no interest to me. I put my cdm key in that WVD folder.

Once set up, this is useful (it gives all the commands)

uv run unshackle dl -?

Member 'phased' gave you a collection of amended services: https://forum.videohelp.com/threads/414154-Devine-Modular-Movie-TV-and-Music-Archival-...60#post2778797
Put them in the services folder. I didn't use those. I got my collection from WhiskeyJack for which I thank him.

Downloading a programme is similar to devine, eg.

uv run unshackle dl all4 https://www.channel4.com/programmes/the-veil/on-demand/78102-001
uv run unshackle dl -w s02 itvx https://www.itv.com/watch/karen-pirie/10a0641

Since I had used to get unshackle from github:

git clone https://github.com/unshackle-dl/unshackle.git

I find the easiest way to update unshackle when new versions come along (and they seem to be frequent):
1. Cut/paste (ie. move) your existing unshackle.yaml to somewhere else. If you just back it up without moving (cutting) it, the update will abort with

error: Your local changes to the following files would be overwritten by merge:
        unshackle/unshackle.yaml
Please commit your changes or stash them before you merge.
Aborting

2. browse to your \unshackle folder
3.

git pull
uv sync

4. Replace the 'new' unshackle.yaml with your original

No other files/folders that you've created will be touched. `git pull` will only update tracked files that's in the repository.

[WhiskeyJack]

Put them in the services folder. I didn't use those. I got my collection from WhiskeyJack for which I thank him.

As always, you're welcome.

[Tom Saurus]

So Devine and Unshackle can both be on one's computer and co-exist. I like having more than one tool to get things done.

[ImSp4rky]

So Devine and Unshackle can both be on one's computer and co-exist. I like having more than one tool to get things done.

Correct, Unshackle lives within the .venv file that's created on installation by default. Devine can also be installed into .venv, but the majority of people install it with

pip install -r requirements.txt

which would install it across the system.

[Danker1990]

like devine this is going to need an idiots guide to use

[phased]

I like having more than one tool to get things done.

The same services are in each devine fork. Same tool, different paint. Services are the weak point.

[PunchDrunkL0ve]

@ImSp4rky great work, much appreciated, please keep it up

Found a few minor issues:

-The audio track isn't labeled as 'Default' in the mkv container
-BBC iP puts the year of release in the title and that's being picked up by unshackle unlike devine. Is it possible to omit the year from the mkv filename?
-Can the TMDB ID search string be in the form of 'tv/123456' and 'movie/123456'

Thanks.

[deccavox]

like devine this is going to need an idiots guide to use

I've shown you what to do: https://forum.videohelp.com/threads/418705-Unshackle-Modular-Movie-TV-and-Music-Archiv...re#post2778898

I don't think I can explain it any more clearer.

Once it's set up instead of using

devine dl etc etc

use

uv run unshackle dl etc etc

The etc etc bits are the same for both devine and unshackle.

[achilles]

Is there a simple way to install so that it's just "unshackle dl..."?

[deccavox]

Is there a simple way to install so that it's just "unshackle dl..."?

Assuming Windows
Yes. Create a 'unshackle.bat' file in the main unshackle folder
Put this code into it

@echo off
uv run unshackle %*

Now you can just open a CMD box in the unshackle folder and type as you say 'unshackle dl etc etc'

[WhiskeyJack]

Is there a simple way to install so that it's just "unshackle dl..."?

uv tool install git+https://github.com/unshackle-dl/unshackle.git

[sipho]

Is there a simple way to install so that it's just "unshackle dl..."?

Installing Unshackle in a virtual environment works just fine.

python -m venv .venv

Then activate the venv (add this command to a batch file for ease of use)
.venv\scripts\activate.bat

Simply use unshackle dl --no-proxy ALL4 https://www.channel4.com/programmes/xxxx

In other words, if you use a venv then run your normal commands.

[PunchDrunkL0ve]

@ImSp4rky great work, much appreciated, please keep it up

Found a few minor issues:

-The audio track isn't labeled as 'Default' in the mkv container
-BBC iP puts the year of release in the title and that's being picked up by unshackle unlike devine. Is it possible to omit the year from the mkv filename?
-Can the TMDB ID search string be in the form of 'tv/123456' and 'movie/123456'

Thanks.

Also, an attempt to install v1.0.1 with

git pull origin main

gives:

From https://github.com/unshackle-dl/unshackle
* branch main -> FETCH_HEAD
Updating 5a15e24..20285f4
error: Your local changes to the following files would be overwritten by merge:
unshackle/unshackle.yaml
Please commit your changes or stash them before you merge.
Aborting

[phased]

From https://github.com/unshackle-dl/unshackle
* branch main -> FETCH_HEAD
Updating 5a15e24..20285f4
error: Your local changes to the following files would be overwritten by merge:
unshackle/unshackle.yaml
Please commit your changes or stash them before you merge.
Aborting

That is an error caused by you and Git is trying to protect you against yourself. You have made some changes in the unshackle folder and git refuses the update as it would over-write your change. Ask chatGPT how to get out of the mess. Or just remove your unshackle folder and clone a new unshackle from git. I would save your unshackle.yaml first though as the new clone will over-write everything.

That as another good point about devine - it never updated -so nothing ever got overwritten!

I just asked chatGPT about updating but keep a local file as is. - I was thinking of unshackle/unshackle.yaml
And got this helpful reply https://chatgpt.com/share/687f665f-6138-800e-bbae-d63bc301fff6 looks like assume unchanged is the best option.

 git update-index --assume-unchanged unshackle/unshackle.yaml

EDIT: I have now had a further conversation with chatGPT about the uv tool install git+https://github.com/unshackle-dl/unshackle.git method of install and how to update and not overwrite unshackle yaml. It produced this solution for me. It would need editing depending where you want to keep unshackle.yaml backed up. It seems the uv tool can only update by a re-install so will over-write everything. the script here handles the download and puts the stashed copy of unshackle.yaml back.

#!/bin/bash

set -euo pipefail

# Custom config
MY_CONFIG="$HOME/.config/unshackle.yaml"

# Where to install from
REPO="git+https://github.com/unshackle-dl/unshackle.git"

echo "🔷 Installing unshackle from $REPO ..."
uv tool install "$REPO"

# Path where uv installs the package
UV_TOOL_DIR="$HOME/.local/share/uv/tools/unshackle"

TARGET="$UV_TOOL_DIR/lib/python3.13/site-packages/unshackle/unshackle.yaml"

echo "🔷 Replacing $TARGET with your custom config at $MY_CONFIG ..."
if [[ ! -f "$MY_CONFIG" ]]; then
    echo "❌ Custom config $MY_CONFIG not found. Aborting."
    exit 1
fi

cp -v "$MY_CONFIG" "$TARGET"

echo "✅ Done! Your custom unshackle.yaml has been restored." 

That all hard coded with paths for my system - so edit before use on yours

[PunchDrunkL0ve]

From https://github.com/unshackle-dl/unshackle
* branch main -> FETCH_HEAD
Updating 5a15e24..20285f4
error: Your local changes to the following files would be overwritten by merge:
unshackle/unshackle.yaml
Please commit your changes or stash them before you merge.
Aborting

That is an error caused by you and Git is trying to protect you against yourself. You have made some changes in the unshackle folder and git refuses the update as it would over-write your change. Ask chatGPT how to get out of the mess. Or just remove your unshackle folder and clone a new unshackle from git.

Thanks, I'm tagging the dev @ImSp4rky

Best solution would be for ImSp4rky to rename the 'unshackle.yaml' to something like 'example-unshackle.yaml' on their GitHub repository so that git doesn't detect the conflict when you attempt to pull?

[phased]

Best solution would be for ImSp4rky to rename the 'unshackle.yaml' to something like 'example-unshackle.yaml' on their GitHub repository so that git doesn't detect the conflict when you attempt to pull?

And make everyone change its name before use? if you offer to answer all the questions like "how do I rename the file?" or "where does it go now I've renamed it? or my install doesn't have unshackle.yaml - what should I do?"

[pelago]

Config files shouldn't really live in an application folder.

[phased]

Config files shouldn't really live in an application folder.

Agree. But the rub is unshackle uses unshackle.yaml to point to external configs. Unshackle hasn't been set up thoughtfully. Devine used an external location on my system in .local/share/devine

[deccavox]

So, when unshackle version updating just do as I suggested:
Move (Cut/Paste in Windows) 'unshackle.yaml' to another location outside the unshackle folder.
Do your update.
Move your original 'unshackle.yaml' back to \unshackle\unshackle overwriting the 'new' updated 'unshackle.yaml'.
or do as PunchDrunkL0ve suggested:
Rename your 'unshackle.yaml' to (say) 'unshackle_final.yaml'
Do your update
Delete the 'new' updated 'unshackle.yaml' and rename 'unshackle_final.yaml' file back to 'unshackle.yaml'.

No big deal really. A few extra seconds of work.

[phased]

.

No big deal really. A few extra seconds of work.

Yeah, but I had to re-copy services/ and an HTTAPI.py file into unshackle/vaults because I had made a fresh clone, and that's apart from the yaml. It is not good!

There is a .gitignore on gihub for unshackle with this:


[Attachment 87905 - Click to enlarge]
It probably needs the unshackle.yaml path changing to unshackle/unshackle.yaml

[F1sav28]

I appreciate all the comments so far, but for the life of me I can't seem to get the services recognised. I'll assume it's just me, but whatever I do I get "Error: There are no services added yet". I've added them into /.../unshakle/unshackle/services

__initi__.py seems to suggest the service is coded 'from unshackle' and not 'from devine'.

I've pointed the yaml file to the services folder (much like Devine), to no avail, I'm sure it's something obvious but I just can't see it.

Install went fine, added a WVD without a problem, but nope, services are baffling me at the moment.

EDIT: I did fix it by removing the [- /path/to/services - /other/path/to/services] lines, and sucessfully downloaded a few epsiodes. However, trying again today and I'm back to square one. Unshackle didn't like my updated .yaml and it keeps breaking apart when I try and point to the services folder. A clean install still brings me back to things working OK, but without services.

services:
- /path/to/services
- /other/path/to/services

I'm sure it's related to this part, everything else works. For those who have it running well, can I kindly ask how are you pointing to services and how your are treating /path and /other lines?

Thanks

[PunchDrunkL0ve]

There is a .gitignore on gihub for unshackle with this:


[Attachment 87905 - Click to enlarge]
It probably needs the unshackle.yaml path changing to unshackle/unshackle.yaml

Good catch

[mickmars]

I installed it as per deccavox post#6 , then i added the services - I hadnt set up my yaml yet .
I closed the CMD and when i reopened it I get

'uv' is not recognized as an internal or external command,
operable program or batch file.

It definitely installed because I watched it and command uv run unshackle --help worked.

I presume I have to add UV to eviroment variables - Any suggestions would be very welcome on exactly how to do that

Cheers

[deccavox]

I installed it as per deccavox post#6 , then i added the services - I hadnt set up my yaml yet .
I closed the CMD and when i reopened it I get

'uv' is not recognized as an internal or external command,
operable program or batch file.

It definitely installed because I watched it and command uv run unshackle --help worked.

I presume I have to add UV to eviroment variables - Any suggestions would be very welcome on exactly how to do that

Cheers

Mmm. I never had that problem.
In a CMD box type:

pipx list

I get

venvs are in C:\Users\MyName\pipx\venvs
apps are exposed on your $PATH at C:\Users\MyName\.local\bin
manual pages are exposed at C:\Users\MyName\.local\share\man
   package uv 0.7.14, installed using Python 3.10.1
    - uv.exe
    - uvw.exe
    - uvx.exe

So, uv apps are in 'C:\Users\MyName\.local\bin' which needs to be in your PATH.

Press Windows Key + Pause/Break to open System Properties
In 'Find a setting' box start to type 'environme` until you get 'Edit the system environmental variables' as an option. Click that option.

Look in both “User variables” or “System variables,” find "Path", and click "Edit". to see if the above path is included.
If not, add the 'C:\Users\<YourName>\.local\bin' (or whatever pipx list showed). As it happens, mine's in "User Variables", obviously that's what my installation of pipx did. If it's nowhere to be seen, I tend to put all my paths in "System Variables" to make it more global.

After modifying the PATH variable, close all CMD windows and open a fresh one.
Type

uv --version

to see if uv is now recognised.

[phased]

Well you've got me confused! Pipx and uv are separate package managers aren't they?
@mickmars Follow the installation advice on unshackle github.