[Release] UniDL — TUI downloader

[Chris20]

Hello everyone,

I would like to share UniDL, an open-source, terminal-first media browser and native downloader for Windows, macOS and Linux.

Project links

GitHub:
https://github.com/chis47747/unidl

PyPI:
https://pypi.org/project/unidl/

Latest release:
https://github.com/chis47747/unidl/releases/

Documentation:
https://github.com/chis47747/unidl/tree/main/docs. Please read them first

Note: There is only BBC iPlayer service for testing reasons, you can add more service flowing detailed documentation on how to write a service.

What UniDL provides

- A keyboard- and mouse-friendly terminal interface for browsing media services.
- A consistent workflow for opening URLs, searching titles, selecting seasons and episodes, choosing tracks, and downloading or recording media.
- Support for DASH/MPD, HLS, ISM/Smooth Streaming, JSON manifests and direct media URLs.
- Independent video, audio and subtitle track selection.
- Subtitle and chapter handling, output naming, resumable transfers and native muxing.
- Live recording with replay/DVR windows, duration control and cancellation.
- Audio-only workflows with metadata, cover art and MP3 export.
- JSON command/export files for automation and reproducible downloads.
- Localized interfaces including English, Simplified Chinese, Traditional Chinese, Spanish, French and Portuguese.
- Project-relative configuration for credentials, cookies, tokens, helpers, CDM devices, vaults and output files.

The project is divided into three layers:

1. Service packages handle provider-specific login, catalogue/search, manifests, settings and licence transport.
2. Core/TUI handles navigation, settings, credentials, track selection, progress, logs and workflow control.
3. The native downloader handles manifest parsing, segment transfer, decryption, subtitles, chapters and muxing in-process.

Installation

Python 3.11 or newer is required. FFmpeg and ffprobe are recommended for muxing, media probing and audio conversion.

```text
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install unidl
unidl

[ringy9]

Has anyone managed to get this up and running? I'm struggling to work it out

[phased]

Has anyone managed to get this up and running? I'm struggling to work it out

Has only a single service, BBC.

[ringy9]

@phased thanks for the reply. So it needs services like unshackle etc

[phased]

@phased thanks for the reply. So it needs services like unshackle etc

Yeah looks like it. I got it running using uv lock; uv sync and the uv run unidl --config ./unidl.private.yaml

Then set your download folder by editing unidl.yaml,

Start with uv run unidl. The interface isn't too user friendly - but there is a lot going on. It downloaded an episode of Vigil
But it failed with subtitles - there is an xml file with subs but conversion didn't happen.

Download failed: Vigil.S03E02.Amy.races.to.save.a.hostage.1080p.iP. WEB-DL.H.264:
muxing command failed with status 183: Error opening input file
/unidl/subtitles/bbc/Vigil.S03E02.Amy.races.to.save.a.h
ostage.en.3b25992329bc.xml. | Error opening input files: Invalid data found when
processing input

The video was saved to a ts file.

[Chris20]

@phased thanks for the reply. So it needs services like unshackle etc

Yeah looks like it. I got it running using uv lock; uv sync and the uv run unidl --config ./unidl.private.yaml

Then set your download folder by editing unidl.yaml,

Start with uv run unidl. The interface isn't too user friendly - but there is a lot going on. It downloaded an episode of Vigil
But it failed with subtitles - there is an xml file with subs but conversion didn't happen.

Download failed: Vigil.S03E02.Amy.races.to.save.a.hostage.1080p.iP. WEB-DL.H.264:
muxing command failed with status 183: Error opening input file
/unidl/subtitles/bbc/Vigil.S03E02.Amy.races.to.save.a.h
ostage.en.3b25992329bc.xml. | Error opening input files: Invalid data found when
processing input

The video was saved to a ts file.

Hi, BBC subtitle conversion requires subby to be installed first, and that's why it leaves ts file in the end. there shoud be a warning in here
But I will patch this problem to let BBC use native subtitle conversion first.

[Attachment 93811 - Click to enlarge]

[phased]

Hi, This line in pyproject.toml - under dependecies does it for uv users:
"subby @ git+https://github.com/vevv/subby.git@a057280f31acd3a0ba5c6dc69eaefbb88aea974e ",

With that it works.