Metadata-Version: 2.4
Name: hyperdm
Version: 0.2.0
Summary: HyperDM — a fast multi-connection download manager for Linux, with browser integration and video-site support
Author: HyperDM contributors
License: LGPL-3.0-or-later
Project-URL: Homepage, https://github.com/0xAr4fat/HyperDM
Project-URL: Issues, https://github.com/0xAr4fat/HyperDM/issues
Keywords: download-manager,idm,segmented-download,yt-dlp,linux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Communications :: File Sharing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: gui
Requires-Dist: PySide6>=6.6; extra == "gui"
Provides-Extra: video
Requires-Dist: yt-dlp>=2024.1.1; extra == "video"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: PySide6>=6.6; extra == "dev"
Requires-Dist: yt-dlp>=2024.1.1; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: setuptools>=68; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# HyperDM

A fast, open-source download manager for Linux — a clean-room alternative to
IDM. It splits every download across multiple connections, catches downloads
straight out of your browser, and grabs video from YouTube and ~35 other sites
at whatever quality you pick.

- **Multi-connection downloads** — each file is split into segments fetched in
  parallel, with work-stealing rebalancing so a single slow connection can't
  hold the whole download back.
- **Pause, resume, retry** — progress is kept in a `.hdm` sidecar file, so a
  paused (or crashed, or rebooted) download resumes from exactly where it
  stopped.
- **Browser integration** — a Manifest V3 extension for Chrome/Brave/Edge and
  Firefox. Clicking a download in the browser hands it to HyperDM; the popup
  also lists media it detected on the current page.
- **Video sites** — YouTube, Vimeo, X/Twitter, TikTok, Reddit, Twitch,
  Dailymotion, SoundCloud, Bilibili, Odysee, Rumble and more, via `yt-dlp`.
- **Pick your quality** — the extension and the desktop dialog both ask
  `yt-dlp` what the page actually offers and let you choose: 4K down to 360p,
  or audio-only.
- **HLS/DASH capture** — `.m3u8` and `.mpd` streams are remuxed to a real file
  with `ffmpeg`.
- **Queue and scheduler** — concurrency limits, sequential mode, a global speed
  cap, and an "only download between 00:00 and 07:00" window.
- **Clipboard monitor** — copy a URL, get an offer to download it.
- **Native GUI** — PySide6/Qt, dark and light themes, live speed graph, system
  tray, desktop notifications.
- **Automatic filing** — finished files are sorted into `Video/`, `Music/`,
  `Documents/`, `Programs/`, `Compressed/` by type.

License: LGPL-3.0-or-later.

## Requirements

| | |
|---|---|
| Linux | any modern distro (X11 or Wayland) |
| Python | 3.11 or newer |
| `ffmpeg` | needed for HLS/DASH and for merging high-quality video+audio |
| `yt-dlp` | installed automatically into HyperDM's virtualenv |

`ffmpeg` is a system package — install it with your package manager:

```bash
sudo apt install ffmpeg      # Debian / Ubuntu
sudo pacman -S ffmpeg        # Arch
sudo dnf install ffmpeg      # Fedora
```

Everything else (PySide6, httpx, yt-dlp) is pulled into a local `.venv` by the
scripts below — nothing is installed system-wide.

## Install

```bash
git clone <this-repo> HyperDM
cd HyperDM
./install.sh
```

This creates `.venv`, installs the app and `yt-dlp`, adds a `hyperdm` launcher
to `~/.local/bin`, installs a desktop entry and icon, registers the browser
native-messaging host, and stages the browser extensions in `dist-extension/`.

Then launch it from your application menu, or:

```bash
hyperdm
```

Make sure `~/.local/bin` is on your `PATH`.

### From PyPI

No clone needed:

```bash
pip install "hyperdm[gui,video]"
```

This installs the same launchers as `install.sh` — `hyperdm` for the GUI and
`hyperdm-cli` for the headless downloader. The browser native-messaging host
still needs registering; run `hyperdm-install-host` once, or use the source
install above which does it for you.

### Or run it without installing

```bash
./run.sh
```

First run builds the virtualenv; after that it starts immediately. No launcher,
no desktop entry, no host registration.

### Uninstall

```bash
./uninstall.sh
```

## Browser extension

The extension talks to the app over native messaging, so **HyperDM must be
installed** (`./install.sh`) for it to work — `run.sh` alone doesn't register
the messaging host.

**Chrome / Brave / Edge**

