Unshackle - Modular Movie, TV, and Music Archival Software

[WhiskeyJack]

I have created a new folder and made code changes in the most recent push. This update will help resolve any confusion regarding binaries and PATH issues. Inside the "unshackle" folder, there is a subfolder called "binaries" where you can place everything. Please refer to the attached image for the naming conventions to follow.

For example, "shaka-packager" should be searched for as "packager-win-x64.exe," etc.


[Attachment 87945 - Click to enlarge]

cool. but you may need to edit for linux users, some systems have shaka-packager in the repos but the system call is packager.

unshackle env check
                                                                                
                ▄• ▄▌ ▐ ▄ .▄▄ ·  ▄ .▄ ▄▄▄·  ▄▄· ▄ •▄ ▄▄▌  ▄▄▄ .                 
                █▪██▌•█▌▐█▐█ ▀. ██▪▐█▐█ ▀█ ▐█ ▌▪█▌▄▌▪██•  ▀▄.▀·                 
                █▌▐█▌▐█▐▐▌▄▀▀▀█▄██▀▐█▄█▀▀█ ██ ▄▄▐▀▀▄·██▪  ▐▀▀▪▄                 
                ▐█▄█▌██▐█▌▐█▄▪▐███▌▐▀▐█ ▪▐▌▐███▌▐█.█▌▐█▌▐▌▐█▄▄▌                 
                 ▀▀▀ ▀▀ █▪ ▀▀▀▀ ▀▀▀ · ▀  ▀ ·▀▀▀ ·▀  ▀.▀▀▀  ▀▀▀                  
                   v 3.3.3 Copyright © 2019-2025 rlaphoenix                     
                              v 1.0.1 - unshackle                               
                                                                                
                                                                                
                                  Dependencies                                  
     ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓     
     ┃ Name               ┃  Installed  ┃ Path                            ┃     
     ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩     
     │ CCExtractor        │      ✔      │ /usr/local/bin/ccextractor      │     
     │ FFMpeg             │      ✔      │ /usr/bin/ffmpeg                 │     
     │ MKVToolNix         │      ✔      │ /usr/bin/mkvmerge               │     
     │ Shaka-Packager     │     ❌      │ Not Found                       │     
     │ N_m3u8DL-RE        │      ✔      │ /usr/bin/n-m3u8dl-re            │     
     │ Aria2(c)           │      ✔      │ /usr/bin/aria2c                 │     
     └────────────────────┴─────────────┴─────────────────────────────────┘

on arch

yay shaka-packager
1 aur/shaka-packager-bin 3.4.2-1 (+0 0.00) (Installed)
    A tool and a media packaging SDK for DASH and HLS packaging and encryption.
==> Packages to install (eg: 1 2 3, 1-3 or ^4)
==> 
------
shaka-packager --version
packager version v3.4.2-c819dea-release
------
packager --version
packager version v3.4.2-c819dea-release

[PunchDrunkL0ve]

+1 for packager-win-x64 ----> shaka-packager

[ImSp4rky]

I have created a new folder and made code changes in the most recent push. This update will help resolve any confusion regarding binaries and PATH issues. Inside the "unshackle" folder, there is a subfolder called "binaries" where you can place everything. Please refer to the attached image for the naming conventions to follow.

For example, "shaka-packager" should be searched for as "packager-win-x64.exe," etc.


[Attachment 87945 - Click to enlarge]

cool. but you may need to edit for linux users, some systems have shaka-packager in the repos but the system call is packager.

unshackle env check
                                                                                
                ▄• ▄▌ ▐ ▄ .▄▄ ·  ▄ .▄ ▄▄▄·  ▄▄· ▄ •▄ ▄▄▌  ▄▄▄ .                 
                █▪██▌•█▌▐█▐█ ▀. ██▪▐█▐█ ▀█ ▐█ ▌▪█▌▄▌▪██•  ▀▄.▀·                 
                █▌▐█▌▐█▐▐▌▄▀▀▀█▄██▀▐█▄█▀▀█ ██ ▄▄▐▀▀▄·██▪  ▐▀▀▪▄                 
                ▐█▄█▌██▐█▌▐█▄▪▐███▌▐▀▐█ ▪▐▌▐███▌▐█.█▌▐█▌▐▌▐█▄▄▌                 
                 ▀▀▀ ▀▀ █▪ ▀▀▀▀ ▀▀▀ · ▀  ▀ ·▀▀▀ ·▀  ▀.▀▀▀  ▀▀▀                  
                   v 3.3.3 Copyright © 2019-2025 rlaphoenix                     
                              v 1.0.1 - unshackle                               
                                                                                
                                                                                
                                  Dependencies                                  
     ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓     
     ┃ Name               ┃  Installed  ┃ Path                            ┃     
     ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩     
     │ CCExtractor        │      ✔      │ /usr/local/bin/ccextractor      │     
     │ FFMpeg             │      ✔      │ /usr/bin/ffmpeg                 │     
     │ MKVToolNix         │      ✔      │ /usr/bin/mkvmerge               │     
     │ Shaka-Packager     │     ❌      │ Not Found                       │     
     │ N_m3u8DL-RE        │      ✔      │ /usr/bin/n-m3u8dl-re            │     
     │ Aria2(c)           │      ✔      │ /usr/bin/aria2c                 │     
     └────────────────────┴─────────────┴─────────────────────────────────┘

