ember-dl 0.9.0__py3-none-any.whl

ember/__init__.py

@@ -0,0 +1,66 @@
+"""Ember — extract direct media links from social platforms.
+
+An embeddable, cobalt-like (imputnet/cobalt) Python library.
+
+Usage:
+    import ember
+    result = ember.extract("https://www.tiktok.com/@user/video/123...")
+    for m in result.media:
+        print(m.kind, m.url)
+
+Logging: the package logs to the "ember" logger and is silent by default
+(NullHandler). To see logs from your app:
+    import logging; logging.basicConfig(); logging.getLogger("ember").setLevel(logging.INFO)
+"""
+
+import logging as _logging
+
+# best practice: a library must not force output — silent by default
+_logging.getLogger("ember").addHandler(_logging.NullHandler())
+
+from .errors import (
+    EmberError,
+    ExtractionError,
+    NetworkError,
+    UnsupportedUrlError,
+)
+from .cookies import cookies_from_browser, cookies_from_file
+from .download import (DownloadProgress, RateLimiter, available_qualities,
+                       download, download_media, ffmpeg_available, probe_size)
+from .models import Media, MediaVariant, Playlist, Result, Subtitle
+from .router import (can_extract, extract, extract_highlights, extract_playlist,
+                     extract_timeline, supported_services, supports_highlights,
+                     supports_playlist, supports_timeline)
+
+__version__ = "0.9.0"
+
+__all__ = [
+    "extract",
+    "extract_playlist",
+    "extract_timeline",
+    "extract_highlights",
+    "can_extract",
+    "supports_playlist",
+    "supports_timeline",
+    "supports_highlights",
+    "supported_services",
+    "cookies_from_browser",
+    "cookies_from_file",
+    "download",
+    "download_media",
+    "available_qualities",
+    "ffmpeg_available",
+    "probe_size",
+    "DownloadProgress",
+    "RateLimiter",
+    "MediaVariant",
+    "Playlist",
+    "Result",
+    "Media",
+    "Subtitle",
+    "EmberError",
+    "UnsupportedUrlError",
+    "NetworkError",
+    "ExtractionError",
+    "__version__",
+]

ember/__main__.py

