m3u8-cli 0.1.0__py3-none-any.whl

m3u8_cli/__init__.py

@@ -0,0 +1,3 @@
+"""HLS 视频下载与格式转换工具。"""
+
+__version__ = "0.1.0"

m3u8_cli/__main__.py

@@ -0,0 +1,6 @@
+"""支持 python -m m3u8_cli。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

m3u8_cli/cli.py

@@ -0,0 +1,186 @@
+"""命令行入口与下载流程编排。"""
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import requests
+
+from .convert import convert_video
+from .download import DownloadOptions, download_hls
+from .errors import HLSException
+from .serve import run_serve
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="m3u8-cli",
+        description="HLS 下载与视频格式转换工具",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    download = subparsers.add_parser(
+        "download",
+        help="下载 HLS（m3u8）视频",
+        description="并发下载 HLS 分片，产物保存在任务子目录中",
+    )
+    download.add_argument("url", help="m3u8 地址")
+    download.add_argument(
+        "-f", "--format", choices=("mp4", "hls"), default="mp4",
+        help="输出格式：mp4（合并封装，默认）或 hls（保留分片，不合并）",
+    )
+    download.add_argument(
+        "-o", "--output",
+        help="mp4: 最终文件名；hls: 任务目录（默认 output.mp4 / output）",
+    )
+    download.add_argument("-j", "--jobs", type=int, default=8)
+    download.add_argument("--retries", type=int, default=3)
+    download.add_argument("--timeout", type=int, default=30)
+    download.add_argument("--referer")
+    download.add_argument("--cookie")
+    download.add_argument("--user-agent", default="Mozilla/5.0")
+    download.add_argument(
+        "--overwrite", action="store_true",
+        help="覆盖已有输出文件",
+    )
+
+    convert = subparsers.add_parser(
+        "convert",
+        help="把本地视频转换为 HLS 或其他格式",
+        description="用 FFmpeg 转换视频格式，默认输出 HLS",
+    )
+    convert.add_argument("input", help="输入视频文件")
+    convert.add_argument(
+        "-f", "--format", choices=("hls", "mp4", "mkv", "webm"),
+        default="hls", help="输出格式（默认 hls）",
+    )
+    convert.add_argument(
+        "-c", "--codec", choices=("h264", "hevc", "copy"),
+        default="h264", help="编码方式（默认 h264）",
+    )
+    convert.add_argument(
+        "-o", "--output-dir",
+        help="输出目录；默认为输入文件名",
+    )
+    convert.add_argument(
+        "--segment-time", type=int, default=6,
+        help="HLS 分片时长（秒，默认 6）",
+    )
+    convert.add_argument(
+        "--overwrite", action="store_true",
+        help="覆盖已有产物",
+    )
+    convert.add_argument(
+        "--encrypt", action="store_true",
+        help="为 HLS 分片启用 AES-128 加密",
+    )
+
+    serve = subparsers.add_parser(
+        "serve",
+        help="启动 RESTful 下载服务",
+        description="在局域网启动 HTTP API，接受远程下载任务",
+    )
+    serve.add_argument("--host", default="0.0.0.0")
+    serve.add_argument("--port", type=int, default=8787)
+    serve.add_argument(
+        "--token", help="Bearer token；省略时自动生成并打印",
+    )
+    serve.add_argument(
+        "--output-dir", default=".",
+        help="任务目录根路径（默认当前目录）",
+    )
+    serve.add_argument(
+        "--max-tasks", type=int, default=3,
+        help="同时运行的任务数上限",
+    )
+    serve.add_argument(
+        "--jobs", type=int, default=8,
+        help="请求未指定 jobs 时的分片并发默认值",
+    )
+    serve.add_argument(
+        "--state-file", help="任务状态文件路径",
+    )
+    return parser
+
+
+def run_download(args):
+    if args.format == "mp4" and not shutil.which("ffmpeg"):
+        sys.exit("请先安装 ffmpeg")
+
+    output_arg = args.output if args.output is not None else (
+        "output" if args.format == "hls" else "output.mp4"
+    )
+
+    headers = {"User-Agent": args.user_agent}
+    if args.referer:
+        headers["Referer"] = args.referer
+    if args.cookie:
+        headers["Cookie"] = args.cookie
+
+    def on_progress(completed, total):
+        print(f"\r下载进度：{completed}/{total}", end="", flush=True)
+
+    output = download_hls(
+        DownloadOptions(
+            url=args.url,
+            output=Path(output_arg),
+            format=args.format,
+            jobs=args.jobs,
+            retries=args.retries,
+            timeout=args.timeout,
+            headers=headers,
+            overwrite=args.overwrite,
+        ),
+        on_progress=on_progress,
+    )
+    print()
+    print(f"完成：{output}")
+
+
+def run_convert(args):
+    if not shutil.which("ffmpeg"):
+        sys.exit("请先安装 ffmpeg")
+
+    output = convert_video(
+        args.input,
+        args.format,
+        args.codec,
+        args.output_dir,
+        args.segment_time,
+        args.overwrite,
+        args.encrypt,
+    )
+    print(f"完成：{output}")
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "download":
+        if args.jobs < 1 or args.timeout < 1 or args.retries < 0:
+            parser.error("jobs/timeout 必须为正数，retries 不能为负数")
+        handler = run_download
+    elif args.command == "convert":
+        if args.encrypt and args.format != "hls":
+            parser.error("--encrypt 仅适用于 HLS")
+        if args.format == "hls" and args.segment_time < 1:
+            parser.error("segment-time 必须为正整数")
+        handler = run_convert
+    elif args.command == "serve":
+        # 0 表示由操作系统分配空闲端口（服务实际监听端口见启动日志）
+        if not 0 <= args.port <= 65535:
+            parser.error("port 必须在 0 到 65535 之间")
+        if args.max_tasks < 1 or args.jobs < 1:
+            parser.error("max-tasks/jobs 必须为正整数")
+        handler = run_serve
+    else:
+        parser.error(f"未知子命令：{args.command}")
+
+    try:
+        handler(args)
+    except (HLSException, OSError, requests.RequestException,
+            subprocess.CalledProcessError) as exc:
+        sys.exit(f"\n错误：{exc}")

m3u8_cli/convert.py

@@ -0,0 +1,277 @@
+"""视频格式转换（FFmpeg）。"""
+
+import secrets
+import subprocess
+from pathlib import Path
+
+from .errors import HLSException
+
+HLS_KEY_NAME = "key.bin"
+HLS_KEY_INFO_NAME = ".key_info.txt"
+HLS_KEY_SIZE = 16
+
+FORMAT_SUFFIX = {
+    "hls": None,
+    "mp4": ".mp4",
+    "mkv": ".mkv",
+    "webm": ".webm",
+}
+
+CODEC_ARGS = {
+    "h264": ["-c:v", "libx264", "-c:a", "aac"],
+    "hevc": ["-c:v", "libx265", "-c:a", "aac"],
+    "copy": ["-c", "copy"],
+}
+
+WEBM_CODEC_ARGS = {
+    # WebM 不支持 H.264/AAC，重编码统一使用 VP9/Opus。
+    "h264": [
+        "-c:v", "libvpx-vp9", "-crf", "32", "-b:v", "0",
+        "-c:a", "libopus",
+    ],
+    "hevc": [
+        "-c:v", "libvpx-vp9", "-crf", "32", "-b:v", "0",
+        "-c:a", "libopus",
+    ],
+    "copy": ["-c", "copy"],
+}
+
+
+def resolve_output_dir(input_path, output_arg):
+    """返回输出目录；未指定时使用输入文件 stem 作为目录名。"""
+    if output_arg:
+        output_dir = Path(output_arg).expanduser().resolve()
+    else:
+        output_dir = (Path.cwd() / input_path.stem).resolve()
+
+    if output_dir.exists() and not output_dir.is_dir():
+        raise HLSException(f"输出路径不是目录：{output_dir}")
+
+    try:
+        output_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise HLSException(f"无法创建输出目录：{output_dir}（{exc}）") from exc
+    return output_dir
+
+
+def codec_args(fmt, codec):
+    """返回目标格式对应的 FFmpeg 编码参数。"""
+    if fmt == "webm":
+        return WEBM_CODEC_ARGS[codec]
+    return CODEC_ARGS[codec]
+
+
+def build_hls_command(input_path, output_dir, codec, segment_time,
+                      encrypt=False):
+    """构造 HLS 转换的 FFmpeg 命令。"""
+    command = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(input_path),
+        "-map", "0:v?", "-map", "0:a?",
+        *codec_args("hls", codec),
+    ]
+
+    if codec != "copy":
+        command += [
+            "-force_key_frames",
+            f"expr:gte(t,n_forced*{segment_time})",
+        ]
+
+    command += [
+        "-f", "hls",
+        "-hls_time", str(segment_time),
+        "-hls_playlist_type", "vod",
+        "-hls_list_size", "0",
+        "-hls_base_url", "ts/",
+    ]
+
+    if encrypt:
+        command += [
+            "-hls_key_info_file",
+            str(output_dir / HLS_KEY_INFO_NAME),
+        ]
+
+    command += [
+        "-hls_segment_filename", str(output_dir / "ts" / "%06d.ts"),
+        str(output_dir / "playlist.m3u8"),
+    ]
+    return command
+
+
+def build_file_command(input_path, fmt, codec, partial):
+    """构造单文件格式转换的 FFmpeg 命令。"""
+    command = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(input_path),
+        "-map", "0:v?", "-map", "0:a?",
+        *codec_args(fmt, codec),
+    ]
+
+    if fmt == "mp4":
+        command += ["-movflags", "+faststart"]
+        if codec == "hevc":
+            command += ["-tag:v", "hvc1"]
+
+    command.append(str(partial))
+    return command
+
+
+def _clear_hls_output(playlist, segments_dir):
+    """只清理旧播放列表与 6 位编号分片，保留 ts/ 中的其他文件。"""
+    playlist.unlink(missing_ok=True)
+    if not segments_dir.is_dir():
+        return
+    for entry in segments_dir.iterdir():
+        stem = entry.name[:-3]
+        if (
+            entry.name.endswith(".ts")
+            and len(stem) == 6
+            and stem.isascii()
+            and stem.isdigit()
+            and (entry.is_file() or entry.is_symlink())
+        ):
+            entry.unlink()
+
+
+def _write_hls_key(output_dir):
+    """生成新的 AES-128 密钥并返回其路径。"""
+    key_path = output_dir / HLS_KEY_NAME
+    if key_path.is_symlink():
+        key_path.unlink()
+    elif key_path.exists() and key_path.is_dir():
+        raise HLSException(f"密钥路径是目录：{key_path}")
+    key_path.write_bytes(secrets.token_bytes(HLS_KEY_SIZE))
+    return key_path
+
+
+def _write_key_info(output_dir, key_path):
+    """写入 FFmpeg 的 key-info 临时文件并返回其路径。"""
+    key_info = output_dir / HLS_KEY_INFO_NAME
+    if key_info.is_symlink():
+        key_info.unlink()
+    elif key_info.exists() and key_info.is_dir():
+        raise HLSException(f"密钥信息路径是目录：{key_info}")
+    key_info.write_text(
+        f"{HLS_KEY_NAME}\n{key_path}\n",
+        encoding="utf-8",
+    )
+    return key_info
+
+
+def convert_video(input_arg, fmt, codec, output_arg,
+                  segment_time, overwrite, encrypt=False):
+    """转换视频并返回最终产物路径。"""
+    if encrypt and fmt != "hls":
+        raise HLSException("--encrypt 仅适用于 HLS")
+
+    input_path = Path(input_arg).expanduser().resolve()
+    if not input_path.is_file():
+        raise HLSException(f"输入文件不存在：{input_path}")
+
+    output_dir = resolve_output_dir(input_path, output_arg)
+
+    if fmt == "hls":
+        playlist = output_dir / "playlist.m3u8"
+        segments_dir = output_dir / "ts"
+        key_path = output_dir / HLS_KEY_NAME
+        key_info_path = output_dir / HLS_KEY_INFO_NAME
+
+        if encrypt:
+            if key_path.is_dir() and not key_path.is_symlink():
+                raise HLSException(f"密钥路径是目录：{key_path}")
+            if key_info_path.is_dir() and not key_info_path.is_symlink():
+                raise HLSException(f"密钥信息路径是目录：{key_info_path}")
+
+        if playlist == input_path:
+            raise HLSException(f"输出文件与输入文件相同：{playlist}")
+        if segments_dir == input_path or segments_dir in input_path.parents:
+            raise HLSException(f"输入文件位于分片目录中：{input_path}")
+        if encrypt and (key_path == input_path or key_info_path == input_path):
+            raise HLSException(f"输出文件与输入文件相同：{input_path}")
+        if segments_dir.is_symlink():
+            raise HLSException(f"分片路径是符号链接：{segments_dir}")
+        if segments_dir.exists() and not segments_dir.is_dir():
+            raise HLSException(f"分片路径不是目录：{segments_dir}")
+        if playlist.is_dir():
+            raise HLSException(f"播放列表路径不是文件：{playlist}")
+        if not overwrite and (
+            playlist.exists()
+            or playlist.is_symlink()
+            or segments_dir.exists()
+            or (
+                encrypt
+                and (
+                    key_path.exists()
+                    or key_path.is_symlink()
+                    or key_info_path.exists()
+                    or key_info_path.is_symlink()
+                )
+            )
+        ):
+            raise HLSException(
+                f"目标已存在：{output_dir}，使用 --overwrite 覆盖"
+            )
+
+        if overwrite:
+            _clear_hls_output(playlist, segments_dir)
+        segments_dir.mkdir(parents=True, exist_ok=True)
+
+        key_info = None
+        if encrypt:
+            key_path = _write_hls_key(output_dir)
+            try:
+                key_info = _write_key_info(output_dir, key_path)
+            except BaseException:
+                key_path.unlink(missing_ok=True)
+                raise
+        else:
+            key_path = None
+
+        try:
+            subprocess.run(
+                build_hls_command(
+                    input_path, output_dir, codec, segment_time, encrypt
+                ),
+                check=True,
+            )
+        except BaseException:
+            if key_path is not None:
+                key_path.unlink(missing_ok=True)
+            raise
+        finally:
+            if key_info is not None:
+                key_info.unlink(missing_ok=True)
+
+        return playlist
+
+    output = output_dir / (input_path.stem + FORMAT_SUFFIX[fmt])
+    if output == input_path:
+        raise HLSException(f"输出文件与输入文件相同：{output}")
+    if output.is_dir():
+        raise HLSException(f"输出路径是目录：{output}")
+    if not overwrite and (output.exists() or output.is_symlink()):
+        raise HLSException(
+            f"输出文件已存在：{output}，使用 --overwrite 覆盖"
+        )
+
+    partial = output_dir / (
+        input_path.stem + ".partial" + FORMAT_SUFFIX[fmt]
+    )
+    if partial.is_symlink():
+        partial.unlink()
+    elif partial.exists():
+        if partial.is_dir():
+            raise HLSException(f"临时输出路径是目录：{partial}")
+        partial.unlink()
+
+    try:
+        subprocess.run(
+            build_file_command(input_path, fmt, codec, partial),
+            check=True,
+        )
+        partial.replace(output)
+    except Exception:
+        if partial.is_file() or partial.is_symlink():
+            partial.unlink()
+        raise
+    return output

m3u8_cli/download.py

@@ -0,0 +1,193 @@
+"""可复用的 HLS 下载流程。"""
+
+import concurrent.futures
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .downloader import Downloader
+from .errors import DownloadCancelled, HLSException
+from .hls_export import export_hls
+from .merge import combine_segments, mux
+from .paths import resolve_task_paths
+from .playlist import load_playlist
+
+
+@dataclass
+class DownloadOptions:
+    url: str
+    output: Path
+    format: str = "mp4"
+    jobs: int = 8
+    retries: int = 3
+    timeout: int = 30
+    headers: dict = field(default_factory=dict)
+    overwrite: bool = False
+
+
+def _check_cancel(cancel):
+    if cancel is not None and cancel.is_set():
+        raise DownloadCancelled("下载已取消")
+
+
+def _resolve_paths(options):
+    if options.format == "hls":
+        task_dir = Path(options.output).expanduser().resolve()
+        if task_dir.exists() and not task_dir.is_dir():
+            raise HLSException(f"任务目录不是目录：{task_dir}")
+        return task_dir / "playlist.m3u8", task_dir / "cache"
+    return resolve_task_paths(options.output)
+
+
+def _load_state(state_file):
+    if not state_file.exists():
+        return None
+    try:
+        return json.loads(state_file.read_text("utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def download_hls(options, on_progress=None, cancel=None):
+    """下载 HLS 并输出；mp4 返回最终文件，hls 返回任务目录。"""
+    if options.format not in ("mp4", "hls"):
+        raise HLSException(f"不支持的输出格式：{options.format}")
+
+    _check_cancel(cancel)
+    final, cache = _resolve_paths(options)
+    task_dir = cache.parent
+
+    if final.exists() and not options.overwrite:
+        raise HLSException(
+            f"输出文件已存在：{final}，使用 --overwrite 覆盖"
+        )
+
+    cache.mkdir(parents=True, exist_ok=True)
+
+    print("读取 m3u8...")
+    playlist = load_playlist(options.url, options.headers, options.timeout)
+    segments = playlist["segments"]
+    fingerprint = playlist["fingerprint"]
+
+    state_file = cache / "state.json"
+    previous = _load_state(state_file)
+    if previous and (
+        previous.get("fingerprint") != fingerprint
+        or previous.get("mode", "mp4") != options.format
+    ):
+        print("播放列表或输出模式已变化，清除旧分片缓存")
+        for p in cache.glob("segment_*.bin"):
+            p.unlink(missing_ok=True)
+        for p in cache.glob("map_*.bin"):
+            p.unlink(missing_ok=True)
+
+    state_file.write_text(
+        json.dumps(
+            {"fingerprint": fingerprint, "mode": options.format},
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+
+    downloader = Downloader(
+        options.headers, options.timeout, options.retries
+    )
+
+    key_data = {}
+    key_names = {}
+    if options.format == "hls":
+        key_uris = list(dict.fromkeys(
+            s["key"]["uri"] for s in segments if s.get("key")
+        ))
+        for uri in key_uris:
+            _check_cancel(cancel)
+            key_data[uri] = downloader.get_key(uri)
+        for index, uri in enumerate(key_uris):
+            key_names[uri] = (
+                "key.bin" if len(key_uris) == 1
+                else f"key_{index:03d}.bin"
+            )
+
+    map_paths = {}
+    for i, map_url in enumerate(playlist["maps"]):
+        _check_cancel(cancel)
+        path = cache / f"map_{i:04d}.bin"
+        map_paths[map_url] = downloader.download(
+            map_url, path, decrypt=False
+        )
+        print(f"初始化片段已准备：{i + 1}/{len(playlist['maps'])}")
+
+    jobs = [
+        (i, segment, cache / f"segment_{i:06d}.bin")
+        for i, segment in enumerate(segments)
+    ]
+    print(f"共 {len(jobs)} 个分片，并发数 {options.jobs}")
+
+    completed = 0
+    decrypt = options.format == "mp4"
+
+    with concurrent.futures.ThreadPoolExecutor(
+        max_workers=options.jobs
+    ) as pool:
+        pending = set()
+        iterator = iter(jobs)
+
+        def submit_next():
+            try:
+                i, segment, path = next(iterator)
+            except StopIteration:
+                return False
+            future = pool.submit(
+                downloader.download,
+                segment["url"],
+                path,
+                segment["key"],
+                segment["sequence"],
+                decrypt,
+            )
+            pending.add(future)
+            return True
+
+        try:
+            _check_cancel(cancel)
+            for _ in range(options.jobs * 2):
+                if not submit_next():
+                    break
+
+            while pending:
+                done, _ = concurrent.futures.wait(
+                    pending,
+                    return_when=concurrent.futures.FIRST_COMPLETED,
+                )
+                for future in done:
+                    pending.discard(future)
+                    future.result()
+                    completed += 1
+                    if on_progress is not None:
+                        on_progress(completed, len(jobs))
+                _check_cancel(cancel)
+                for _ in range(len(done)):
+                    if not submit_next():
+                        break
+        except BaseException:
+            for future in pending:
+                future.cancel()
+            raise
+
+    if options.format == "hls":
+        _check_cancel(cancel)
+        return export_hls(
+            playlist,
+            cache,
+            task_dir,
+            key_data,
+            key_names,
+            options.overwrite,
+        )
+
+    print("\n所有分片下载完成，开始本地合并")
+    combined = combine_segments(
+        segments, playlist["maps"], map_paths, cache
+    )
+    mux(combined, cache, final)
+    return final