xmcam-fs 0.1.0__tar.gz

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

@@ -0,0 +1,77 @@
+name: Test, Build and Publish
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - 'main'
+
+jobs:
+  test:
+    name: Test and Lint
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system deps (libfuse3 for pyfuse3)
+        run: sudo apt-get update && sudo apt-get install -y libfuse3-dev pkg-config
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Check formatting with Black
+        run: black --check .
+
+      - name: Type check with Mypy
+        run: mypy src
+
+      - name: Test with pytest
+        run: pytest
+
+  publish:
+    name: Build and Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write # OIDC authentication with PyPI (trusted publishing)
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

xmcam_fs-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+
+# FUSE cache / downloaded footage (never commit)
+*.xmraw
+*.mp4
+cache/
+.xmcam-cache/
+mnt/
+mountpoint/
+
+# Local secrets / scratch
+.env
+secrets.*
+_scratch/

xmcam_fs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 theundefined
+
+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.

xmcam_fs-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: xmcam-fs
+Version: 0.1.0
+Summary: Mount a Xiongmai / iCSee / XMeye IP camera as a FUSE filesystem and browse its recordings as files (MP4 or raw), sshfs-style. No cloud.
+Project-URL: Homepage, https://github.com/theundefined/xmcam-fs
+Project-URL: Repository, https://github.com/theundefined/xmcam-fs
+Project-URL: Issues, https://github.com/theundefined/xmcam-fs/issues
+Author-email: theundefined <undefine@aramin.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cctv,dvrip,filesystem,fuse,icsee,ip-camera,mount,nvr,onvif,pyfuse3,recordings,xiongmai,xm,xmeye
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.10
+Requires-Dist: pyfuse3>=3.2.0
+Requires-Dist: trio>=0.22
+Requires-Dist: xmcam-py>=0.1.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# xmcam-fs
+
+**Mount a Xiongmai (XM) / iCSee / XMeye IP camera as a filesystem** and browse
+its recordings as ordinary files — like `sshfs`, but for your camera's SD
+card/disk. Built on [`xmcam`](https://github.com/theundefined/xmcam-py) and
+[`pyfuse3`](https://github.com/libfuse/pyfuse3). Everything stays on the local
+network: **no cloud, no internet.**
+
+```
+mnt/
+└── 2026-11-10/
+    ├── mp4/
+    │   ├── 08.00.00-08.05.00.mp4      # playable MP4, produced on first open
+    │   └── 08.05.00-08.09.17.mp4
+    └── raw/
+        ├── 08.00.00-08.05.00.xmraw    # original Xiongmai container
+        └── 08.05.00-08.09.17.xmraw
+```
+
+Each recording appears twice:
+
+- **`mp4/`** — a playable MP4 (HEVC/H.264, stream-copied, no re-encode). The
+  first time you open one, the whole segment is downloaded and converted, then
+  cached — so the first read is slow (~2 min for a 5-minute segment on these
+  cameras) and later reads are instant.
+- **`raw/`** — the original `.xmraw` container, exact size, no conversion cost.
+
+The filesystem is **read-only**.
+
+## Why a filesystem?
+
+Because then every tool you already have just works: `cp`, `rsync`, `mpv
+mnt/2026-11-10/mp4/08.00.00-08.05.00.mp4`, a file manager, a backup script.
+No bespoke download command needed.
+
+## Requirements
+
+- Linux with FUSE 3 (`/dev/fuse`, `fusermount3`).
+- **`libfuse3-dev`** and `pkg-config` are needed to *build* `pyfuse3` (its only
+  non-Python dependency). On Debian/Ubuntu: `sudo apt install libfuse3-dev pkg-config`.
+- `ffmpeg` for the `mp4/` view (the `raw/` view works without it).
+
+## Install
+
+```bash
+pipx install xmcam-fs        # or: pip install xmcam-fs
+```
+
+## Usage
+
+```bash
+# Mount the camera (credentials auto-recovered from anonymous ONVIF if omitted)
+xmcam-fs 192.0.2.10 ./mnt
+
+# Only index the last 3 days, foreground (Ctrl-C to unmount)
+xmcam-fs 192.0.2.10 ./mnt --days 3 --foreground
+
+# With explicit credentials and the smaller sub-stream
+XMCAM_USER=... XMCAM_PASS=... xmcam-fs 192.0.2.10 ./mnt --stream Sub
+
+# Unmount
+fusermount3 -u ./mnt
+```
+
+Options: `--days N` (how many past days to index, default 7), `--stream Main|Sub`,
+`--channel N`, `--cache-dir PATH` (default under `$XDG_CACHE_HOME`),
+`--user/--password`, `--foreground`, `--debug`.
+
+## How it works
+
+On mount, `xmcam-fs` recovers the camera account (anonymous ONVIF), lists the
+recordings for the chosen window (DVRIP `OPFileQuery`) and builds a read-only
+tree. `ls` is cheap — it never downloads. Opening a file triggers a one-off
+download (DVRIP `OPPlayBack`) in a worker thread; for the `mp4/` view the
+Xiongmai container is demuxed and remuxed to MP4. Results are cached on disk, so
+re-opening is instant.
+
+> The recording list is a snapshot taken at mount time. Remount to pick up
+> newer footage. (Live refresh is planned.)
+
+## Security & ethics
+
+`xmcam-fs` can recover camera credentials and pull footage over the LAN because
+the firmware exposes them to anonymous ONVIF. **Use it only on cameras you own
+or are authorised to administer.** No cloud is ever contacted and no credentials
+are written to disk (they are recovered per-run and kept in memory). The on-disk
+cache under `--cache-dir` holds decoded footage — put it somewhere appropriate
+and clear it when done.
+
+## License
+
+MIT © theundefined

xmcam_fs-0.1.0/README.md

@@ -0,0 +1,92 @@
+# xmcam-fs
+
+**Mount a Xiongmai (XM) / iCSee / XMeye IP camera as a filesystem** and browse
+its recordings as ordinary files — like `sshfs`, but for your camera's SD
+card/disk. Built on [`xmcam`](https://github.com/theundefined/xmcam-py) and
+[`pyfuse3`](https://github.com/libfuse/pyfuse3). Everything stays on the local
+network: **no cloud, no internet.**
+
+```
+mnt/
+└── 2026-11-10/
+    ├── mp4/
+    │   ├── 08.00.00-08.05.00.mp4      # playable MP4, produced on first open
+    │   └── 08.05.00-08.09.17.mp4
+    └── raw/
+        ├── 08.00.00-08.05.00.xmraw    # original Xiongmai container
+        └── 08.05.00-08.09.17.xmraw
+```
+
+Each recording appears twice:
+
+- **`mp4/`** — a playable MP4 (HEVC/H.264, stream-copied, no re-encode). The
+  first time you open one, the whole segment is downloaded and converted, then
+  cached — so the first read is slow (~2 min for a 5-minute segment on these
+  cameras) and later reads are instant.
+- **`raw/`** — the original `.xmraw` container, exact size, no conversion cost.
+
+The filesystem is **read-only**.
+
+## Why a filesystem?
+
+Because then every tool you already have just works: `cp`, `rsync`, `mpv
+mnt/2026-11-10/mp4/08.00.00-08.05.00.mp4`, a file manager, a backup script.
+No bespoke download command needed.
+
+## Requirements
+
+- Linux with FUSE 3 (`/dev/fuse`, `fusermount3`).
+- **`libfuse3-dev`** and `pkg-config` are needed to *build* `pyfuse3` (its only
+  non-Python dependency). On Debian/Ubuntu: `sudo apt install libfuse3-dev pkg-config`.
+- `ffmpeg` for the `mp4/` view (the `raw/` view works without it).
+
+## Install
+
+```bash
+pipx install xmcam-fs        # or: pip install xmcam-fs
+```
+
+## Usage
+
+```bash
+# Mount the camera (credentials auto-recovered from anonymous ONVIF if omitted)
+xmcam-fs 192.0.2.10 ./mnt
+
+# Only index the last 3 days, foreground (Ctrl-C to unmount)
+xmcam-fs 192.0.2.10 ./mnt --days 3 --foreground
+
+# With explicit credentials and the smaller sub-stream
+XMCAM_USER=... XMCAM_PASS=... xmcam-fs 192.0.2.10 ./mnt --stream Sub
+
+# Unmount
+fusermount3 -u ./mnt
+```
+
+Options: `--days N` (how many past days to index, default 7), `--stream Main|Sub`,
+`--channel N`, `--cache-dir PATH` (default under `$XDG_CACHE_HOME`),
+`--user/--password`, `--foreground`, `--debug`.
+
+## How it works
+
+On mount, `xmcam-fs` recovers the camera account (anonymous ONVIF), lists the
+recordings for the chosen window (DVRIP `OPFileQuery`) and builds a read-only
+tree. `ls` is cheap — it never downloads. Opening a file triggers a one-off
+download (DVRIP `OPPlayBack`) in a worker thread; for the `mp4/` view the
+Xiongmai container is demuxed and remuxed to MP4. Results are cached on disk, so
+re-opening is instant.
+
+> The recording list is a snapshot taken at mount time. Remount to pick up
+> newer footage. (Live refresh is planned.)
+
+## Security & ethics
+
+`xmcam-fs` can recover camera credentials and pull footage over the LAN because
+the firmware exposes them to anonymous ONVIF. **Use it only on cameras you own
+or are authorised to administer.** No cloud is ever contacted and no credentials
+are written to disk (they are recovered per-run and kept in memory). The on-disk
+cache under `--cache-dir` holds decoded footage — put it somewhere appropriate
+and clear it when done.
+
+## License
+
+MIT © theundefined

xmcam_fs-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xmcam-fs"
+version = "0.1.0"
+description = "Mount a Xiongmai / iCSee / XMeye IP camera as a FUSE filesystem and browse its recordings as files (MP4 or raw), sshfs-style. No cloud."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "theundefined", email = "undefine@aramin.net" }]
+keywords = [
+    "xiongmai", "xm", "icsee", "xmeye", "dvrip", "onvif", "fuse", "pyfuse3",
+    "filesystem", "ip-camera", "cctv", "nvr", "recordings", "mount",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Video",
+    "Topic :: System :: Filesystems",
+]
+dependencies = [
+    "xmcam-py>=0.1.0",
+    "pyfuse3>=3.2.0",
+    "trio>=0.22",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "ruff>=0.3.0",
+    "black>=24.0.0",
+    "mypy>=1.9.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/theundefined/xmcam-fs"
+Repository = "https://github.com/theundefined/xmcam-fs"
+Issues = "https://github.com/theundefined/xmcam-fs/issues"
+
+[project.scripts]
+xmcam-fs = "xmcamfs.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xmcamfs"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.black]
+line-length = 120
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.mypy]
+ignore_missing_imports = true

xmcam_fs-0.1.0/release.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+
+# Exit immediately if a command exits with a non-zero status.
+set -e
+
+# Configuration
+PROJECT_NAME="xmcam-fs"
+DEFAULT_INITIAL_VERSION="v0.1.0"
+VERSION_BUMP_TYPE="patch" # Can be major, minor, patch
+
+# Function to display usage
+usage() {
+  echo "Usage: $0 [major|minor|patch|vX.Y.Z]"
+  echo "  Automatically bumps the version, creates a git tag, and pushes it."
+  echo "  If a version is specified (vX.Y.Z), it will use that exact version."
+  exit 1
+}
+
+# Parse arguments
+if [ "$#" -eq 1 ]; then
+  if [[ "$1" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    NEW_VERSION_ARG="$1"
+  elif [[ "$1" =~ ^(major|minor|patch)$ ]]; then
+    VERSION_BUMP_TYPE="$1"
+  else
+    usage
+  fi
+elif [ "$#" -ne 0 ]; then
+  usage
+fi
+
+# Fetch all tags to ensure we have the latest
+echo "Fetching latest tags..."
+git fetch origin --tags
+
+# Get the latest version tag
+LAST_TAG=$(git describe --tags --abbrev=0 --match "v[0-9]*.[0-9]*.[0-9]*" 2>/dev/null || echo "$DEFAULT_INITIAL_VERSION")
+
+# If no semantic version tags exist, start with the default initial version and assume 0.0.0 for first bump
+if [ "$LAST_TAG" = "$DEFAULT_INITIAL_VERSION" ] && [ "$(git tag --list "$DEFAULT_INITIAL_VERSION")" = "" ]; then
+    echo "No semantic version tags found. Starting with $DEFAULT_INITIAL_VERSION."
+    CURRENT_VERSION_SEMVER="0.0.0" # Base for first bump
+else
+    CURRENT_VERSION_SEMVER=$(echo "$LAST_TAG" | sed 's/^v//')
+fi
+
+# Determine the new version
+if [ -n "$NEW_VERSION_ARG" ]; then
+    NEW_VERSION=$(echo "$NEW_VERSION_ARG" | sed 's/^v//')
+    echo "Using specified version: v$NEW_VERSION"
+else
+    # Split version into major, minor, patch
+    IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION_SEMVER"
+
+    case "$VERSION_BUMP_TYPE" in
+        major)
+            MAJOR=$((MAJOR + 1))
+            MINOR=0
+            PATCH=0
+            ;;
+        minor)
+            MINOR=$((MINOR + 1))
+            PATCH=0
+            ;;
+        patch)
+            PATCH=$((PATCH + 1))
+            ;;
+        *)
+            echo "Invalid bump type: $VERSION_BUMP_TYPE. Must be major, minor, or patch."
+            usage
+            ;;
+    esac
+    NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+    echo "Bumping $VERSION_BUMP_TYPE version: v$CURRENT_VERSION_SEMVER -> v$NEW_VERSION"
+fi
+
+# Update version in pyproject.toml
+sed -i "s/^version = \".*\"/version = \"$NEW_VERSION\"/" pyproject.toml
+
+# Create commit for version bump only if there are changes
+git add pyproject.toml
+if ! git diff --cached --quiet; then
+    git commit -m "Bump version to v$NEW_VERSION"
+    echo "Committed version bump."
+else
+    echo "Version in pyproject.toml is already up to date. Skipping commit."
+fi
+
+# Create new tag if it doesn't exist
+NEW_TAG="v$NEW_VERSION"
+if git rev-parse "$NEW_TAG" >/dev/null 2>&1; then
+    echo "Tag $NEW_TAG already exists."
+else
+    echo "Creating git tag: $NEW_TAG"
+    git tag "$NEW_TAG" -m "$PROJECT_NAME Release $NEW_VERSION"
+fi
+
+# Push commit and tag
+echo "Pushing changes and tag to origin..."
+git push origin main || echo "Main already up to date or push failed (skipping)"
+git push origin "$NEW_TAG"
+
+# Get repository owner and name
+REPO_URL=$(git config --get remote.origin.url)
+REPO_OWNER=$(echo "$REPO_URL" | sed -E 's/.*github.com[:/]([^/]+)\/.*/\1/')
+REPO_NAME=$(echo "$REPO_URL" | sed -E 's/.*github.com[:/][^/]+\/([^/\. ]+)(\.git)?/\1/')
+REPO_PATH="$REPO_OWNER/$REPO_NAME"
+
+# Construct Actions URL
+ACTIONS_URL="https://github.com/$REPO_PATH/actions/workflows/ci.yml"
+echo "Monitor action status here: $ACTIONS_URL"
+
+echo "Release process initiated with tag $NEW_TAG. Check GitHub Actions for build status."

