Metadata-Version: 2.5
Name: hlsfetch
Version: 0.3.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: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: http2
Requires-Dist: httpx[http2]>=0.26; extra == 'http2'
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
- **Subtitles** (WebVTT tracks) saved as `.vtt` files, re-timed to match the video
- **Clips**: download only a time range (`--start 10:00 --end 15:00`)
- **Audio only**: save just the soundtrack as `.m4a`
- **Live recording** until the stream ends, a time limit, or Ctrl+C
- **Batch downloads** from several URLs or a file of links; finished files are skipped
- Quality selection, custom headers, cookies, proxy (HTTP or SOCKS), HTTP/2, speed limit
- Retries with back-off that honour `Retry-After`; output files are written atomically
- Remux to `.mp4` / `.mkv` through ffmpeg (stream copy, no re-encoding)
- Two dependencies: `httpx` and `cryptography`. Fully typed, checked with mypy.

## Install

```bash
pip install hlsfetch
```

Extras: `pip install "hlsfetch[socks]"` for SOCKS proxies, `pip install "hlsfetch[http2]"` for HTTP/2.

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 and subtitle tracks, duration, encryption and an estimated file size, and marks with `*` what would be downloaded. Add `--json` for machine-readable output.

```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

# only minutes 10 to 15, with Vietnamese and English subtitles (ep1.vi.vtt, ep1.en.vtt)
hlsfetch URL --start 10:00 --end 15:00 --subs vi,en -o ep1.mp4

# just the audio
hlsfetch URL --audio-only -o talk.m4a

# a whole list of links into one folder (lines starting with # are ignored)
hlsfetch -a links.txt -P downloads/
```

Proxies can also come from the usual environment variables (`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY`), and a custom CA bundle from `SSL_CERT_FILE`.

Files that already exist are skipped, so a batch can simply be run again after a failure; use `--force` to download them anyway. When several links would get the same file name, each gets a short suffix derived from its URL (`ep-3f9a1c.mp4`), so a link keeps its name between runs. `-v` shows retries and other details.

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 [URL ...] [-a FILE] [-o OUTPUT | -P DIR] [-q best|worst|720] [-i] [-f]

  -a, --batch-file FILE        read URLs from FILE, one per line ('-' = stdin)
  -o, --output FILE            output file (single URL only)
  -P, --output-dir DIR         folder for output files
  -q, --quality Q              best, worst, or a max height like 720 (default: best)
  -i, --info                   show stream info and exit
  -J, --json                   print stream info as JSON (implies --info)
  -f, --force                  download even if the output file exists

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
  --http2                      use HTTP/2 (needs hlsfetch[http2])
  -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
  --audio-only                 save only the audio (default extension .m4a)
  --no-audio                   skip separate audio tracks
  --subs LANGS                 save subtitles as .vtt: comma-separated languages, or 'all'
  --embed-subs                 put the subtitles inside the .mp4/.mkv instead
  --start TIME                 download from TIME (e.g. 10:00)
  --end TIME                   download up to TIME (e.g. 15:30)
  --no-remux                   never call ffmpeg; write raw streams to the given name
  --keep-parts                 keep the downloaded segment folder
  --quiet                      no progress output
  -v, --verbose                log retries and other details

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

  -V, --version                print the version
```

</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)
```

Download a clip with subtitles, or only the audio:

```python
hlsfetch.download(url, "clip.mp4", start=600, end=900, subtitles=["vi", "en"])  # + clip.vi.vtt, clip.en.vtt
hlsfetch.download(url, "talk.m4a", audio_only=True)
```

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"`) |
| `audio_only` | `False` | Save only the audio: the separate audio track, an audio-only variant, or the variant's audio extracted with ffmpeg |
| `subtitles` | `None` | `"all"` or languages like `["vi", "en"]`; saved next to the output as `<name>.<lang>.vtt` |
| `embed_subtitles` | `False` | Put the subtitles inside the output instead (`.mp4`, `.mkv`, `.mov`; needs ffmpeg) |
| `start` / `end` | `None` | Only download this time range, in seconds (rounded out to whole segments; audio and subtitle tracks follow the video's segments) |
| `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 |
| `http2` | `False` | Use HTTP/2 (needs the `h2` package: `hlsfetch[http2]`) |
| `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.

## Logging

hlsfetch logs retries, resumed downloads and track choices to the `hlsfetch` logger at `INFO` level:

```python
import logging

logging.basicConfig()
logging.getLogger("hlsfetch").setLevel(logging.INFO)
```

## 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.
- Subtitles aren't recorded from live streams.
- `start`/`end` cut at segment boundaries, so a clip can begin a few seconds early and end a few seconds late.
- fMP4 streams with ad breaks (several init sections) are joined with ffmpeg. Saved as `.mkv`, the joins can show a few harmless timestamp warnings in ffmpeg because Matroska stores millisecond timestamps; `.mp4` doesn't have this.
- 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 . && mypy
```

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