on arch

yay shaka-packager
1 aur/shaka-packager-bin 3.4.2-1 (+0 0.00) (Installed)
    A tool and a media packaging SDK for DASH and HLS packaging and encryption.
==> Packages to install (eg: 1 2 3, 1-3 or ^4)
==> 
------
shaka-packager --version
packager version v3.4.2-c819dea-release
------
packager --version
packager version v3.4.2-c819dea-release

Fixed a slight bug in env check and few other locations wasn't actually using the binaries.find but was using old shutil.which so if the files aren't in the PATH it won't work so now it will prioritise the binaries folder then anywhere else on the machine. env check now includes more information of "Required" files and "Optional"


[Attachment 87959 - Click to enlarge]

Also fixed env info not loading correctly.

[PunchDrunkL0ve]

Thanks ImSp4rky


Any chance we could have the audio track set as default during muxing? Thanks.

https://github.com/unshackle-dl/unshackle/blob/1b9fbe340174691dd08e2235c4725a958fbe647...tracks.py#L325

       for i, at in enumerate(self.audio):
            if not at.path or not at.path.exists():
                raise ValueError("Audio Track must be downloaded before muxing...")
            events.emit(events.Types.TRACK_MULTIPLEX, track=at)
            cl.extend(
                [
                    "--track-name", 
                    f"0:{at.get_track_name() or ''}",
                    "--language", 
                    f"0:{at.language}",
                    "--default-track", 
                    f"0:{i == 0}",
                    "--visual-impaired-flag", 
                    f"0:{at.descriptive}",
                    "--original-flag", 
                    f"0:{at.is_original_lang}",
                    "--compression", 
                    "0:none",  # disable extra compression
                    "(", str(at.path), ")"
                ]
            )

[ImSp4rky]

Thanks ImSp4rky


Any chance we could have the audio track set as default during muxing? Thanks.

https://github.com/unshackle-dl/unshackle/blob/1b9fbe340174691dd08e2235c4725a958fbe647...tracks.py#L325

       for i, at in enumerate(self.audio):
            if not at.path or not at.path.exists():
                raise ValueError("Audio Track must be downloaded before muxing...")
            events.emit(events.Types.TRACK_MULTIPLEX, track=at)
            cl.extend(
                [
                    "--track-name", 
                    f"0:{at.get_track_name() or ''}",
                    "--language", 
                    f"0:{at.language}",
                    "--default-track", 
                    f"0:{i == 0}",
                    "--visual-impaired-flag", 
                    f"0:{at.descriptive}",
                    "--original-flag", 
                    f"0:{at.is_original_lang}",
                    "--compression", 
                    "0:none",  # disable extra compression
                    "(", str(at.path), ")"
                ]
            )

Default track is set by is_original_lang = true inside the get_tracks

Method 1: Set during Audio track creation

  tracks.add(Audio(
      id=audio_id,
      url=audio_url,
      language=audio_language,
      is_original_lang=True,  # or some condition
      # other parameters...
  ))

Method 2: Set after track creation

  track = Audio(id=audio_id, url=audio_url, language=audio_language)
  track.is_original_lang = True
  tracks.add(track)

Method 3: Compare with title language

is_original_lang=is_close_match(audio_language, [title.language])

Method 4: Check if it matches original content language

is_original_lang=is_close_match(x["code"], [title.language])

The key is to determine which audio track represents the original language of the content and set is_original_lang=True for that track only.

It will be down to you to identify the correct audio for the show/movie and flag it within the service, I was tempted to set it if audio tracks only = 1 but if its 1 track its already selected when playing.

[PunchDrunkL0ve]

It will be down to you to identify the correct audio for the show/movie and flag it within the service, I was tempted to set it if audio tracks only = 1 but if its 1 track its already selected when playing.

OK thanks.
Some (older) players require the default tag even if there is only one audio track so it would be nice to have it

[mickmars]

How would I completely thoroughly uninstall every single trace of unshackle and UV to start over ?

[ImSp4rky]

It will be down to you to identify the correct audio for the show/movie and flag it within the service, I was tempted to set it if audio tracks only = 1 but if its 1 track its already selected when playing.

OK thanks.
Some (older) players require the default tag even if there is only one audio track so it would be nice to have it