@@ -0,0 +1,497 @@
+"""Ember CLI.
+
+Show links:     ember "URL"
+Download:       ember -d "URL"                 (site-derived name, current folder)
+Custom name:    ember -d -o myclip "URL"
+Custom folder:  ember -d -p downloads "URL"
+Installed entry point is `ember`; `python -m ember` works too.
+"""
+
+import argparse
+import re
+import shutil
+import sys
+import time
+
+from . import (DownloadProgress, EmberError, __version__, available_qualities,
+               can_extract, cookies_from_file, download, extract,
+               extract_highlights, extract_playlist, extract_timeline,
+               probe_size, supported_services, supports_playlist,
+               supports_timeline)
+from .http import make_context
+
+# browsers understood by --cookies-from-browser (same set as yt-dlp)
+BROWSERS = ["brave", "chrome", "chromium", "edge", "firefox",
+            "opera", "safari", "vivaldi", "whale"]
+
+# options that take a value (can accidentally swallow the URL) + example values
+_VALUE_OPTS = {
+    "-o": "myfile", "--output": "myfile", "-p": "downloads", "--path": "downloads",
+    "-a": "links.txt", "--batch-file": "links.txt",
+    "--max-height": "720", "--concurrency": "6", "--timeout": "20",
+    "--proxy": "http://host:port", "--cookies": '"a=1; b=2"',
+    "--cookies-file": "cookies.txt", "--cookies-from-browser": "firefox",
+    "--browser-profile": "Default",
+}
+
+
+def _parse_cookies_arg(raw: str) -> dict:
+    cookies = {}
+    for pair in raw.split(";"):
+        pair = pair.strip()
+        if "=" in pair:
+            name, _, value = pair.partition("=")
+            cookies[name.strip()] = value.strip()
+    return cookies
+
+
+_parse_cookies_file = cookies_from_file       # библиотечный парсер Netscape
+
+
+_RATE_UNITS = {"": 1, "k": 1000, "m": 1000 ** 2, "g": 1000 ** 3,
+               "ki": 1024, "mi": 1024 ** 2, "gi": 1024 ** 3}
+
+
+def _parse_rate(raw: str) -> float:
+    """'500K' / '2M' / '1.5MiB' / '800' -> bytes per second."""
+    m = re.fullmatch(r"\s*([\d.]+)\s*([KMGkmg]i?)?B?/?[sS]?\s*", raw)
+    if not m:
+        raise ValueError(f"could not parse rate {raw!r}")
+    value = float(m.group(1))
+    unit = (m.group(2) or "").lower()
+    return value * _RATE_UNITS[unit]
+
+
+def _bar(frac: float, width: int = 30) -> str:
+    filled = int(frac * width)
+    if filled >= width:
+        return "=" * width
+    return "=" * filled + ">" + "-" * (width - filled - 1)
+
+
+def _eta(seconds: float) -> str:
+    s = int(seconds)
+    return f"{s // 60:02d}m{s % 60:02d}s"
+
+
+def _enable_vt() -> None:
+    """Windows: turn on VT processing so \\r and \\x1b[K redraw in place."""
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+        k = ctypes.windll.kernel32
+        h = k.GetStdHandle(-11)                      # STD_OUTPUT_HANDLE
+        mode = ctypes.c_uint32()
+        if k.GetConsoleMode(h, ctypes.byref(mode)):
+            k.SetConsoleMode(h, mode.value | 0x0004)  # VIRTUAL_TERMINAL_PROCESSING
+    except Exception:
+        pass
+
+
+def _cols() -> int:
+    return shutil.get_terminal_size((80, 20)).columns
+
+
+def _line(text: str) -> None:
+    """Redraw one line in place. Skipped when stdout is not a terminal —
+    there \\r would pile up as new lines."""
+    try:
+        if not sys.stdout.isatty():
+            return
+    except Exception:
+        return
+    print("\r\x1b[K" + text[:_cols() - 1], end="", flush=True)
+
+
+def _make_progress_printer():
+    """One-line progress: MiB / MiB [bar] pct speed ETA (CLI only)."""
+    state = {"last": 0.0}
+    MiB = 1048576
+
+    def cb(p: DownloadProgress):
+        now = time.time()
+        if p.stage != "download":
+            _line(f"  {p.stage}…")
+            return
+        if now - state["last"] < 0.1:
+            return
+        state["last"] = now
+        dl, spd = p.downloaded / MiB, p.speed / MiB
+        if p.total:
+            frac = p.fraction or 0
+            # bar shrinks so the whole line fits the console
+            bar = _bar(frac, max(10, _cols() - 56))
+            _line(f"  {dl:.2f} MiB / {p.total / MiB:.2f} MiB [{bar}]"
+                  f" {frac * 100:6.2f}% {spd:.2f} MiB/s {_eta(p.eta or 0)}")
+        elif p.segments_total:
+            _line(f"  segment {p.segments_done}/{p.segments_total}"
+                  f"  {dl:.2f} MiB  {spd:.2f} MiB/s")
+        else:
+            _line(f"  {dl:.2f} MiB  {spd:.2f} MiB/s")
+
+    return cb
+
+
+def _print_result(result, size=False, ctx=None) -> None:
+    print(f"service:  {result.service}")
+    print(f"type:     {result.kind}")
+    print(f"author:   {result.author or '-'}")
+    print(f"title:    {result.title or '-'}")
+    if result.duration:
+        print(f"duration: {int(result.duration // 60)}:{int(result.duration % 60):02d}")
+    if result.timestamp:
+        from datetime import datetime, timezone
+        print(f"date:     {datetime.fromtimestamp(result.timestamp, timezone.utc):%Y-%m-%d}")
+    if result.view_count is not None:
+        print(f"views:    {result.view_count}")
+    if result.like_count is not None:
+        print(f"likes:    {result.like_count}")
+    print(f"filename: {result.filename_hint}")
+    if result.thumbnail:
+        print(f"thumb:    {result.thumbnail}")
+    for i, m in enumerate(result.media, 1):
+        q = f" [{m.quality}]" if m.quality else ""
+        print(f"  {i}. {m.kind}{q} .{m.ext}")
+        print(f"     {m.url}")
+        qs = available_qualities(m) if m.variants else []
+        if qs:
+            print(f"     qualities: {qs}")
+        if size:
+            b = probe_size(m, ctx)
+            if b:
+                print(f"     size: {b / 1048576:.1f} MB")
+    if result.subtitles:
+        print(f"subs:     {', '.join(s.lang for s in result.subtitles)}")
+    if result.requires_merge:
+        print("! video and audio are separate — downloading needs ffmpeg")
+
+
+class _Parser(argparse.ArgumentParser):
+    """Turns confusing argparse errors into short, clear CLI messages
+    (especially when a value-taking option accidentally swallows the URL)."""
+
+    def _fail(self, text: str):
+        # короткое сообщение без простыни usage
+        sys.stderr.write(f"ember: error: {text}\n")
+        self.exit(2)
+
+    def error(self, message):
+        argv = sys.argv[1:]
+        url = next((a for a in argv if a.startswith(("http://", "https://"))), None)
+
+        # 1) ссылка «съедена» как значение опции (напр. --cookies-from-browser URL)
+        if url:
+            i = argv.index(url)
+            prev = argv[i - 1] if i > 0 else None
+            if prev in _VALUE_OPTS:
+                sample = _VALUE_OPTS[prev]
+                self._fail(
+                    f'"{prev}" needs a value, but your link was taken as its value.\n'
+                    f'  put the value after "{prev}", e.g.:  '
+                    f'ember {prev} {sample} "{url}"\n'
+                    f'  or just show links:                 ember "{url}"')
+
+        # 2) опция требует значение, но его нет (напр. в конце строки)
+        m = re.search(r"argument ([^:]+): expected one argument", message)
+        if m:
+            opt = m.group(1).split("/")[-1].strip()
+            sample = _VALUE_OPTS.get(opt, "<value>")
+            self._fail(f'"{opt}" needs a value, e.g.:  ember {opt} {sample} "URL"')
+
+        # 3) ссылка есть, но не встала как позиционный аргумент
+        if "required: url" in message and url:
+            self._fail(f'put the link as the last argument, e.g.:  ember "{url}"')
+
+        super().error(message)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = _Parser(prog="ember",
+                description="Extract and download media (a cobalt-like library)")
+    p.add_argument("--version", action="version", version=f"ember {__version__}")
+    p.add_argument("--list-services", action="store_true",
+                   help="print supported services and exit")
+    p.add_argument("url", nargs="?", help="link to a post / track / video")
+    p.add_argument("-a", "--batch-file", metavar="FILE",
+                   help="read links from a file (one per line, '#' comments; '-' = stdin)")
+    p.add_argument("--json", action="store_true", help="print metadata as JSON")
+    p.add_argument("-F", "--list-formats", action="store_true",
+                   help="list available qualities and exit (no download)")
+    p.add_argument("-v", "--verbose", action="count", default=0,
+                   help="log to stderr; -vv for debug")
+    p.add_argument("--timeout", type=float, default=15.0, metavar="SEC",
+                   help="per-request timeout, seconds (default 15)")
+    # download
+    p.add_argument("-d", "--download", action="store_true",
+                   help="download the media (otherwise only links are shown)")
+    p.add_argument("-o", "--output", metavar="NAME",
+                   help="output file name without extension, or a template with "
+                        "%%(title)s/%%(author)s/%%(service)s/%%(id)s; implies --download")
+    p.add_argument("-p", "--path", metavar="DIR",
+                   help="target folder (default: current folder); implies --download")
+    p.add_argument("--max-height", type=int, metavar="N",
+                   help="cap quality by height, e.g. 720")
+    p.add_argument("--audio-only", action="store_true",
+                   help="keep audio only (needs ffmpeg); implies --download")
+    p.add_argument("--subs", action="store_true",
+                   help="also download subtitle tracks; implies --download")
+    p.add_argument("--thumbnail", action="store_true",
+                   help="also save the cover image; implies --download")
+    p.add_argument("--write-info", action="store_true", dest="write_info",
+                   help="save a .info.json sidecar with all metadata; implies --download")
+    p.add_argument("--size", action="store_true",
+                   help="print file size before downloading (extra request)")
+    p.add_argument("--concurrency", type=int, default=1, metavar="N",
+                   help="parallel HLS segments, and parallel gallery items (default 1)")
+    p.add_argument("--skip-existing", action="store_true", dest="skip_existing",
+                   help="do not re-download files that already exist")
+    p.add_argument("--rate-limit", metavar="RATE", dest="rate_limit",
+                   help="cap download speed, e.g. 500K, 2M, 1.5MiB (default: unlimited)")
+    p.add_argument("--embed-metadata", "--metadata", action="store_true",
+                   dest="embed_metadata",
+                   help="write title/author into the file (needs ffmpeg); implies --download")
+    p.add_argument("--playlist", action="store_true",
+                   help="treat as a playlist/set (SoundCloud sets)")
+    p.add_argument("--timeline", action="store_true",
+                   help="treat the URL as a profile/channel and list latest posts")
+    p.add_argument("--highlights", action="store_true",
+                   help="treat the URL as a profile and list its story highlights "
+                        "(Instagram; needs cookies)")
+    p.add_argument("--limit", type=int, default=30, metavar="N",
+                   help="max items for --timeline (default 30)")
+    p.add_argument("--proxy", metavar="URL",
+                   help="proxy for all requests, e.g. http://host:port "
+                        "(helps with IP-blocked sites)")
+    # cookies
+    p.add_argument("--cookies", metavar='"name=value; ..."',
+                   help="cookies as a string (NSFW tweets, private Instagram)")
+    p.add_argument("--cookies-file", metavar="cookies.txt",
+                   help="cookies.txt in Netscape format (like yt-dlp)")
+    p.add_argument("--cookies-from-browser", metavar="BROWSER", choices=BROWSERS,
+                   help="read cookies from a browser; one of: " + ", ".join(BROWSERS))
+    p.add_argument("--browser-profile", metavar="PROFILE",
+                   help="browser profile for --cookies-from-browser")
+    return p
+
+
+def _report_error(msg: str, prefix: str = "error") -> None:
+    """Print an error and, when relevant, a hint with CLI flags (not Python API)."""
+    print(f"{prefix}: {msg}", file=sys.stderr)
+    low = msg.lower()
+    if "cookie" in low and "could not read cookies" not in low and "app-bound" not in low:
+        print('hint: pass cookies with  --cookies "name=value; ..."  |  '
+              "--cookies-file cookies.txt  |  --cookies-from-browser firefox",
+              file=sys.stderr)
+    if "proxy" in low or "network policy" in low:
+        print("hint: try another IP with  --proxy http://host:port", file=sys.stderr)
+
+
+def _setup_logging(verbose: int) -> None:
+    if verbose <= 0:
+        return
+    import logging
+    h = logging.StreamHandler(sys.stderr)
+    h.setFormatter(logging.Formatter("[%(name)s] %(message)s"))
+    lg = logging.getLogger("ember")
+    lg.addHandler(h)
+    lg.setLevel(logging.DEBUG if verbose >= 2 else logging.INFO)
+
+
+def _read_batch(path: str) -> list:
+    src = sys.stdin if path == "-" else open(path, encoding="utf-8", errors="replace")
+    try:
+        urls = []
+        for line in src:
+            line = line.strip()
+            if line and not line.startswith("#"):
+                urls.append(line)
+        return urls
+    finally:
+        if src is not sys.stdin:
+            src.close()
+
+
+def _render_name(template: str, result) -> str:
+    if "%(" not in template:
+        return template
+    fields = {"title": result.title or "", "author": result.author or "",
+              "uploader": result.author or "", "service": result.service,
+              "id": result.filename_hint or ""}
+    try:
+        return template % fields
+    except (KeyError, ValueError):
+        return template
+
+
+def _list_formats(result) -> None:
+    print(f"# {result.service}: {result.title or result.filename_hint}")
+    for i, m in enumerate(result.media, 1):
+        qs = available_qualities(m)
+        label = ", ".join(f"{h}p" for h in qs) if qs else (m.quality or "single")
+        print(f"  {i}. {m.kind} .{m.ext}: {label}")
+    for s in result.subtitles:
+        print(f"  sub: {s.lang} ({s.ext})")
+
+
+def main() -> int:
+    # Windows-консоль часто cp1251/cp866 -> не-ASCII падает/рисуется квадратами.
+    # Данные в str корректны; правим только вывод.
+    for _s in (sys.stdout, sys.stderr):
+        try:
+            _s.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+    _enable_vt()
+    args = _build_parser().parse_args()
+    _setup_logging(args.verbose)
+
+    if args.list_services:
+        print(", ".join(supported_services()))
+        return 0
+
+    urls = []
+    if args.url:
+        urls.append(args.url)
+    if args.batch_file:
+        try:
+            urls += _read_batch(args.batch_file)
+        except OSError as e:
+            print(f"could not read batch file: {e}", file=sys.stderr)
+            return 1
+    if not urls:
+        print("error: provide a URL or --batch-file FILE", file=sys.stderr)
+        return 2
+
+    cookies = {}
+    if args.cookies_file:
+        try:
+            cookies.update(_parse_cookies_file(args.cookies_file))
+        except OSError as e:
+            print(f"could not read cookies file: {e}", file=sys.stderr)
+            return 1
+    if args.cookies:
+        cookies.update(_parse_cookies_arg(args.cookies))
+
+    rate_limit = None
+    if args.rate_limit:
+        try:
+            rate_limit = _parse_rate(args.rate_limit)
+        except ValueError as e:
+            print(f"error: {e} (use e.g. 500K, 2M, 1.5MiB)", file=sys.stderr)
+            return 2
+
+    proxies = {"http": args.proxy, "https": args.proxy} if args.proxy else None
+    common = dict(timeout=args.timeout, proxies=proxies, cookies=cookies or None,
+                  cookies_from_browser=args.cookies_from_browser,
+                  browser_profile=args.browser_profile)
+
+    do_download = (args.download or args.output or args.path or args.audio_only
+                   or args.embed_metadata or args.subs or args.thumbnail
+                   or args.write_info or args.skip_existing or args.rate_limit)
+    dl_ctx = make_context(timeout=args.timeout, proxies=proxies) if (do_download or args.size) else None
+    cb = _make_progress_printer()
+    rc = 0
+
+    for url in urls:
+        # профиль/канал -> лента; авто, если ссылка не пост
+        is_timeline = (not args.highlights
+                       and (args.timeline
+                            or (supports_timeline(url) and not can_extract(url))))
+        try:
+            if args.highlights:
+                pl = extract_highlights(url, limit=args.limit, **common)
+                results = pl.entries
+                print(f"highlights: {pl.author or '-'} ({len(results)} collections)")
+            elif is_timeline:
+                pl = extract_timeline(url, limit=args.limit, **common)
+                results = pl.entries
+                if do_download:
+                    results = list(reversed(results))     # старые -> новые
+                print(f"timeline: {pl.author or '-'} ({len(results)} items)")
+            elif args.playlist or supports_playlist(url):
+                playlist = extract_playlist(url, **common)
+                results = playlist.entries
+                print(f"playlist: {playlist.title or '-'} ({len(results)} items)")
+            else:
+                results = [extract(url, **common)]
+        except EmberError as e:
+            _report_error(str(e))
+            rc = 1
+            continue
+        except Exception as e:  # ничего не должно долетать сюда сырым
+            print(f"error: {type(e).__name__}: {e}", file=sys.stderr)
+            rc = 1
+            continue
+
+        # лента/highlights без -d: компактный список, не вываливаем полные блоки
+        if ((is_timeline or args.highlights) and not do_download
+                and not args.json and not args.list_formats):
+            for i, r in enumerate(results, 1):
+                extra = (f"  [{len(r.media)} items]" if args.highlights
+                         else f"  {r.source_url}")
+                print(f"  {i:2d}. {(r.title or r.filename_hint or '')[:60]}{extra}")
+            continue
+
+        if args.json:
+            import json
+            payload = [r.to_dict() for r in results]
+            print(json.dumps(payload if len(payload) > 1 else payload[0],
+                             ensure_ascii=False, indent=2))
+            continue
+        if args.list_formats:
+            for r in results:
+                _list_formats(r)
+            continue
+        if not do_download:
+            for r in results:
+                _print_result(r, size=args.size, ctx=dl_ctx)
+                if len(results) > 1 or len(urls) > 1:
+                    print("-" * 40)
+            continue
+
+        out_dir = args.path or "."
+        single = len(results) == 1 and len(urls) == 1
+        if args.output and "%(" not in args.output and not single:
+            print(f'warning: -o "{args.output}" is a literal name but there are '
+                  "multiple files — ignored, using site-derived names instead. "
+                  "Use a template, e.g. -o \"%(title)s\"", file=sys.stderr)
+        for r in results:
+            print(f"downloading: {r.title or r.filename_hint}")
+            if args.output and "%(" in args.output:
+                name = _render_name(args.output, r)      # шаблон — на каждый результат
+            elif args.output and single:
+                name = args.output                        # литеральное имя — только один файл
+            else:
+                name = None                               # иначе имя с сайта
+            try:
+                paths = download(r, out_dir, filename=name, ctx=dl_ctx,
+                                 max_height=args.max_height,
+                                 concurrency=args.concurrency, on_progress=cb,
+                                 audio_only=args.audio_only,
+                                 embed_metadata=args.embed_metadata,
+                                 subtitles=args.subs, thumbnail=args.thumbnail,
+                                 write_info=args.write_info,
+                                 skip_existing=args.skip_existing,
+                                 rate_limit=rate_limit)
+            except EmberError as e:
+                print()
+                _report_error(str(e), prefix="  error")
+                rc = 1
+                continue
+            _line("")                       # стираем строку прогресса
+            for p in paths:
+                print(f"\r  saved: {p}")
+    return rc
+
+
+def _run() -> int:
+    try:
+        return main()
+    except KeyboardInterrupt:
+        print("\ncancelled", file=sys.stderr)
+        return 130                          # общепринятый код для SIGINT
+
+
+if __name__ == "__main__":
+    sys.exit(_run())