hlsfetch 0.1.0__tar.gz

hlsfetch-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hlsfetch/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

hlsfetch-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+*.parts/
+*.ts
+*.mp4

hlsfetch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 doumamay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hlsfetch-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: hlsfetch
+Version: 0.1.0
+Summary: Fast async HLS (m3u8) downloader for Python: resume, AES-128, fMP4, ffmpeg remux.
+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,m3u8,streaming,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41
+Requires-Dist: httpx>=0.26
+Provides-Extra: socks
+Requires-Dist: httpx[socks]>=0.26; extra == 'socks'
+Description-Content-Type: text/markdown
+
+# hlsfetch
+
+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: run the same call again and finished segments are skipped
+- AES-128 decryption (key rotation and explicit or implicit IVs are handled)
+- MPEG-TS and fMP4 (`#EXT-X-MAP`) streams, plus `#EXT-X-BYTERANGE`
+- Quality selection: `best`, `worst`, max height, or your own function
+- Custom headers, Referer, proxy (HTTP or SOCKS)
+- Optional remux to `.mp4` through ffmpeg (stream copy, no re-encoding)
+- Only two dependencies: `httpx` and `cryptography`
+
+## Install
+
+```bash
+pip install hlsfetch
+```
+
+For SOCKS proxies: `pip install "hlsfetch[socks]"`. To get `.mp4` output from MPEG-TS streams, install [ffmpeg](https://ffmpeg.org/) and put it on your `PATH`. Without ffmpeg the raw `.ts` file is saved.
+
+## Command line
+
+```bash
+hlsfetch "https://example.com/video/master.m3u8" -o movie.mp4
+```
+
+```text
+hlsfetch URL [-o OUTPUT] [-q best|worst|720] [-H 'Name: value']... [-r REFERER]
+             [-j CONCURRENCY] [--retries N] [--timeout S] [--proxy URL]
+             [--no-remux] [--keep-parts] [-i/--info]
+```
+
+`hlsfetch URL --info` lists the variants, segment count, duration and encryption without downloading anything.
+
+If a download is interrupted, run the same command again to resume it.
+
+## Library
+
+```python
+import hlsfetch
+
+path = hlsfetch.download(
+    "https://example.com/video/master.m3u8",
+    "movie.mp4",
+    quality=720,                      # "best", "worst", 720, or a callable
+    headers={"Referer": "https://example.com/"},
+    concurrency=16,
+)
+print(path)
+```
+
+Async, with a progress callback:
+
+```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())
+```
+
+The callback may also be an `async def`. You can pass your own `httpx.AsyncClient` through `client=` to share cookies or connection pools.
+
+Parse a playlist yourself:
+
+```python
+pl = hlsfetch.parse_playlist(text, url)
+if isinstance(pl, hlsfetch.MasterPlaylist):
+    for v in pl.variants:
+        print(v.resolution, v.bandwidth, v.uri)
+else:
+    print(len(pl.segments), "segments,", pl.duration, "seconds")
+```
+
+### `download()` / `adownload()` options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `quality` | `"best"` | `"best"`, `"worst"`, max height (`720`), or `callable(variants) -> Variant` |
+| `headers` | `None` | Extra HTTP headers |
+| `concurrency` | `8` | Segments downloaded at once |
+| `retries` | `5` | Retries per request (network errors, 408/429/5xx) |
+| `timeout` | `30.0` | Request timeout in seconds |
+| `proxy` | `None` | Proxy URL |
+| `remux` | `True` | Use ffmpeg when the output extension differs from the stream's container |
+| `keep_parts` | `False` | Keep the `<output>.parts/` folder after merging |
+| `progress` | `None` | Called with a `Progress` after each segment |
+| `client` | `None` | Your own `httpx.AsyncClient` (it is not closed for you) |
+
+Errors are raised as subclasses of `hlsfetch.HLSFetchError`: `PlaylistError`, `UnsupportedError` and `DownloadError`.
+
+## Limitations
+
+- VOD only. Live playlists (no `#EXT-X-ENDLIST`) raise `UnsupportedError`.
+- No DRM (`SAMPLE-AES`, Widevine, FairPlay), and there are no plans to add it.
+- Separate audio renditions (`#EXT-X-MEDIA`) are not merged yet. Only the selected variant is downloaded.
+
+## Disclaimer
+
+Only download content you have the right to download. You are responsible for following the terms of service of the sites you use and the copyright law where you live.
+
+## License
+
+MIT

hlsfetch-0.1.0/README.md

@@ -0,0 +1,110 @@
+# hlsfetch
+
+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: run the same call again and finished segments are skipped
+- AES-128 decryption (key rotation and explicit or implicit IVs are handled)
+- MPEG-TS and fMP4 (`#EXT-X-MAP`) streams, plus `#EXT-X-BYTERANGE`
+- Quality selection: `best`, `worst`, max height, or your own function
+- Custom headers, Referer, proxy (HTTP or SOCKS)
+- Optional remux to `.mp4` through ffmpeg (stream copy, no re-encoding)
+- Only two dependencies: `httpx` and `cryptography`
+
+## Install
+
+```bash
+pip install hlsfetch
+```
+
+For SOCKS proxies: `pip install "hlsfetch[socks]"`. To get `.mp4` output from MPEG-TS streams, install [ffmpeg](https://ffmpeg.org/) and put it on your `PATH`. Without ffmpeg the raw `.ts` file is saved.
+
+## Command line
+
+```bash
+hlsfetch "https://example.com/video/master.m3u8" -o movie.mp4
+```
+
+```text
+hlsfetch URL [-o OUTPUT] [-q best|worst|720] [-H 'Name: value']... [-r REFERER]
+             [-j CONCURRENCY] [--retries N] [--timeout S] [--proxy URL]
+             [--no-remux] [--keep-parts] [-i/--info]
+```
+
+`hlsfetch URL --info` lists the variants, segment count, duration and encryption without downloading anything.
+
+If a download is interrupted, run the same command again to resume it.
+
+## Library
+
+```python
+import hlsfetch
+
+path = hlsfetch.download(
+    "https://example.com/video/master.m3u8",
+    "movie.mp4",
+    quality=720,                      # "best", "worst", 720, or a callable
+    headers={"Referer": "https://example.com/"},
+    concurrency=16,
+)
+print(path)
+```
+
+Async, with a progress callback:
+
+```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())
+```
+
+The callback may also be an `async def`. You can pass your own `httpx.AsyncClient` through `client=` to share cookies or connection pools.
+
+Parse a playlist yourself:
+
+```python
+pl = hlsfetch.parse_playlist(text, url)
+if isinstance(pl, hlsfetch.MasterPlaylist):
+    for v in pl.variants:
+        print(v.resolution, v.bandwidth, v.uri)
+else:
+    print(len(pl.segments), "segments,", pl.duration, "seconds")
+```
+
+### `download()` / `adownload()` options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `quality` | `"best"` | `"best"`, `"worst"`, max height (`720`), or `callable(variants) -> Variant` |
+| `headers` | `None` | Extra HTTP headers |
+| `concurrency` | `8` | Segments downloaded at once |
+| `retries` | `5` | Retries per request (network errors, 408/429/5xx) |
+| `timeout` | `30.0` | Request timeout in seconds |
+| `proxy` | `None` | Proxy URL |
+| `remux` | `True` | Use ffmpeg when the output extension differs from the stream's container |
+| `keep_parts` | `False` | Keep the `<output>.parts/` folder after merging |
+| `progress` | `None` | Called with a `Progress` after each segment |
+| `client` | `None` | Your own `httpx.AsyncClient` (it is not closed for you) |
+
+Errors are raised as subclasses of `hlsfetch.HLSFetchError`: `PlaylistError`, `UnsupportedError` and `DownloadError`.
+
+## Limitations
+
+- VOD only. Live playlists (no `#EXT-X-ENDLIST`) raise `UnsupportedError`.
+- No DRM (`SAMPLE-AES`, Widevine, FairPlay), and there are no plans to add it.
+- Separate audio renditions (`#EXT-X-MEDIA`) are not merged yet. Only the selected variant is downloaded.
+
+## Disclaimer
+
+Only download content you have the right to download. You are responsible for following the terms of service of the sites you use and the copyright law where you live.
+
+## License
+
+MIT

hlsfetch-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hlsfetch"
+dynamic = ["version"]
+description = "Fast async HLS (m3u8) downloader for Python: resume, AES-128, fMP4, ffmpeg remux."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "doumamay" }]
+keywords = ["hls", "m3u8", "downloader", "video", "streaming", "asyncio", "aes-128"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "httpx>=0.26",
+    "cryptography>=41",
+]
+
+[project.optional-dependencies]
+socks = ["httpx[socks]>=0.26"]
+
+[project.scripts]
+hlsfetch = "hlsfetch.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/doumamay/hlsfetch"
+Issues = "https://github.com/doumamay/hlsfetch/issues"
+
+[tool.hatch.version]
+path = "src/hlsfetch/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hlsfetch"]

