mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-14 21:15:06 +00:00
imSp4rky
5bc92b5517
Take video, audio, subtitles, or chapters from other services and mux them with the primary download. Each cross-service authenticates, licenses, and decrypts with its own CDM, key vault, and proxy. Audio and subtitles merge with the primary's tracks (video and chapters replace) and flow through the normal best-per-language selection, with an id-namespace guard so a cross track can never shadow a primary track's DRM routing. Per-source offsets emit an mkvmerge --sync argument; episodes auto-match with per-type --cross-*-wanted overrides. Adds unit and offline end-to-end tests and a cross-service muxing guide.
102 lines
4.7 KiB
Markdown
102 lines
4.7 KiB
Markdown
# Cross-service muxing
|
|
|
|
Some titles are on more than one service, and each service is strong at something
|
|
different: one carries the 4K HDR video, another the better dub, a third the fuller
|
|
subtitles. Cross-service muxing lets you download the video from one service and pull
|
|
the audio, subtitles, or chapters from others, then mux the result into a single file.
|
|
|
|
!!! warning "This is a power-user feature"
|
|
unshackle does not check that the services carry the same cut of the title. You are
|
|
responsible for pairing services that share the same edit. A different cut, a
|
|
different frame rate, or an extra recap will not line up, and a single offset cannot
|
|
fix it. See [Limitations](#limitations).
|
|
|
|
## How it works
|
|
|
|
You download from a **primary** service as normal, the positional `SERVICE URL` at the
|
|
end of the command. Each `--cross-*` flag names **another** service tag and URL to take a
|
|
track type from:
|
|
|
|
- **Video** and **chapters** *replace* what the primary provides. There is only ever one
|
|
video source and one set of chapters.
|
|
- **Audio** and **subtitles** *merge* with the primary's own tracks. Your normal track
|
|
selection (`-l`, quality, codec, channels) then runs across the combined set, so the
|
|
best version of each language wins whichever service it came from.
|
|
|
|
```bash
|
|
# Download EXAMPLE's video, but take the audio from EXAMPLE2
|
|
unshackle dl --cross-audio EXAMPLE2 "https://example2.com/show/1" EXAMPLE "https://example.com/show/1"
|
|
```
|
|
|
|
You can combine several sources in one run:
|
|
|
|
```bash
|
|
# Video from the primary, a dub from one service, subtitles from another
|
|
unshackle dl \
|
|
--cross-audio EXAMPLE2 "https://example2.com/show/1" \
|
|
--cross-subtitles EXAMPLE3 "https://example3.com/show/1" \
|
|
EXAMPLE "https://example.com/show/1"
|
|
```
|
|
|
|
The full flag list is in the [CLI reference](cli-reference.md#cross-service-muxing).
|
|
|
|
## Authentication, DRM, and proxies
|
|
|
|
Each cross-service behaves like a download of its own. It authenticates with **its own**
|
|
credentials, licenses and decrypts with **its own** CDM, and stores keys in **its own**
|
|
key vault. A PlayReady-only cross-service works even when the primary uses Widevine,
|
|
because it loads the CDM its own configuration asks for.
|
|
|
|
!!! note "You need credentials for every service"
|
|
A cross-service authenticates the same way it would on a normal download, so its
|
|
profile, cookies, or credentials must be set up. Use `--cross-profile` to pick a
|
|
profile for the cross-services (it defaults to `--profile`).
|
|
|
|
By default each cross-service resolves **its own** proxy from its configuration, so a
|
|
geo-restricted source still reaches the right region. Set `--cross-proxy` to force one
|
|
proxy for every cross-service instead.
|
|
|
|
## Choosing the episode
|
|
|
|
For a TV title, each cross-service is matched to the **same season and episode** as the
|
|
title you download. When a service numbers its episodes differently, override the match:
|
|
|
|
- `--cross-wanted S01E03` sets a shared override for every cross-service.
|
|
- `--cross-audio-wanted`, `--cross-video-wanted`, `--cross-subtitles-wanted`, and
|
|
`--cross-chapters-wanted` are per-type overrides that win over `--cross-wanted`.
|
|
|
|
If a cross-service has no title matching the request, unshackle warns and keeps the
|
|
primary's own tracks for that type.
|
|
|
|
## Offsets
|
|
|
|
If a cross-service begins with a short buffer the primary does not have, such as an advert
|
|
or a splash screen, its tracks start a few seconds late. Nudge them back into line:
|
|
|
|
```bash
|
|
# EXAMPLE2's audio starts 3 seconds late; shift it earlier
|
|
unshackle dl --cross-audio EXAMPLE2 "https://example2.com/show/1" \
|
|
--cross-audio-offset -3s EXAMPLE "https://example.com/show/1"
|
|
```
|
|
|
|
`--cross-audio-offset` and `--cross-subtitle-offset` accept `10s`, `500ms`, or `-5.5s`; a
|
|
bare number is milliseconds. The offset is passed to the muxer, which shifts the track's
|
|
start. It does not re-time or resample the media, so a single offset only corrects a
|
|
constant lead or lag, not drift that grows through the title.
|
|
|
|
## Limitations
|
|
|
|
Cross-service muxing assumes the sources are the same cut of the title. The current
|
|
release does not:
|
|
|
|
- **Sync mismatched cuts.** Different edits, ad breaks, or frame rates are out of scope;
|
|
the offset is a manual nudge for a constant lead, not automatic synchronisation.
|
|
- **Pin a language to a service.** Merged audio and subtitles are chosen by the normal
|
|
best-per-language selection. You cannot yet force the English from one service when
|
|
another service's English scores higher.
|
|
- **Reuse a cross-service across a season.** Each title in a season download loads and
|
|
authenticates its cross-services again, so a login-rate-limited service is contacted
|
|
once per episode.
|
|
- **Run a cross-service's own post-download steps.** Only the primary service's
|
|
post-download hooks fire.
|