I'll look at making a config change if you want that feature.

[ImSp4rky]

How would I completely thoroughly uninstall every single trace of unshackle and UV to start over ?

delete the folder if you installed via git clone and uv sync. But if you installed with uv tool install use

uv tool uninstall unshackle

That will remove every trace of it.

[PunchDrunkL0ve]

It will be down to you to identify the correct audio for the show/movie and flag it within the service, I was tempted to set it if audio tracks only = 1 but if its 1 track its already selected when playing.

OK thanks.
Some (older) players require the default tag even if there is only one audio track so it would be nice to have it

I'll look at making a config change if you want that feature.

That would be very much appreciated

[Danker1990]

has uktv changed its code or method of connecting as tried both scripts ànd i get this.

[PSXman_uk]

What is the command you are using ? I have no issues so far with U

[phased]

If you've made a local repo for unshackle and made changes, such as to unshackle/unshackle.yaml and services/ ,then git allows you to keep the changes with a bit of commitment. (pun intended)

This is the process I've just followed to allow me to keep unshackle.yaml; unshackle/services/ and vaults/HTTPAPI.py and pull new changes from the online repo.

git add . 
git commit -m 'keep local changes '
git pull

(Note the full stop after git add )

[PunchDrunkL0ve]

I believe .gitignore now works as intended and `git pull` doesn't overwrite services, vaults and unshackle.yaml anymore, at least on my setup

[PSXman_uk]

phased how do you revert the change

git add .
git commit -m 'keep local changes '
git pull

[WhiskeyJack]

git revert

[phased]

I believe .gitignore now works as intended and `git pull` doesn't overwrite services, vaults and unshackle.yaml anymore, at least on my setup

That wasn't the case for me. .gitignore and .gitattributes get over-written by the pull and what is in them doesn't appear to stop the yaml and services being clobbered.

[membranaraptor]

Like a previous poster I am getting the error: Error: There are no Services added yet, therefore the 'itv' Service could not be found.

Installed with git clone

Installed to C:\Users\XXX\unshackle

.yaml file details:

directories:
services: C:\Users\XXX\unshackle\Services
downloads: C:\Users\XXX\Downloads
wvds: C:\Users\XXX\unshackle
temp: C:\Users\XXX\unshackle\Temp

I must be missing something but I don't know what

[deccavox]

Like a previous poster I am getting the error: Error: There are no Services added yet, therefore the 'itv' Service could not be found.

Installed with git clone

Installed to C:\Users\XXX\unshackle

.yaml file details:

directories:
services: C:\Users\XXX\unshackle\Services
downloads: C:\Users\XXX\Downloads
wvds: C:\Users\XXX\unshackle
temp: C:\Users\XXX\unshackle\Temp

I must be missing something but I don't know what

