emby-cli 0.1.0__tar.gz

emby_cli-0.1.0/.env.example

@@ -0,0 +1,14 @@
+# Emby server (required)
+EMBY_SERVER=http://emby.example:8096
+
+# Auth: API key OR username/password
+EMBY_API_KEY=
+EMBY_USERNAME=
+EMBY_PASSWORD=
+
+# Optional defaults
+# EMBY_OUTPUT=./downloads
+# EMBY_ITEM_ID=
+# EMBY_LIBRARY=
+# EMBY_METHOD=download
+# EMBY_PLAYER=vlc

emby_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q

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

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          TAG="${TAG#v}"
+          WHEEL_VERSION=$(unzip -p dist/*.whl '*.dist-info/METADATA' | grep '^Version:' | cut -d' ' -f2)
+          echo "Tag: $TAG — Wheel: $WHEEL_VERSION"
+          test "$WHEEL_VERSION" = "$TAG"
+
+      - name: Check metadata
+        run: pip install twine && twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

emby_cli-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+src/emby_cli/_version.py

emby_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Unreleased
+
+- Initial packaging as `emby-cli` (modular CLI from emby-downloader).

emby_cli-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Creative Commons Attribution-NonCommercial 4.0 International
+
+Copyright (c) 2026 Sergio Garcia <soukron@gmbros.net>
+
+This work is licensed under the Creative Commons Attribution-NonCommercial
+4.0 International License.
+
+You are free to:
+  - Share — copy and redistribute the material in any medium or format
+  - Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+  - Attribution — You must give appropriate credit, provide a link to the
+    license, and indicate if changes were made.
+  - NonCommercial — You may not use the material for commercial purposes.
+
+No additional restrictions — You may not apply legal terms or technological
+measures that legally restrict others from doing anything the license permits.
+
+Full license text: https://creativecommons.org/licenses/by-nc/4.0/legalcode

emby_cli-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: emby-cli
+Version: 0.1.0
+Summary: CLI to list, search, play, and download/backup original media from an Emby server via its REST API.
+Project-URL: Homepage, https://github.com/soukron/emby-cli
+Project-URL: Repository, https://github.com/soukron/emby-cli
+Project-URL: Issues, https://github.com/soukron/emby-cli/issues
+Author-email: Sergio Garcia <soukron@gmbros.net>
+Maintainer-email: Sergio Garcia <soukron@gmbros.net>
+License-Expression: CC-BY-NC-4.0
+License-File: LICENSE
+Keywords: backup,cli,download,emby,media
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: Free for non-commercial use
+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: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Requires-Dist: m3u8>=4.0
+Requires-Dist: requests>=2.31
+Requires-Dist: static-ffmpeg>=3.0
+Requires-Dist: tqdm>=4.66
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# emby-cli
+
+[PyPI](https://pypi.org/project/emby-cli/)
+[License: CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/)
+
+CLI to **list, search, play, and download/backup** original media files from an [Emby](https://emby.media/) server via its REST API. Only HTTP access is required (default port 8096) — no SSH or rsync.
+
+## Install
+
+```bash
+pip install emby-cli
+```
+
+Development (from a clone of this repo):
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+In the gmbros.net ops tree (`emby-downloader/`), use the root Makefile instead:
+
+```bash
+cd ~/.local/gmbros.net/emby-downloader
+make install
+```
+
+## Configuration
+
+Set environment variables (or pass CLI flags):
+
+| Variable | Description |
+|----------|-------------|
+| `EMBY_SERVER` | Server URL (required) |
+| `EMBY_API_KEY` | API key (or use username/password) |
+| `EMBY_USERNAME` / `EMBY_PASSWORD` | Name/password auth |
+| `EMBY_OUTPUT` | Download directory (default `./downloads`) |
+| `EMBY_METHOD` | `download`, `stream`, or `hls` |
+| `EMBY_PLAYER` | External player for `play` |
+
+See `.env.example`. The app does not load `.env` itself — `source` it or export vars.
+
+## Usage
+
+```bash
+emby-cli list
+emby-cli search "Title"
+emby-cli download -i <itemId> -o ./downloads
+emby-cli sync -l "Movies"
+emby-cli batch -F titles.txt -n
+emby-cli play "Movie (2010)"
+```
+
+Download methods (`-m` / `EMBY_METHOD`):
+
+- `download` — `GET /Items/{id}/Download`
+- `stream` — DirectStreamUrl / `original.*` (Emby Web style)
+- `hls` — HLS segments remuxed to `.mkv` (needs `static-ffmpeg`)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+python -m build && twine check dist/*
+```
+
+Ops Makefile (gmbros.net host only, not in this repo):
+
+```bash
+cd ~/.local/gmbros.net/emby-downloader
+make install / make test / make build / make check
+make push
+make release VERSION=0.1.0   # tag + gh release → CI publishes to PyPI
+```
+
+## License
+
+[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/)

emby_cli-0.1.0/README.md

@@ -0,0 +1,79 @@
+# emby-cli
+
+[PyPI](https://pypi.org/project/emby-cli/)
+[License: CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/)
+
+CLI to **list, search, play, and download/backup** original media files from an [Emby](https://emby.media/) server via its REST API. Only HTTP access is required (default port 8096) — no SSH or rsync.
+
+## Install
+
+```bash
+pip install emby-cli
+```
+
+Development (from a clone of this repo):
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+In the gmbros.net ops tree (`emby-downloader/`), use the root Makefile instead:
+
+```bash
+cd ~/.local/gmbros.net/emby-downloader
+make install
+```
+
+## Configuration
+
+Set environment variables (or pass CLI flags):
+
+| Variable | Description |
+|----------|-------------|
+| `EMBY_SERVER` | Server URL (required) |
+| `EMBY_API_KEY` | API key (or use username/password) |
+| `EMBY_USERNAME` / `EMBY_PASSWORD` | Name/password auth |
+| `EMBY_OUTPUT` | Download directory (default `./downloads`) |
+| `EMBY_METHOD` | `download`, `stream`, or `hls` |
+| `EMBY_PLAYER` | External player for `play` |
+
+See `.env.example`. The app does not load `.env` itself — `source` it or export vars.
+
+## Usage
+
+```bash
+emby-cli list
+emby-cli search "Title"
+emby-cli download -i <itemId> -o ./downloads
+emby-cli sync -l "Movies"
+emby-cli batch -F titles.txt -n
+emby-cli play "Movie (2010)"
+```
+
+Download methods (`-m` / `EMBY_METHOD`):
+
+- `download` — `GET /Items/{id}/Download`
+- `stream` — DirectStreamUrl / `original.*` (Emby Web style)
+- `hls` — HLS segments remuxed to `.mkv` (needs `static-ffmpeg`)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+python -m build && twine check dist/*
+```
+
+Ops Makefile (gmbros.net host only, not in this repo):
+
+```bash
+cd ~/.local/gmbros.net/emby-downloader
+make install / make test / make build / make check
+make push
+make release VERSION=0.1.0   # tag + gh release → CI publishes to PyPI
+```
+
+## License
+
+[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/)

emby_cli-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "emby-cli"
+dynamic = ["version"]
+description = "CLI to list, search, play, and download/backup original media from an Emby server via its REST API."
+readme = "README.md"
+license = "CC-BY-NC-4.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+    { name = "Sergio Garcia", email = "soukron@gmbros.net" },
+]
+maintainers = [
+    { name = "Sergio Garcia", email = "soukron@gmbros.net" },
+]
+keywords = ["emby", "media", "download", "backup", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: Free for non-commercial use",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "requests>=2.31",
+    "tqdm>=4.66",
+    "m3u8>=4.0",
+    "static-ffmpeg>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/soukron/emby-cli"
+Repository = "https://github.com/soukron/emby-cli"
+Issues = "https://github.com/soukron/emby-cli/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+emby-cli = "emby_cli.cli:main"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/emby_cli"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/emby_cli" = "emby_cli"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/emby_cli/_version.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

emby_cli-0.1.0/src/emby_cli/__init__.py

@@ -0,0 +1,6 @@
+"""emby-cli — backup and stream media from an Emby server."""
+
+from emby_cli.client import EmbyClient
+from emby_cli.version import get_version
+
+__all__ = ["EmbyClient", "get_version"]

emby_cli-0.1.0/src/emby_cli/__main__.py

@@ -0,0 +1,4 @@
+from emby_cli.cli import main
+
+if __name__ == "__main__":
+    main()

emby_cli-0.1.0/src/emby_cli/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

emby_cli-0.1.0/src/emby_cli/cli.py

@@ -0,0 +1,134 @@
+"""Argument parser and entrypoint for emby-cli."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import warnings
+
+# macOS system Python ships LibreSSL; urllib3 v2 only warns, TLS still works.
+warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL")
+
+import requests
+
+from emby_cli.client import EmbyClient
+from emby_cli.commands.batch import cmd_batch
+from emby_cli.commands.download import cmd_download
+from emby_cli.commands.list import cmd_list
+from emby_cli.commands.play import cmd_play
+from emby_cli.commands.search import cmd_search
+from emby_cli.commands.sync import cmd_sync
+from emby_cli.constants import DEFAULT_OUTPUT
+
+
+def build_parser() -> argparse.ArgumentParser:
+    env = os.environ.get
+
+    p = argparse.ArgumentParser(
+        prog="emby-cli",
+        description="Download / backup original media files from an Emby server via its REST API.",
+    )
+    p.add_argument("--server", "-s", default=env("EMBY_SERVER"), help="Emby server URL (env: EMBY_SERVER)")
+    p.add_argument("--api-key", "-k", default=env("EMBY_API_KEY"), help="API key (env: EMBY_API_KEY)")
+    p.add_argument("--username", "-u", default=env("EMBY_USERNAME"), help="Username (env: EMBY_USERNAME)")
+    p.add_argument("--password", "-p", default=env("EMBY_PASSWORD"), help="Password (env: EMBY_PASSWORD)")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    ls = sub.add_parser("list", help="List libraries or items in a library")
+    ls.add_argument("--library", "-l", help="Library name to list items for")
+
+    dl = sub.add_parser("download", help="Download items")
+    dl.add_argument("--library", "-l", help="Library name to download")
+    dl.add_argument("--item-id", "-i", default=env("EMBY_ITEM_ID"), help="Specific item ID to download (env: EMBY_ITEM_ID)")
+    dl.add_argument("--output", "-o", default=env("EMBY_OUTPUT", DEFAULT_OUTPUT),
+                    help=f"Output directory (env: EMBY_OUTPUT, default: {DEFAULT_OUTPUT})")
+    dl.add_argument("--force", "-f", action="store_true", help="Re-download even if file exists with matching size")
+    dl.add_argument("--throttle", "-t", type=float, nargs="?", const=1.0, default=0,
+                    help="Limit speed to playback rate. Optional multiplier: 1=realtime, 1.5=50%% faster (default: off)")
+    dl.add_argument("--method", "-m", default=env("EMBY_METHOD", "download"),
+                    choices=["download", "stream", "hls"],
+                    help="Download method: 'download' (API Download), 'stream' (browser-like original.*), "
+                         "or 'hls' (stream chunks + remux) (env: EMBY_METHOD)")
+
+    sr = sub.add_parser("search", help="Search for items by name")
+    sr.add_argument("query", help="Search query")
+
+    pl = sub.add_parser("play", help="Play an item via DirectStreamUrl in an external player")
+    pl.add_argument("query", nargs="?",
+                    help="Title line like batch: 'Movie (2010)' or 'Show (2000) S01E01'")
+    pl.add_argument("--item-id", "-i", default=env("EMBY_ITEM_ID"),
+                    help="Item ID to play (env: EMBY_ITEM_ID)")
+    pl.add_argument("--player", default=env("EMBY_PLAYER"),
+                    help="External player command or path (env: EMBY_PLAYER), e.g. vlc or "
+                         "/Applications/VLC.app/Contents/MacOS/VLC")
+    pl.add_argument("--wait", action="store_true",
+                    help="Block until the player process exits (default: detach and return)")
+    pl.add_argument("--pick-best-item", type=int, choices=[0, 1], default=0,
+                    help="On ambiguous search results: 0=list and require --item-id (default), "
+                         "1=auto-select best ≤1080p like batch")
+
+    sy = sub.add_parser("sync", help="Sync all libraries (or one with --library)")
+    sy.add_argument("--library", "-l", default=env("EMBY_LIBRARY"), help="Specific library to sync (env: EMBY_LIBRARY)")
+    sy.add_argument("--output", "-o", default=env("EMBY_OUTPUT", DEFAULT_OUTPUT),
+                    help=f"Output directory (env: EMBY_OUTPUT, default: {DEFAULT_OUTPUT})")
+    sy.add_argument("--force", "-f", action="store_true", help="Re-download even if file exists with matching size")
+    sy.add_argument("--throttle", "-t", type=float, nargs="?", const=1.0, default=0,
+                    help="Limit speed to playback rate. Optional multiplier: 1=realtime, 1.5=50%% faster (default: off)")
+    sy.add_argument("--method", "-m", default=env("EMBY_METHOD", "download"),
+                    choices=["download", "stream", "hls"],
+                    help="Download method: 'download' (API Download), 'stream' (browser-like original.*), "
+                         "or 'hls' (stream chunks + remux) (env: EMBY_METHOD)")
+
+    ba = sub.add_parser("batch", help="Download titles from a text file (movies, seasons, episodes)")
+    ba.add_argument("--file", "-F", required=True, help="Text file with one title per line")
+    ba.add_argument("--dry-run", "-n", action="store_true", help="Search and select only, do not download")
+    ba.add_argument("--output", "-o", default=env("EMBY_OUTPUT", DEFAULT_OUTPUT),
+                    help=f"Output directory (env: EMBY_OUTPUT, default: {DEFAULT_OUTPUT})")
+    ba.add_argument("--force", "-f", action="store_true", help="Re-download even if file exists with matching size")
+    ba.add_argument("--throttle", "-t", type=float, nargs="?", const=1.0, default=0,
+                    help="Limit speed to playback rate. Optional multiplier: 1=realtime, 1.5=50%% faster (default: off)")
+    ba.add_argument("--method", "-m", default=env("EMBY_METHOD", "download"),
+                    choices=["download", "stream", "hls"],
+                    help="Download method: 'download' (API Download), 'stream' (browser-like original.*), "
+                         "or 'hls' (stream chunks + remux) (env: EMBY_METHOD)")
+
+    return p
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if not args.server:
+        parser.error("Provide --server or set EMBY_SERVER")
+
+    if not args.api_key and not args.username:
+        parser.error("Provide --api-key / EMBY_API_KEY or --username / EMBY_USERNAME")
+
+    client = EmbyClient(args.server, api_key=args.api_key)
+
+    if args.username is not None:
+        pw = args.password if args.password is not None else ""
+        print(f"Authenticating as '{args.username}'...")
+        try:
+            client.authenticate(args.username, pw)
+        except requests.HTTPError as exc:
+            print(f"Authentication failed: {exc}")
+            sys.exit(1)
+        print("OK\n")
+
+    commands = {
+        "list": cmd_list,
+        "download": cmd_download,
+        "search": cmd_search,
+        "play": cmd_play,
+        "sync": cmd_sync,
+        "batch": cmd_batch,
+    }
+    commands[args.command](client, args)
+
+
+if __name__ == "__main__":
+    main()