1. Go to `chrome://extensions`, enable **Developer mode**.
2. **Load unpacked** → select `dist-extension/chrome`.
3. Copy the extension ID shown on the card, then authorise it:
   ```bash
   ./install.sh --chrome-id <ID>
   ```

**Firefox**

1. Go to `about:debugging#/runtime/this-firefox`.
2. **Load Temporary Add-on** → select `dist-extension/firefox/manifest.json`.

(If `dist-extension/` is missing, run `./packaging/build-extension.sh`.)

### Using it

- **Any download** you start in the browser is handed to HyperDM instead.
- **On a video page**, the popup shows the video with a quality dropdown —
  populated with the formats that page actually has — and a Download button. A
  floating button on the page itself does the same thing.
- **Other media on the page** (direct `.mp4`, `.mp3`, HLS streams) is listed in
  the popup, each with its own grab button.
- The popup's status pill tells you whether the app is running.

Extension settings (right-click the icon → Options) cover the default video
quality, whether to intercept every file type or only media, whether to include
audio and HLS/DASH streams in detection, an ad-network filter, a minimum file
size, and a per-site disable list.

## Configuration

Settings live in the GUI under **Settings**, and are stored at
`~/.config/hyperdm/config.json`:

| Setting | Default | |
|---|---|---|
| Download folder | `~/Downloads` | where finished files land |
| Max concurrent downloads | `4` | or switch to strict sequential mode |
| Connections per download | `8` | segments fetched in parallel |
| Speed limit | unlimited | global cap in bytes/sec |
| Organise by category | on | sort into `Video/`, `Music/`, … |
| Confirm browser downloads | on | show a prefilled dialog instead of queueing silently |
| Video site quality | Best available | default for `yt-dlp` downloads |
| Video site cookies | off | lift cookies from Firefox/Chrome/Brave/… for age-restricted or login-walled videos |
| Theme | dark | dark or light |
| Proxy | none | |
| Schedule | off | e.g. only download 00:00–07:00 |

Other paths: database at `~/.local/share/hyperdm/hyperdm.db`, IPC socket at
`$XDG_RUNTIME_DIR/hyperdm/ipc.sock` (mode 0600, user-only).

**Age-restricted or members-only videos** usually fail with "Sign in to
confirm…". Set **Video site cookies** to the browser you're logged into and try
again.

## Command line

A minimal downloader is available without the GUI:

```bash
hyperdm-cli <url> -o out.iso -n 16
```

| | |
|---|---|
| `-o, --output` | destination path |
| `-n, --connections` | parallel connections (default 8) |
| `--referrer` | send a `Referer` header |

## Packaging

- **Arch / AUR** — `packaging/pkgbuild/PKGBUILD`
- **AppImage** — `packaging/appimage/build-appimage.sh`
- **Wheel** — `python -m build` (extras: `[gui]`, `[video]`, `[dev]`)

## Development

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest -q   # Python tests
node --test extension/tests/*.js                          # extension tests
```

`QT_QPA_PLATFORM=offscreen` lets the GUI tests run without a display.

### Layout

```
hyperdm/core/         segmented engine, chunk manager, queue, scheduler,
                      SQLite DAO, HLS/DASH + yt-dlp downloaders
hyperdm/gui/          PySide6 window, dialogs, tray, theming
hyperdm/native_host/  native-messaging host + Unix-socket IPC to the app
extension/            Manifest V3 extension (Chrome + Firefox)
packaging/            desktop entry, icon, PKGBUILD, AppImage, extension build
tests/                pytest suite
```

One thing to know if you touch site detection: the "is this a video page?"
logic exists twice — `hyperdm/core/ytdlp_downloader.py::is_video_page_url` and
`extension/common.js::isVideoPage`. They must stay in sync; if they diverge, a
download silently goes to the wrong engine and produces a broken file. Both
files carry a comment pointing at the other, and both are covered by tests.

## Troubleshooting

**"App not running" in the extension.** Start HyperDM. If it is running, the
native-messaging host may not be registered for your browser — re-run
`./install.sh` (and `--chrome-id <ID>` for Chrome).

**A video downloads without sound, or fails at "merging".** `ffmpeg` is
missing. High-quality streams are stored as separate video and audio tracks and
need it to combine them.

**A YouTube download fails with an extractor error.** `yt-dlp` goes stale when
sites change. Update it:

```bash
.venv/bin/pip install -U yt-dlp
```

**Downloads are slower than expected.** Some servers cap per-connection speed
(more connections help) and others cap per-IP (they won't). Try raising
*Connections per download*; if nothing changes, the server is the limit.
