Metadata-Version: 2.5
Name: hlsfetch
Version: 0.2.0
Summary: Fast async HLS (m3u8) downloader for Python: resume, AES-128, fMP4, separate audio, live recording.
Project-URL: Homepage, https://github.com/doumamay/hlsfetch
Project-URL: Issues, https://github.com/doumamay/hlsfetch/issues
Author: doumamay
License-Expression: MIT
License-File: LICENSE
Keywords: aes-128,asyncio,downloader,hls,live,m3u8,streaming,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: cryptography>=41
Requires-Dist: httpx>=0.26
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: socks
Requires-Dist: httpx[socks]>=0.26; extra == 'socks'
Description-Content-Type: text/markdown

# hlsfetch

[![PyPI](https://img.shields.io/pypi/v/hlsfetch)](https://pypi.org/project/hlsfetch/)
[![Python](https://img.shields.io/pypi/pyversions/hlsfetch)](https://pypi.org/project/hlsfetch/)
[![Tests](https://github.com/doumamay/hlsfetch/actions/workflows/tests.yml/badge.svg)](https://github.com/doumamay/hlsfetch/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Fast, async HLS (`.m3u8`) downloader for Python, usable as a library or from the command line.

- Parallel segment downloads on `asyncio` + `httpx`
- **Resumes** interrupted downloads, and detects when the leftover data belongs to a different stream
- **AES-128** decryption (key rotation and explicit or implicit IVs are handled)
- MPEG-TS and **fMP4** (`#EXT-X-MAP`) streams, `#EXT-X-BYTERANGE`, `#EXT-X-GAP`
- **Separate audio tracks** (`#EXT-X-MEDIA`), with language selection, muxed into one file
- **Live recording** until the stream ends, a time limit, or Ctrl+C
- Quality selection, custom headers, cookies, proxy (HTTP or SOCKS), speed limit
- Remux to `.mp4` / `.mkv` through ffmpeg (stream copy, no re-encoding)
- Two dependencies: `httpx` and `cryptography`. Fully typed.

## Install

```bash
pip install hlsfetch
```

For SOCKS proxies: `pip install "hlsfetch[socks]"`.

Install [ffmpeg](https://ffmpeg.org/) and put it on your `PATH` if you want `.mp4`/`.mkv` output from MPEG-TS streams, or when a stream has a separate audio track. Without ffmpeg, hlsfetch still works: it saves the raw streams (`.ts`, `.aac`, ...) and prints a warning.

## Command line

```bash
hlsfetch "https://example.com/video/master.m3u8" -o movie.mp4
```

Look before you download: `--info` lists variants, audio tracks, duration and encryption, and marks with `*` what would be downloaded.

```bash
hlsfetch "https://example.com/video/master.m3u8" --info
```

Common options:

```bash
# 720p at most, Vietnamese audio, from a site that checks Referer
hlsfetch URL -q 720 --audio-lang vi -r "https://example.com/" -o ep1.mp4

# use your browser's cookies (exported cookies.txt) and limit speed to 2 MB/s
hlsfetch URL -c cookies.txt --limit-rate 2M

# record a live stream for one hour
hlsfetch URL --live --max-duration 1:00:00 -o live.mp4
```

If a download is interrupted, run the same command again to resume it. While recording a live stream, press Ctrl+C once to stop and save what was recorded (twice to abort). Live recordings start at the live edge, like a player would; add `--live-from-start` to also grab everything the server still lists.

<details>
<summary>All options</summary>

```text
hlsfetch URL [-o OUTPUT] [-q best|worst|720] [-i]

network:
  -H, --header 'NAME: VALUE'   extra HTTP header (repeatable)
  -r, --referer URL            set the Referer (and Origin) header
  -A, --user-agent UA          set the User-Agent header
  -c, --cookies FILE           cookies.txt file (Netscape format)
  --proxy URL                  http://, https:// or socks5:// proxy
  -j, --concurrency N          parallel segment downloads (default: 8)
  --retries N                  retries per request (default: 5)
  --timeout SECONDS            request timeout (default: 30)
  --limit-rate RATE            max speed, e.g. 500K or 2M

tracks and output:
  --audio-lang LANG            preferred audio language, e.g. en or vi
  --no-audio                   skip separate audio tracks
  --no-remux                   never call ffmpeg; write raw streams to the given name
  --keep-parts                 keep the downloaded segment folder
  --quiet                      no progress output

live streams:
  --live                       record a live stream
  --max-duration TIME          stop after TIME (90, 1:30, 1:00:00)
  --live-from-start            start at the oldest listed segment, not the live edge
```

</details>

## Library

```python
import hlsfetch

path = hlsfetch.download(
    "https://example.com/video/master.m3u8",
    "movie.mp4",
    quality=720,  # "best", "worst", 720, or a callable
    audio_lang="en",
    headers={"Referer": "https://example.com/"},
    concurrency=16,
)
print(path)
```

Async, with a progress callback (plain or `async def`):

```python
import asyncio

import hlsfetch


def on_progress(p: hlsfetch.Progress):
    print(f"{p.done}/{p.total} segments, {p.bytes / 1e6:.1f} MB, {p.speed / 1e6:.1f} MB/s")


async def main():
    await hlsfetch.adownload(url, "movie.mp4", progress=on_progress)


asyncio.run(main())
```

Inspect a stream without downloading it:

```python
info = asyncio.run(hlsfetch.probe(url, quality="best"))
print(info.variant, info.audio_rendition, info.video.duration)
for v in info.master.variants:
    print(v.resolution, v.bandwidth)
```

Record a live stream, stopping from your own code:

```python
async def record(url):
    stop = asyncio.Event()
    asyncio.get_running_loop().call_later(600, stop.set)  # stop after 10 minutes
    return await hlsfetch.adownload(url, "live.mp4", live=True, stop_event=stop)
```

Drop segments, for example the part between two `#EXT-X-DISCONTINUITY` tags (often an ad break):

```python
hlsfetch.download(url, "show.mp4", segment_filter=lambda seg: seg.period != 1)
```

Pass your own `httpx.AsyncClient` through `client=` to share cookies or connection pools (hlsfetch won't close it), or build one with `hlsfetch.make_client(...)`.

### `download()` / `adownload()` options

| Option | Default | Meaning |
|---|---|---|
| `quality` | `"best"` | `"best"`, `"worst"`, max height (`720`), or `callable(variants) -> Variant` |
| `audio` | `True` | Download the separate audio track when the stream has one |
| `audio_lang` | `None` | Preferred audio language (prefix match: `"en"` matches `"en-US"`) |
| `headers` | `None` | Extra HTTP headers |
| `cookies` | `None` | `dict`, `http.cookiejar.CookieJar` or `httpx.Cookies` |
| `concurrency` | `8` | Segments downloaded at once |
| `retries` | `5` | Retries per request (network errors, 408, 425, 429 and 5xx except 501/505) |
| `timeout` | `30.0` | Request timeout in seconds |
| `proxy` | `None` | Proxy URL |
| `rate_limit` | `None` | Max bytes per second, across all connections |
| `remux` | `True` | Use ffmpeg when needed (other container, separate audio). With `False`, the raw stream is written to `output` exactly as named, and a separate audio track next to it as `<name>.audio.<ext>` |
| `keep_parts` | `False` | Keep the `<output>.parts/` folder after merging |
| `segment_filter` | `None` | `callable(Segment) -> bool`; segments returning `False` are skipped |
| `live` | `False` | Allow recording live playlists |
| `live_from_start` | `False` | Live: start at the oldest segment the server lists instead of the live edge |
| `max_duration` | `None` | Live: stop after this many seconds of media |
| `stop_event` | `None` | Live: an `asyncio.Event` that stops recording when set |
| `progress` | `None` | Called with a `Progress` after each segment |
| `client` | `None` | Your own `httpx.AsyncClient` |

Errors are raised as subclasses of `hlsfetch.HLSFetchError`: `PlaylistError`, `UnsupportedError` and `DownloadError`. When one segment fails for good, hlsfetch stops starting new requests, lets the ones in flight finish (so they count toward the next resume), and raises.

## How resuming works

Segments are stored in `<output>.parts/` as they arrive, and are merged into the output once all of them are there. Running the same download again skips the segments already on disk. The folder also records which variant and audio track were chosen, plus a fingerprint of the playlist (paths and durations, without query strings, because those often contain expiring tokens). If you pick another quality or the URL now points to different content, the old parts are discarded instead of being mixed into the new file. Live recordings always start fresh.

## Limitations

- No DRM (Widevine, FairPlay, PlayReady, `SAMPLE-AES`), and there are no plans to add it.
- Subtitle tracks aren't downloaded yet.
- Live recording follows the playlist as it updates. A segment that can't be downloaded (for example because it already left the server's window) is left out with a warning, and the rest of the recording is kept. If the playlist itself can't be reloaded five times in a row, recording stops and what was recorded is saved.

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check . && ruff format --check .
```

The tests run a local HTTP server, so they need no network access. Tests that need ffmpeg are skipped when it isn't installed.

## Disclaimer

hlsfetch is a general-purpose tool for working with HLS streams, intended for
legitimate uses such as archiving your own content, testing and debugging
streaming setups, and downloading media you are licensed or permitted to save.

- **You are responsible for how you use it.** Only download content you own,
  content that is in the public domain, or content you have explicit permission
  to download. Respect the terms of service of the sites you access and the
  copyright laws of your country.
- **No DRM circumvention.** hlsfetch does not and will not support DRM systems
  (Widevine, FairPlay, PlayReady, SAMPLE-AES). It only handles standard
  AES-128 HLS encryption, using keys that the stream itself makes publicly
  available to any compatible player.
- **No affiliation.** This project is not affiliated with, endorsed by, or
  connected to any streaming service or content provider.
- **No warranty.** The software is provided "as is", without warranty of any
  kind, as stated in the MIT License. The authors are not liable for any misuse
  or damage arising from its use.

If you are a rights holder and believe this project infringes your rights,
please open an issue so it can be addressed.

## License

MIT