Have you actually installed the services in C:\Users\XXX\unshackle\Services (eg. from https://files.videohelp.com/u/312095/unshackle_services.zip)

Make sure it's the contents of that unzipped folder that's added to the \services folder and not \services\services\the contents.
ie. just the folders ALL4, AUBC, CBC, etc, etc.
That's because your services are located at 'C:\Users\XXX\unshackle\Services' and not 'C:\Users\XXX\unshackle\Services\services'

[membranaraptor]

Like a previous poster I am getting the error: Error: There are no Services added yet, therefore the 'itv' Service could not be found.

Installed with git clone

Installed to C:\Users\XXX\unshackle

.yaml file details:

directories:
services: C:\Users\XXX\unshackle\Services
downloads: C:\Users\XXX\Downloads
wvds: C:\Users\XXX\unshackle
temp: C:\Users\XXX\unshackle\Temp

I must be missing something but I don't know what

Have you actually installed the services in C:\Users\XXX\unshackle\Services (eg. from https://files.videohelp.com/u/312095/unshackle_services.zip)

Make sure it's the contents of that unzipped folder that's added to the \services folder and not \services\services\the contents.
ie. just the folders ALL4, AUBC, CBC, etc, etc.
That's because your services are located at 'C:\Users\XXX\unshackle\Services' and not 'C:\Users\XXX\unshackle\Services\services'

RESOLVED: I had to put the .yaml file in the unshackled/unshackled folder rather than just in the unshackled folder, if that makes sense. Thanks for your help, sorry to waste your time - forgive me, I am a worm

[membranaraptor]

Everything is working fine now, but checking requirements it says that mkvpropedit is required but is not installed/not found. The programme works fine without it but I was wondering how I install this? I have MKVToolNix installed

[ImSp4rky]

Everything is working fine now, but checking requirements it says that mkvpropedit is required but is not installed/not found. The programme works fine without it but I was wondering how I install this? I have MKVToolNix installed

Best way to test is to do

uv run unshackle env check

and

uv run unshackle env info

Will give you all the information you need on where to put files, where to make changes or where to fix your unshackle.yaml file

[A_n_g_e_l_a]

For people who do this:-

[Attachment 88026 - Click to enlarge]
They will have installed unshackle as a tool available as 'unshackle', so VineFeeder may call it globally. Updating the unshackle tool requires a re-install. Everything will get over-written by re-install of the git.

Save the yaml outside of the unshackle tree and configure services to be stored outside the directory tree too. As well as anything else you might need saved.

I'm using Devine's locations my for my services etc -

directories:
  cache: /home/angela/.local/tmp/devine
  cookies: /home/angela/.local/tmp/devine/Cookies
  dcsl: DCSL # Device Certificate Status List
  downloads: /home/angela/Downloads/devine
  logs: /home/angela/.local/tmp/devine/
  temp: /home/angela/.local/tmp/devine/
  wvds: /home/angela/.local/share/devine/WVDs/
  prds: PRDs
  # Additional directories that can be configured:
  # commands: Commands
  services:
    - /home/angela/.local/share/devine/services/
  vaults: /home/angela/.local/share/devine/vaults/
  # fonts: Fonts

[milflover]

Works perfectly, and very fast! Thank you!

[kev043]

Thanks for the fantastic work ImSp4rk, I've been testing Unshackle and right away I love how it installs using uv and that it's contained in one folder which is far easier to manage, I'm using n_m3u8dl_re as the downloader and right away I noticed how fast the downloads are.

Big thanks to everyone who works on this a contributes, if I can be of any help I will. Cheers.

[SummerArk]

Everyone,

Unshackle is under heavy commiting.

In
https://github.com/unshackle-dl/unshackle/commits/main/
July 31, 2025 - 3 commits
July 30, 2025 - 11 commits
July 29, 2025 - 7 commits

In
Hybrid HDR #1
https://github.com/unshackle-dl/unshackle/pull/1/commits
July 29 & 30, 2025 - 7 commits

using a 'burner' github account, 'Andy' submitted many changes recently.

Looks like 'Andy' is trying to add to Unshackle the feature:

HDR10+DV Hybrid - Hybrid Dolby Vision injection

in
https://github.com/unshackle-dl/unshackle/pull/1/commits/c97de0c32ba95bfac82dcae20b1014203c58c0ff

[sipho]

Any idea how to change the downloaded series folder name from something like this

World.War.II.Secrets.From.Above.S01.1080p.AAC2.0.H.264

to something like this

World War II Secrets From Above

I looked in core\tracks and core\titles but nothing jumped out as obvious.

I was able to remove the ghastly WEB-DL from core\titles\episode.py

[Tom Saurus]

Any idea how to change the downloaded series folder name from something like this

World.War.II.Secrets.From.Above.S01.1080p.AAC2.0.H.264

to something like this

World War II Secrets From Above

I looked in core\tracks and core\titles but nothing jumped out as obvious.

I was able to remove the ghastly WEB-DL from core\titles\episode.py

I would at the beginning of the download process write the name of the series in Notepad and just use it to copy and paste when you chose to rename the folder. As for episodes names there are programs such as Rename My TV Series. Hint for shows like "Love Boat" just leave them as they are as they are too much of a pain to rename the episodes.

[phased]

Any idea how to change the downloaded series folder name from something like this

World.War.II.Secrets.From.Above.S01.1080p.AAC2.0.H.264

to something like this

World War II Secrets From Above

I looked in core\tracks and core\titles but nothing jumped out as obvious.

I was able to remove the ghastly WEB-DL from core\titles\episode.py

It all happens in core/titles/episode.py. You'll see lots of 'name += whatever ' that just add garbage to titles.

The name is set perfectly well at line 107 in episode.py after that try commenting out any line starting name +=
If name += is directly underneath an if statement - you'll need to add 'pass' indented underneath if... or comment out the if statement entirely.

the same thing needs doing in core/titles/movie.py and core/titles/song.py too!!

Edit: I've found a better way. lots of edits but this works and produced this save:-

[Attachment 88062 - Click to enlarge]

1. in unshackle yaml add 

scene_naming: false

2. in core/config.py  @ line 81 add

self.scene_naming: str = kwargs.get("scene_naming") or ""

3. in core/titles/episode.py @ line 109 add

if config.scene_naming:

4. indent lines 110  .. 182

5. after line 182 outdent and add

else:
    return name
   
    
Do a similar process for song and movie

[sipho]

I would at the beginning of the download process write the name of the series in Notepad and just use it to copy and paste when you chose to rename the folder. As for episodes names there are programs such as Rename My TV Series. Hint for shows like "Love Boat" just leave them as they are as they are too much of a pain to rename the episodes.

Thank you Tom. I use filebot to rename stuff after the fact but wanted to have downloaded files cleaned up before processing. phased has the answer I was looking for.