hlsfetch-0.1.0/src/hlsfetch/__init__.py

@@ -0,0 +1,34 @@
+"""hlsfetch: download HLS (m3u8) streams from Python."""
+
+from .downloader import Progress, adownload, download, fetch_playlist, select_variant
+from .errors import DownloadError, HLSFetchError, PlaylistError, UnsupportedError
+from .playlist import (
+    InitSection,
+    Key,
+    MasterPlaylist,
+    MediaPlaylist,
+    Segment,
+    Variant,
+    parse_playlist,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "download",
+    "adownload",
+    "fetch_playlist",
+    "select_variant",
+    "parse_playlist",
+    "Progress",
+    "MasterPlaylist",
+    "MediaPlaylist",
+    "Variant",
+    "Segment",
+    "Key",
+    "InitSection",
+    "HLSFetchError",
+    "PlaylistError",
+    "UnsupportedError",
+    "DownloadError",
+]

hlsfetch-0.1.0/src/hlsfetch/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

hlsfetch-0.1.0/src/hlsfetch/cli.py

@@ -0,0 +1,131 @@
+"""Command-line interface: ``hlsfetch URL -o out.mp4``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+import warnings
+from pathlib import PurePosixPath
+from urllib.parse import urlparse
+
+from . import __version__
+from .downloader import Progress, _make_client, adownload, fetch_playlist
+from .errors import HLSFetchError
+from .playlist import MasterPlaylist, parse_playlist
+
+_GENERIC = {"index", "master", "playlist", "prog_index", "chunklist", "manifest", "video", "stream", "main"}
+
+
+def _default_output(url: str) -> str:
+    parts = [p for p in PurePosixPath(urlparse(url).path).parts if p != "/"]
+    for p in reversed(parts):
+        stem = PurePosixPath(p).stem
+        if stem and stem.lower() not in _GENERIC and not stem.lower().startswith(("index", "chunklist")):
+            return stem + ".mp4"
+    return "video.mp4"
+
+
+def _fmt_size(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} GB"
+
+
+def _print_progress(p: Progress) -> None:
+    bar = int(p.fraction * 30)
+    sys.stderr.write(
+        f"\r[{'#' * bar}{'.' * (30 - bar)}] {p.done}/{p.total} "
+        f"{p.fraction * 100:5.1f}%  {_fmt_size(p.bytes)}  {_fmt_size(p.speed)}/s   "
+    )
+    sys.stderr.flush()
+
+
+def _parse_headers(items, referer):
+    headers = {}
+    for h in items or []:
+        if ":" not in h:
+            raise SystemExit(f"invalid header (expected 'Name: value'): {h}")
+        k, v = h.split(":", 1)
+        headers[k.strip()] = v.strip()
+    if referer:
+        headers["Referer"] = referer
+        headers.setdefault("Origin", "{0.scheme}://{0.netloc}".format(urlparse(referer)))
+    return headers
+
+
+async def _info(url, headers, proxy, timeout) -> None:
+    async with _make_client(headers, proxy, timeout) as client:
+        r = await client.get(url)
+        r.raise_for_status()
+        pl = parse_playlist(r.text, str(r.url))
+        if isinstance(pl, MasterPlaylist):
+            print(f"Master playlist with {len(pl.variants)} variants:")
+            for v in sorted(pl.variants, key=lambda v: v.bandwidth, reverse=True):
+                print(f"  {v}  {v.codecs or ''}")
+        media, variant = await fetch_playlist(url, client)
+        if variant:
+            print(f"\nBest variant: {variant}")
+        kind = "fMP4" if media.is_fmp4 else "MPEG-TS"
+        enc = sorted({s.key.method for s in media.segments if s.key}) or ["none"]
+        m, s = divmod(int(media.duration), 60)
+        print(f"Segments: {len(media.segments)}  Duration: {m // 60}:{m % 60:02d}:{s:02d}  "
+              f"Container: {kind}  Encryption: {', '.join(enc)}  "
+              f"{'VOD' if media.endlist else 'LIVE'}")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="hlsfetch", description="Download HLS (m3u8) streams.")
+    ap.add_argument("url", help="URL of a master or media .m3u8 playlist")
+    ap.add_argument("-o", "--output", help="output file (default: derived from URL, .mp4)")
+    ap.add_argument("-q", "--quality", default="best",
+                    help="best, worst, or max height like 720 (default: best)")
+    ap.add_argument("-H", "--header", action="append", metavar="'NAME: VALUE'",
+                    help="extra HTTP header, repeatable")
+    ap.add_argument("-r", "--referer", help="set Referer (and Origin) header")
+    ap.add_argument("-j", "--concurrency", type=int, default=8, help="parallel segment downloads (default: 8)")
+    ap.add_argument("--retries", type=int, default=5, help="retries per request (default: 5)")
+    ap.add_argument("--timeout", type=float, default=30.0, help="request timeout in seconds (default: 30)")
+    ap.add_argument("--proxy", help="proxy URL, e.g. http://127.0.0.1:8080 or socks5://...")
+    ap.add_argument("--no-remux", action="store_true", help="never call ffmpeg; write the raw stream")
+    ap.add_argument("--keep-parts", action="store_true", help="keep the downloaded segment folder")
+    ap.add_argument("-i", "--info", action="store_true", help="show stream info and exit")
+    ap.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    args = ap.parse_args(argv)
+
+    headers = _parse_headers(args.header, args.referer)
+    quality = int(args.quality.rstrip("p")) if args.quality.rstrip("p").isdigit() else args.quality
+
+    try:
+        if args.info:
+            asyncio.run(_info(args.url, headers, args.proxy, args.timeout))
+            return 0
+        output = args.output or _default_output(args.url)
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            path = asyncio.run(adownload(
+                args.url, output,
+                quality=quality, headers=headers, concurrency=args.concurrency,
+                retries=args.retries, timeout=args.timeout, proxy=args.proxy,
+                remux=not args.no_remux, keep_parts=args.keep_parts, progress=_print_progress,
+            ))
+        sys.stderr.write("\n")
+        for w in caught:
+            sys.stderr.write(f"warning: {w.message}\n")
+        print(f"Saved to {path}")
+        return 0
+    except KeyboardInterrupt:
+        sys.stderr.write("\nInterrupted. Run the same command again to resume.\n")
+        return 130
+    except (HLSFetchError, ValueError) as e:
+        sys.stderr.write(f"\nerror: {e}\n")
+        return 1
+    except Exception as e:  # httpx errors from --info, etc.
+        sys.stderr.write(f"\nerror: {type(e).__name__}: {e}\n")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hlsfetch-0.1.0/src/hlsfetch/downloader.py

@@ -0,0 +1,288 @@
+"""Async HLS downloader."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import shutil
+import subprocess
+import time
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Awaitable, Callable, Mapping, Optional, Union
+
+import httpx
+from cryptography.hazmat.primitives import padding
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from .errors import DownloadError, PlaylistError, UnsupportedError
+from .playlist import InitSection, MasterPlaylist, MediaPlaylist, Segment, Variant, parse_playlist
+
+Quality = Union[str, int, Callable[[list], Variant]]
+
+DEFAULT_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36"
+_RETRY_STATUS = {408, 425, 429, 500, 502, 503, 504}
+
+
+@dataclass
+class Progress:
+    done: int
+    total: int
+    bytes: int
+    elapsed: float
+
+    @property
+    def fraction(self) -> float:
+        return self.done / self.total if self.total else 1.0
+
+    @property
+    def speed(self) -> float:
+        """Average bytes per second since the download started."""
+        return self.bytes / self.elapsed if self.elapsed > 0 else 0.0
+
+
+ProgressCallback = Callable[[Progress], Union[None, Awaitable[None]]]
+
+
+def select_variant(variants: list, quality: Quality = "best") -> Variant:
+    """Pick a variant: ``"best"``, ``"worst"``, a max height (``720``) or a callable."""
+    if callable(quality):
+        return quality(list(variants))
+    by_bw = sorted(variants, key=lambda v: v.bandwidth)
+    if quality == "best":
+        return by_bw[-1]
+    if quality == "worst":
+        return by_bw[0]
+    try:
+        max_h = int(str(quality).rstrip("p"))
+    except ValueError:
+        raise ValueError(f"invalid quality: {quality!r}") from None
+    fitting = [v for v in by_bw if v.height is not None and v.height <= max_h]
+    return fitting[-1] if fitting else by_bw[0]
+
+
+def _decrypt(data: bytes, key: bytes, iv: bytes) -> bytes:
+    dec = Cipher(algorithms.AES(key), modes.CBC(iv)).decryptor()
+    out = dec.update(data) + dec.finalize()
+    try:
+        unpadder = padding.PKCS7(128).unpadder()
+        return unpadder.update(out) + unpadder.finalize()
+    except ValueError:
+        return out  # some servers don't pad; keep the raw plaintext
+
+
+class _Fetcher:
+    def __init__(self, client: httpx.AsyncClient, retries: int):
+        self.client = client
+        self.retries = retries
+        self.keys: dict = {}
+
+    async def get(self, url: str, byterange=None) -> bytes:
+        headers = {}
+        if byterange:
+            off, length = byterange
+            headers["Range"] = f"bytes={off}-{off + length - 1}"
+        last_exc: Exception = DownloadError(url)
+        for attempt in range(self.retries + 1):
+            try:
+                r = await self.client.get(url, headers=headers)
+                if r.status_code in _RETRY_STATUS:
+                    last_exc = DownloadError(f"HTTP {r.status_code} for {url}")
+                elif r.status_code >= 400:
+                    raise DownloadError(f"HTTP {r.status_code} for {url}")
+                else:
+                    data = r.content
+                    if byterange and r.status_code == 200:  # server ignored Range
+                        data = data[byterange[0]:byterange[0] + byterange[1]]
+                    return data
+            except httpx.HTTPError as e:
+                last_exc = DownloadError(f"{type(e).__name__} for {url}: {e}")
+            if attempt < self.retries:
+                await asyncio.sleep(min(2 ** attempt, 30) + random.random())
+        raise last_exc
+
+    async def key(self, uri: str) -> bytes:
+        if uri not in self.keys:
+            data = await self.get(uri)
+            if len(data) != 16:
+                raise DownloadError(f"AES-128 key at {uri} is {len(data)} bytes, expected 16")
+            self.keys[uri] = data
+        return self.keys[uri]
+
+    async def payload(self, uri, byterange, key, iv) -> bytes:
+        data = await self.get(uri, byterange)
+        if key is not None:
+            data = _decrypt(data, await self.key(key.uri), iv)
+        return data
+
+
+def _check_supported(pl: MediaPlaylist) -> None:
+    if not pl.endlist:
+        raise UnsupportedError("live streams are not supported (playlist has no #EXT-X-ENDLIST)")
+    if not pl.segments:
+        raise PlaylistError("media playlist has no segments")
+    for seg in pl.segments:
+        for k in (seg.key, seg.init.key if seg.init else None):
+            if k and k.method != "AES-128":
+                raise UnsupportedError(f"encryption method {k.method} is not supported")
+            if k and not k.uri:
+                raise PlaylistError("EXT-X-KEY without URI")
+
+
+async def fetch_playlist(url: str, client: httpx.AsyncClient, quality: Quality = "best"):
+    """Fetch ``url`` and resolve it to a media playlist. Returns (media, variant_or_None)."""
+    fetcher = _Fetcher(client, retries=3)
+    pl = parse_playlist((await fetcher.get(url)).decode("utf-8", "replace"), url)
+    if isinstance(pl, MasterPlaylist):
+        variant = select_variant(pl.variants, quality)
+        media = parse_playlist((await fetcher.get(variant.uri)).decode("utf-8", "replace"), variant.uri)
+        if isinstance(media, MasterPlaylist):
+            raise PlaylistError("variant URI points to another master playlist")
+        return media, variant
+    return pl, None
+
+
+def _make_client(headers, proxy, timeout) -> httpx.AsyncClient:
+    h = {"User-Agent": DEFAULT_UA}
+    h.update(headers or {})
+    return httpx.AsyncClient(headers=h, proxy=proxy, timeout=timeout, follow_redirects=True,
+                             limits=httpx.Limits(max_connections=64))
+
+
+async def adownload(
+    url: str,
+    output: Union[str, os.PathLike],
+    *,
+    quality: Quality = "best",
+    headers: Optional[Mapping[str, str]] = None,
+    concurrency: int = 8,
+    retries: int = 5,
+    timeout: float = 30.0,
+    proxy: Optional[str] = None,
+    remux: bool = True,
+    keep_parts: bool = False,
+    progress: Optional[ProgressCallback] = None,
+    client: Optional[httpx.AsyncClient] = None,
+) -> Path:
+    """Download the HLS stream at ``url`` into ``output`` and return the final path.
+
+    Segments are stored in ``<output>.parts/`` while downloading, so an interrupted
+    run picks up where it left off. If ``output`` ends in a different container
+    than the stream (e.g. ``.mp4`` for an MPEG-TS stream) and ``remux`` is true,
+    ffmpeg is used to remux without re-encoding; without ffmpeg the raw stream is
+    saved next to ``output`` with its native extension.
+    """
+    output = Path(output)
+    own_client = client is None
+    client = client or _make_client(headers, proxy, timeout)
+    try:
+        media, _ = await fetch_playlist(url, client, quality)
+        _check_supported(media)
+        fetcher = _Fetcher(client, retries)
+
+        parts = output.with_name(output.name + ".parts")
+        parts.mkdir(parents=True, exist_ok=True)
+
+        inits: dict = {}  # InitSection -> path
+        for seg in media.segments:
+            if seg.init and seg.init not in inits:
+                inits[seg.init] = parts / f"init{len(inits)}.mp4"
+        for init, path in inits.items():
+            if not path.exists():
+                iv = (init.key.iv or b"\0" * 16) if init.key else None
+                path.write_bytes(await fetcher.payload(init.uri, init.byterange, init.key, iv))
+
+        ext = ".m4s" if media.is_fmp4 else ".ts"
+        seg_path = lambda s: parts / f"{s.index:06d}{ext}"  # noqa: E731
+
+        total = len(media.segments)
+        state = {"done": 0, "bytes": 0}
+        start = time.monotonic()
+
+        async def report():
+            if progress:
+                r = progress(Progress(state["done"], total, state["bytes"], time.monotonic() - start))
+                if asyncio.iscoroutine(r):
+                    await r
+
+        for seg in media.segments:
+            p = seg_path(seg)
+            if p.exists():
+                state["done"] += 1
+                state["bytes"] += p.stat().st_size
+        await report()
+
+        sem = asyncio.Semaphore(max(1, concurrency))
+
+        async def worker(seg: Segment):
+            p = seg_path(seg)
+            if p.exists():
+                return
+            async with sem:
+                data = await fetcher.payload(seg.uri, seg.byterange, seg.key, seg.iv)
+            tmp = p.with_suffix(p.suffix + ".tmp")
+            tmp.write_bytes(data)
+            os.replace(tmp, p)
+            state["done"] += 1
+            state["bytes"] += len(data)
+            await report()
+
+        tasks = [asyncio.ensure_future(worker(s)) for s in media.segments]
+        try:
+            await asyncio.gather(*tasks)
+        except BaseException:
+            for t in tasks:
+                t.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            raise
+
+        final = _merge(media, inits, seg_path, output, remux)
+        if not keep_parts:
+            shutil.rmtree(parts, ignore_errors=True)
+        return final
+    finally:
+        if own_client:
+            await client.aclose()
+
+
+def _merge(media: MediaPlaylist, inits: dict, seg_path, output: Path, remux: bool) -> Path:
+    native = ".mp4" if media.is_fmp4 else ".ts"
+    need_remux = remux and output.suffix.lower() != native
+    ffmpeg = shutil.which("ffmpeg") if need_remux else None
+    if need_remux and not ffmpeg:
+        warnings.warn(f"ffmpeg not found; saving raw stream as {native} instead of remuxing",
+                      RuntimeWarning, stacklevel=3)
+        output = output.with_suffix(native)
+        need_remux = False
+
+    raw = output.with_name(output.stem + ".raw" + native) if need_remux else output
+    current_init: Optional[InitSection] = None
+    with open(raw, "wb") as out:
+        for seg in media.segments:
+            if seg.init is not None and seg.init != current_init:
+                out.write(inits[seg.init].read_bytes())
+                current_init = seg.init
+            with open(seg_path(seg), "rb") as f:
+                shutil.copyfileobj(f, out)
+
+    if need_remux:
+        cmd = [ffmpeg, "-y", "-loglevel", "error", "-i", str(raw), "-c", "copy"]
+        if native == ".ts" and output.suffix.lower() in (".mp4", ".m4v", ".mov"):
+            cmd += ["-bsf:a", "aac_adtstoasc"]
+        cmd.append(str(output))
+        res = subprocess.run(cmd, capture_output=True, text=True)
+        if res.returncode != 0:
+            raise DownloadError(f"ffmpeg remux failed, raw stream kept at {raw}: {res.stderr.strip()}")
+        raw.unlink()
+    return output
+
+
+def download(url: str, output: Union[str, os.PathLike], **kwargs) -> Path:
+    """Blocking wrapper around :func:`adownload`. Takes the same keyword arguments."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(adownload(url, output, **kwargs))
+    raise RuntimeError("download() can't run inside an event loop; use `await adownload(...)`")

hlsfetch-0.1.0/src/hlsfetch/errors.py

@@ -0,0 +1,14 @@
+class HLSFetchError(Exception):
+    """Base class for all hlsfetch errors."""
+
+
+class PlaylistError(HLSFetchError):
+    """The playlist could not be parsed or is not usable."""
+
+
+class UnsupportedError(HLSFetchError):
+    """The stream uses a feature hlsfetch does not support (live, SAMPLE-AES, ...)."""
+
+
+class DownloadError(HLSFetchError):
+    """A segment, key or playlist could not be downloaded."""

hlsfetch-0.1.0/src/hlsfetch/playlist.py

@@ -0,0 +1,198 @@
+"""Minimal M3U8 parser covering what a VOD downloader needs."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional, Tuple, Union
+from urllib.parse import urljoin
+
+from .errors import PlaylistError
+
+_ATTR_RE = re.compile(r'([A-Z0-9-]+)=("[^"]*"|[^,]*)')
+
+
+def _attrs(s: str) -> dict:
+    return {k: v.strip('"') for k, v in _ATTR_RE.findall(s)}
+
+
+def _byterange(value: str, prev_end: Optional[int]) -> Tuple[int, int]:
+    """Return (offset, length) for a BYTERANGE value like ``1000@200``."""
+    length, _, offset = value.partition("@")
+    if offset:
+        return int(offset), int(length)
+    if prev_end is None:
+        raise PlaylistError(f"BYTERANGE without offset and no previous range: {value}")
+    return prev_end, int(length)
+
+
+@dataclass(frozen=True)
+class Key:
+    method: str
+    uri: Optional[str]
+    iv: Optional[bytes]
+
+
+@dataclass(frozen=True)
+class InitSection:
+    uri: str
+    byterange: Optional[Tuple[int, int]] = None
+    key: Optional[Key] = None
+
+
+@dataclass(frozen=True)
+class Segment:
+    index: int
+    uri: str
+    duration: float
+    sequence: int
+    key: Optional[Key] = None
+    byterange: Optional[Tuple[int, int]] = None
+    init: Optional[InitSection] = None
+
+    @property
+    def iv(self) -> Optional[bytes]:
+        if self.key is None:
+            return None
+        return self.key.iv or self.sequence.to_bytes(16, "big")
+
+
+@dataclass(frozen=True)
+class Variant:
+    uri: str
+    bandwidth: int
+    resolution: Optional[Tuple[int, int]] = None
+    codecs: Optional[str] = None
+    frame_rate: Optional[float] = None
+
+    @property
+    def height(self) -> Optional[int]:
+        return self.resolution[1] if self.resolution else None
+
+    def __str__(self) -> str:
+        res = f"{self.resolution[0]}x{self.resolution[1]}" if self.resolution else "audio/unknown"
+        return f"{res} @ {self.bandwidth / 1000:.0f} kbps"
+
+
+@dataclass
+class MasterPlaylist:
+    url: str
+    variants: list = field(default_factory=list)
+
+
+@dataclass
+class MediaPlaylist:
+    url: str
+    segments: list = field(default_factory=list)
+    target_duration: float = 0.0
+    endlist: bool = False
+
+    @property
+    def duration(self) -> float:
+        return sum(s.duration for s in self.segments)
+
+    @property
+    def is_fmp4(self) -> bool:
+        return any(s.init is not None for s in self.segments)
+
+
+Playlist = Union[MasterPlaylist, MediaPlaylist]
+
+
+def parse_playlist(text: str, url: str) -> Playlist:
+    """Parse M3U8 text fetched from ``url`` (used to resolve relative URIs)."""
+    lines = [ln.strip() for ln in text.lstrip("").splitlines()]
+    lines = [ln for ln in lines if ln]
+    if not lines or not lines[0].startswith("#EXTM3U"):
+        raise PlaylistError("not an M3U8 playlist (missing #EXTM3U)")
+
+    if any(ln.startswith("#EXT-X-STREAM-INF") for ln in lines):
+        return _parse_master(lines, url)
+    return _parse_media(lines, url)
+
+
+def _parse_master(lines: list, url: str) -> MasterPlaylist:
+    master = MasterPlaylist(url=url)
+    pending = None
+    for ln in lines:
+        if ln.startswith("#EXT-X-STREAM-INF:"):
+            pending = _attrs(ln.split(":", 1)[1])
+        elif ln.startswith("#"):
+            continue
+        elif pending is not None:
+            res = None
+            if "RESOLUTION" in pending:
+                w, _, h = pending["RESOLUTION"].lower().partition("x")
+                res = (int(w), int(h))
+            master.variants.append(Variant(
+                uri=urljoin(url, ln),
+                bandwidth=int(pending.get("BANDWIDTH", 0)),
+                resolution=res,
+                codecs=pending.get("CODECS"),
+                frame_rate=float(pending["FRAME-RATE"]) if "FRAME-RATE" in pending else None,
+            ))
+            pending = None
+    if not master.variants:
+        raise PlaylistError("master playlist has no variants")
+    return master
+
+
+def _parse_key(value: str, url: str) -> Optional[Key]:
+    a = _attrs(value)
+    method = a.get("METHOD", "NONE").upper()
+    if method == "NONE":
+        return None
+    iv = None
+    if "IV" in a:
+        hexiv = a["IV"][2:] if a["IV"].lower().startswith("0x") else a["IV"]
+        iv = bytes.fromhex(hexiv.rjust(32, "0"))
+    return Key(method=method, uri=urljoin(url, a["URI"]) if "URI" in a else None, iv=iv)
+
+
+def _parse_media(lines: list, url: str) -> MediaPlaylist:
+    pl = MediaPlaylist(url=url)
+    seq = 0
+    key: Optional[Key] = None
+    init: Optional[InitSection] = None
+    duration: Optional[float] = None
+    byterange: Optional[Tuple[int, int]] = None
+    range_end: dict = {}  # uri -> end offset of the last byterange, for implicit offsets
+
+    for ln in lines:
+        if ln.startswith("#EXT-X-MEDIA-SEQUENCE:"):
+            seq = int(ln.split(":", 1)[1])
+        elif ln.startswith("#EXT-X-TARGETDURATION:"):
+            pl.target_duration = float(ln.split(":", 1)[1])
+        elif ln.startswith("#EXT-X-ENDLIST"):
+            pl.endlist = True
+        elif ln.startswith("#EXT-X-KEY:"):
+            key = _parse_key(ln.split(":", 1)[1], url)
+        elif ln.startswith("#EXT-X-MAP:"):
+            a = _attrs(ln.split(":", 1)[1])
+            br = _byterange(a["BYTERANGE"], 0) if "BYTERANGE" in a else None
+            init = InitSection(uri=urljoin(url, a["URI"]), byterange=br, key=key)
+        elif ln.startswith("#EXTINF:"):
+            duration = float(ln.split(":", 1)[1].split(",", 1)[0] or 0)
+        elif ln.startswith("#EXT-X-BYTERANGE:"):
+            byterange = ln.split(":", 1)[1]
+        elif ln.startswith("#"):
+            continue
+        else:
+            uri = urljoin(url, ln)
+            br = None
+            if byterange is not None:
+                br = _byterange(byterange, range_end.get(uri))
+                range_end[uri] = br[0] + br[1]
+            pl.segments.append(Segment(
+                index=len(pl.segments),
+                uri=uri,
+                duration=duration or 0.0,
+                sequence=seq,
+                key=key,
+                byterange=br,
+                init=init,
+            ))
+            seq += 1
+            duration = None
+            byterange = None
+    return pl