xmcam_fs-0.1.0/src/xmcamfs/__init__.py

@@ -0,0 +1,14 @@
+"""xmcam-fs - mount a Xiongmai / iCSee / XMeye camera as a FUSE filesystem.
+
+Browse a camera's recording archive as ordinary files, sshfs-style, backed by
+the :mod:`xmcam` library. Each recording appears twice:
+
+* under ``mp4/`` as a playable MP4 (produced lazily on first open and cached), and
+* under ``raw/`` as the original Xiongmai ``.xmraw`` container.
+
+The filesystem is read-only and talks only to the local network - no cloud.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

xmcam_fs-0.1.0/src/xmcamfs/cache.py

@@ -0,0 +1,113 @@
+"""On-disk cache of camera segments: download once, serve from disk.
+
+A segment is slow to fetch (DVRIP streams at roughly realtime/2), so each one is
+produced exactly once and then read straight off disk. Because a Xiongmai camera
+has a single playback channel, downloads are serialised with one lock -- running
+two ``OPPlayBack`` sessions at once provokes ``Ret 103``.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+from xmcam.dvrip import DVRIPClient
+from xmcam.exceptions import XMCamError
+from xmcam.media import convert_raw, have_ffmpeg
+from xmcam.models import Credentials, Recording
+from xmcam.playback import download_recording
+
+
+def _safe_stem(rec: Recording) -> str:
+    """A flat, collision-free filename stem derived from the recording path.
+
+    The camera path already contains the date and a unique ``[@token]``, so
+    flattening it yields a stable, unique name.
+    """
+    stem = (rec.filename or "recording").strip("/").replace("/", "_")
+    for ch in "[]":
+        stem = stem.replace(ch, "")
+    for ext in (".h264", ".h265", ".jpg"):
+        if stem.lower().endswith(ext):
+            stem = stem[: -len(ext)]
+            break
+    return stem or "recording"
+
+
+class SegmentCache:
+    """Produce and cache the ``mp4`` / ``raw`` rendering of a recording."""
+
+    def __init__(
+        self,
+        host: str,
+        credentials: Credentials,
+        cache_dir,
+        port: int = 34567,
+        channel: int = 0,
+        stream: str = "Main",
+    ) -> None:
+        self.host = host
+        self.creds = credentials
+        self.cache_dir = Path(cache_dir)
+        self.port = port
+        self.channel = channel
+        self.stream = stream
+        self._download_lock = threading.Lock()  # one playback channel per camera
+
+        for sub in ("raw", "mp4", ".tmp"):
+            (self.cache_dir / sub).mkdir(parents=True, exist_ok=True)
+
+    # -- public ---------------------------------------------------------------
+    def path_for(self, rec: Recording, view: str) -> Path:
+        """The cache path for this (recording, view), whether or not it exists yet."""
+        stem = _safe_stem(rec)
+        if view.lower() == "raw":
+            return self.cache_dir / "raw" / f"{stem}.xmraw"
+        return self.cache_dir / "mp4" / f"{stem}.mp4"
+
+    def ensure(self, rec: Recording, view: str) -> Path:
+        """Return the cache path, downloading/converting once if needed (BLOCKING)."""
+        dest = self.path_for(rec, view)
+        if dest.exists() and dest.stat().st_size > 0:
+            return dest
+
+        with self._download_lock:
+            # Re-check: another thread may have produced it while we waited.
+            if dest.exists() and dest.stat().st_size > 0:
+                return dest
+            if view.lower() == "raw":
+                self._download_raw(rec, dest)
+            else:
+                self._produce_mp4(rec, dest)
+        return dest
+
+    # -- internals ------------------------------------------------------------
+    def _client(self) -> DVRIPClient:
+        cam = DVRIPClient(self.host, user=self.creds.username, password=self.creds.password, port=self.port)
+        cam.login_or_raise()
+        return cam
+
+    def _download_raw(self, rec: Recording, dest: Path) -> None:
+        tmp = dest.with_name(dest.name + ".part")
+        cam = self._client()
+        try:
+            download_recording(cam, rec, tmp, channel=self.channel, stream=self.stream)
+        finally:
+            cam.close()
+        tmp.replace(dest)
+
+    def _produce_mp4(self, rec: Recording, dest: Path) -> None:
+        if not have_ffmpeg():
+            raise XMCamError("ffmpeg not found; cannot produce the MP4 view")
+        stem = _safe_stem(rec)
+        raw_tmp = self.cache_dir / ".tmp" / (stem + ".xmraw")
+        self._download_raw(rec, raw_tmp)
+        # The temp output must keep a real ``.mp4`` extension so ffmpeg can infer
+        # the muxer (a ``.part`` suffix makes it fail with "no output format").
+        tmp_mp4 = self.cache_dir / ".tmp" / (stem + ".partial.mp4")
+        ok = convert_raw(raw_tmp, tmp_mp4, keep_raw=False)
+        if not ok or not tmp_mp4.exists():
+            if tmp_mp4.exists():
+                tmp_mp4.unlink()
+            raise XMCamError(f"MP4 conversion failed for {rec.filename}")
+        tmp_mp4.replace(dest)