feat(scripts): prune Forgejo releases >90 days in ship.sh

Adds step 6 to scripts/ship.sh: after smoke checks, list Forgejo
releases and delete any with created_at older than FORGEJO_PRUNE_DAYS
(default 90). Bounded retention prevents the tc-git CPX11 disk from
filling up (each release ≈ 511MB of attachments × 1/week pace).

Skipped silently with a warn if FORGEJO_TOKEN is not exported, so
the step is opt-in via secret presence (no token = no destructive
action). Tunables: FORGEJO_PRUNE_DAYS, FORGEJO_REPO, FORGEJO_BASE,
SKIP_FORGEJO_PRUNE.

.forgejo/workflows/ci.yml

@@ -12,35 +12,26 @@ permissions:
 jobs:
   test:
     name: Test
-    runs-on: ubuntu-latest
+    runs-on: docker
-    strategy:
+    container:
-      matrix:
+      image: docker.io/library/golang:1.25
-        go-version: ["1.25"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v4
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: ${{ matrix.go-version }}
 
       - name: Run tests
         run: go test -v -race -count=1 ./...
 
   build:
     name: Build
-    runs-on: ubuntu-latest
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
     strategy:
       matrix:
         goos: [linux, darwin, windows]
         goarch: [amd64, arm64]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v4
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: "1.25"
 
       - name: Build
         env:
@@ -50,30 +41,30 @@ jobs:
 
   lint:
     name: Lint
-    runs-on: ubuntu-latest
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v4
 
-      - name: Set up Go
+      - name: Install golangci-lint
-        uses: actions/setup-go@v6
+        run: |
-        with:
+          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/v2.11.4/install.sh \
-          go-version: "1.25"
+            | sh -s -- -b /usr/local/bin v2.11.4
 
       - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@v9
+        run: golangci-lint run ./...
-        with:
-          version: v2.11.4
 
   coverage:
     name: Coverage
-    runs-on: ubuntu-latest
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v4
 
-      - name: Set up Go
+      - name: Install python3
-        uses: actions/setup-go@v6
+        run: apt-get update && apt-get install -y --no-install-recommends python3
-        with:
-          go-version: "1.25"
 
       - name: Run tests with coverage (all packages)
         run: |
@@ -86,14 +77,11 @@ jobs:
         run: |
           # Threshold applies only to engine and agent — cmd contains interactive UI
           # commands (config menus, daemon, auth browser) that are not unit-testable.
-          # WebRTC files are excluded: deprecated, slated for removal in 0.9.0.
           go test -race -coverprofile=coverage-core.out -covermode=atomic \
             ./internal/engine/... \
             ./internal/agent/...
-          # Strip webrtc lines from the profile before computing the threshold.
+          COVERAGE=$(go tool cover -func=coverage-core.out | grep ^total | awk '{print $3}' | tr -d '%')
-          grep -v '/internal/engine/webrtc' coverage-core.out > coverage-core-filtered.out
+          echo "Coverage on engine+agent: ${COVERAGE}%"
-          COVERAGE=$(go tool cover -func=coverage-core-filtered.out | grep ^total | awk '{print $3}' | tr -d '%')
-          echo "Coverage on engine+agent (excluding webrtc): ${COVERAGE}%"
           python3 -c "
           coverage = float('${COVERAGE}')
           threshold = 50.0
@@ -105,24 +93,13 @@ jobs:
               print('OK: Coverage meets minimum threshold')
           "
 
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v6
-        with:
-          files: ./coverage.out
-          fail_ci_if_error: false
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
   vet:
     name: Vet
-    runs-on: ubuntu-latest
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v4
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: "1.25"
 
       - name: Run go vet
         run: go vet ./...

.forgejo/workflows/docker-rebuild.yml

@@ -0,0 +1,61 @@
+# Rebuilds and re-pushes the `latest` image without a version bump so newly
+# *fixed* Alpine / ffmpeg / Go patches land between tagged releases. Versioned
+# tags are immutable and never touched here. Runs weekly and on demand.
+name: Docker rebuild
+
+on:
+  schedule:
+    # Mondays 04:17 UTC (off the hour to avoid the scheduler rush)
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+jobs:
+  rebuild:
+    runs-on: docker
+    container:
+      image: docker.io/library/docker:27-cli
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install build deps
+        run: apk add --no-cache curl git bash
+
+      - name: Install buildx
+        run: |
+          mkdir -p ~/.docker/cli-plugins
+          curl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-linux-amd64 \
+            -o ~/.docker/cli-plugins/docker-buildx
+          chmod +x ~/.docker/cli-plugins/docker-buildx
+
+      - name: Set up qemu
+        run: docker run --rm --privileged tonistiigi/binfmt --install all
+
+      # Stamp the binary with the most recent release tag (not "dev").
+      - name: Resolve version
+        id: ver
+        run: |
+          v=$(git describe --tags --abbrev=0 2>/dev/null || echo dev)
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+
+      - name: Login to Docker Hub
+        env:
+          DH_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+          DH_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+        run: echo "$DH_TOKEN" | docker login -u "$DH_USER" --password-stdin
+
+      - name: Build + push (refresh latest)
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          docker buildx create --name builder --use --driver docker-container
+          # Refresh the floating tag only — never overwrite a versioned release.
+          # Force a fresh base pull so apk upgrade picks up new patches.
+          docker buildx build \
+            --platform linux/amd64,linux/arm64 \
+            --build-arg "VERSION=$VERSION" \
+            --tag "torrentclaw/unarr:latest" \
+            --no-cache \
+            --push \
+            .

.forgejo/workflows/release.yml

@@ -0,0 +1,118 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install build deps (bash, curl, jq, ffmpeg fetch deps)
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends bash curl ca-certificates jq xz-utils unzip
+
+      - name: Install goreleaser
+        run: |
+          curl -sSfL https://github.com/goreleaser/goreleaser/releases/latest/download/goreleaser_Linux_x86_64.tar.gz \
+            | tar -xz -C /usr/local/bin goreleaser
+
+      - name: Run goreleaser
+        env:
+          # Forgejo runner auto-injects GITHUB_TOKEN (a per-job, instance-scoped
+          # token usable against the Forgejo REST API). goreleaser only accepts
+          # one token; with both GITHUB_TOKEN + GITEA_TOKEN set it errors out
+          # ("multiple tokens"). Unset GITHUB_TOKEN before invoking goreleaser so
+          # it picks the Gitea code path + the gitea_urls block in .goreleaser.yml.
+          GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          # Empty when RELEASE_SIGNING_PUBKEY variable is unset — goreleaser
+          # accepts it and the resulting binary disables signature checks
+          # (back-compat: pre-signing releases continue to update). Set
+          # RELEASE_SIGNING_PUBKEY (variable) + RELEASE_SIGNING_KEY (secret)
+          # to turn verification on.
+          RELEASE_SIGNING_PUBKEY: ${{ vars.RELEASE_SIGNING_PUBKEY }}
+        run: |
+          unset GITHUB_TOKEN
+          goreleaser release --clean
+
+      - name: Sign checksums.txt with ed25519
+        if: ${{ vars.RELEASE_SIGNING_PUBKEY != '' && secrets.RELEASE_SIGNING_KEY != '' }}
+        env:
+          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          FORGEJO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Tailscale IP — domain-agnostic; the runner shares the dokploy-network with
+          # forgejo (hostname `forgejo`), so the in-cluster hostname is fastest, but the
+          # Tailscale IP is the documented fallback.
+          FORGEJO_API: http://forgejo:3000/api/v1
+          REPO: torrentclaw/unarr
+        run: |
+          set -euo pipefail
+          go run ./scripts/sign-checksums \
+            -key "$RELEASE_SIGNING_KEY" \
+            -in  dist/checksums.txt \
+            -out dist/checksums.txt.sig
+
+          # Find the release ID for this tag, then upload the sig as an asset.
+          rel_id=$(curl -sSf "$FORGEJO_API/repos/$REPO/releases/tags/$RELEASE_TAG" \
+            -H "Authorization: token $FORGEJO_TOKEN" | jq -r '.id')
+          curl -sSf -X POST \
+            "$FORGEJO_API/repos/$REPO/releases/$rel_id/assets?name=checksums.txt.sig" \
+            -H "Authorization: token $FORGEJO_TOKEN" \
+            -F "attachment=@dist/checksums.txt.sig"
+
+  docker:
+    needs: release
+    runs-on: docker
+    container:
+      # Docker-in-Docker capable image — buildx + qemu pre-installed.
+      image: docker.io/library/docker:27-cli
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install buildx
+        run: |
+          apk add --no-cache curl
+          mkdir -p ~/.docker/cli-plugins
+          curl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-linux-amd64 \
+            -o ~/.docker/cli-plugins/docker-buildx
+          chmod +x ~/.docker/cli-plugins/docker-buildx
+
+      - name: Login to Docker Hub
+        env:
+          DH_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+          DH_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+        run: echo "$DH_TOKEN" | docker login -u "$DH_USER" --password-stdin
+
+      - name: Set up qemu
+        run: docker run --rm --privileged tonistiigi/binfmt --install all
+
+      - name: Build + push multi-arch image
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          VERSION_SEMVER="${VERSION#v}"
+          MAJOR_MINOR="${VERSION_SEMVER%.*}"
+          docker buildx create --name builder --use --driver docker-container
+          docker buildx build \
+            --platform linux/amd64,linux/arm64 \
+            --build-arg "VERSION=$VERSION" \
+            --tag "torrentclaw/unarr:$VERSION_SEMVER" \
+            --tag "torrentclaw/unarr:$MAJOR_MINOR" \
+            --tag "torrentclaw/unarr:latest" \
+            --push \
+            .

.github/workflows/docker-rebuild.yml

@@ -1,52 +0,0 @@
-# Rebuilds and re-pushes the `latest` image without a version bump so newly
-# *fixed* Alpine / ffmpeg / Go patches land between tagged releases. Versioned
-# tags are immutable and never touched here. Runs weekly and on demand.
-name: Docker rebuild
-
-on:
-  schedule:
-    # Mondays 04:17 UTC (off the hour to avoid the scheduler rush)
-    - cron: "17 4 * * 1"
-  workflow_dispatch:
-
-jobs:
-  rebuild:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      # Stamp the binary with the most recent release tag (not "dev").
-      - name: Resolve version
-        id: ver
-        run: echo "version=$(git describe --tags --abbrev=0 2>/dev/null || echo dev)" >> "$GITHUB_OUTPUT"
-
-      - uses: docker/setup-qemu-action@v4
-      - uses: docker/setup-buildx-action@v4
-
-      - uses: docker/login-action@v4
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - uses: docker/build-push-action@v7
-        with:
-          context: .
-          push: true
-          platforms: linux/amd64,linux/arm64
-          # Refresh the floating tag only — never overwrite a versioned release.
-          tags: torrentclaw/unarr:latest
-          build-args: |
-            VERSION=${{ steps.ver.outputs.version }}
-          # Force a fresh base pull so apk upgrade picks up new patches.
-          no-cache: true
-
-      - name: Scan image for fixable CVEs (gate)
-        uses: docker/scout-action@v1
-        with:
-          command: cves
-          image: torrentclaw/unarr:latest
-          only-severities: critical,high
-          only-fixed: true
-          exit-code: true

.github/workflows/pages.yml

@@ -1,52 +0,0 @@
-name: Deploy install scripts to Pages
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - install.sh
-      - install.ps1
-      - CNAME
-      - .nojekyll
-      - .github/workflows/pages.yml
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/configure-pages@v5
-      - name: Stage install scripts
-        run: |
-          mkdir -p _site
-          cp install.sh install.ps1 _site/
-          [ -f CNAME ] && cp CNAME _site/
-          touch _site/.nojekyll
-          # Also index page (humans landing)
-          cat > _site/index.html <<'HTML'
-          <!doctype html>
-          <html><head><meta charset=utf-8><title>unarr installer</title></head>
-          <body><h1>unarr CLI installer</h1>
-          <pre>Linux/macOS:  curl -fsSL https://unarr.torrentclaw.com/install.sh | sh
-          Windows:      irm https://unarr.torrentclaw.com/install.ps1 | iex</pre>
-          <p>Source: <a href="https://github.com/torrentclaw/unarr">github.com/torrentclaw/unarr</a></p>
-          </body></html>
-          HTML
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: _site
-      - id: deployment
-        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -1,210 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - "v*"
-
-permissions:
-  contents: write
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-go@v6
-        with:
-          go-version-file: go.mod
-
-      - uses: goreleaser/goreleaser-action@v6
-        with:
-          version: "~> v2"
-          args: release --clean
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
-          # Empty when RELEASE_SIGNING_PUBKEY variable is unset — goreleaser
-          # accepts it and the resulting binary disables signature checks
-          # (back-compat: pre-signing releases continue to update). Set
-          # RELEASE_SIGNING_PUBKEY (variable) + RELEASE_SIGNING_KEY (secret)
-          # to turn verification on.
-          RELEASE_SIGNING_PUBKEY: ${{ vars.RELEASE_SIGNING_PUBKEY }}
-
-      - name: Sign checksums.txt with ed25519
-        # Reference secrets.X directly — step-level env defined in this same
-        # step is unreliable to read from this step's own if: expression.
-        if: ${{ vars.RELEASE_SIGNING_PUBKEY != '' && secrets.RELEASE_SIGNING_KEY != '' }}
-        env:
-          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
-          RELEASE_TAG: ${{ github.ref_name }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euo pipefail
-          go run ./scripts/sign-checksums \
-            -key "$RELEASE_SIGNING_KEY" \
-            -in  dist/checksums.txt \
-            -out dist/checksums.txt.sig
-          gh release upload "$RELEASE_TAG" dist/checksums.txt.sig --clobber
-
-  docker:
-    needs: release
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@v6
-        with:
-          images: torrentclaw/unarr
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=raw,value=latest
-
-      - uses: docker/setup-qemu-action@v4
-      - uses: docker/setup-buildx-action@v4
-
-      - uses: docker/login-action@v4
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - uses: docker/build-push-action@v7
-        with:
-          context: .
-          push: true
-          platforms: linux/amd64,linux/arm64
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          build-args: |
-            VERSION=${{ github.ref_name }}
-
-      # CVE gate. Fails the release on FIXABLE critical/high only — unfixed
-      # upstream ffmpeg codec CVEs are accepted (see SECURITY.md), so the
-      # codec noise does not block. Runs post-push (image already published);
-      # a failure here flags that a fixable CVE slipped through.
-      - name: Scan image for fixable CVEs (gate)
-        uses: docker/scout-action@v1
-        with:
-          command: cves
-          image: torrentclaw/unarr:latest
-          only-severities: critical,high
-          only-fixed: true
-          exit-code: true
-
-      # Sync the Docker Hub repo description from DOCKERHUB.md. Non-fatal: a
-      # description-API auth hiccup must not undo a successful image push.
-      - name: Update Docker Hub description
-        uses: peter-evans/dockerhub-description@v4
-        continue-on-error: true
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-          repository: torrentclaw/unarr
-          readme-filepath: ./DOCKERHUB.md
-          short-description: "unarr — the single binary that replaces your *arr stack"
-
-
-  virustotal:
-    needs: release
-    runs-on: ubuntu-latest
-    if: vars.VT_ENABLED == 'true'
-    steps:
-      - name: Get release tag
-        id: tag
-        run: echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-
-      - name: Download release assets
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          mkdir -p assets
-          gh release download "${{ steps.tag.outputs.tag }}" \
-            --repo "${{ github.repository }}" \
-            --dir assets \
-            --pattern '*.tar.gz' \
-            --pattern '*.zip' \
-            --pattern 'checksums.txt'
-
-      - name: Scan assets with VirusTotal
-        env:
-          VT_API_KEY: ${{ secrets.VT_API_KEY }}
-        run: |
-          mkdir -p results
-          for file in assets/*; do
-            filename=$(basename "$file")
-            echo "Uploading $filename to VirusTotal..."
-
-            response=$(curl -s --request POST \
-              --url https://www.virustotal.com/api/v3/files \
-              --header "x-apikey: $VT_API_KEY" \
-              --form "file=@$file")
-
-            analysis_id=$(echo "$response" | jq -r '.data.id // empty')
-            if [ -z "$analysis_id" ]; then
-              echo "::warning::Failed to upload $filename: $response"
-              continue
-            fi
-
-            echo "$filename=$analysis_id" >> results/scans.txt
-            echo "  Analysis ID: $analysis_id"
-
-            # Rate limit: VT free tier allows 4 req/min
-            sleep 16
-          done
-
-      - name: Wait for analysis completion
-        env:
-          VT_API_KEY: ${{ secrets.VT_API_KEY }}
-        run: |
-          echo "Waiting 60s for VirusTotal analysis to complete..."
-          sleep 60
-
-          vt_report="## 🛡️ VirusTotal Scan Results\n\n"
-          vt_report+="| File | Result | Link |\n"
-          vt_report+="|------|--------|------|\n"
-
-          while IFS='=' read -r filename analysis_id; do
-            result=$(curl -s --request GET \
-              --url "https://www.virustotal.com/api/v3/analyses/$analysis_id" \
-              --header "x-apikey: $VT_API_KEY")
-
-            malicious=$(echo "$result" | jq -r '.data.attributes.stats.malicious // 0')
-            undetected=$(echo "$result" | jq -r '.data.attributes.stats.undetected // 0')
-            sha256=$(echo "$result" | jq -r '.meta.file_info.sha256 // empty')
-
-            if [ "$malicious" = "0" ]; then
-              status="✅ Clean ($undetected engines)"
-            else
-              status="⚠️ $malicious detections"
-            fi
-
-            link="https://www.virustotal.com/gui/file/$sha256"
-            vt_report+="| \`$filename\` | $status | [View]($link) |\n"
-
-            sleep 16
-          done < results/scans.txt
-
-          echo -e "$vt_report" > results/report.md
-          cat results/report.md
-
-      - name: Append scan results to release notes
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          current_body=$(gh release view "${{ steps.tag.outputs.tag }}" \
-            --repo "${{ github.repository }}" \
-            --json body --jq '.body')
-
-          new_body="${current_body}
-
-          $(cat results/report.md)"
-
-          gh release edit "${{ steps.tag.outputs.tag }}" \
-            --repo "${{ github.repository }}" \
-            --notes "$new_body"

.gitignore

@@ -41,4 +41,7 @@ dist-ffbinaries/
 # Docker
 tmp/
 config/
-dist-ffbinaries/
+dist-ffbinaries/
+
+# Claude Code: keep entirely local, do not track
+.claude/

.goreleaser.yml

@@ -59,6 +59,22 @@ changelog:
       - "^test:"
       - "^chore:"
 
+# Self-hosted Forgejo at git.torrentclaw.com. goreleaser detects GITEA_TOKEN +
+# these URLs and publishes the release there instead of GitHub. Reachable via
+# `forgejo` hostname inside the dokploy-network (the runner shares it); for
+# local goreleaser runs outside the network, override via env GITEA_API_URL.
+#
+# In goreleaser v2 `gitea_urls` is a top-level key (was nested under `release`
+# in v1).
+gitea_urls:
+  api: http://forgejo:3000/api/v1
+  download: https://git.torrentclaw.com
+  skip_tls_verify: false
+
+release:
+  draft: false
+  prerelease: auto
+
 # Homebrew tap — requires PAT with repo scope (not GITHUB_TOKEN)
 # Enable when torrentclaw/homebrew-tap PAT is configured as HOMEBREW_TAP_TOKEN
 # brews:

CHANGELOG.md

@@ -5,18 +5,131 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.9.2] - 2026-05-21
+## [0.9.15] - 2026-05-27
+
 
 ### Added
 
-- **vpn**: `unarr vpn` command (`status`, `enable`, `disable`) to manage the managed
+- **sentry**: enhance error handling by skipping user input errors in CaptureError
-  WireGuard split-tunnel, with `vpn status --check` to verify provisioning.
-- **vpn**: report split-tunnel state (active, exit server) to the web on register
-  + every sync, so the dashboard shows which agent holds the single WireGuard slot.
-- **vpn**: send the agent id when fetching the VPN config so the web can arbitrate
-  the single WireGuard slot — the first agent claims it; the rest are told to run
-  OpenVPN on their own host (1 agent on WireGuard + up to 9 on OpenVPN).
 
+### Changed
+
+- **ci**: point Forgejo URLs at torrentclaw org (post-transfer)
+- **sentry**: decouple agent import via string-match, rename predicate
+
+### Documentation
+
+- **positioning**: reframe unarr around download/stream/transcode, drop misleading search-first wording
+
+### Fixed
+
+- **ci**: unset GITHUB_TOKEN so goreleaser uses GITEA_TOKEN
+- **sentry**: skip "daemon not running" stop/reload errors
+
+### Other
+
+- **scripts**: harden release.sh against double-release and inline version bumps
+- untrack .claude/ (private local config)
+## [0.9.14] - 2026-05-27
+
+
+### Added
+
+- **vaapi**: hybrid CPU-scale + hwupload encode path (QW2, 0.9.14)
+
+### CI/CD
+
+- port workflows from .github/ to .forgejo/ (Forgejo Actions)
+
+### Fixed
+
+- **daemon**: defensive IsClosed check in watchSessionReady poll loop
+- **daemon**: use parent ctx for MarkSessionReady so cancel propagates
+- **release**: move gitea_urls to top-level (goreleaser v2 schema)
+## [0.9.13] - 2026-05-27
+
+
+### Added
+
+- **agent**: session-ready webhook for SSE-driven player handshake (0.9.13)
+- **agent**: send full transcoder diagnostic in register payload (0.9.12)
+
+### Fixed
+
+- **daemon**: defer probeCancel so a panic mid-diagnostic still releases ctx
+
+### Other
+
+- **release**: add ship.sh end-to-end pipeline as GH Actions backup
+- **skills**: add /publish slash command + allow .claude/ in git
+## [0.9.11] - 2026-05-27
+
+
+### Added
+
+- **hls**: pre-segmentación delantada — 2 s segments + async session start (0.9.10)
+- **hls**: faster first-start — probe cache + tighter encoder presets (0.9.9)
+
+### Changed
+
+- **hls**: critico-driven hardening of fase 3.2
+
+### Fixed
+
+- **cors**: allow play from .to / staging / onion mirrors
+- **library**: classify resolution by width + height, not height alone
+- **transcode**: make preset libx264-only + restore quality opt-in
+
+### Other
+
+- **release**: 0.9.11
+## [0.9.8] - 2026-05-27
+
+
+### Fixed
+
+- **upgrade**: break auto-apply restart loop (0.9.8)
+## [0.9.7] - 2026-05-26
+
+
+### Added
+
+- **hls**: persistent fMP4 segment cache + integrity + stats (0.9.7)
+## [0.9.6] - 2026-05-26
+
+
+### Added
+
+- **daemon**: auto-apply upgrades when server signals (0.9.6)
+## [0.9.5] - 2026-05-26
+
+
+### Added
+
+- **funnel**: cloudflare quick tunnel embedded subprocess (0.9.5)
+## [0.9.4] - 2026-05-26
+
+
+### Added
+
+- **stream**: retire WebRTC, HLS-only, bump 0.9.4 (**BREAKING**)
+## [0.9.3] - 2026-05-26
+
+
+### Added
+
+- **usenet**: warn at startup when par2 or extractor is missing
+
+### Fixed
+
+- **engine**: truncate errorMessage before reporting status
+- **hls**: clamp ffmpeg bitrate to the level we derive from outputHeight
+## [0.9.2] - 2026-05-22
+
+
+### Added
+
+- **vpn**: unarr vpn command + report/arbitrate the WireGuard slot
 ## [0.9.1] - 2026-05-21
 
 
@@ -27,6 +140,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **security**: bump golang.org/x deps and add container CVE scan gate
+
+### Other
+
+- **release**: 0.9.1
 ## [0.9.0] - 2026-05-21
 
 
@@ -36,6 +153,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **vpn**: local config_file for self-hosted/personal VPN testing
 - **vpn**: split-tunnel torrent traffic through managed WireGuard
 
+### CI/CD
+
+- deploy install scripts to GitHub Pages
+
 ### Documentation
 
 - **docker**: refresh Docker Hub README + sync description in CI
@@ -49,6 +170,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Other
 
+- **pages**: add .nojekyll to disable Jekyll processing
+- **pages**: set custom domain unarr.torrentclaw.com
 - **release**: 0.9.0
 ## [0.8.1] - 2026-05-08
 
@@ -422,6 +545,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Build
 
 - add -s -w -trimpath to Makefile, add build-small target with UPX
+[0.9.15]: https://github.com/torrentclaw/unarr/compare/v0.9.14...v0.9.15
+[0.9.14]: https://github.com/torrentclaw/unarr/compare/v0.9.13...v0.9.14
+[0.9.13]: https://github.com/torrentclaw/unarr/compare/v0.9.11...v0.9.13
+[0.9.11]: https://github.com/torrentclaw/unarr/compare/v0.9.8...v0.9.11
+[0.9.8]: https://github.com/torrentclaw/unarr/compare/v0.9.7...v0.9.8
+[0.9.7]: https://github.com/torrentclaw/unarr/compare/v0.9.6...v0.9.7
+[0.9.6]: https://github.com/torrentclaw/unarr/compare/v0.9.5...v0.9.6
+[0.9.5]: https://github.com/torrentclaw/unarr/compare/v0.9.4...v0.9.5
+[0.9.4]: https://github.com/torrentclaw/unarr/compare/v0.9.3...v0.9.4
+[0.9.3]: https://github.com/torrentclaw/unarr/compare/v0.9.2...v0.9.3
+[0.9.2]: https://github.com/torrentclaw/unarr/compare/v0.9.1...v0.9.2
 [0.9.1]: https://github.com/torrentclaw/unarr/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/torrentclaw/unarr/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/torrentclaw/unarr/compare/v0.8.0...v0.8.1

DOCKERHUB.md

@@ -1,8 +1,9 @@
 # unarr
 
-**The single binary that replaces your whole *arr stack.** Search 30+ torrent
+**The single binary that replaces your whole *arr stack.** Built-in torrent,
-sources, inspect real quality before you download, grab subtitles, and manage
+debrid, and usenet engines. Stream, transcode, and organize your library from
-your media library — all from one terminal tool or a headless daemon.
+one terminal — or run it as a headless daemon with a web dashboard, WireGuard
+split-tunnel, and Cloudflare Funnel remote access.
 
 **[Website & docs](https://torrentclaw.com/unarr)** · **[Install guide](https://torrentclaw.com/cli)** · **[Get an API key](https://torrentclaw.com)**
 

Dockerfile

@@ -21,10 +21,23 @@ FROM alpine:3.22
 # Use Alpine's native musl ffmpeg + ffprobe instead of the johnvansickle /
 # BtbN static glibc builds — those need a glibc shim on Alpine and the
 # vector-math symbols the GPL builds reference are not satisfiable by
-# gcompat. Alpine ships ffmpeg ~7.x which is fine for the WebRTC
+# gcompat. Alpine ships ffmpeg ~7.x which is fine for the HLS transcoding
-# transcoding pipeline (libx264 + libfdk-aac alternatives included).
+# pipeline (libx264 + libfdk-aac alternatives included).
 RUN apk upgrade --no-cache && \
-    apk add --no-cache ca-certificates tzdata ffmpeg
+    apk add --no-cache ca-certificates tzdata ffmpeg wget
+
+# Bundle cloudflared so `unarr funnel on` (default: on, see config defaults)
+# Just Works on a headless container with no first-run network round-trip.
+# TARGETARCH is set automatically by Docker buildx during cross-builds.
+ARG TARGETARCH=amd64
+RUN case "$TARGETARCH" in \
+      amd64) CF_ARCH=amd64 ;; \
+      arm64) CF_ARCH=arm64 ;; \
+      arm)   CF_ARCH=armhf ;; \
+      *)     echo "unsupported TARGETARCH=$TARGETARCH" >&2; exit 1 ;; \
+    esac && \
+    wget -qO /usr/local/bin/cloudflared "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-$CF_ARCH" && \
+    chmod +x /usr/local/bin/cloudflared
 
 # Non-root user (UID 1000 matches typical host user for volume permissions)
 RUN addgroup -g 1000 unarr && adduser -u 1000 -G unarr -D -h /home/unarr unarr

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build test lint coverage clean fmt vet check install-hooks changelog release release-patch release-minor release-major release-dry
+.PHONY: all build test lint coverage clean fmt vet check install-hooks changelog release release-patch release-minor release-major release-dry ship ship-dry ship-push
 
 BINARY = unarr
 SENTRY_DSN ?=
@@ -71,6 +71,19 @@ release-dry:
 	@test -n "$(V)" || { echo "Usage: make release-dry V=patch|minor|major|0.5.0"; exit 1; }
 	@./scripts/release.sh --dry-run $(V)
 
+## Ship a release end-to-end (goreleaser + Hetzner + Docker Hub). Standalone backup for GH Actions.
+## Reads version from internal/cmd/version.go unless V= is provided.
+ship:
+	@./scripts/ship.sh $(V)
+
+## Ship + git push tag to GH afterwards
+ship-push:
+	@./scripts/ship.sh --push $(V)
+
+## Preview ship steps without executing
+ship-dry:
+	@./scripts/ship.sh --dry-run $(V)
+
 ## Remove generated files
 clean:
 	rm -f $(BINARY) coverage.out coverage.html

README.md

@@ -11,9 +11,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Go Version](https://img.shields.io/github/go-mod/go-version/torrentclaw/unarr)](go.mod)
 
-Powerful terminal tool for torrent search and management. **Free and open source.**
+The single-binary terminal client for torrent, debrid, and usenet downloads. **Free and open source.**
 
-Search 30+ torrent sources, inspect torrent quality, discover popular content, find streaming providers, and manage your media collection — all from your terminal.
+Built-in torrent engine, debrid (Real-Debrid / AllDebrid), and NZB support. Stream to mpv/vlc, transcode on the fly with hardware acceleration, and manage your library — one binary or a headless daemon with WireGuard split-tunnel and Cloudflare Funnel remote access.
 
 <!-- GIF demo placeholder -->
 <!-- ![unarr Demo](docs/demo.gif) -->
@@ -343,6 +343,58 @@ unarr self-update --force   # reinstall even if up to date
 
 `unarr doctor` checks: config file, API key, server connectivity (with latency), agent registration, download directory, disk space, and version.
 
+### Updating unarr
+
+unarr supports three update paths. Pick whichever fits your workflow.
+
+**1. Manual self-update (always available).**
+
+```bash
+unarr self-update                # interactive update to latest
+unarr self-update --force        # reinstall same version
+unarr self-update --allow-unsigned # accept releases without checksum signature
+```
+
+The CLI downloads the new release archive over HTTPS (from
+`torrentclaw.com/releases/download/v<ver>/`), verifies SHA-256, swaps the
+binary in place (`.backup` kept next to it), and restarts the systemd
+user unit if the daemon is running.
+
+**2. Auto-apply on server signal (default, since 0.9.6).**
+
+When you press **"Force update now"** on the web (Settings → Agent → Force
+update), the server sets a flag your daemon polls every sync (~3 s). On
+the next sync the daemon downloads the new binary, replaces itself, and
+exits — `systemd Restart=always` respawns on the new version. No SSH, no
+terminal access required. Works headless on NAS / Docker.
+
+The button shows an amber warning if your agent is below 0.9.6 (older
+daemons see the signal but only log "run unarr update" — the operator
+must run the command manually that one time).
+
+**Opt out of auto-apply.** Some users prefer reviewing CHANGELOG before
+applying. Disable in `config.toml`:
+
+```toml
+[daemon]
+auto_upgrade = false
+```
+
+With `auto_upgrade = false`, pressing the web button still flags your
+agent (so the daemon logs the new version on next sync), but the daemon
+will not download / replace anything — you run `unarr self-update` when
+you're ready.
+
+**3. Docker auto-restart with a new tag.**
+
+```bash
+docker pull torrentclaw/unarr:latest
+docker compose up -d
+```
+
+Tags published: `latest`, `0.9`, `0.9.7`, ... — pin to a minor (`0.9`)
+for opt-in patch updates without surprises.
+
 ## Clean
 
 Remove temporary files, logs, resume data, and other artifacts generated by unarr. Shows what will be removed and asks for confirmation before deleting.
@@ -424,6 +476,7 @@ tv_shows_dir = "~/Media/TV Shows"
 [daemon]
 poll_interval = "30s"
 heartbeat_interval = "30s"
+auto_upgrade = true   # apply server-flagged upgrades in-place (since 0.9.6)
 
 [notifications]
 enabled = true
@@ -434,24 +487,12 @@ country = "US"
 
 ### Streaming reference
 
-The in-browser player on torrentclaw.com streams from the daemon over WebRTC
+The in-browser player on torrentclaw.com streams from the daemon over HLS
-(low-latency P2P) or HLS (HTTP fragments + ffmpeg transcode for codecs the
+(HTTP fragments + ffmpeg transcode for codecs the browser can't decode
-browser can't decode natively). Both are enabled by default — a fresh install
+natively). Enabled by default — a fresh install "just works" without editing
-"just works" without editing the TOML. Disable surgically only if you have a
+the TOML.
-reason.
 
 ```toml
-[downloads.webrtc]
-enabled       = true                                    # master switch
-trackers      = ["wss://tracker.torrentclaw.com"]      # signaling trackers
-stun_servers  = [                                       # NAT traversal
-  "stun:stun.l.google.com:19302",
-  "stun:stun1.l.google.com:19302",
-]
-turn_servers  = []                                      # optional TURN relays
-turn_user     = ""
-turn_pass     = ""
-
 [downloads.transcode]
 enabled        = true        # master switch
 hw_accel       = "auto"      # auto | none | nvenc | qsv | vaapi | videotoolbox
@@ -462,16 +503,6 @@ max_height     = 0           # 0 = no cap; e.g. 720 forces 720p max
 max_concurrent = 2           # max simultaneous ffmpeg processes
 ```
 
-#### `[downloads.webrtc]`
-
-| Key | Type | Default | Notes |
-|-----|------|---------|-------|
-| `enabled` | bool | `true` | Browser↔daemon WebRTC peer for the in-browser P2P player. Disable to skip WebRTC tracker signalling (saves ~5MB RAM, blocks WebRTC streaming — HLS still works). |
-| `trackers` | `[]string` | `["wss://tracker.torrentclaw.com"]` | Signaling trackers for peer discovery. |
-| `stun_servers` | `[]string` | Google public STUN ×2 | ICE candidate gathering. |
-| `turn_servers` | `[]string` | `[]` | Optional TURN relays for symmetric-NAT users. |
-| `turn_user` / `turn_pass` | string | `""` | Credentials for authed TURN servers. Applied to all `turn_servers`. |
-
 #### `[downloads.transcode]`
 
 | Key | Type | Default | Notes |
@@ -488,6 +519,40 @@ If `transcode.enabled = true` but `ffmpeg` / `ffprobe` aren't on PATH, the
 daemon logs a warning at startup and HLS sessions are rejected at runtime
 with a clear error — install ffmpeg or set `enabled = false`.
 
+#### `[downloads.hls_cache]` — persistent HLS segment cache
+
+```toml
+[downloads.hls_cache]
+enabled = true   # on by default
+size_gb = 5      # disk budget; LRU eviction once exceeded
+dir     = ""     # custom path; empty = ~/.cache/unarr/hls-cache
+```
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `enabled` | bool | `true` | Persists finished HLS encodes per `(source, quality, audio_index)`. A second play of the same file at the same quality reuses the segments — no ffmpeg, near-zero CPU, instant playback. Set to `false` to delete segments on session close (original behavior). |
+| `size_gb` | int | `5` | Cache budget in gigabytes. When exceeded the LRU sweeper evicts the least-recently-used cached encodes hourly. Minimum 1 GB (smaller values are clamped up). |
+| `dir` | string | `""` | Custom storage path. Empty defaults to `~/.cache/unarr/hls-cache` (Linux/macOS) or the user cache dir (Windows). |
+
+**What it does.** First play encodes normally (ffmpeg writes segments).
+On session close, if every segment is on disk and ffmpeg exited cleanly,
+the directory is sealed with a `.complete` marker and kept. Next time the
+same source + quality combo is requested, the daemon serves segments
+straight from disk — no transcode, no warm-up, no CPU cost.
+
+**Why per (source, quality, audio).** Renaming the file or switching
+quality invalidates the entry: the segments are tied to the exact source
+bytes and the exact ffmpeg parameters. Re-encoding generates a new key.
+
+**Eviction.** A background goroutine wakes every hour. If total cache size
+exceeds `size_gb`, it deletes the oldest entries (by mtime) until under
+budget. Active sessions are pinned — they never get evicted mid-play.
+
+**Disable.** Either edit the TOML to set `enabled = false`, or remove the
+cache directory manually (it'll be recreated as needed). Disabling does
+not delete existing cached segments — drop `dir` (or `~/.cache/unarr/hls-cache`)
+to reclaim the space.
+
 #### `[downloads.vpn]`
 
 | Key | Type | Default | Notes |
@@ -498,6 +563,64 @@ with a clear error — install ffmpeg or set `enabled = false`.
 See the [VPN](#vpn) section above for how it works (split-tunnel, no root) and
 how to protect your other devices.
 
+#### `[downloads.funnel]` — public HTTPS hostname for the daemon (CloudFlare Quick Tunnel)
+
+```toml
+[downloads.funnel]
+enabled = false   # off by default
+```
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `enabled` | bool | `false` | Spawns `cloudflared tunnel --url http://localhost:<stream_port>` as a child process at daemon startup. Toggle with `unarr funnel on` / `off`. Requires `cloudflared` on PATH. |
+
+**What it does.** Without a tunnel, the daemon is reachable on `localhost`,
+your LAN, and (if installed) Tailscale. That covers the same-machine and
+Tailscale-connected cases, but the **browser-based player on torrentclaw.com
+fails on any other network** because HTTPS pages can't fetch HTTP resources
+("mixed content"). Enabling the funnel gives the daemon a public
+`https://<random>.trycloudflare.com` hostname so the web player picks it up
+and playback works from anywhere — phone on cellular, friend's laptop on a
+foreign Wi-Fi, anywhere. The Stremio addon already works cross-network
+(native mpv/VLC players ignore CORS), so this is strictly a web-player fix.
+
+**Privacy posture.** Bytes pass through CloudFlare's edge — TorrentClaw never
+relays content (we don't see your traffic), CloudFlare does. Quick Tunnels
+are **anonymous** (no CF account required); the registration is unauthenticated
+and the hostname is a random label, but CF logs request metadata like any CDN
+would. If you want zero third-party byte access, use Tailscale instead.
+
+**Limitations (free Quick Tunnels).**
+| Aspect | Limit |
+|--------|-------|
+| Session lifetime | ~6 hours, then the hostname rotates. cloudflared re-registers automatically; the web picks up the new URL on the next sync. In-flight HLS sessions break across the rotation (browser retries). |
+| Bandwidth | No documented hard cap, but CF reserves the right to throttle. 1080p HLS (~6 Mbps) is fine; 4K HEVC at 25 Mbps may hit throttling. |
+| Latency | +20–80 ms vs direct LAN/Tailscale (extra hop browser → CF edge → tunnel). HLS player buffer absorbs it. |
+| Concurrency | One tunnel serves N viewers. CF rate-limits ~200 req/s, plenty for HLS segments. |
+| TOS | CloudFlare flags Quick Tunnels as "not for production traffic". They can decommission an abusive tunnel without notice. |
+
+For heavy / high-throughput / persistent-URL use cases, switch to a CloudFlare
+Named Tunnel (free, needs a CF account) or run your own reverse proxy — both
+out of scope for the bundled command.
+
+**Disable.** `unarr funnel off` flips `enabled` to `false` in the TOML and
+prompts you to restart the daemon. You can also edit `config.toml` directly:
+
+```toml
+[downloads.funnel]
+enabled = false
+```
+
+**Install cloudflared.**
+- Linux: `apt install cloudflared` (after adding CF's apt repo) — see
+  <https://pkg.cloudflare.com>. Or pull the static binary from
+  <https://github.com/cloudflare/cloudflared/releases>.
+- macOS: `brew install cloudflared`.
+- Windows: `winget install --id Cloudflare.cloudflared`.
+
+If `cloudflared` is not on PATH the daemon logs a warning at startup and
+falls back to LAN/Tailscale-only reachability.
+
 ### Environment variables
 
 Environment variables override config file values:

SECURITY.md

@@ -72,7 +72,7 @@ Docker Hub vulnerability count:
   package pulls ~40 codec/parser libraries (`x264`, `x265`, `libvpx`, `aom`,
   `dav1d`, `libtheora`, `libvorbis`, `libwebp`, `libbluray`, `libopenmpt`, …).
   Each carries a long NVD history that Alpine does not backport. ffmpeg is a
-  **functional dependency** — the WebRTC/HLS transcode pipeline shells out to
+  **functional dependency** — the HLS transcode pipeline shells out to
   `ffmpeg`/`ffprobe` to decode untrusted media and re-encode to H.264 + AAC.
 
 ### Accepted risk and policy
@@ -100,7 +100,7 @@ Recommended additions for exposed deployments:
       - no-new-privileges:true
 ```
 
-If you do not need WebRTC/HLS transcoding, you can run with transcoding disabled to
+If you do not need HLS transcoding, you can run with transcoding disabled to
 avoid feeding untrusted media to ffmpeg at all.
 
 ## Disclosure Policy

cmd/wstracker-probe/main.go

@@ -1,268 +0,0 @@
-// wstracker-probe — connects to a WebSocket BitTorrent tracker and either
-// (a) advertises a fake info_hash to verify announce signalling, or
-// (b) seeds a real file via the WebTorrent protocol so a browser
-// webtorrent.js client can fetch it for end-to-end verification.
-//
-// Modes:
-//
-//	wstracker-probe -tracker wss://tracker.torrentclaw.com
-//	    Announces a random info_hash; exits 0 on TrackerAnnounceSuccessful.
-//
-//	wstracker-probe -tracker wss://… -seed /path/to/file.mp4
-//	    Builds a single-file torrent in memory, seeds forever, prints the
-//	    magnet (with the WSS tracker injected). Ctrl-C to stop.
-//
-// Useful for browser ↔ unarr e2e — point a webtorrent.js page at the
-// printed magnet and the player should pull pieces via WebRTC data channel.
-package main
-
-import (
-	"context"
-	"crypto/rand"
-	"flag"
-	"fmt"
-	"log"
-	"net/url"
-	"os"
-	"os/signal"
-	"path/filepath"
-	"syscall"
-	"time"
-
-	alog "github.com/anacrolix/log"
-	"github.com/anacrolix/torrent"
-	"github.com/anacrolix/torrent/bencode"
-	"github.com/anacrolix/torrent/metainfo"
-	"github.com/anacrolix/torrent/storage"
-	"github.com/pion/webrtc/v4"
-)
-
-func main() {
-	tracker := flag.String("tracker", "wss://tracker.torrentclaw.com", "WSS tracker URL to probe")
-	timeout := flag.Duration("timeout", 30*time.Second, "max wait for successful announce (ignored in -seed mode)")
-	seedPath := flag.String("seed", "", "path to a file to seed (single-file torrent). When set, runs forever instead of exiting on first announce.")
-	flag.Parse()
-
-	if *seedPath != "" {
-		runSeeder(*seedPath, *tracker)
-		return
-	}
-
-	runProbe(*tracker, *timeout)
-}
-
-// runProbe — single random-hash announce, exits on success/error/timeout.
-func runProbe(trackerURL string, timeout time.Duration) {
-	tmp, err := os.MkdirTemp("", "wstracker-probe-*")
-	if err != nil {
-		log.Fatalf("temp dir: %v", err)
-	}
-	defer os.RemoveAll(tmp)
-
-	cfg := baseClientConfig(tmp)
-
-	annSuccess := make(chan struct{}, 1)
-	annError := make(chan error, 1)
-	cfg.Callbacks.StatusUpdated = append(
-		cfg.Callbacks.StatusUpdated,
-		func(e torrent.StatusUpdatedEvent) {
-			switch e.Event { //nolint:exhaustive // peer events are noise for tracker probe
-			case torrent.TrackerConnected:
-				if e.Error != nil {
-					fmt.Printf("[probe] tracker connect FAILED: %v\n", e.Error)
-				} else {
-					fmt.Printf("[probe] tracker connected: %s\n", e.Url)
-				}
-			case torrent.TrackerAnnounceSuccessful:
-				fmt.Printf("[probe] tracker announce OK: %s ih=%s\n", e.Url, e.InfoHash)
-				select {
-				case annSuccess <- struct{}{}:
-				default:
-				}
-			case torrent.TrackerAnnounceError:
-				fmt.Printf("[probe] tracker announce ERROR: %s ih=%s err=%v\n", e.Url, e.InfoHash, e.Error)
-				select {
-				case annError <- e.Error:
-				default:
-				}
-			case torrent.TrackerDisconnected:
-				fmt.Printf("[probe] tracker disconnected: %s err=%v\n", e.Url, e.Error)
-			}
-		},
-	)
-
-	client, err := torrent.NewClient(cfg)
-	if err != nil {
-		log.Fatalf("create torrent client: %v", err)
-	}
-	defer client.Close()
-
-	var ih [20]byte
-	if _, err := rand.Read(ih[:]); err != nil {
-		log.Fatalf("random info_hash: %v", err)
-	}
-	magnet := fmt.Sprintf("magnet:?xt=urn:btih:%x&tr=%s", ih, trackerURL)
-	fmt.Printf("[probe] tracker=%s info_hash=%x timeout=%s\n", trackerURL, ih, timeout)
-
-	t, err := client.AddMagnet(magnet)
-	if err != nil {
-		log.Fatalf("add magnet: %v", err)
-	}
-	defer t.Drop()
-
-	ctx, cancel := context.WithTimeout(context.Background(), timeout)
-	defer cancel()
-
-	select {
-	case <-annSuccess:
-		fmt.Println("[probe] OK — tracker announce succeeded")
-		os.Exit(0)
-	case err := <-annError:
-		fmt.Printf("[probe] FAIL — tracker announce error: %v\n", err)
-		os.Exit(1)
-	case <-ctx.Done():
-		fmt.Printf("[probe] FAIL — timeout after %s\n", timeout)
-		os.Exit(2)
-	}
-}
-
-// runSeeder — builds a single-file torrent for the given path, adds it to
-// a WebTorrent-enabled client, and seeds until SIGINT/SIGTERM.
-func runSeeder(filePath, trackerURL string) {
-	abs, err := filepath.Abs(filePath)
-	if err != nil {
-		log.Fatalf("resolve seed path: %v", err)
-	}
-	st, err := os.Stat(abs)
-	if err != nil {
-		log.Fatalf("stat seed file: %v", err)
-	}
-	if st.IsDir() {
-		log.Fatalf("-seed currently supports a single file, not a directory: %s", abs)
-	}
-
-	dataDir := filepath.Dir(abs)
-
-	// Build single-file torrent metadata.
-	info := metainfo.Info{
-		PieceLength: chooseSeedPieceLength(st.Size()),
-		Name:        filepath.Base(abs),
-	}
-	if err := info.BuildFromFilePath(abs); err != nil {
-		log.Fatalf("build info from file: %v", err)
-	}
-	infoBytes, err := bencode.Marshal(info)
-	if err != nil {
-		log.Fatalf("marshal info: %v", err)
-	}
-
-	mi := &metainfo.MetaInfo{
-		InfoBytes:    infoBytes,
-		AnnounceList: metainfo.AnnounceList{{trackerURL}},
-		CreatedBy:    "wstracker-probe",
-	}
-	ih := mi.HashInfoBytes()
-
-	cfg := baseClientConfig(dataDir)
-	cfg.Seed = true
-
-	cfg.Callbacks.StatusUpdated = append(
-		cfg.Callbacks.StatusUpdated,
-		func(e torrent.StatusUpdatedEvent) {
-			switch e.Event { //nolint:exhaustive
-			case torrent.TrackerConnected:
-				if e.Error != nil {
-					fmt.Printf("[seed] tracker connect FAILED: %v\n", e.Error)
-				} else {
-					fmt.Printf("[seed] tracker connected: %s\n", e.Url)
-				}
-			case torrent.TrackerAnnounceSuccessful:
-				fmt.Printf("[seed] tracker announce OK: %s ih=%s\n", e.Url, e.InfoHash)
-			case torrent.TrackerAnnounceError:
-				fmt.Printf("[seed] tracker announce ERROR: %s err=%v\n", e.Url, e.Error)
-			case torrent.TrackerDisconnected:
-				fmt.Printf("[seed] tracker disconnected: %s err=%v\n", e.Url, e.Error)
-			}
-		},
-	)
-
-	client, err := torrent.NewClient(cfg)
-	if err != nil {
-		log.Fatalf("create torrent client: %v", err)
-	}
-	defer client.Close()
-
-	t, err := client.AddTorrent(mi)
-	if err != nil {
-		log.Fatalf("add torrent: %v", err)
-	}
-	t.DownloadAll()
-
-	dn := url.QueryEscape(info.Name)
-	enc := url.QueryEscape(trackerURL)
-	magnet := fmt.Sprintf("magnet:?xt=urn:btih:%s&dn=%s&tr=%s", ih.HexString(), dn, enc)
-
-	fmt.Printf("[seed] file=%s size=%d bytes piece_length=%d\n", abs, st.Size(), info.PieceLength)
-	fmt.Printf("[seed] info_hash=%s\n", ih.HexString())
-	fmt.Printf("[seed] magnet=%s\n", magnet)
-	fmt.Println("[seed] seeding via WebRTC. Ctrl-C to stop.")
-
-	stop := make(chan os.Signal, 1)
-	signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
-	statTicker := time.NewTicker(5 * time.Second)
-	defer statTicker.Stop()
-
-	for {
-		select {
-		case <-statTicker.C:
-			s := t.Stats()
-			fmt.Printf("[seed] peers=%d uploaded=%d bytes seeders=%d leechers=%d\n",
-				s.ActivePeers, s.BytesWrittenData.Int64(),
-				s.ConnectedSeeders, s.ActivePeers-s.ConnectedSeeders)
-		case <-stop:
-			fmt.Println("[seed] stopping")
-			return
-		}
-	}
-}
-
-// baseClientConfig — shared anacrolix client config for both modes.
-// WebTorrent is the only transport enabled; TCP/uTP/DHT/IPv6 are disabled
-// to keep the moving parts to the minimum required for a WSS-only test.
-func baseClientConfig(dataDir string) *torrent.ClientConfig {
-	cfg := torrent.NewDefaultClientConfig()
-	cfg.DataDir = dataDir
-	cfg.DefaultStorage = storage.NewMMap(dataDir)
-	cfg.NoUpload = false
-	cfg.DisableTCP = true
-	cfg.DisableUTP = true
-	cfg.DisableIPv6 = true
-	cfg.NoDHT = true
-	cfg.NoDefaultPortForwarding = true
-	cfg.ListenPort = 0
-	cfg.Logger = alog.Default.FilterLevel(alog.Critical)
-	cfg.DisableWebtorrent = false
-	cfg.ICEServerList = []webrtc.ICEServer{
-		{URLs: []string{"stun:stun.l.google.com:19302"}},
-		{URLs: []string{"stun:stun1.l.google.com:19302"}},
-	}
-	return cfg
-}
-
-// chooseSeedPieceLength picks a sane piece size for a given file size.
-// Mirrors the libtorrent / qBittorrent ladder so the resulting torrent
-// is interoperable with mainstream clients.
-func chooseSeedPieceLength(size int64) int64 {
-	switch {
-	case size < 4*1024*1024: // < 4 MiB
-		return 16 * 1024 // 16 KiB
-	case size < 64*1024*1024: // < 64 MiB
-		return 64 * 1024 // 64 KiB
-	case size < 512*1024*1024: // < 512 MiB
-		return 256 * 1024 // 256 KiB
-	case size < 4*1024*1024*1024: // < 4 GiB
-		return 1024 * 1024 // 1 MiB
-	default:
-		return 4 * 1024 * 1024 // 4 MiB
-	}
-}

go.mod

@@ -13,7 +13,6 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/huin/goupnp v1.3.0
 	github.com/olekukonko/tablewriter v1.1.4
-	github.com/pion/webrtc/v4 v4.2.11
 	github.com/spf13/cobra v1.10.2
 	github.com/torrentclaw/go-client v0.2.0
 	golang.org/x/term v0.43.0
@@ -107,6 +106,7 @@ require (
 	github.com/pion/stun/v3 v3.1.1 // indirect
 	github.com/pion/transport/v4 v4.0.1 // indirect
 	github.com/pion/turn/v4 v4.1.4 // indirect
+	github.com/pion/webrtc/v4 v4.2.11 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/protolambda/ctxlock v0.1.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect

internal/agent/client.go

@@ -91,6 +91,45 @@ func (c *Client) Deregister(ctx context.Context, agentID string) error {
 	return nil
 }
 
+// ReportUpgradeResult tells the server the outcome of a previously requested
+// upgrade so the server can clear `upgrade_requested`. Without this call the
+// flag stays sticky and the daemon would re-trigger applyAutoUpgrade on every
+// sync after upgrade — even for "already on target version" no-ops.
+func (c *Client) ReportUpgradeResult(ctx context.Context, agentID string, success bool, version, errMsg string) error {
+	req := struct {
+		AgentID string `json:"agentId"`
+		Success bool   `json:"success"`
+		Version string `json:"version,omitempty"`
+		Error   string `json:"error,omitempty"`
+	}{AgentID: agentID, Success: success, Version: version, Error: errMsg}
+	var resp StatusResponse
+	if err := c.doPost(ctx, "/api/internal/agent/upgrade-result", req, &resp); err != nil {
+		return fmt.Errorf("report upgrade result: %w", err)
+	}
+	return nil
+}
+
+// MarkSessionReady signals the server that the first HLS segment + init.mp4
+// landed on disk for the given session. The web side flips
+// streaming_session.ready_at = NOW(), which its SSE endpoint emits to
+// subscribed players so the "Preparando…" UI ends without polling HEAD
+// on /hls/<id>/master.m3u8.
+//
+// Best-effort: the server is the source of truth for session state and
+// will reach the same conclusion via HEAD probes anyway if this call
+// fails. We log the error in the caller but don't retry — by the time
+// a retry would land the user is likely already playing.
+func (c *Client) MarkSessionReady(ctx context.Context, sessionID string) error {
+	req := struct {
+		SessionID string `json:"sessionId"`
+	}{SessionID: sessionID}
+	var resp StatusResponse
+	if err := c.doPost(ctx, "/api/internal/agent/session-ready", req, &resp); err != nil {
+		return fmt.Errorf("mark session ready: %w", err)
+	}
+	return nil
+}
+
 // ReportStatus reports download progress. Returns server-side flags the CLI must act on.
 func (c *Client) ReportStatus(ctx context.Context, update StatusUpdate) (*StatusResponse, error) {
 	var resp StatusResponse

internal/agent/daemon.go

@@ -11,6 +11,8 @@ import (
 	"strings"
 	"sync/atomic"
 	"time"
+
+	"github.com/torrentclaw/unarr/internal/upgrade"
 )
 
 // DaemonConfig holds daemon runtime settings.
@@ -26,6 +28,15 @@ type DaemonConfig struct {
 	ScanPaths          []string // configured scan paths for file deletion validation
 	HWAccel            string   // detected encoder backend ("nvenc"/"qsv"/"vaapi"/"videotoolbox"/"none")
 	MaxTranscodeHeight int      // resolution cap the agent can transcode comfortably (px)
+	// Diagnostic data populated by engine.DetectHWAccelDiagnostic at daemon
+	// start. Surfaced in the web "Diagnose transcoder" modal — lets a user
+	// see which encoders the ffmpeg binary supports and which devices the
+	// host exposes without running `unarr probe-hwaccel`.
+	FFmpegVersion string   // first line of `ffmpeg -version`
+	FFmpegPath    string   // resolved binary path
+	HWEncoders    []string // HW-class encoder names found in `ffmpeg -encoders`
+	HWDevices     []string // device files + driver bins detected at probe time
+	AutoUpgrade   bool     // honor server-flagged upgrades by downloading + restarting (default: true)
 }
 
 // Daemon manages agent registration and the sync loop.
@@ -38,7 +49,7 @@ type Daemon struct {
 	// Callbacks — set by cmd/daemon.go before calling Run.
 	OnTasksClaimed    func(tasks []Task)
 	OnStreamRequested func(req StreamRequest)
-	OnWebRTCSession   func(sess WebRTCSession)
+	OnStreamSession   func(sess StreamSession)
 	OnControlAction   func(action, taskID string, deleteFiles bool)
 	GetActiveCount    func() int // returns number of active downloads (wired from manager)
 
@@ -55,6 +66,10 @@ type Daemon struct {
 	vpnMode   string
 	vpnServer string
 
+	// CloudFlare Quick Tunnel public URL; folded into DaemonState + heartbeat
+	// so the web can prefer it over Tailscale/LAN for in-browser playback.
+	funnelURL string
+
 	// Watching tracks whether a user is viewing download progress in the web UI.
 	Watching atomic.Bool
 
@@ -85,6 +100,15 @@ func (d *Daemon) SetVPNState(active bool, mode, server string) {
 	d.vpnServer = server
 }
 
+// SetFunnelURL records the CloudFlare Quick Tunnel hostname so it's reflected
+// in the daemon state file (read by `unarr funnel status`) and in heartbeat
+// requests (so the web prefers it over Tailscale/LAN). Pass "" to clear.
+func (d *Daemon) SetFunnelURL(url string) {
+	d.funnelURL = url
+	d.State.FunnelURL = url
+	WriteState(&d.State)
+}
+
 // UpdateStreamPort updates the stream port reported in sync requests.
 func (d *Daemon) UpdateStreamPort(port int) {
 	d.cfg.StreamPort = port
@@ -106,9 +130,14 @@ func (d *Daemon) Register(ctx context.Context) error {
 		TailscaleIP:        d.cfg.TailscaleIP,
 		HWAccel:            d.cfg.HWAccel,
 		MaxTranscodeHeight: d.cfg.MaxTranscodeHeight,
+		FFmpegVersion:      d.cfg.FFmpegVersion,
+		FFmpegPath:         d.cfg.FFmpegPath,
+		HWEncoders:         d.cfg.HWEncoders,
+		HWDevices:          d.cfg.HWDevices,
 		VPNActive:          d.vpnActive,
 		VPNMode:            d.vpnMode,
 		VPNServer:          d.vpnServer,
+		FunnelURL:          d.funnelURL,
 	}
 	if free, total, err := DiskInfo(d.cfg.DownloadDir); err == nil {
 		req.DiskFreeBytes = free
@@ -162,6 +191,7 @@ func (d *Daemon) Register(ctx context.Context) error {
 		VPNActive:   d.vpnActive,
 		VPNMode:     d.vpnMode,
 		VPNServer:   d.vpnServer,
+		FunnelURL:   d.funnelURL,
 	}
 	WriteState(&d.State)
 
@@ -210,16 +240,22 @@ func (d *Daemon) Run(ctx context.Context) error {
 			d.OnStreamRequested(req)
 		}
 	}
-	d.sync.OnWebRTCSession = func(sess WebRTCSession) {
+	d.sync.OnStreamSession = func(sess StreamSession) {
-		if d.OnWebRTCSession != nil {
+		if d.OnStreamSession != nil {
-			d.OnWebRTCSession(sess)
+			d.OnStreamSession(sess)
 		}
 	}
 	d.sync.OnUpgrade = func(version string) {
-		if version != d.lastNotifiedVersion {
+		if version == d.lastNotifiedVersion {
-			d.lastNotifiedVersion = version
+			return
-			log.Printf("New version available: %s (run `unarr self-update` to upgrade)", version)
 		}
+		d.lastNotifiedVersion = version
+		if !d.cfg.AutoUpgrade {
+			log.Printf("[upgrade] new version available: %s — auto_upgrade=false, run `unarr update` to apply", version)
+			return
+		}
+		log.Printf("[upgrade] new version available: %s — applying auto-upgrade", version)
+		go d.applyAutoUpgrade(version)
 	}
 	d.sync.OnScan = func() {
 		log.Printf("Library scan requested by server")
@@ -234,6 +270,9 @@ func (d *Daemon) Run(ctx context.Context) error {
 	d.sync.GetVPNState = func() (bool, string, string) {
 		return d.vpnActive, d.vpnMode, d.vpnServer
 	}
+	d.sync.GetFunnelURL = func() string {
+		return d.funnelURL
+	}
 	d.sync.OnSyncSuccess = func() {
 		d.State.LastHeartbeat = time.Now()
 		if d.GetActiveCount != nil {
@@ -263,6 +302,67 @@ func (d *Daemon) Deregister() {
 	RemoveState()
 }
 
+// applyAutoUpgrade downloads the target version and exits so the service
+// supervisor (systemd Restart=always on Linux) respawns on the new binary.
+// Triggered by the server's upgrade signal — opt-in flag set by the user from
+// the web UI; the daemon never auto-upgrades on a passive version bump.
+//
+// Reports the outcome to /api/internal/agent/upgrade-result so the server
+// clears `upgrade_requested`. Without this report the flag stays sticky and
+// the daemon would loop on every sync — including the no-op case where it's
+// already on the target version.
+func (d *Daemon) applyAutoUpgrade(targetVersion string) {
+	currentClean := strings.TrimPrefix(d.cfg.Version, "v")
+	targetClean := strings.TrimPrefix(targetVersion, "v")
+
+	// No-op: server signal arrived but we're already running the target. This
+	// happens when the daemon restarts after a previous auto-upgrade before
+	// reportUpgradeResult cleared the flag, or when the operator manually
+	// installed the same version off-band. Skip Execute (which would also
+	// no-op) AND skip os.Exit, but DO clear the flag — otherwise we loop.
+	if currentClean == targetClean {
+		log.Printf("[upgrade] already on v%s — clearing server flag", currentClean)
+		ctxR, cancelR := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancelR()
+		if err := d.client.ReportUpgradeResult(ctxR, d.cfg.AgentID, true, currentClean, ""); err != nil {
+			log.Printf("[upgrade] report-result failed (will retry on next signal): %v", err)
+		}
+		return
+	}
+
+	upgrader := &upgrade.Upgrader{
+		CurrentVersion: currentClean,
+		OnProgress: func(msg string) {
+			log.Printf("[upgrade] %s", msg)
+		},
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
+	defer cancel()
+	result := upgrader.Execute(ctx, targetVersion)
+	if !result.Success {
+		log.Printf("[upgrade] auto-upgrade failed: %v", result.Error)
+		errMsg := ""
+		if result.Error != nil {
+			errMsg = result.Error.Error()
+		}
+		ctxR, cancelR := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancelR()
+		if err := d.client.ReportUpgradeResult(ctxR, d.cfg.AgentID, false, targetClean, errMsg); err != nil {
+			log.Printf("[upgrade] report-result failed: %v", err)
+		}
+		return
+	}
+	log.Printf("[upgrade] upgraded v%s → v%s; reporting result + exiting so service supervisor restarts on new binary",
+		result.OldVersion, result.NewVersion)
+	ctxR, cancelR := context.WithTimeout(context.Background(), 10*time.Second)
+	if err := d.client.ReportUpgradeResult(ctxR, d.cfg.AgentID, true, result.NewVersion, ""); err != nil {
+		log.Printf("[upgrade] report-result failed: %v", err)
+	}
+	cancelR()
+	time.Sleep(500 * time.Millisecond)
+	os.Exit(0)
+}
+
 // isTransientError returns true for errors worth retrying (429, 5xx, network).
 func isTransientError(err error) bool {
 	if err == nil {

internal/agent/signal_client.go

@@ -1,258 +0,0 @@
-package agent
-
-import (
-	"bufio"
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-)
-
-// SignalRole identifies who produced a signalling message. The opposite role
-// receives it.
-type SignalRole string
-
-const (
-	SignalRoleBrowser SignalRole = "browser"
-	SignalRoleAgent   SignalRole = "agent"
-)
-
-// SignalMessageType matches the server-side z.enum on
-// /api/internal/stream/signal/[sessionId] route.
-type SignalMessageType string
-
-const (
-	SignalMsgOffer        SignalMessageType = "offer"
-	SignalMsgAnswer       SignalMessageType = "answer"
-	SignalMsgCandidate    SignalMessageType = "candidate"
-	SignalMsgCandidateEnd SignalMessageType = "candidate-end"
-	SignalMsgBye          SignalMessageType = "bye"
-)
-
-// SignalMessage mirrors the bus envelope on the web side.
-type SignalMessage struct {
-	From    SignalRole        `json:"from"`
-	Type    SignalMessageType `json:"type"`
-	Payload string            `json:"payload"`
-	TS      int64             `json:"ts"`
-}
-
-// PostSignal enqueues a signalling message produced by this agent. The
-// browser receives it on its next SSE event push.
-func (c *Client) PostSignal(ctx context.Context, sessionID string, msg SignalMessage) error {
-	body := map[string]any{
-		"from":    string(SignalRoleAgent),
-		"type":    string(msg.Type),
-		"payload": msg.Payload,
-	}
-	path := fmt.Sprintf("/api/internal/stream/signal/%s", sessionID)
-	return c.doPost(ctx, path, body, &struct {
-		OK bool `json:"ok"`
-	}{})
-}
-
-// SignalEventStream wraps an open SSE connection. Read messages from Events()
-// until the channel closes (server timeout or context cancel). Always defer
-// Close() to release the underlying response body.
-type SignalEventStream struct {
-	resp   *http.Response
-	cancel context.CancelFunc
-	events chan SignalMessage
-	errs   chan error
-	done   chan struct{}
-}
-
-// Events streams browser-produced messages addressed to the agent.
-// The channel closes when the SSE connection ends; the caller should then
-// call Close() and reopen if it wants to keep listening.
-func (s *SignalEventStream) Events() <-chan SignalMessage { return s.events }
-
-// Err returns the terminating error (if any) once Events() has closed.
-func (s *SignalEventStream) Err() error {
-	select {
-	case err := <-s.errs:
-		return err
-	default:
-		return nil
-	}
-}
-
-// Close cancels the underlying HTTP request and waits for the reader goroutine
-// to drain. Safe to call more than once.
-func (s *SignalEventStream) Close() error {
-	if s.cancel != nil {
-		s.cancel()
-	}
-	if s.resp != nil {
-		s.resp.Body.Close()
-	}
-	<-s.done
-	return nil
-}
-
-// OpenSignalStream opens a long-lived SSE connection to the signal events
-// endpoint. Caller MUST cancel ctx (or call Close()) to free resources.
-//
-// The server caps each response at ~25 s; OpenSignalStream surfaces the
-// disconnect by closing the events channel. Caller should reopen until the
-// session ends.
-func (c *Client) OpenSignalStream(ctx context.Context, sessionID string) (*SignalEventStream, error) {
-	streamCtx, cancel := context.WithCancel(ctx)
-
-	url := fmt.Sprintf("%s/api/internal/stream/signal/%s/events", c.baseURL(), sessionID)
-	req, err := http.NewRequestWithContext(streamCtx, http.MethodGet, url, nil)
-	if err != nil {
-		cancel()
-		return nil, fmt.Errorf("open signal stream: %w", err)
-	}
-	req.Header.Set("Accept", "text/event-stream")
-	req.Header.Set("Authorization", "Bearer "+c.apiKey)
-	req.Header.Set("User-Agent", c.userAgent)
-	req.Header.Set("Cache-Control", "no-cache")
-
-	// Use a per-call client with no timeout (SSE connections are long).
-	sseClient := &http.Client{}
-	resp, err := sseClient.Do(req)
-	if err != nil {
-		cancel()
-		return nil, fmt.Errorf("open signal stream: %w", err)
-	}
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
-		resp.Body.Close()
-		cancel()
-		return nil, fmt.Errorf("open signal stream: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
-	}
-
-	stream := &SignalEventStream{
-		resp:   resp,
-		cancel: cancel,
-		events: make(chan SignalMessage, 8),
-		errs:   make(chan error, 1),
-		done:   make(chan struct{}),
-	}
-
-	go stream.read()
-	return stream, nil
-}
-
-// sseMaxLineBytes caps the size of a single SSE line. Real signalling lines
-// are JSON payloads of a few hundred bytes; 256 KiB is generous enough to
-// survive a future schema bump but small enough that a hostile or buggy
-// server cannot grow daemon memory by streaming a single line forever.
-const sseMaxLineBytes = 256 * 1024
-
-// sseMaxEventBytes caps the total bytes buffered across the lines of one
-// SSE event. Without a cap, a peer could send unbounded `data:` continuation
-// lines and OOM the daemon between blank-line dispatches.
-const sseMaxEventBytes = 1024 * 1024
-
-func (s *SignalEventStream) read() {
-	defer close(s.done)
-	defer close(s.events)
-
-	scanner := bufio.NewScanner(s.resp.Body)
-	scanner.Buffer(make([]byte, 16*1024), sseMaxLineBytes)
-
-	var dataBuf bytes.Buffer
-	var eventName string
-
-	for scanner.Scan() {
-		line := strings.TrimRight(scanner.Text(), "\r")
-		if line == "" {
-			// End of an event — dispatch if we have data.
-			if dataBuf.Len() == 0 {
-				eventName = ""
-				continue
-			}
-			if eventName == "" || eventName == "signal" {
-				var msg SignalMessage
-				if err := json.Unmarshal(dataBuf.Bytes(), &msg); err == nil {
-					select {
-					case s.events <- msg:
-					case <-s.resp.Request.Context().Done():
-						return
-					}
-				}
-			}
-			dataBuf.Reset()
-			eventName = ""
-			continue
-		}
-		if strings.HasPrefix(line, ":") {
-			// SSE comment (heartbeat); ignore.
-			continue
-		}
-		if strings.HasPrefix(line, "event:") {
-			eventName = strings.TrimSpace(line[len("event:"):])
-			continue
-		}
-		if strings.HasPrefix(line, "data:") {
-			payload := strings.TrimSpace(line[len("data:"):])
-			// Refuse to grow the event buffer past the cap. Reset so a
-			// well-formed event after the offender can still be parsed,
-			// and surface an error so SignalLoop reconnects.
-			if dataBuf.Len()+len(payload)+1 > sseMaxEventBytes {
-				dataBuf.Reset()
-				eventName = ""
-				select {
-				case s.errs <- fmt.Errorf("sse: event exceeded %d bytes", sseMaxEventBytes):
-				default:
-				}
-				return
-			}
-			if dataBuf.Len() > 0 {
-				dataBuf.WriteByte('\n')
-			}
-			dataBuf.WriteString(payload)
-			continue
-		}
-		// id:, retry:, anything else — ignore for now.
-	}
-	if err := scanner.Err(); err != nil {
-		select {
-		case s.errs <- err:
-		default:
-		}
-	}
-}
-
-// SignalLoop runs an SSE consumer that reconnects automatically on disconnect.
-// onMessage is called for every browser-produced message. Returns when ctx is
-// cancelled. Reconnect backoff is fixed at 1 s — the server already paces
-// reconnects with `retry: 1500` headers so churn is bounded.
-func (c *Client) SignalLoop(ctx context.Context, sessionID string, onMessage func(SignalMessage)) error {
-	for ctx.Err() == nil {
-		stream, err := c.OpenSignalStream(ctx, sessionID)
-		if err != nil {
-			select {
-			case <-time.After(time.Second):
-			case <-ctx.Done():
-				return ctx.Err()
-			}
-			continue
-		}
-		for msg := range stream.Events() {
-			onMessage(msg)
-		}
-		streamErr := stream.Err()
-		stream.Close()
-		if ctx.Err() != nil {
-			return ctx.Err()
-		}
-		// Server closes the SSE every ~25 s; reconnect immediately.
-		// Hard error → small backoff so we don't hammer.
-		if streamErr != nil {
-			select {
-			case <-time.After(time.Second):
-			case <-ctx.Done():
-				return ctx.Err()
-			}
-		}
-	}
-	return ctx.Err()
-}

internal/agent/signal_client_test.go

@@ -1,196 +0,0 @@
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-)
-
-// fakeSSEServer streams a fixed set of SSE events then closes the connection.
-func fakeSSEServer(t *testing.T, msgs []SignalMessage, holdOpenAfter bool) *httptest.Server {
-	t.Helper()
-	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Header.Get("Authorization") != "Bearer test-key" {
-			http.Error(w, "auth", http.StatusUnauthorized)
-			return
-		}
-		w.Header().Set("Content-Type", "text/event-stream")
-		w.Header().Set("Cache-Control", "no-cache")
-		flusher, ok := w.(http.Flusher)
-		if !ok {
-			t.Fatal("server: ResponseWriter is not a Flusher")
-		}
-		fmt.Fprint(w, "retry: 1500\n\n")
-		flusher.Flush()
-		for _, m := range msgs {
-			data, _ := json.Marshal(m)
-			fmt.Fprintf(w, "id: %d\nevent: signal\ndata: %s\n\n", m.TS, data)
-			flusher.Flush()
-		}
-		// Send a heartbeat comment to verify it's ignored.
-		fmt.Fprint(w, ": heartbeat\n\n")
-		flusher.Flush()
-		if holdOpenAfter {
-			// Hold the connection until the client disconnects so the test can
-			// exercise stream.Close().
-			<-r.Context().Done()
-		}
-	}))
-}
-
-func TestSignalStreamReadsMessages(t *testing.T) {
-	want := []SignalMessage{
-		{From: SignalRoleBrowser, Type: SignalMsgOffer, Payload: "{sdp:1}", TS: 1},
-		{From: SignalRoleBrowser, Type: SignalMsgCandidate, Payload: "{cand:1}", TS: 2},
-	}
-	srv := fakeSSEServer(t, want, false)
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "test-key", "test-ua")
-	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
-	defer cancel()
-
-	stream, err := c.OpenSignalStream(ctx, "session-1")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	defer stream.Close()
-
-	var got []SignalMessage
-	for m := range stream.Events() {
-		got = append(got, m)
-		if len(got) == len(want) {
-			break
-		}
-	}
-	if len(got) != len(want) {
-		t.Fatalf("got %d messages, want %d", len(got), len(want))
-	}
-	for i, m := range got {
-		if m.From != want[i].From || m.Type != want[i].Type || m.Payload != want[i].Payload {
-			t.Errorf("[%d] mismatch: %+v want %+v", i, m, want[i])
-		}
-	}
-}
-
-func TestSignalStreamPropagatesAuthError(t *testing.T) {
-	srv := fakeSSEServer(t, nil, false)
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "wrong-key", "test-ua")
-	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
-	defer cancel()
-
-	_, err := c.OpenSignalStream(ctx, "session-1")
-	if err == nil {
-		t.Fatal("expected auth error, got nil")
-	}
-}
-
-func TestSignalStreamCloseCancelsRead(t *testing.T) {
-	srv := fakeSSEServer(t, nil, true)
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "test-key", "test-ua")
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-
-	stream, err := c.OpenSignalStream(ctx, "session-1")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-
-	// Close on a separate goroutine then make sure the events channel drains.
-	var wg sync.WaitGroup
-	wg.Add(1)
-	go func() {
-		defer wg.Done()
-		time.Sleep(50 * time.Millisecond)
-		stream.Close()
-	}()
-
-	for range stream.Events() {
-		// drain
-	}
-	wg.Wait()
-}
-
-// TestSignalStreamRejectsOversizedEvent verifies that a hostile or buggy
-// server sending an unbounded `data:` event surfaces an error and stops
-// the reader instead of growing daemon memory forever.
-func TestSignalStreamRejectsOversizedEvent(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Header.Get("Authorization") != "Bearer test-key" {
-			http.Error(w, "auth", http.StatusUnauthorized)
-			return
-		}
-		w.Header().Set("Content-Type", "text/event-stream")
-		flusher := w.(http.Flusher)
-		// Send many data: continuation lines until we blow past the
-		// per-event cap. Each chunk is a short legitimate-looking line.
-		chunk := "data: " + strings.Repeat("x", 4096) + "\n"
-		fmt.Fprint(w, "event: signal\n")
-		for i := 0; i < (sseMaxEventBytes/4096)+8; i++ {
-			fmt.Fprint(w, chunk)
-		}
-		flusher.Flush()
-		<-r.Context().Done()
-	}))
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "test-key", "test-ua")
-	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
-	defer cancel()
-
-	stream, err := c.OpenSignalStream(ctx, "session-overflow")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	defer stream.Close()
-
-	for range stream.Events() {
-		// Should never receive a parsed event — the over-sized buffer must
-		// be rejected before dispatch.
-	}
-	if err := stream.Err(); err == nil {
-		t.Fatal("expected error from oversized event, got nil")
-	}
-}
-
-func TestPostSignalSendsCorrectBody(t *testing.T) {
-	var bodySeen map[string]any
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Header.Get("Authorization") != "Bearer test-key" {
-			http.Error(w, "auth", http.StatusUnauthorized)
-			return
-		}
-		_ = json.NewDecoder(r.Body).Decode(&bodySeen)
-		w.Header().Set("Content-Type", "application/json")
-		fmt.Fprint(w, `{"ok":true}`)
-	}))
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "test-key", "test-ua")
-	err := c.PostSignal(context.Background(), "sess-x", SignalMessage{
-		Type:    SignalMsgAnswer,
-		Payload: "{sdp:answer}",
-	})
-	if err != nil {
-		t.Fatalf("post: %v", err)
-	}
-	if bodySeen["from"] != string(SignalRoleAgent) {
-		t.Errorf("expected from=agent, got %v", bodySeen["from"])
-	}
-	if bodySeen["type"] != string(SignalMsgAnswer) {
-		t.Errorf("expected type=answer, got %v", bodySeen["type"])
-	}
-	if bodySeen["payload"] != "{sdp:answer}" {
-		t.Errorf("expected payload mismatch, got %v", bodySeen["payload"])
-	}
-}

internal/agent/state.go

@@ -2,6 +2,8 @@ package agent
 
 import (
 	"encoding/json"
+	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"time"
@@ -9,6 +11,13 @@ import (
 	"github.com/torrentclaw/unarr/internal/config"
 )
 
+// ErrDaemonNotRunning is returned when no daemon state file exists on disk.
+// Callers may wrap it with %w; downstream code uses errors.Is to detect it.
+// NOTE: the message text is matched by the sentry package (string-match, to
+// avoid an import cycle). Keep the prefix "daemon does not appear to be
+// running" stable, or update sentry.daemonNotRunningMarker accordingly.
+var ErrDaemonNotRunning = errors.New("daemon does not appear to be running (state file not found)")
+
 // DaemonState is written to disk every heartbeat for external tools to read.
 type DaemonState struct {
 	AgentID         string         `json:"agentId"`
@@ -29,6 +38,11 @@ type DaemonState struct {
 	VPNActive bool   `json:"vpnActive,omitempty"`
 	VPNMode   string `json:"vpnMode,omitempty"`   // managed | self-hosted
 	VPNServer string `json:"vpnServer,omitempty"` // WireGuard endpoint (ip:port)
+
+	// CloudFlare Quick Tunnel state, so `unarr funnel status` can report the
+	// HTTPS hostname the daemon is reachable at from anywhere on the internet.
+	// Empty when the funnel is off or hasn't registered yet.
+	FunnelURL string `json:"funnelUrl,omitempty"`
 }
 
 // stateFilePathFn is overridable for testing.
@@ -64,17 +78,31 @@ func WriteState(state *DaemonState) {
 	os.Rename(tmp, path)
 }
 
-// ReadState reads the daemon state from disk. Returns nil if not found.
+// ReadState reads the daemon state from disk. Returns nil if not found or
+// unreadable. Use LoadState when callers need to distinguish "not running"
+// from "state file corrupted".
 func ReadState() *DaemonState {
+	state, _ := LoadState()
+	return state
+}
+
+// LoadState reads the daemon state and returns explicit errors:
+//   - ErrDaemonNotRunning when the state file does not exist
+//   - a wrapped json error when the file exists but cannot be decoded
+//     (a real bug worth reporting to Sentry)
+func LoadState() (*DaemonState, error) {
 	data, err := os.ReadFile(StateFilePath())
 	if err != nil {
-		return nil
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, ErrDaemonNotRunning
+		}
+		return nil, err
 	}
 	var state DaemonState
-	if json.Unmarshal(data, &state) != nil {
+	if err := json.Unmarshal(data, &state); err != nil {
-		return nil
+		return nil, fmt.Errorf("decode daemon state %s: %w", StateFilePath(), err)
 	}
-	return &state
+	return &state, nil
 }
 
 // RemoveState deletes the state file (called on clean shutdown).

internal/agent/state_test.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"errors"
 	"os"
 	"path/filepath"
 	"testing"
@@ -104,3 +105,39 @@ func TestReadStateCorruptedJSON(t *testing.T) {
 		t.Errorf("ReadState() should return nil for corrupted JSON, got %+v", state)
 	}
 }
+
+func TestLoadStateNotFound(t *testing.T) {
+	tmpDir := t.TempDir()
+	origFn := stateFilePathFn
+	stateFilePathFn = func() string { return filepath.Join(tmpDir, "nonexistent.json") }
+	defer func() { stateFilePathFn = origFn }()
+
+	state, err := LoadState()
+	if state != nil {
+		t.Errorf("LoadState() state = %+v, want nil", state)
+	}
+	if !errors.Is(err, ErrDaemonNotRunning) {
+		t.Errorf("LoadState() err = %v, want ErrDaemonNotRunning", err)
+	}
+}
+
+func TestLoadStateCorruptedJSON(t *testing.T) {
+	tmpDir := t.TempDir()
+	origFn := stateFilePathFn
+	path := filepath.Join(tmpDir, "daemon.state.json")
+	stateFilePathFn = func() string { return path }
+	defer func() { stateFilePathFn = origFn }()
+
+	os.WriteFile(path, []byte("not valid json{{{"), 0o644)
+
+	state, err := LoadState()
+	if state != nil {
+		t.Errorf("LoadState() state = %+v, want nil", state)
+	}
+	if err == nil {
+		t.Fatal("LoadState() err = nil, want decode error")
+	}
+	if errors.Is(err, ErrDaemonNotRunning) {
+		t.Error("corrupt state must not be reported as ErrDaemonNotRunning — it would be filtered from Sentry")
+	}
+}

internal/agent/sync.go

@@ -29,7 +29,7 @@ type SyncClient struct {
 	OnNewTasks       func(tasks []Task)
 	OnControl        func(action, taskID string, deleteFiles bool)
 	OnStreamRequest  func(req StreamRequest)
-	OnWebRTCSession  func(sess WebRTCSession)
+	OnStreamSession  func(sess StreamSession)
 	OnUpgrade        func(version string)
 	OnScan           func()
 	OnWatchingChange func(watching bool)
@@ -40,6 +40,9 @@ type SyncClient struct {
 	// WireGuard tunnel is up, the mode, and the exit server) so the web can track
 	// which agent holds the single WG slot.
 	GetVPNState func() (active bool, mode, server string)
+	// GetFunnelURL returns the CloudFlare Quick Tunnel public hostname if one
+	// is active, else "". Sent on every sync so the web picks it up live.
+	GetFunnelURL func() string
 	// OnDeleteFiles is called when the server requests file deletion from disk.
 	// It should delete the files and return the IDs of successfully deleted items.
 	OnDeleteFiles func(items []LibraryDeleteRequest) []int
@@ -162,6 +165,9 @@ func (sc *SyncClient) buildRequest() SyncRequest {
 	if sc.GetVPNState != nil {
 		req.VPNActive, req.VPNMode, req.VPNServer = sc.GetVPNState()
 	}
+	if sc.GetFunnelURL != nil {
+		req.FunnelURL = sc.GetFunnelURL()
+	}
 	// Flush confirmed deletions from previous cycle.
 	// Once flushed, remove IDs from deleteInFlight — the server will stop sending
 	// them after this sync, so deduplication protection is no longer needed.
@@ -199,10 +205,10 @@ func (sc *SyncClient) processResponse(resp *SyncResponse) {
 		}
 	}
 
-	// WebRTC streaming sessions
+	// HLS streaming sessions.
-	for _, ws := range resp.WebRTCSessions {
+	for _, ws := range resp.StreamSessions {
-		if sc.OnWebRTCSession != nil {
+		if sc.OnStreamSession != nil {
-			sc.OnWebRTCSession(ws)
+			sc.OnStreamSession(ws)
 		}
 	}
 

internal/agent/types.go

@@ -26,6 +26,15 @@ type RegisterRequest struct {
 	// up to 2160p.
 	HWAccel            string `json:"hwAccel,omitempty"`
 	MaxTranscodeHeight int    `json:"maxTranscodeHeight,omitempty"`
+	// Diagnostic surface filled by engine.DetectHWAccelDiagnostic at daemon
+	// start. Surfaced in the web "Diagnose transcoder" modal so users can
+	// see *why* their HWAccel landed on "none" without running
+	// `unarr probe-hwaccel` locally — most commonly the ffmpeg binary
+	// shipped without HW encoders (linuxbrew, brew's default formula).
+	FFmpegVersion string   `json:"ffmpegVersion,omitempty"`
+	FFmpegPath    string   `json:"ffmpegPath,omitempty"`
+	HWEncoders    []string `json:"hwEncoders,omitempty"`
+	HWDevices     []string `json:"hwDevices,omitempty"`
 	// Managed-VPN split-tunnel state. The web tracks which agent holds the single
 	// WireGuard slot (1 VPNResellers account = 1 WG keypair = 1 concurrent
 	// connection); other agents are told to use OpenVPN on their host instead.
@@ -34,6 +43,9 @@ type RegisterRequest struct {
 	VPNActive bool   `json:"vpnActive"`
 	VPNMode   string `json:"vpnMode,omitempty"` // managed | self-hosted
 	VPNServer string `json:"vpnServer,omitempty"`
+	// CloudFlare Quick Tunnel hostname when enabled; the web prefers it over
+	// Tailscale/LAN for in-browser playback because it works on any network.
+	FunnelURL string `json:"funnelUrl,omitempty"`
 }
 
 // RegisterResponse is returned by the server after registration.
@@ -359,6 +371,8 @@ type SyncRequest struct {
 	VPNActive bool   `json:"vpnActive"`
 	VPNMode   string `json:"vpnMode,omitempty"`
 	VPNServer string `json:"vpnServer,omitempty"`
+	// CloudFlare Quick Tunnel hostname when enabled, else empty.
+	FunnelURL string `json:"funnelUrl,omitempty"`
 }
 
 // ControlAction represents a server-side control signal for a task.
@@ -374,29 +388,22 @@ type LibraryDeleteRequest struct {
 	FilePath string `json:"filePath"`
 }
 
-// WebRTCSession is a request to open a streaming session for a browser
+// StreamSession is a request to open an HLS streaming session for an
-// player. Transport selects the on-the-wire protocol: empty/"webrtc" runs the
+// in-browser player. The CLI registers the HLS session in the StreamServer's
-// legacy custom WebRTC DataChannel pipeline; "hls" spawns an HLS session
+// HLS registry; source bytes come from FilePath (or, when only InfoHash is
-// (ffmpeg producing fragmented MP4 served over HTTP). The CLI must POST an
+// set, from a download_task on disk).
-// SDP answer to /api/internal/stream/signal/<sessionId> for WebRTC sessions
+type StreamSession struct {
-// and register the HLS session in the StreamServer's HLS registry for HLS
+	SessionID  string `json:"sessionId"`
-// sessions; either way the source bytes come from FilePath (or, when only
+	FilePath   string `json:"filePath,omitempty"`
-// InfoHash is set, from a download_task on disk).
+	InfoHash   string `json:"infoHash,omitempty"`
-type WebRTCSession struct {
+	TaskID     string `json:"taskId,omitempty"`
-	SessionID string `json:"sessionId"`
+	FileName   string `json:"fileName,omitempty"`
-	// Transport selects the streaming protocol. "" or "webrtc" → legacy
+	FileSize   int64  `json:"fileSize,omitempty"`
-	// WebRTC + MSE pipeline (Phase 1). "hls" → HLS over HTTP (Phase 2).
-	Transport string `json:"transport,omitempty"`
-	FilePath  string `json:"filePath,omitempty"`
-	InfoHash  string `json:"infoHash,omitempty"`
-	TaskID    string `json:"taskId,omitempty"`
-	FileName  string `json:"fileName,omitempty"`
-	FileSize  int64  `json:"fileSize,omitempty"`
 	// Quality target the daemon should aim for when transcoding. One of
 	// "2160p" | "1080p" | "720p" | "480p" | "original" | "" (defer to config).
 	Quality string `json:"quality,omitempty"`
 	// AudioIndex selects the source audio track (-map 0:a:N). -1 means
-	// "use the default/first track" (HLS) or ignored (WebRTC).
+	// "use the default/first track".
 	AudioIndex int `json:"audioIndex,omitempty"`
 }
 
@@ -405,7 +412,7 @@ type SyncResponse struct {
 	NewTasks       []Task                 `json:"newTasks,omitempty"`
 	Controls       []ControlAction        `json:"controls,omitempty"`
 	StreamRequests []StreamRequest        `json:"streamRequests,omitempty"`
-	WebRTCSessions []WebRTCSession        `json:"webrtcSessions,omitempty"`
+	StreamSessions []StreamSession        `json:"streamSessions,omitempty"`
 	Watching       bool                   `json:"watching"`
 	Upgrade        *UpgradeSignal         `json:"upgrade,omitempty"`
 	Scan           bool                   `json:"scan,omitempty"`

internal/cmd/daemon.go

@@ -17,6 +17,7 @@ import (
 	"github.com/torrentclaw/unarr/internal/agent"
 	"github.com/torrentclaw/unarr/internal/config"
 	"github.com/torrentclaw/unarr/internal/engine"
+	"github.com/torrentclaw/unarr/internal/funnel"
 	"github.com/torrentclaw/unarr/internal/library"
 	"github.com/torrentclaw/unarr/internal/library/mediainfo"
 	"github.com/torrentclaw/unarr/internal/usenet/download"
@@ -142,7 +143,19 @@ func runDaemonStart() error {
 	// is what the web side uses to decide whether the user should pre-empt
 	// transcoding by downloading a smaller version (4K source on a software
 	// libx264-only host is the canonical case where pre-download wins).
-	hwAccelPick := engine.DetectHWAccel(context.Background(), cfg.Library.FFmpegPath)
+	//
+	// Use the full diagnostic (encoders + devices + ffmpeg version) instead
+	// of just the picked backend — the extra fields ride along in the
+	// register payload so the web "Diagnose transcoder" modal can show *why*
+	// libx264 was selected on a host with a GPU (e.g. brew's ffmpeg without
+	// --enable-nvenc). 10 s ceiling so a hung ffmpeg binary can't stall
+	// startup forever.
+	ffmpegResolved, _ := mediainfo.ResolveFFmpeg(cfg.Library.FFmpegPath)
+	probeCtx, probeCancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer probeCancel() // guard against a panic inside DetectHWAccelDiagnostic
+	hwDiag := engine.DetectHWAccelDiagnostic(probeCtx, ffmpegResolved)
+	log.Println(hwDiag.LogLine())
+	hwAccelPick := hwDiag.Pick
 	maxTranscodeHeight := 1080
 	if hwAccelPick != engine.HWAccelNone {
 		maxTranscodeHeight = 2160
@@ -161,6 +174,11 @@ func runDaemonStart() error {
 		ScanPaths:          library.ResolveScanPaths(cfg.Download.Dir, cfg.Organize.MoviesDir, cfg.Organize.TVShowsDir, cfg.Library.ScanPath),
 		HWAccel:            string(hwAccelPick),
 		MaxTranscodeHeight: maxTranscodeHeight,
+		FFmpegVersion:      hwDiag.FFmpegVersion,
+		FFmpegPath:         hwDiag.FFmpegPath,
+		HWEncoders:         hwDiag.Encoders,
+		HWDevices:          hwDiag.Devices,
+		AutoUpgrade:        cfg.Daemon.AutoUpgradeEnabled(),
 	}
 
 	// Create HTTP client with mirror failover so a `.com` block-out rolls
@@ -255,9 +273,6 @@ func runDaemonStart() error {
 		MaxUploadRate:   maxUl,
 		ListenPort:      cfg.Download.ListenPort,
 		SeedEnabled:     false,
-		WebRTCEnabled:   cfg.Download.WebRTC.Enabled,
-		WebRTCTrackers:  cfg.Download.WebRTC.Trackers,
-		ICEServers:      engine.BuildICEServers(cfg.Download.WebRTC),
 		VPNTunnel:       vpnTunnel,
 	})
 	if err != nil {
@@ -294,18 +309,61 @@ func runDaemonStart() error {
 	// Create persistent stream server
 	streamSrv := engine.NewStreamServer(cfg.Download.StreamPort)
 	streamSrv.SetUPnPEnabled(cfg.Download.EnableUPnP)
-	streamSrv.SetCORSAllowedOrigins(cfg.Download.CORSExtraOrigins)
+	// CORS extras = operator config + dynamic mirror list from /api/mirrors.
+	// Without the mirror merge, a user playing from `torrentclaw.to` (or any
+	// future mirror) hits the daemon, gets 200 + body, but no
+	// `Access-Control-Allow-Origin` → browser drops the response → player
+	// reports "404 todos los canales". Fetching /api/mirrors at startup
+	// future-proofs against mirror additions without a CLI rebuild.
+	corsExtras := append([]string(nil), cfg.Download.CORSExtraOrigins...)
+	corsExtras = append(corsExtras, mirrorCORSOrigins(ctx, cfg, userAgent)...)
+	streamSrv.SetCORSAllowedOrigins(corsExtras)
 	// Reap HLS tmpdirs left over from a previous daemon run before we start
 	// accepting new sessions. The in-memory registry doesn't survive a
 	// restart, so without this disk usage grows unbounded across restarts.
 	if err := engine.CleanupHLSOrphanDirs(); err != nil {
 		log.Printf("[hls] orphan tmpdir cleanup: %v", err)
 	}
+
+	// Persistent HLS segment cache — survives across sessions so re-plays
+	// of the same file at the same quality skip ffmpeg entirely. Off when
+	// hls_cache.enabled = false; size cap from hls_cache.size_gb; path from
+	// hls_cache.dir (defaults to ~/.cache/unarr/hls-cache).
+	var hlsCache *engine.HLSCache
+	if cfg.Download.HLSCache.Enabled {
+		cacheDir := cfg.Download.HLSCache.Dir
+		if cacheDir == "" {
+			if base, err := os.UserCacheDir(); err == nil {
+				cacheDir = filepath.Join(base, "unarr", "hls-cache")
+			} else {
+				cacheDir = filepath.Join(os.TempDir(), "unarr-hls-cache")
+			}
+		}
+		c, err := engine.NewHLSCache(cacheDir, cfg.Download.HLSCache.SizeGB)
+		if err != nil {
+			log.Printf("[hls_cache] init failed (%v) — falling back to per-session tmpdirs", err)
+		} else {
+			hlsCache = c
+			hlsCache.StartSweeper(ctx, time.Hour)
+			log.Printf("[hls_cache] enabled: dir=%s budget=%dGB", cacheDir, cfg.Download.HLSCache.SizeGB)
+		}
+	} else {
+		log.Printf("[hls_cache] disabled by config — every play re-encodes from scratch")
+	}
 	if err := streamSrv.Listen(ctx); err != nil {
 		return fmt.Errorf("start stream server: %w", err)
 	}
 	d.UpdateStreamPort(streamSrv.Port())
 
+	// CloudFlare Quick Tunnel — needs the ACTUAL listening port (the
+	// configured port may have been busy and bumped). Spawning here ensures
+	// cloudflared --url points at the right socket. Failures degrade to
+	// Tailscale/LAN only; the supervisor keeps the tunnel up across CF's
+	// periodic rotation + transient cloudflared crashes.
+	if cfg.Download.Funnel.Enabled {
+		go superviseFunnel(ctx, d, streamSrv.Port())
+	}
+
 	// Warn at startup if transcode is enabled but ffmpeg/ffprobe are missing.
 	// HLS sessions get rejected at runtime (see daemon.go ~line 455), but
 	// surfacing it here gives the operator a chance to install ffmpeg before
@@ -330,13 +388,7 @@ func runDaemonStart() error {
 	// Wire: sync receives new tasks → submit to manager or handle stream
 	d.OnTasksClaimed = func(tasks []agent.Task) {
 		for _, t := range tasks {
-			if t.Mode == "seed_file" {
+			if t.Mode == "stream" {
-				// Browser asked us to wrap an arbitrary on-disk file as
-				// a single-file torrent + seed it via WebRTC. Runs in
-				// its own goroutine so a slow / failing seed can't
-				// stall the rest of the claim batch.
-				go handleSeedFileTask(t, torrentDl, agentClient)
-			} else if t.Mode == "stream" {
 				if isStreamingTask(t.ID) {
 					continue
 				}
@@ -497,23 +549,23 @@ func runDaemonStart() error {
 		}()
 	}
 
-	// Wire: sync receives custom WebRTC streaming session requests.
+	// Wire: sync receives HLS streaming session requests. Each session spawns
-	// Each session is a one-shot browser↔daemon DataChannel. Validate the
+	// one ffmpeg process and registers its HLS playlist with the StreamServer.
-	// FilePath against allowed dirs to prevent path traversal abuse from a
+	// Validate FilePath against allowed dirs to prevent path traversal abuse
-	// compromised server, then spawn the pion peer in its own goroutine.
+	// from a compromised server.
-	d.OnWebRTCSession = func(sess agent.WebRTCSession) {
+	d.OnStreamSession = func(sess agent.StreamSession) {
-		if webrtcRegistry.has(sess.SessionID) {
+		if playerSessionRegistry.has(sess.SessionID) {
 			return // already running
 		}
 		filePath := sess.FilePath
 		if filePath == "" {
-			log.Printf("webrtc session %s rejected: empty file path", agent.ShortID(sess.SessionID))
+			log.Printf("[hls %s] rejected: empty file path", agent.ShortID(sess.SessionID))
 			return
 		}
 		filePath = filepath.Clean(filePath)
 		if !isAllowedStreamPath(filePath, cfg.Download.Dir, cfg.Library.ScanPath,
 			cfg.Organize.MoviesDir, cfg.Organize.TVShowsDir) {
-			log.Printf("webrtc session %s rejected: path outside allowed dirs: %s",
+			log.Printf("[hls %s] rejected: path outside allowed dirs: %s",
 				agent.ShortID(sess.SessionID), filePath)
 			return
 		}
@@ -521,74 +573,50 @@ func runDaemonStart() error {
 		if info, err := os.Stat(filePath); err == nil && info.IsDir() {
 			found := engine.FindVideoFile(filePath)
 			if found == "" {
-				log.Printf("webrtc session %s rejected: no video file in dir %s",
+				log.Printf("[hls %s] rejected: no video file in dir %s",
 					agent.ShortID(sess.SessionID), filePath)
 				return
 			}
 			filePath = found
 		}
 
-		// Branch on transport: HLS sessions only need ffmpeg + StreamServer,
+		tcRuntime := buildTranscodeRuntime(ctx, cfg)
-		// not a WebRTC peer, so they must bypass the WebRTC.Enabled gate.
+		if tcRuntime.FFmpegPath == "" || tcRuntime.FFprobePath == "" {
-		// Default ("" or "webrtc") runs the DataChannel pipeline and requires it.
+			log.Printf("[hls %s] rejected: ffmpeg/ffprobe unavailable", agent.ShortID(sess.SessionID))
-		if strings.EqualFold(sess.Transport, "hls") {
+			return
-			tcRuntime := buildTranscodeRuntime(ctx, cfg)
+		}
-			if tcRuntime.FFmpegPath == "" || tcRuntime.FFprobePath == "" {
+		hlsCtx, hlsCancel := context.WithCancel(ctx)
-				log.Printf("[hls %s] rejected: ffmpeg/ffprobe unavailable", agent.ShortID(sess.SessionID))
+		playerSessionRegistry.add(sess.SessionID, hlsCancel)
-				return
+		hlsCfg := engine.HLSSessionConfig{
-			}
+			SessionID:  sess.SessionID,
-			hlsCtx, hlsCancel := context.WithCancel(ctx)
+			SourcePath: filePath,
-			webrtcRegistry.add(sess.SessionID, hlsCancel)
+			FileName:   sess.FileName,
-			hlsCfg := engine.HLSSessionConfig{
+			Quality:    sess.Quality,
-				SessionID:  sess.SessionID,
+			AudioIndex: sess.AudioIndex,
-				SourcePath: filePath,
+			Transcode:  tcRuntime,
-				FileName:   sess.FileName,
+			Cache:      hlsCache,
-				Quality:    sess.Quality,
+		}
-				AudioIndex: sess.AudioIndex,
+		// StartHLSSession runs ffprobe (15 s cap, typical 0.3–1 s) before
-				Transcode:  tcRuntime,
+		// returning. Doing this synchronously inside the sync handler holds
-			}
+		// the next sync HTTP cycle until ffprobe is done, so any other
+		// pending actions (new tasks, deletes) wait too. Hand it off so
+		// the sync loop returns immediately — browser HEAD probes already
+		// have a 30 s retry budget that absorbs the gap until
+		// `streamSrv.HLS().Register` lands.
+		go func() {
 			hsess, err := engine.StartHLSSession(hlsCtx, hlsCfg)
 			if err != nil {
-				webrtcRegistry.remove(sess.SessionID)
+				playerSessionRegistry.remove(sess.SessionID)
 				hlsCancel()
 				log.Printf("[hls %s] start failed: %v", agent.ShortID(sess.SessionID), err)
 				return
 			}
 			streamSrv.HLS().Register(hsess)
-			return
+			// Tell the server seg-0 is on disk as soon as it lands so the
-		}
+			// player's SSE subscription flips its "Preparando…" UI without
-
+			// waiting for the browser HEAD-probe loop to discover it
-		// Non-HLS transport requires WebRTC peer support.
+			// independently. Cache-HIT sessions are ready immediately.
-		if !cfg.Download.WebRTC.Enabled {
+			go watchSessionReady(hlsCtx, agentClient, hsess, sess.SessionID)
-			log.Printf("webrtc session %s rejected: webrtc disabled in config", agent.ShortID(sess.SessionID))
-			return
-		}
-
-		sessCtx, sessCancel := context.WithCancel(ctx) //nolint:gosec // G118 cancel stored in registry
-		webrtcRegistry.add(sess.SessionID, sessCancel)
-		go func() {
-			defer func() {
-				webrtcRegistry.remove(sess.SessionID)
-				sessCancel()
-			}()
-			tcRuntime := buildTranscodeRuntime(ctx, cfg)
-			runCfg := engine.WebRTCStreamConfig{
-				SessionID:  sess.SessionID,
-				FilePath:   filePath,
-				FileName:   sess.FileName,
-				FileSize:   sess.FileSize,
-				Quality:    sess.Quality,
-				ICEServers: engine.BuildICEServers(cfg.Download.WebRTC),
-				Signal:     agentClient,
-				Logger:     stdLogger{},
-				Transcode:  tcRuntime,
-			}
-			log.Printf("[wrtc %s] starting session: %s", agent.ShortID(sess.SessionID), filepath.Base(filePath))
-			if err := engine.RunWebRTCStream(sessCtx, runCfg); err != nil {
-				if sessCtx.Err() == nil {
-					log.Printf("[wrtc %s] ended: %v", agent.ShortID(sess.SessionID), err)
-				}
-			}
 		}()
 	}
 
@@ -658,7 +686,7 @@ func runDaemonStart() error {
 	case sig := <-sigCh:
 		fmt.Printf("\n  Received %s, shutting down...\n", sig)
 		cancelStreamContexts()
-		cancelAllWebRTCSessions()
+		cancelAllPlayerSessions()
 		streamSrv.Shutdown(context.Background())
 		cancel()
 
@@ -673,7 +701,7 @@ func runDaemonStart() error {
 
 	case err := <-errCh:
 		cancelStreamContexts()
-		cancelAllWebRTCSessions()
+		cancelAllPlayerSessions()
 		streamSrv.Shutdown(context.Background())
 		cancel()
 		return err
@@ -821,3 +849,144 @@ func runAutoScan(ctx context.Context, cfg config.Config, interval time.Duration,
 		}
 	}
 }
+
+// superviseFunnel keeps a CloudFlare Quick Tunnel up across cloudflared
+// crashes and CF's ~6h tunnel rotation. On a clean exit (cancellation) it
+// returns; on a crash it clears the reported URL and respawns with an
+// exponential backoff so we don't hammer cloudflared into a tight loop when
+// it can't reach the CF edge.
+func superviseFunnel(ctx context.Context, d *agent.Daemon, port int) {
+	backoff := 2 * time.Second
+	const maxBackoff = 5 * time.Minute
+	for ctx.Err() == nil {
+		t, err := funnel.Start(ctx, funnel.Config{Port: port})
+		if err != nil {
+			log.Printf("[funnel] could not start CloudFlare tunnel (%v) — retrying in %s", err, backoff)
+			select {
+			case <-time.After(backoff):
+			case <-ctx.Done():
+				return
+			}
+			backoff = min(backoff*2, maxBackoff)
+			continue
+		}
+		log.Printf("[funnel] cloudflared started, waiting for public URL...")
+		go func() {
+			url, werr := t.WaitURL(45 * time.Second)
+			if werr != nil {
+				log.Printf("[funnel] cloudflared did not emit a URL (%v)", werr)
+				return
+			}
+			log.Printf("[funnel] public URL: %s", url)
+			d.SetFunnelURL(url)
+		}()
+		// Block until cloudflared exits (CF rotation, crash, or shutdown).
+		exitErr := <-t.Done()
+		_ = t.Close()
+		d.SetFunnelURL("")
+		if ctx.Err() != nil {
+			return
+		}
+		if exitErr != nil {
+			log.Printf("[funnel] cloudflared exited: %v — restarting in %s", exitErr, backoff)
+		} else {
+			log.Printf("[funnel] cloudflared exited cleanly — restarting in %s", backoff)
+		}
+		select {
+		case <-time.After(backoff):
+		case <-ctx.Done():
+			return
+		}
+		backoff = min(backoff*2, maxBackoff)
+	}
+}
+
+// mirrorCORSOrigins fetches /api/mirrors from the configured primary (+ extra
+// mirror candidates + static IPFS fallback) and returns the discovered URLs as
+// Origin strings. Best-effort: any failure logs a warning and returns an empty
+// slice; the static defaultCORSAllowedOrigins in validate.go covers the known
+// mirrors (.com / .to / built-in onion) so the daemon still accepts the
+// official surfaces when this call fails.
+//
+// Bounded to a short timeout so a slow /api/mirrors response can't delay
+// daemon startup — every second here is a second the user can't play.
+func mirrorCORSOrigins(parent context.Context, cfg config.Config, userAgent string) []string {
+	ctx, cancel := context.WithTimeout(parent, 10*time.Second)
+	defer cancel()
+
+	candidates := append([]string{cfg.Auth.APIURL}, cfg.Auth.Mirrors...)
+	resp, err := agent.FetchMirrorsWithFallback(ctx, candidates, userAgent)
+	if err != nil {
+		log.Printf("[cors] mirror discovery failed (%v) — using static allowlist only", err)
+		return nil
+	}
+
+	seen := make(map[string]struct{})
+	out := make([]string, 0, len(resp.Mirrors))
+	add := func(rawURL string) {
+		if rawURL == "" {
+			return
+		}
+		origin := strings.TrimRight(rawURL, "/")
+		if _, dup := seen[origin]; dup {
+			return
+		}
+		seen[origin] = struct{}{}
+		out = append(out, origin)
+	}
+	for _, m := range resp.Mirrors {
+		add(m.URL)
+	}
+	if resp.Tor != nil {
+		add(resp.Tor.URL)
+	}
+	if len(out) > 0 {
+		log.Printf("[cors] merged %d mirror origins from /api/mirrors", len(out))
+	}
+	return out
+}
+
+// watchSessionReady polls HLSSession.ReadyCount until the first segment +
+// init.mp4 are on disk, then POSTs /api/internal/agent/session-ready so
+// the web side flips streaming_session.ready_at — which its SSE endpoint
+// pushes to subscribed players. Cache-HIT sessions are ready the moment
+// StartHLSSession returns and POST immediately.
+//
+// Bounded by a 60 s deadline so a permanently stuck encoder doesn't keep
+// a goroutine alive forever; if seg-0 never lands the player falls back
+// to its existing HEAD-probe retry path anyway.
+func watchSessionReady(ctx context.Context, client *agent.Client, hsess *engine.HLSSession, sessionID string) {
+	deadline := time.Now().Add(60 * time.Second)
+	ticker := time.NewTicker(200 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		// Session torn down through a path that didn't cancel ctx (registry
+		// replace, idle sweep, internal kill). Bail before polling further —
+		// without this check the watcher could keep alive for up to 60 s on
+		// a dead HLSSession that's never going to become ready.
+		if hsess.IsClosed() {
+			return
+		}
+		// Cache HIT or seg-0 ready → notify + done.
+		if hsess.FromCache() || hsess.ReadyCount() >= 1 {
+			// Parent ctx so a session cancel mid-POST (user closed tab,
+			// daemon shutdown) tears down the in-flight webhook instead of
+			// blocking the goroutine for up to 10 s on a now-orphan call.
+			rctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+			if err := client.MarkSessionReady(rctx, sessionID); err != nil {
+				log.Printf("[hls %s] mark-ready failed: %v", agent.ShortID(sessionID), err)
+			}
+			cancel()
+			return
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+		if time.Now().After(deadline) {
+			log.Printf("[hls %s] mark-ready: timeout waiting for seg-0", agent.ShortID(sessionID))
+			return
+		}
+	}
+}

internal/cmd/daemon_control.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"os"
 	"os/exec"
@@ -262,9 +263,12 @@ func runDaemonReload() error {
 // stopDaemonByPID reads the state file and sends a graceful stop to the daemon PID.
 // Used as fallback on platforms without a service manager (and as Windows implementation).
 func stopDaemonByPID() error {
-	state := agent.ReadState()
+	state, err := agent.LoadState()
-	if state == nil {
+	if err != nil {
-		return fmt.Errorf("daemon does not appear to be running (state file not found)")
+		if errors.Is(err, agent.ErrDaemonNotRunning) {
+			return err
+		}
+		return fmt.Errorf("read daemon state: %w", err)
 	}
 	return killPID(state.PID)
 }

internal/cmd/download.go

@@ -114,9 +114,6 @@ func runDownloadWithDeps(input, method string, deps downloadDeps) error {
 		StallTimeout:    10 * time.Minute,
 		MaxTimeout:      0, // unlimited
 		SeedEnabled:     false,
-		WebRTCEnabled:   cfg.Download.WebRTC.Enabled,
-		WebRTCTrackers:  cfg.Download.WebRTC.Trackers,
-		ICEServers:      engine.BuildICEServers(cfg.Download.WebRTC),
 	})
 	if err != nil {
 		return fmt.Errorf("create downloader: %w", err)

internal/cmd/funnel.go

@@ -0,0 +1,165 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+func newFunnelCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "funnel",
+		Short: "Expose the daemon over a public HTTPS hostname via CloudFlare Quick Tunnel",
+		Long: `Turn the CloudFlare Quick Tunnel on/off and check its status.
+
+When on, the daemon spawns cloudflared as a child process and registers a
+` + "`https://<random>.trycloudflare.com`" + ` hostname tunnelled to its local
+HLS server. The torrentclaw.com / torrentclaw.to web player picks the tunnel
+URL first so cross-network playback works from any browser without Tailscale
+or port forwarding.
+
+Trade-offs:
+  • Bytes proxy through CloudFlare. We don't relay; CF does. Preserves the
+    TorrentClaw legal posture but means CF sees your traffic shape.
+  • Quick Tunnels are anonymous — no CF account required.
+  • Hostname is random per session and rotates roughly every 6 h.
+
+Requires the cloudflared binary on PATH. Install:
+  Linux  : https://pkg.cloudflare.com (apt) or download from
+           https://github.com/cloudflare/cloudflared/releases
+  macOS  : brew install cloudflared
+  Windows: winget install --id Cloudflare.cloudflared`,
+		Example: `  unarr funnel status   # is the tunnel up? what's the URL?
+  unarr funnel on       # turn it on
+  unarr funnel off      # turn it off`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Help()
+		},
+	}
+	cmd.AddCommand(newFunnelStatusCmd(), newFunnelOnCmd(), newFunnelOffCmd())
+	return cmd
+}
+
+func newFunnelStatusCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "status",
+		Short:   "Show CloudFlare tunnel configuration + live URL",
+		Example: "  unarr funnel status",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runFunnelStatus()
+		},
+	}
+}
+
+func runFunnelStatus() error {
+	bold := color.New(color.Bold)
+	dim := color.New(color.FgHiBlack)
+	green := color.New(color.FgGreen)
+	yellow := color.New(color.FgYellow)
+	cyan := color.New(color.FgCyan)
+
+	cfg := loadConfig()
+
+	fmt.Println()
+	bold.Println("  CloudFlare Quick Tunnel")
+	fmt.Println()
+
+	if !cfg.Download.Funnel.Enabled {
+		dim.Println("  Mode:    off")
+		fmt.Println()
+		dim.Println("  Enable with `unarr funnel on` to give the daemon a public HTTPS URL")
+		dim.Println("  so cross-network browser playback works without Tailscale.")
+		fmt.Println()
+		return nil
+	}
+	cyan.Println("  Mode:    on")
+
+	state := agent.ReadState()
+	alive := state != nil && isDaemonAlive(state)
+	fmt.Println()
+	switch {
+	case alive && state.FunnelURL != "":
+		green.Println("  ✓ Tunnel ACTIVE")
+		fmt.Printf("    URL:  %s\n", state.FunnelURL)
+		fmt.Println()
+		dim.Println("  This URL rotates roughly every 6 h. The web player picks it up")
+		dim.Println("  automatically — no action needed on your side.")
+	case alive:
+		yellow.Println("  ⚠  Daemon is running but the tunnel hasn't registered yet.")
+		dim.Println("     Check `unarr daemon logs` for a [funnel] line. Common cause:")
+		dim.Println("     cloudflared isn't installed on PATH.")
+	default:
+		dim.Println("  Daemon not running — start it (`unarr start`) to bring the tunnel up.")
+	}
+	fmt.Println()
+	return nil
+}
+
+func newFunnelOnCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "on",
+		Short:   "Turn the CloudFlare tunnel on",
+		Example: "  unarr funnel on",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return setFunnelEnabled(true)
+		},
+	}
+}
+
+func newFunnelOffCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "off",
+		Short:   "Turn the CloudFlare tunnel off",
+		Example: "  unarr funnel off",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return setFunnelEnabled(false)
+		},
+	}
+}
+
+func setFunnelEnabled(enabled bool) error {
+	green := color.New(color.FgGreen)
+	dim := color.New(color.FgHiBlack)
+
+	cfg := loadConfig()
+	if cfg.Download.Funnel.Enabled == enabled {
+		fmt.Println()
+		dim.Printf("  Tunnel is already %s — nothing to do.\n", onOffWord(enabled))
+		fmt.Println()
+		return nil
+	}
+
+	cfg.Download.Funnel.Enabled = enabled
+
+	configPath := config.FilePath()
+	if cfgFile != "" {
+		configPath = cfgFile
+	}
+	if err := config.Save(cfg, configPath); err != nil {
+		return fmt.Errorf("save config: %w", err)
+	}
+	appCfg = cfg
+
+	fmt.Println()
+	green.Printf("  ✓ CloudFlare tunnel %s.\n", onOffWord(enabled))
+
+	// Subprocess is launched/torn down by the daemon at startup; a plain config
+	// reload does not bring it up. Prompt for a restart when the daemon is alive.
+	if state := agent.ReadState(); state != nil && isDaemonAlive(state) {
+		fmt.Println()
+		dim.Println("  The daemon is running. Restart it for this to take effect:")
+		dim.Println("    unarr daemon restart")
+	}
+	fmt.Println()
+	return nil
+}
+
+func onOffWord(enabled bool) string {
+	if enabled {
+		return "on"
+	}
+	return "off"
+}

internal/cmd/player_session_registry.go

@@ -2,7 +2,6 @@ package cmd
 
 import (
 	"context"
-	"log"
 	"sync"
 
 	"github.com/torrentclaw/unarr/internal/config"
@@ -10,66 +9,57 @@ import (
 	"github.com/torrentclaw/unarr/internal/library/mediainfo"
 )
 
-// webrtcRegistry tracks per-session cancel funcs for active custom WebRTC
+// playerSessionRegistry tracks per-session cancel funcs for active in-browser
-// streams (engine.RunWebRTCStream goroutines). Each session lives only as
+// HLS streaming sessions. Each session lives only as long as its ffmpeg
-// long as its DataChannel; the registry exists so duplicate sync responses
+// process; the registry exists so duplicate sync responses don't double-spawn
-// don't double-spawn the same session and so daemon shutdown can drain.
+// the same session and so daemon shutdown can drain.
-var webrtcRegistry = &webrtcSessionRegistry{
+var playerSessionRegistry = &playerSessionRegistryT{
 	cancels: make(map[string]context.CancelFunc),
 }
 
-type webrtcSessionRegistry struct {
+type playerSessionRegistryT struct {
 	mu      sync.Mutex
 	cancels map[string]context.CancelFunc
 }
 
-func (r *webrtcSessionRegistry) has(sessionID string) bool {
+func (r *playerSessionRegistryT) has(sessionID string) bool {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	_, ok := r.cancels[sessionID]
 	return ok
 }
 
-func (r *webrtcSessionRegistry) add(sessionID string, cancel context.CancelFunc) {
+func (r *playerSessionRegistryT) add(sessionID string, cancel context.CancelFunc) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	r.cancels[sessionID] = cancel
 }
 
-func (r *webrtcSessionRegistry) remove(sessionID string) {
+func (r *playerSessionRegistryT) remove(sessionID string) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	delete(r.cancels, sessionID)
 }
 
-// cancelAllWebRTCSessions cancels every running session. Called on daemon
+// cancelAllPlayerSessions cancels every running session. Called on daemon
-// shutdown so pion peers and SSE consumers exit cleanly.
+// shutdown so the ffmpeg children and SSE consumers exit cleanly.
-func cancelAllWebRTCSessions() {
+func cancelAllPlayerSessions() {
-	webrtcRegistry.mu.Lock()
+	playerSessionRegistry.mu.Lock()
-	cancels := make([]context.CancelFunc, 0, len(webrtcRegistry.cancels))
+	cancels := make([]context.CancelFunc, 0, len(playerSessionRegistry.cancels))
-	for _, c := range webrtcRegistry.cancels {
+	for _, c := range playerSessionRegistry.cancels {
 		cancels = append(cancels, c)
 	}
-	webrtcRegistry.cancels = make(map[string]context.CancelFunc)
+	playerSessionRegistry.cancels = make(map[string]context.CancelFunc)
-	webrtcRegistry.mu.Unlock()
+	playerSessionRegistry.mu.Unlock()
 	for _, c := range cancels {
 		c()
 	}
 }
 
-// stdLogger is a tiny adapter so engine.RunWebRTCStream can log through the
-// standard library logger without pulling in a logging dependency.
-type stdLogger struct{}
-
-func (stdLogger) Infof(format string, args ...any)  { log.Printf(format, args...) }
-func (stdLogger) Warnf(format string, args ...any)  { log.Printf("WARN: "+format, args...) }
-func (stdLogger) Errorf(format string, args ...any) { log.Printf("ERROR: "+format, args...) }
-
 // buildTranscodeRuntime resolves the ffmpeg/ffprobe binaries + config knobs
-// for the WebRTC streaming pipeline. Failure to resolve a binary returns a
+// for the HLS streaming pipeline. Failure to resolve a binary returns a
-// runtime with empty paths so engine.RunWebRTCStream falls back to
+// runtime with empty paths so the caller can short-circuit instead of
-// passthrough — the user gets a clearer codec error from the browser than a
+// launching a transcoder that will immediately fail.
-// daemon-side abort.
 func buildTranscodeRuntime(ctx context.Context, cfg config.Config) engine.TranscodeRuntime {
 	if !cfg.Download.Transcode.Enabled {
 		return engine.TranscodeRuntime{Disabled: true}

internal/cmd/probe_hwaccel.go

@@ -15,7 +15,7 @@ import (
 )
 
 // newProbeHWAccelCmd reports the hardware-acceleration capabilities the daemon
-// would actually use for HLS/WebRTC transcoding. The motivation: a beefy host
+// would actually use for HLS transcoding. The motivation: a beefy host
 // (e.g. RTX 3090) can still fall back to software encoding when the installed
 // ffmpeg binary was built without nvenc/qsv/vaapi support — Homebrew ffmpeg
 // is a common offender. Without this command, users see slow / failing 4K

internal/cmd/reload_unix.go

@@ -3,6 +3,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"log"
 	"os"
@@ -43,9 +44,12 @@ func startReloadWatcher(rc *ReloadableConfig) {
 
 // sendReloadSignal sends SIGUSR1 to the running daemon process.
 func sendReloadSignal() error {
-	state := agent.ReadState()
+	state, err := agent.LoadState()
-	if state == nil {
+	if err != nil {
-		return fmt.Errorf("daemon does not appear to be running (state file not found)")
+		if errors.Is(err, agent.ErrDaemonNotRunning) {
+			return err
+		}
+		return fmt.Errorf("read daemon state: %w", err)
 	}
 	p, err := os.FindProcess(state.PID)
 	if err != nil {

internal/cmd/root.go

@@ -25,16 +25,20 @@ var (
 
 func init() {
 	rootCmd = &cobra.Command{
-		Use:   "unarr",
+		Use:     "unarr",
-		Short: "unarr — torrent search and management",
+		Version: Version,
-		Long: `unarr is a powerful terminal tool for torrent search and management.
+		Short:   "Terminal torrent + debrid + usenet client — download, stream, transcode",
-
+		Long: `unarr is a terminal-native client that downloads torrents, debrid links,
-Search 30+ torrent sources, inspect torrent quality, discover popular content,
+and usenet (NZB) — all from the same binary. It streams content straight
-find streaming providers, and manage your media collection — all from your terminal.
+to mpv/vlc with sequential piece prioritization, transcodes on the fly via
+ffmpeg with hardware acceleration (NVENC, QSV, VA-API, VideoToolbox), and
+organizes your library into Movies/TV folders. Run it one-shot or as a
+long-running daemon with a built-in WireGuard split-tunnel and remote
+playback over Cloudflare Funnel.
 
 Get started:
   unarr init                           First-time configuration wizard
-  unarr search "breaking bad"          Search for content
+  unarr download <magnet|hash>         Grab a torrent one-shot
   unarr start                          Start the download daemon
 
 Documentation:  https://torrentclaw.com/cli
@@ -55,7 +59,7 @@ Source:         https://github.com/torrentclaw/unarr`,
 	// Command groups for organized help output
 	rootCmd.AddGroup(
 		&cobra.Group{ID: "start", Title: "Getting Started:"},
-		&cobra.Group{ID: "search", Title: "Search & Discovery:"},
+		&cobra.Group{ID: "search", Title: "Catalog & Discovery:"},
 		&cobra.Group{ID: "download", Title: "Downloads & Streaming:"},
 		&cobra.Group{ID: "daemon", Title: "Daemon Management:"},
 		&cobra.Group{ID: "system", Title: "System & Diagnostics:"},
@@ -105,6 +109,8 @@ Source:         https://github.com/torrentclaw/unarr`,
 	daemonCmd.GroupID = "daemon"
 	vpnCmd := newVPNCmd()
 	vpnCmd.GroupID = "daemon"
+	funnelCmd := newFunnelCmd()
+	funnelCmd.GroupID = "daemon"
 
 	// System & Diagnostics
 	statsCmd := newStatsCmd()
@@ -149,6 +155,7 @@ Source:         https://github.com/torrentclaw/unarr`,
 		statusCmd,
 		daemonCmd,
 		vpnCmd,
+		funnelCmd,
 		// System & Diagnostics
 		statsCmd,
 		doctorCmd,

internal/cmd/scan.go

@@ -241,7 +241,7 @@ func printScanSummary(cache *library.LibraryCache) {
 			continue
 		}
 
-		res := library.ResolveResolution(item.MediaInfo.Video.Height)
+		res := library.ResolveResolution(item.MediaInfo.Video.Width, item.MediaInfo.Video.Height)
 		if res == "" {
 			res = "other"
 		}

internal/cmd/seed_file_handler.go

@@ -1,65 +0,0 @@
-package cmd
-
-import (
-	"context"
-	"log"
-	"time"
-
-	"github.com/torrentclaw/unarr/internal/agent"
-	"github.com/torrentclaw/unarr/internal/engine"
-)
-
-// handleSeedFileTask wraps an arbitrary on-disk file as a single-file
-// torrent and adds it to the existing torrent client so the WebRTC
-// peer can serve pieces to a browser. Reports the generated info_hash
-// back to the server so the web player can target /stream/<hash>.
-//
-// Runs in its own goroutine; never blocks the claim batch.
-func handleSeedFileTask(t agent.Task, dl *engine.TorrentDownloader, client *agent.Client) {
-	short := agent.ShortID(t.ID)
-
-	if t.FilePath == "" {
-		log.Printf("[%s] seed_file: missing filePath, marking failed", short)
-		reportSeedFileFailed(client, t.ID, "Missing filePath")
-		return
-	}
-
-	log.Printf("[%s] seed_file: building torrent from %s", short, t.FilePath)
-	hash, err := engine.SeedFileOnDownloader(dl, t.FilePath)
-	if err != nil {
-		log.Printf("[%s] seed_file: %v", short, err)
-		reportSeedFileFailed(client, t.ID, err.Error())
-		return
-	}
-
-	infoHash := hash.HexString()
-	log.Printf("[%s] seed_file: seeding ih=%s", short, infoHash)
-
-	// Push the info_hash + downloading status (file is on disk; from the
-	// client's perspective it's already complete). The web side polls
-	// /api/internal/stream/seed-file/<taskId> waiting for this update.
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
-	_, reportErr := client.ReportStatus(ctx, agent.StatusUpdate{
-		TaskID:   t.ID,
-		Status:   "downloading", // semantic: actively serving
-		InfoHash: infoHash,
-		FilePath: t.FilePath,
-	})
-	if reportErr != nil {
-		log.Printf("[%s] seed_file: failed to push info_hash: %v", short, reportErr)
-	}
-}
-
-func reportSeedFileFailed(client *agent.Client, taskID, msg string) {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	_, err := client.ReportStatus(ctx, agent.StatusUpdate{
-		TaskID:       taskID,
-		Status:       "failed",
-		ErrorMessage: msg,
-	})
-	if err != nil {
-		log.Printf("[%s] seed_file: report-failed itself failed: %v", agent.ShortID(taskID), err)
-	}
-}

internal/cmd/version.go

@@ -1,4 +1,4 @@
 package cmd
 
 // Version is the CLI version. Overridden by goreleaser ldflags at release time.
-var Version = "0.9.3"
+var Version = "0.9.15"

internal/config/config.go

@@ -51,9 +51,30 @@ type DownloadConfig struct {
 	StreamPort       int             `toml:"stream_port"`        // fixed port for streaming HTTP server (default: 11818)
 	EnableUPnP       bool            `toml:"enable_upnp"`        // map StreamPort to the WAN via UPnP/NAT-PMP (default: false; opt-in because it exposes the unauthenticated /stream + /hls endpoints to the public internet)
 	CORSExtraOrigins []string        `toml:"cors_extra_origins"` // extra browser origins added on top of the baked-in allowlist (torrentclaw.com, app.torrentclaw.com, localhost:3030)
-	WebRTC           WebRTCConfig    `toml:"webrtc"`
 	Transcode        TranscodeConfig `toml:"transcode"`
+	HLSCache         HLSCacheConfig  `toml:"hls_cache"`
 	VPN              VPNConfig       `toml:"vpn"`
+	Funnel           FunnelConfig    `toml:"funnel"`
+}
+
+// HLSCacheConfig controls the persistent HLS segment cache. A completed encode
+// is kept on disk so a second play of the same file at the same quality skips
+// ffmpeg entirely. Old entries are evicted (LRU) once the cache exceeds the
+// size budget. Enabled by default — disable to save disk space at the cost of
+// re-encoding every play.
+type HLSCacheConfig struct {
+	Enabled bool   `toml:"enabled"`  // default: true
+	SizeGB  int    `toml:"size_gb"`  // size budget in gigabytes; default: 5; minimum: 1
+	Dir     string `toml:"dir"`      // override storage path; default: ~/.cache/unarr/hls-cache
+}
+
+// FunnelConfig gates the optional CloudFlare Quick Tunnel that exposes the
+// daemon's HLS server over a public HTTPS hostname (https://<random>.try
+// cloudflare.com). Enabling it lets the web player on torrentclaw.com play
+// from this daemon across any network without Tailscale or a public IP —
+// the cost is that bytes proxy through CloudFlare's network. Off by default.
+type FunnelConfig struct {
+	Enabled bool `toml:"enabled"`
 }
 
 // VPNConfig gates the managed-VPN add-on split-tunnel. When enabled, the daemon
@@ -75,28 +96,33 @@ type VPNConfig struct {
 // Disabled by default; enabling requires ffmpeg + ffprobe on PATH (or
 // explicit paths via the library config).
 type TranscodeConfig struct {
-	Enabled       bool   `toml:"enabled"`        // master switch
+	Enabled bool   `toml:"enabled"`  // master switch
-	HWAccel       string `toml:"hw_accel"`       // "auto" | "none" | "nvenc" | "qsv" | "vaapi" | "videotoolbox"
+	HWAccel string `toml:"hw_accel"` // "auto" | "none" | "nvenc" | "qsv" | "vaapi" | "videotoolbox"
-	Preset        string `toml:"preset"`         // libx264 preset; "veryfast" by default
+	// Preset is the encoder speed/quality dial. Only used on software encode
+	// (libx264) — HW backends (NVENC/QSV/VAAPI/VideoToolbox) use vendor
+	// presets that don't share libx264's vocabulary and would be rejected
+	// by ffmpeg if passed here.
+	//
+	// Empty (default) → engine picks "superfast" — latency-biased, ~3 s
+	// first-play on 1080p source on a modern x86 CPU. Marginal quality loss
+	// at 5-25 Mbps target bitrates.
+	//
+	// For better quality at slower first-play (1-2 s slower per seg):
+	//   "veryfast"  — previous default; balanced
+	//   "faster"    — slight quality bump
+	//   "fast"      — meaningful quality bump
+	//   "medium"    — libx264 stock default; CPU-bound on 4K
+	//   "slow" / "slower" / "veryslow" — only for batch encodes, not real-time HLS
+	//
+	// Or faster:
+	//   "ultrafast" — lowest quality, fastest encode
+	Preset        string `toml:"preset"`
 	VideoBitrate  string `toml:"video_bitrate"`  // e.g. "5M"
 	AudioBitrate  string `toml:"audio_bitrate"`  // e.g. "192k"
 	MaxHeight     int    `toml:"max_height"`     // optional downscale cap (e.g. 720)
 	MaxConcurrent int    `toml:"max_concurrent"` // safety cap on simultaneous transcoder processes
 }
 
-// WebRTCConfig opts the daemon into acting as a WebTorrent peer so browsers
-// can fetch pieces via WebRTC data channels — required by the in-browser
-// player on torrentclaw.com. Disabled by default; enabling implies upload
-// is allowed for active torrents (browsers can't download otherwise).
-type WebRTCConfig struct {
-	Enabled     bool     `toml:"enabled"`      // master switch
-	Trackers    []string `toml:"trackers"`     // wss:// signaling trackers
-	STUNServers []string `toml:"stun_servers"` // stun:host:port
-	TURNServers []string `toml:"turn_servers"` // turn:host:port (no auth) — see TURNCredentials for authed
-	TURNUser    string   `toml:"turn_user"`    // optional, applied to all TURNServers
-	TURNPass    string   `toml:"turn_pass"`    // optional
-}
-
 type OrganizeConfig struct {
 	Enabled    bool   `toml:"enabled"`
 	MoviesDir  string `toml:"movies_dir"`
@@ -105,8 +131,27 @@ type OrganizeConfig struct {
 
 type DaemonConfig struct {
 	StatusInterval string `toml:"status_interval"`
+	// AutoUpgrade gates the daemon's response to a server-flagged upgrade
+	// (set via the "Force update" button on the web). When true the daemon
+	// downloads + replaces the binary in-place and exits so the service
+	// supervisor respawns on the new version. When false the daemon only
+	// logs "new version available" and the operator must run `unarr update`
+	// manually. Default: true. Available since unarr 0.9.6.
+	AutoUpgrade *bool `toml:"auto_upgrade"`
 }
 
+// AutoUpgradeEnabled returns the resolved AutoUpgrade flag — defaults to true
+// when the user has not set it explicitly. Pointer-vs-bool because Go's
+// zero-value bool would collapse "unset" and "false" together.
+func (d DaemonConfig) AutoUpgradeEnabled() bool {
+	if d.AutoUpgrade == nil {
+		return true
+	}
+	return *d.AutoUpgrade
+}
+
+func boolPtr(v bool) *bool { return &v }
+
 type NotificationsConfig struct {
 	Enabled bool `toml:"enabled"`
 }
@@ -121,7 +166,7 @@ type LibraryConfig struct {
 	ScanPath     string `toml:"scan_path"`     // remembered from last scan
 	Workers      int    `toml:"workers"`       // concurrent ffprobe (default 8)
 	FFprobePath  string `toml:"ffprobe_path"`  // optional explicit path
-	FFmpegPath   string `toml:"ffmpeg_path"`   // optional explicit path (used by WebRTC streaming transcoder)
+	FFmpegPath   string `toml:"ffmpeg_path"`   // optional explicit path (used by the HLS streaming transcoder)
 	BackupDir    string `toml:"backup_dir"`    // for replaced files
 	AutoScan     bool   `toml:"auto_scan"`     // enable daily auto-scan in daemon (default true)
 	ScanInterval string `toml:"scan_interval"` // e.g. "24h", "12h", "6h" (default "24h")
@@ -146,23 +191,41 @@ func Default() Config {
 			PreferredMethod: "auto",
 			MaxConcurrent:   3,
 			StreamPort:      11818,
-			WebRTC: WebRTCConfig{
-				Enabled:     true,
-				Trackers:    []string{"wss://tracker.torrentclaw.com"},
-				STUNServers: []string{"stun:stun.l.google.com:19302", "stun:stun1.l.google.com:19302"},
-			},
 			Transcode: TranscodeConfig{
 				Enabled:       true,
 				HWAccel:       "auto",
-				Preset:        "veryfast",
+				// Empty preset → engine.ResolveEncoderProfile picks the
+				// latency-biased default ("superfast" on libx264). Override
+				// in config.toml when quality > first-start latency matters.
+				Preset:        "",
 				AudioBitrate:  "192k",
 				MaxConcurrent: 2,
 			},
+			Funnel: FunnelConfig{
+				// On by default so headless installs (NAS / Docker) get cross-network
+				// HTTPS playback without anyone having to terminal in. Users who
+				// don't want bytes proxied through CloudFlare can opt out with
+				// `unarr funnel off` (sets enabled=false in the TOML).
+				Enabled: true,
+			},
+			HLSCache: HLSCacheConfig{
+				// On by default — second play of a recently watched file at the
+				// same quality skips ffmpeg (instant start, near-zero CPU).
+				// Users can opt out (hls_cache.enabled=false) or shrink the
+				// budget (hls_cache.size_gb) when disk is tight.
+				Enabled: true,
+				SizeGB:  5,
+			},
+		},
+		Daemon: DaemonConfig{
+			// Pointer-to-true so Default() round-trips through TOML marshal
+			// as `auto_upgrade = true` instead of an omitted key — keeps the
+			// freshly-written config aligned with what README documents.
+			AutoUpgrade: boolPtr(true),
 		},
 		Organize: OrganizeConfig{
 			Enabled: true,
 		},
-		Daemon: DaemonConfig{},
 		Notifications: NotificationsConfig{
 			Enabled: true,
 		},
@@ -231,19 +294,6 @@ func applyDefaults(cfg *Config, meta toml.MetaData) {
 		cfg.General.Country = "US"
 	}
 
-	if !meta.IsDefined("downloads", "webrtc", "enabled") {
-		cfg.Download.WebRTC.Enabled = true
-	}
-	if !meta.IsDefined("downloads", "webrtc", "trackers") {
-		cfg.Download.WebRTC.Trackers = []string{"wss://tracker.torrentclaw.com"}
-	}
-	if !meta.IsDefined("downloads", "webrtc", "stun_servers") {
-		cfg.Download.WebRTC.STUNServers = []string{
-			"stun:stun.l.google.com:19302",
-			"stun:stun1.l.google.com:19302",
-		}
-	}
-
 	if !meta.IsDefined("downloads", "transcode", "enabled") {
 		cfg.Download.Transcode.Enabled = true
 	}
@@ -251,7 +301,12 @@ func applyDefaults(cfg *Config, meta toml.MetaData) {
 		cfg.Download.Transcode.HWAccel = "auto"
 	}
 	if !meta.IsDefined("downloads", "transcode", "preset") {
-		cfg.Download.Transcode.Preset = "veryfast"
+		// Empty = let engine.ResolveEncoderProfile pick the latency-biased
+		// default ("superfast" on libx264). Users wanting better quality at
+		// slower first-play can override to "veryfast" / "fast" / "medium" in
+		// config.toml. Ignored when hw_accel picks NVENC/QSV/VAAPI/VideoToolbox
+		// (those have built-in vendor presets).
+		cfg.Download.Transcode.Preset = ""
 	}
 	if !meta.IsDefined("downloads", "transcode", "audio_bitrate") {
 		cfg.Download.Transcode.AudioBitrate = "192k"
@@ -259,6 +314,12 @@ func applyDefaults(cfg *Config, meta toml.MetaData) {
 	if !meta.IsDefined("downloads", "transcode", "max_concurrent") {
 		cfg.Download.Transcode.MaxConcurrent = 2
 	}
+	// NOTE: Funnel default-ON only applies to fresh installs (no config file →
+	// Default() returns Funnel.Enabled=true straight off). When an existing
+	// config file lacks `[downloads.funnel]` entirely we intentionally do NOT
+	// flip it on here — that would silently route an upgraded operator's
+	// traffic through CloudFlare without their consent. They opt in with
+	// `unarr funnel on` whenever they're ready.
 }
 
 // Save writes config to the default or specified path using atomic write.

internal/config/config_test.go

@@ -208,17 +208,6 @@ name = "Test"
 		t.Fatalf("Load failed: %v", err)
 	}
 
-	// WebRTC should be on by default for fresh installs.
-	if !cfg.Download.WebRTC.Enabled {
-		t.Error("WebRTC.Enabled should default to true when [downloads.webrtc] is absent")
-	}
-	if len(cfg.Download.WebRTC.Trackers) == 0 {
-		t.Error("WebRTC.Trackers should default to torrentclaw tracker when absent")
-	}
-	if len(cfg.Download.WebRTC.STUNServers) == 0 {
-		t.Error("WebRTC.STUNServers should default to public STUN list when absent")
-	}
-
 	// Transcode should be on by default.
 	if !cfg.Download.Transcode.Enabled {
 		t.Error("Transcode.Enabled should default to true when [downloads.transcode] is absent")
@@ -226,8 +215,11 @@ name = "Test"
 	if cfg.Download.Transcode.HWAccel != "auto" {
 		t.Errorf("Transcode.HWAccel = %q, want auto", cfg.Download.Transcode.HWAccel)
 	}
-	if cfg.Download.Transcode.Preset != "veryfast" {
+	if cfg.Download.Transcode.Preset != "" {
-		t.Errorf("Transcode.Preset = %q, want veryfast", cfg.Download.Transcode.Preset)
+		// Default is now empty — engine.ResolveEncoderProfile picks
+		// "superfast" on libx264 for first-start latency. Users
+		// wanting better quality override in config.toml.
+		t.Errorf("Transcode.Preset = %q, want empty", cfg.Download.Transcode.Preset)
 	}
 	if cfg.Download.Transcode.MaxConcurrent != 2 {
 		t.Errorf("Transcode.MaxConcurrent = %d, want 2", cfg.Download.Transcode.MaxConcurrent)
@@ -238,12 +230,9 @@ func TestLoadRespectsExplicitlyDisabledStreaming(t *testing.T) {
 	tmp := t.TempDir()
 	path := filepath.Join(tmp, "config.toml")
 
-	// User explicitly opted out of webrtc + transcode. Defaults must NOT
+	// User explicitly opted out of transcode. Defaults must NOT override
-	// override them — that would silently re-enable features the user disabled.
+	// it — that would silently re-enable a feature the user disabled.
-	os.WriteFile(path, []byte(`[downloads.webrtc]
+	os.WriteFile(path, []byte(`[downloads.transcode]
-enabled = false
-
-[downloads.transcode]
 enabled = false
 `), 0o644)
 
@@ -252,9 +241,6 @@ enabled = false
 		t.Fatalf("Load failed: %v", err)
 	}
 
-	if cfg.Download.WebRTC.Enabled {
-		t.Error("WebRTC.Enabled = true, want false (user explicitly disabled)")
-	}
 	if cfg.Download.Transcode.Enabled {
 		t.Error("Transcode.Enabled = true, want false (user explicitly disabled)")
 	}

internal/engine/hls.go

@@ -3,9 +3,7 @@
 // Browser ↔ daemon over plain HTTP (LAN / Tailscale / UPnP). The daemon runs
 // ffmpeg in `-f hls` mode, writing fragmented MP4 segments to a per-session
 // tmpdir. Master + media playlists are pre-rendered from the probed source
-// duration so the player knows the full timeline before any segment exists,
+// duration so the player knows the full timeline before any segment exists.
-// which fixes the seek/duration/pause/multi-track problems we hit with the
-// raw fMP4-over-WebRTC pipeline.
 //
 // One HLSSession == one browser playback. Sessions are registered in a
 // process-wide map keyed by session ID; the StreamServer routes
@@ -34,10 +32,46 @@ import (
 	"time"
 )
 
-// hlsSegmentDuration is the target seconds per HLS fragment. Four seconds is
+// hlsSegmentDuration is the target seconds per HLS fragment.
-// the Plex/Apple default — short enough that seek granularity is acceptable,
+//
-// long enough that GOP overhead doesn't dominate.
+// We use 2 seconds (not the more common 4-6 s). Trade-off: 2× more segments
-const hlsSegmentDuration = 4
+// per source (a 2 h movie produces 3600 segments instead of 1800), but the
+// player's first-frame wait drops to ~half — ffmpeg only needs to encode
+// 2 s before seg-0 lands. For software encodes on 4K this is ~1 s instead
+// of ~3 s of cold-cache wait. Well within HLS spec (Apple recommends 6 s,
+// but 2-6 s is acceptable; Low-Latency HLS uses 1-2 s segments).
+//
+// Caveat for existing cached encodes: cache entries from 0.9.9 used 4 s
+// segments. After this bump, VerifyComplete (which checks the highest
+// expected segment index) returns false for those entries — they're
+// invalidated + re-encoded with 2 s segments on next play. Self-healing.
+const hlsSegmentDuration = 2
+
+// segmentDurationFor returns the target duration (in whole seconds) for the
+// segment at index idx. With uniform-duration segments this is always
+// hlsSegmentDuration; the helper exists so a future short-first-segment
+// variant can be slotted in here without touching every call site.
+func segmentDurationFor(idx int) int {
+	return hlsSegmentDuration
+}
+
+// segmentStartSec returns the wall-clock start time of segment idx. Used
+// to compute the `-ss` flag when ffmpeg restarts at a mid-file segment.
+func segmentStartSec(idx int) float64 {
+	if idx <= 0 {
+		return 0
+	}
+	return float64(idx * hlsSegmentDuration)
+}
+
+// segmentCountForDuration returns how many segments cover a source of the
+// given duration. Always returns at least 1.
+func segmentCountForDuration(dur float64) int {
+	if dur <= 0 {
+		return 1
+	}
+	return int((dur + float64(hlsSegmentDuration) - 1) / float64(hlsSegmentDuration))
+}
 
 // hlsSessionTTL is how long a session can sit idle (no segment requests)
 // before the manager kills ffmpeg + cleans the tmpdir.
@@ -102,6 +136,11 @@ type HLSSessionConfig struct {
 	Quality    string // "2160p"|"1080p"|"720p"|"480p"|"original"|""
 	AudioIndex int    // 0-based ffmpeg audio stream selection (-map 0:a:N). -1 = default.
 	Transcode  TranscodeRuntime
+	// Cache is an optional persistent segment cache keyed by (source, quality,
+	// audio). When set, completed encodes are kept across sessions so re-plays
+	// of the same file at the same quality skip ffmpeg entirely. nil disables
+	// caching (per-session tmpdir, deleted on Close — original behavior).
+	Cache *HLSCache
 }
 
 // HLSSession owns a tmpdir + ffmpeg subprocess producing HLS fragments.
@@ -133,14 +172,29 @@ type HLSSession struct {
 	restartCount   int // bounded auto-restart counter (resets on Close)
 	lastRestartAt  time.Time
 
-	// readyCond + readyMax track which segments ffmpeg has finished writing.
+	// readyCh + readyMax track how many segments ffmpeg has finished writing.
-	// Handlers waiting on a future segment block on readyCond until the
+	// readyMax is a COUNT (not an index): readyMax=N means seg-0 … seg-(N-1)
-	// poller advances readyMax past their index (or ffmpeg exits).
+	// are fully on disk. A handler waiting on `idx` blocks until
+	// `idx < readyMax` (segment idx is present). The pollSegments goroutine
+	// advances readyMax and re-creates readyCh on every step.
 	readyMu  sync.Mutex
-	readyMax int // highest segment index whose .m4s file is fully written
+	readyMax int
 	exitErr  error
 	exited   bool
 	readyCh  chan struct{} // closed + replaced each time readyMax advances
+
+	// Persistent cache state. cache==nil means caching disabled for this session.
+	// fromCache=true means the session is replaying a completed encode and no
+	// ffmpeg subprocess was spawned. writerLockHeld=true means this session
+	// owns the per-key TryAcquireWriter claim — Close must ReleaseWriter.
+	// subsDone closes when the subtitle extractor goroutine returns (or is
+	// nil when the source had no subtitle tracks); MarkComplete waits on it
+	// so a HIT replay never serves partial .vtt files.
+	cache          *HLSCache
+	cacheKey       string
+	fromCache      bool
+	writerLockHeld bool
+	subsDone       chan struct{}
 }
 
 // hlsSeekAhead is how many segments past the writer's current position the
@@ -265,18 +319,78 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 		return nil, errors.New("hls: source has no duration")
 	}
 
-	tmpDir := filepath.Join(hlsTmpDirRoot(), cfg.SessionID)
+	// Resolve tmpDir + cache placement. Three states:
+	//   1. cache disabled              → per-session tmpdir, deleted on Close.
+	//   2. cache HIT (.complete found) → read from cache dir, no ffmpeg, Pin.
+	//   3. cache MISS, writer-lock OK  → ffmpeg writes to cache dir, Pin + writer-lock.
+	//   4. cache MISS, writer-lock NO  → another session already writing this
+	//                                    key; fall back to private per-session tmpdir
+	//                                    (no caching for this session — second-writer
+	//                                    would corrupt the first one's segments).
+	var (
+		tmpDir         string
+		cacheKey       string
+		fromCache      bool
+		writerLockHeld bool
+	)
+	if cfg.Cache != nil {
+		cacheKey = cfg.Cache.KeyFor(cfg.SourcePath, cfg.Quality, cfg.AudioIndex)
+		// Integrity gate: HasComplete just stats the marker. If init.mp4 or
+		// the last segment vanished (external rm, partial-disk failure), we
+		// can't actually serve a HIT — drop the dir and re-encode.
+		segCountForVerify := segmentCountForDuration(probe.DurationSec)
+		if cfg.Cache.HasComplete(cacheKey) && !cfg.Cache.VerifyComplete(cacheKey, segCountForVerify) {
+			log.Printf("[hls %s] cache %s sealed but failed integrity check — re-encoding",
+				shortHLSID(cfg.SessionID), cacheKey)
+			_ = cfg.Cache.Invalidate(cacheKey)
+		}
+		if cfg.Cache.HasComplete(cacheKey) {
+			// HIT: read-only replay — many concurrent HITs are fine.
+			tmpDir = cfg.Cache.DirFor(cacheKey)
+			cfg.Cache.Pin(cacheKey)
+			fromCache = true
+			cfg.Cache.RecordHit()
+			_ = cfg.Cache.Touch(cacheKey)
+		} else if cfg.Cache.TryAcquireWriter(cacheKey) {
+			tmpDir = cfg.Cache.DirFor(cacheKey)
+			cfg.Cache.Pin(cacheKey)
+			writerLockHeld = true
+			cfg.Cache.RecordMiss()
+		} else {
+			// Another session is writing this key — fall back to private
+			// dir so we don't trample its segments.
+			log.Printf("[hls %s] cache key %s busy, falling back to per-session tmpdir",
+				shortHLSID(cfg.SessionID), cacheKey)
+			tmpDir = filepath.Join(hlsTmpDirRoot(), cfg.SessionID)
+			cacheKey = "" // disable caching for this session
+			cfg.Cache.RecordMiss()
+		}
+	} else {
+		tmpDir = filepath.Join(hlsTmpDirRoot(), cfg.SessionID)
+	}
+
+	cleanupOnError := func() {
+		if cfg.Cache != nil && cacheKey != "" {
+			cfg.Cache.Unpin(cacheKey)
+			if writerLockHeld {
+				cfg.Cache.ReleaseWriter(cacheKey)
+				_ = cfg.Cache.Invalidate(cacheKey)
+			}
+		} else {
+			_ = os.RemoveAll(tmpDir)
+		}
+	}
+
 	if err := os.MkdirAll(filepath.Join(tmpDir, "video"), 0o755); err != nil {
+		cleanupOnError()
 		return nil, fmt.Errorf("hls: mkdir video: %w", err)
 	}
 	if err := os.MkdirAll(filepath.Join(tmpDir, "subs"), 0o755); err != nil {
+		cleanupOnError()
 		return nil, fmt.Errorf("hls: mkdir subs: %w", err)
 	}
 
-	segCount := int((probe.DurationSec + float64(hlsSegmentDuration) - 1) / float64(hlsSegmentDuration))
+	segCount := segmentCountForDuration(probe.DurationSec)
-	if segCount < 1 {
-		segCount = 1
-	}
 
 	s := &HLSSession{
 		cfg:          cfg,
@@ -287,10 +401,30 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 		startedAt:    time.Now(),
 		lastTouch:    time.Now(),
 		readyCh:      make(chan struct{}),
+		cache:          cfg.Cache,
+		cacheKey:       cacheKey,
+		fromCache:      fromCache,
+		writerLockHeld: writerLockHeld,
 	}
 	s.manifestVideo = renderVideoPlaylist(probe.DurationSec, segCount)
 	s.manifestRoot = renderMasterPlaylist(probe, cfg.Quality)
 
+	// Cache HIT: every segment + init.mp4 is already on disk. Skip ffmpeg
+	// entirely and mark readyMax so handlers don't wait. Background subtitle
+	// extraction is also unnecessary — subs were extracted on the original run.
+	if fromCache {
+		s.readyMu.Lock()
+		s.readyMax = segCount - 1
+		s.exited = true
+		close(s.readyCh)
+		s.readyCh = nil
+		s.readyMu.Unlock()
+		log.Printf("[hls %s] cache HIT %s: %s, %.1fs, %d segs (quality=%s)",
+			shortHLSID(cfg.SessionID), cacheKey, filepath.Base(cfg.SourcePath),
+			probe.DurationSec, segCount, coalesce(cfg.Quality, "auto"))
+		return s, nil
+	}
+
 	// Spawn ffmpeg under a dedicated context so Close() can kill it without
 	// touching the parent ctx.
 	ffCtx, cancel := context.WithCancel(context.Background())
@@ -300,7 +434,7 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 	cmd.Stderr = &hlsStderrCapture{owner: s}
 	if err := cmd.Start(); err != nil {
 		cancel()
-		_ = os.RemoveAll(tmpDir)
+		cleanupOnError()
 		return nil, fmt.Errorf("hls: start ffmpeg: %w", err)
 	}
 	s.cmd = cmd
@@ -309,12 +443,30 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 	go s.pollSegments(ffCtx)
 
 	if len(probe.SubtitleTracks) > 0 {
-		go s.extractSubtitles(ffCtx)
+		s.subsDone = make(chan struct{})
+		go func() {
+			defer close(s.subsDone)
+			s.extractSubtitles(ffCtx)
+		}()
 	}
 
-	log.Printf("[hls %s] started: %s, %.1fs, %d segs (quality=%s)",
+	cachedNote := ""
+	if cfg.Cache != nil {
+		cachedNote = fmt.Sprintf(" (cache-miss %s)", cacheKey)
+	}
+	// Surface the encoder profile so a "first-start was slow" report can be
+	// triaged from the agent log alone — `encoder=libx264 accel=none` means
+	// the user's ffmpeg has no HW encoders compiled in, which is the most
+	// common root cause (linuxbrew, default brew formula on macOS).
+	profile := ResolveEncoderProfile(cfg.Transcode.HWAccel, cfg.Transcode.Preset)
+	presetNote := ""
+	if profile.Preset != "" {
+		presetNote = " preset=" + profile.Preset
+	}
+	log.Printf("[hls %s] started: %s, %.1fs, %d segs (quality=%s, encoder=%s accel=%s%s)%s",
 		shortHLSID(cfg.SessionID), filepath.Base(cfg.SourcePath),
-		probe.DurationSec, segCount, coalesce(cfg.Quality, "auto"))
+		probe.DurationSec, segCount, coalesce(cfg.Quality, "auto"),
+		profile.Codec, string(cfg.Transcode.HWAccel), presetNote, cachedNote)
 	return s, nil
 }
 
@@ -367,6 +519,28 @@ func (s *HLSSession) ProbeInfo() map[string]any {
 	}
 }
 
+// ReadyCount returns how many segments are currently fully on disk.
+// Caller can `>= 1` it to check whether seg-0 has landed (and so the
+// player can be told to attach). For cache-HIT sessions this is always
+// `segmentCount` from the moment StartHLSSession returns.
+func (s *HLSSession) ReadyCount() int {
+	s.readyMu.Lock()
+	defer s.readyMu.Unlock()
+	return s.readyMax
+}
+
+// FromCache reports whether this session was served from the HLS cache
+// (no ffmpeg subprocess spawned). Used by ready-watcher logic to short-
+// circuit polling — a cache HIT is ready the moment we return.
+func (s *HLSSession) FromCache() bool { return s.fromCache }
+
+// IsClosed reports whether Close() has been invoked. Exposed (vs the
+// internal isClosed) so external watchers — the ready-webhook
+// goroutine in cmd/daemon.go — can short-circuit polling on a session
+// that was torn down through a different code path (registry replace,
+// idle sweep) without racing on the unexported helper.
+func (s *HLSSession) IsClosed() bool { return s.isClosed() }
+
 // MasterPlaylist returns the rendered master.m3u8 contents.
 func (s *HLSSession) MasterPlaylist() string { return s.manifestRoot }
 
@@ -387,8 +561,15 @@ func (s *HLSSession) Touch() {
 	s.mu.Unlock()
 }
 
-// Close stops ffmpeg, deletes the tmpdir, and prevents further requests from
+// Close stops ffmpeg and prevents further requests from blocking on segment
-// blocking on segment readiness. Idempotent.
+// readiness. Idempotent.
+//
+// Disk lifecycle:
+//   - cache disabled → delete tmpDir (original behavior).
+//   - cache enabled + this session was a HIT → keep dir, just unpin.
+//   - cache enabled + this was a write session → if ffmpeg exited cleanly and
+//     every segment is on disk, persist with .complete and keep dir. Otherwise
+//     drop the dir so a half-written cache doesn't survive into the next play.
 func (s *HLSSession) Close() error {
 	s.mu.Lock()
 	if s.closed {
@@ -409,7 +590,47 @@ func (s *HLSSession) Close() error {
 		s.readyCh = nil
 	}
 	s.exited = true
+	exitErr := s.exitErr
 	s.readyMu.Unlock()
+
+	if s.cache != nil && s.cacheKey != "" {
+		defer s.cache.Unpin(s.cacheKey)
+		if s.writerLockHeld {
+			defer s.cache.ReleaseWriter(s.cacheKey)
+		}
+		if s.fromCache {
+			log.Printf("[hls %s] closed (cache reuse)", shortHLSID(s.cfg.SessionID))
+			return nil
+		}
+		// Wait briefly for the subtitle extractor to finish so a cached
+		// replay never serves half-written .vtt files. Bounded so a stuck
+		// extractor can't block Close indefinitely; on timeout we treat
+		// the cache as incomplete and drop it.
+		subsOK := true
+		if s.subsDone != nil {
+			select {
+			case <-s.subsDone:
+			case <-time.After(15 * time.Second):
+				log.Printf("[hls %s] subtitle extractor timeout — not caching", shortHLSID(s.cfg.SessionID))
+				subsOK = false
+			}
+		}
+		if subsOK && exitErr == nil && s.allSegmentsPresent() {
+			if err := s.cache.MarkComplete(s.cacheKey); err == nil {
+				log.Printf("[hls %s] cache persisted %s", shortHLSID(s.cfg.SessionID), s.cacheKey)
+				return nil
+			} else {
+				log.Printf("[hls %s] cache persist failed: %v", shortHLSID(s.cfg.SessionID), err)
+			}
+		}
+		// Partial / failed → drop so we re-encode next time.
+		if err := s.cache.Invalidate(s.cacheKey); err != nil {
+			log.Printf("[hls %s] cache invalidate failed: %v", shortHLSID(s.cfg.SessionID), err)
+		}
+		log.Printf("[hls %s] closed (cache discarded)", shortHLSID(s.cfg.SessionID))
+		return nil
+	}
+
 	if tmpDir != "" {
 		_ = os.RemoveAll(tmpDir)
 	}
@@ -417,6 +638,31 @@ func (s *HLSSession) Close() error {
 	return nil
 }
 
+// allSegmentsPresent reports whether every expected segment (and init.mp4) is
+// on disk AND validated by the segment poller. Used to decide whether a
+// finished session is cacheable. We trust readyMax (advanced by pollSegments
+// only after the next segment exists, proving the predecessor is fully closed)
+// over a naive Size>0 stat that could accept truncated mid-write files.
+func (s *HLSSession) allSegmentsPresent() bool {
+	if fi, err := os.Stat(filepath.Join(s.tmpDir, "video", "init.mp4")); err != nil || fi.Size() == 0 {
+		return false
+	}
+	s.readyMu.Lock()
+	readyMax := s.readyMax
+	s.readyMu.Unlock()
+	if readyMax < s.segmentCount-1 {
+		return false
+	}
+	for i := 0; i < s.segmentCount; i++ {
+		path := filepath.Join(s.tmpDir, "video", fmt.Sprintf("seg-%d.m4s", i))
+		fi, err := os.Stat(path)
+		if err != nil || fi.Size() == 0 {
+			return false
+		}
+	}
+	return true
+}
+
 // waitFFmpeg reaps the ffmpeg process and records its exit error for handlers.
 //
 // Auto-restart supervisor: if ffmpeg crashes (non-graceful exit) and the
@@ -717,8 +963,10 @@ func (s *HLSSession) restartFromSegment(targetIdx int) error {
 		time.Sleep(50 * time.Millisecond)
 	}
 
-	// Build args for the new ffmpeg with -ss offset.
+	// Build args for the new ffmpeg with -ss offset. Segments are non-uniform
-	startSec := float64(targetIdx * hlsSegmentDuration)
+	// (seg-0 is hlsInitSegmentDuration s, the rest are hlsSegmentDuration s),
+	// so use segmentStartSec for the seek time instead of multiplying.
+	startSec := segmentStartSec(targetIdx)
 	args := buildHLSFFmpegArgsAt(s.cfg, s.probe, s.tmpDir, targetIdx, startSec)
 
 	ffCtx, cancel := context.WithCancel(context.Background())
@@ -783,23 +1031,77 @@ func buildHLSFFmpegArgs(cfg HLSSessionConfig, probe *StreamProbe, tmpDir string)
 	return buildHLSFFmpegArgsAt(cfg, probe, tmpDir, 0, 0)
 }
 
+// EncoderProfile names the codec + preset + decoder hint combination the HLS
+// pipeline picks for the given hardware backend + transcode config. Exposed
+// so callers can log the chosen encoder before ffmpeg launches and so both
+// the demuxer-side `-hwaccel` flag and the encoder-side argv stay in sync
+// (otherwise the two switches in buildHLSFFmpegArgsAt could silently drift
+// when adding a new backend).
+type EncoderProfile struct {
+	Codec     string // ffmpeg encoder name (e.g. "h264_nvenc", "libx264")
+	Preset    string // preset string, or "" when the codec has no preset knob
+	DecodeHwAccel string // ffmpeg `-hwaccel` value (e.g. "cuda", "qsv", "vaapi"), or ""
+}
+
+// ResolveEncoderProfile mirrors the codec + preset selection inside
+// buildHLSFFmpegArgsAt so callers (registry, log lines, diagnostic
+// endpoints) can know what ffmpeg will be told to do without parsing argv.
+//
+// The configured preset is libx264-specific by vocabulary (ultrafast…
+// veryslow). Passing it through to NVENC / QSV would have ffmpeg reject
+// the argv (NVENC uses p1-p7, QSV uses its own subset). So vendor encoders
+// always use their hardcoded vendor preset and ignore configuredPreset.
+// VideoToolbox has no preset knob at all.
+//
+// DecodeHwAccel mirrors the encoder family — `-hwaccel cuda` for NVENC,
+// `-hwaccel qsv` for QSV, `-hwaccel vaapi` for VAAPI. We intentionally
+// do NOT pass `-hwaccel_output_format vaapi`: that pins decoded frames
+// to GPU memory, but our filter chain (scale/format/setparams) runs on
+// CPU and can't consume VAAPI surfaces. Keeping output frames on CPU
+// makes the filter chain work and the VAAPI encoder still benefits from
+// HW-accelerated DECODE on the input side.
+func ResolveEncoderProfile(hw HWAccel, configuredPreset string) EncoderProfile {
+	codec := hw.FFmpegVideoCodec("h264")
+	switch codec {
+	case "libx264":
+		preset := configuredPreset
+		if preset == "" {
+			preset = "superfast"
+		}
+		return EncoderProfile{Codec: codec, Preset: preset, DecodeHwAccel: ""}
+	case "h264_nvenc":
+		return EncoderProfile{Codec: codec, Preset: "p3", DecodeHwAccel: "cuda"}
+	case "h264_qsv":
+		return EncoderProfile{Codec: codec, Preset: "veryfast", DecodeHwAccel: "qsv"}
+	case "h264_vaapi":
+		return EncoderProfile{Codec: codec, Preset: "", DecodeHwAccel: "vaapi"}
+	case "h264_videotoolbox":
+		// No preset knob for VideoToolbox; the speed/quality dial is `-q:v`.
+		// VideoToolbox uses per-encoder flags rather than a demuxer hint.
+		return EncoderProfile{Codec: codec, Preset: "", DecodeHwAccel: ""}
+	}
+	// Unknown / future codecs: software path.
+	return EncoderProfile{Codec: codec, Preset: "", DecodeHwAccel: ""}
+}
+
 // buildHLSFFmpegArgsAt returns the argv for an HLS encode that starts at the
 // given segment index (`-ss <startSec>`) and writes segments numbered from
 // startIdx so they slot into the existing manifest at the correct position.
 // `-output_ts_offset` keeps the segment PTS aligned with manifest timeline.
 func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir string, startIdx int, startSec float64) []string {
-	hwHint := cfg.Transcode.HWAccel
+	profile := ResolveEncoderProfile(cfg.Transcode.HWAccel, cfg.Transcode.Preset)
 	args := []string{"-y", "-hide_banner", "-loglevel", "warning"}
 
-	switch hwHint {
+	// Demuxer-side HW-decode hint. Sourced from the profile so a future
-	case HWAccelNVENC:
+	// codec/hint mismatch is impossible — the encoder + decode hint are
-		args = append(args, "-hwaccel", "cuda")
+	// computed once and stay coherent. Notably we do NOT add
-	case HWAccelQSV:
+	// `-hwaccel_output_format vaapi` on the VAAPI path: that pins decoded
-		args = append(args, "-hwaccel", "qsv")
+	// frames to GPU memory but our CPU filter chain (scale, format,
-	case HWAccelVAAPI:
+	// setparams) can't consume VAAPI surfaces. Letting frames flow on CPU
-		args = append(args, "-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi")
+	// keeps the filter chain working; the encoder still gets HW-accelerated
-	case HWAccelNone, HWAccelVideoToolbox:
+	// decode on the input side.
-		// No demuxer-side hint.
+	if profile.DecodeHwAccel != "" {
+		args = append(args, "-hwaccel", profile.DecodeHwAccel)
 	}
 
 	// Seek before -i for fast keyframe-aligned start. The new ffmpeg writes
@@ -829,24 +1131,54 @@ func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir strin
 	}
 	args = append(args, "-map", fmt.Sprintf("0:a:%d?", audioIdx))
 
-	// Video encode.
+	// Video encode. Codec + preset come from the EncoderProfile resolved at
-	codec := hwHint.FFmpegVideoCodec("h264")
+	// the top of this function so the demuxer hint, the encoder, and the
+	// per-session log line all stay consistent.
+	//
+	// Defaults are biased for FIRST-START LATENCY over quality — the player
+	// blocks on seg-0 before the first frame paints, and a slow seg-0 is
+	// what users notice ("preparando sesión" stuck). Users who want better
+	// quality can override via `download.transcode.preset` in config.toml.
+	codec := profile.Codec
 	args = append(args, "-c:v", codec)
-	// Encoder-specific tuning. Each HW encoder takes a different "preset"
-	// vocabulary; libx264 uses ultrafast→placebo, NVENC uses p1→p7, QSV uses
-	// veryfast→veryslow, VAAPI/VideoToolbox don't expose presets.
 	switch codec {
 	case "libx264":
-		preset := cfg.Transcode.Preset
+		// superfast = ~15-20% faster than veryfast at marginal quality loss
-		if preset == "" {
+		// for the bitrates we target (5-25 Mbps). For 4K software encodes
-			preset = "veryfast"
+		// this is the difference between ~3 s and ~2.5 s per segment on a
-		}
+		// recent x86 CPU. `-threads 0` is libx264's default but explicit
-		args = append(args, "-preset", preset)
+		// helps when the user has set GOMAXPROCS.
+		args = append(args, "-preset", profile.Preset, "-threads", "0")
 	case "h264_nvenc":
-		// p4 = balanced quality/speed; p1 fastest, p7 highest quality.
+		// p3 + tune=ll trades ~0.3 dB PSNR for 1.5-2× faster encode vs the
-		args = append(args, "-preset", "p4", "-rc", "vbr", "-tune", "hq")
+		// previous p4 + tune=hq pair — first-segment encode drops from
+		// ~1.5 s to ~0.8 s on RTX-class hardware.
+		args = append(args, "-preset", profile.Preset, "-rc", "vbr", "-tune", "ll")
 	case "h264_qsv":
-		args = append(args, "-preset", "medium", "-look_ahead", "0")
+		// veryfast is the fastest realistic QSV preset; medium was too
+		// conservative for first-start. look_ahead=0 keeps the encoder
+		// truly low-latency (no rate-control look-ahead window).
+		args = append(args, "-preset", profile.Preset, "-look_ahead", "0")
+	case "h264_videotoolbox":
+		// VideoToolbox has no "preset" knob; `-realtime` flips into the
+		// low-latency path used by FaceTime. We let the `-b:v / -maxrate
+		// / -bufsize` block (added later in this function) drive rate
+		// control — adding `-q:v` here would conflict because ffmpeg's
+		// videotoolbox encoder treats `-b:v` as authoritative and
+		// silently ignores `-q:v`, so the constant-quality knob never
+		// took effect anyway.
+		args = append(args, "-realtime", "1")
+	case "h264_vaapi":
+		// h264_vaapi has no preset knob. Bitrate args (set later) drive
+		// rate control. Add `-vaapi_device /dev/dri/renderD128` so the
+		// encoder doesn't fall back to a NULL device on multi-GPU hosts
+		// where the default render node is a non-VAAPI GPU (an Nvidia
+		// dGPU's render node, etc.). The filter chain below switches to
+		// `format=nv12,hwupload` so frames land on the right VAAPI
+		// surface before the encoder; we intentionally avoid scale_vaapi
+		// because mesa 25 + Raphael iGPU emits "Cannot allocate memory"
+		// per session start, polluting logs even though encode succeeds.
+		args = append(args, "-vaapi_device", "/dev/dri/renderD128")
 	}
 	// Derive H.264 level from the actual output height. A fixed "4.0" caps the
 	// encoder at 1080p — anything taller (1440p, 4K source on quality=original)
@@ -897,14 +1229,32 @@ func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir strin
 	if maxH == 0 {
 		maxH = cfg.Transcode.MaxHeight
 	}
+	// VAAPI needs frames as nv12 VAAPI surfaces before the encoder. We do
+	// scale + format conversion on CPU then `hwupload` once at the end —
+	// skips the mesa 25 + Raphael iGPU "Cannot allocate memory" log spam
+	// that scale_vaapi triggers per-session-start while still delivering
+	// the encoder a GPU surface. setparams is dropped because VAAPI
+	// surfaces don't expose VUI fields the way libx264 does; the encoder
+	// records its own color metadata via the source PTS chain.
+	pixFormat := "yuv420p"
+	hwUploadTail := ""
+	colorTail := ",setparams=colorspace=bt709:color_trc=bt709:color_primaries=bt709:range=tv"
+	if codec == "h264_vaapi" {
+		pixFormat = "nv12"
+		hwUploadTail = ",hwupload"
+		colorTail = ""
+	}
 	var filterChain string
 	if maxH > 0 && probe.Height > maxH {
 		filterChain = fmt.Sprintf(
-			"scale=-2:%d:force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2,format=yuv420p,setparams=colorspace=bt709:color_trc=bt709:color_primaries=bt709:range=tv",
+			"scale=-2:%d:force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2,format=%s%s%s",
-			maxH,
+			maxH, pixFormat, colorTail, hwUploadTail,
 		)
 	} else {
-		filterChain = "scale=trunc(iw/2)*2:trunc(ih/2)*2,format=yuv420p,setparams=colorspace=bt709:color_trc=bt709:color_primaries=bt709:range=tv"
+		filterChain = fmt.Sprintf(
+			"scale=trunc(iw/2)*2:trunc(ih/2)*2,format=%s%s%s",
+			pixFormat, colorTail, hwUploadTail,
+		)
 	}
 	args = append(args, "-vf", filterChain)
 
@@ -977,6 +1327,10 @@ func (s *HLSSession) extractSubtitles(ctx context.Context) {
 // renderVideoPlaylist builds the VOD media playlist for the video stream.
 // Segment count is derived from the source duration — the player learns the
 // total timeline from the manifest before any segment is fetched.
+//
+// seg-0 is the short init segment (hlsInitSegmentDuration s); seg-1 onward
+// are hlsSegmentDuration s each. The last segment may be shorter than the
+// nominal duration when (duration - init) doesn't divide evenly.
 func renderVideoPlaylist(durationSec float64, segCount int) string {
 	var b strings.Builder
 	b.WriteString("#EXTM3U\n")
@@ -987,7 +1341,7 @@ func renderVideoPlaylist(durationSec float64, segCount int) string {
 	b.WriteString(`#EXT-X-MAP:URI="init.mp4"` + "\n")
 	remaining := durationSec
 	for i := 0; i < segCount; i++ {
-		segDur := float64(hlsSegmentDuration)
+		segDur := float64(segmentDurationFor(i))
 		if remaining < segDur {
 			segDur = remaining
 		}

internal/engine/hls_cache.go

@@ -0,0 +1,410 @@
+package engine
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"sort"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// HLSCache persists transcoded HLS segments per (source, quality, audio) so a
+// second play of the same file at the same quality skips ffmpeg entirely.
+//
+// Layout on disk:
+//
+//	{root}/{key}/init.mp4
+//	{root}/{key}/seg-0.m4s
+//	{root}/{key}/seg-N.m4s
+//	{root}/{key}/.complete
+//
+// Atomicity: the .complete marker is written only when ffmpeg exits 0 AND all
+// segments are on disk. A dir without .complete is treated as a partial run —
+// next session can reuse the segments already present, ffmpeg fills the gaps.
+//
+// Concurrency: Pin/Unpin increments a ref counter per key so the LRU sweeper
+// never evicts a directory that an active session is reading from.
+type HLSCache struct {
+	root     string
+	maxBytes int64
+
+	mu      sync.Mutex
+	refs    map[string]int
+	writers map[string]bool // exclusive ffmpeg writer per key; nil entries are absent
+
+	// Counters surfaced via Stats() — useful for /api/internal/agent/cache-stats
+	// and for the sweeper's daily log line. atomic so RecordHit/RecordMiss are
+	// safe to call from any goroutine without taking the cache mutex.
+	hits   atomic.Uint64
+	misses atomic.Uint64
+}
+
+const (
+	hlsCacheCompleteMarker = ".complete"
+	// hlsCacheMinBudgetGB clamps absurd / zero / negative SizeGB values to
+	// a sane floor. NOT a guarantee that any single encode fits — a long
+	// 4K HEVC re-encode can exceed it. Operators should set size_gb based
+	// on their actual workload.
+	hlsCacheMinBudgetGB = 1
+	// hlsCacheStartupOrphanAge: directories without .complete older than
+	// this are removed on cache startup. Long enough that a daemon crash
+	// during an in-progress encode (which legitimately leaves a partial
+	// dir) doesn't get nuked too aggressively if the daemon restarts fast.
+	hlsCacheStartupOrphanAge = 10 * time.Minute
+)
+
+// NewHLSCache creates the cache rooted at the given dir with a size budget in
+// gigabytes. A budget < hlsCacheMinBudgetGB is clamped up so a single play
+// doesn't get instantly evicted mid-stream.
+func NewHLSCache(root string, sizeGB int) (*HLSCache, error) {
+	if root == "" {
+		return nil, errors.New("hls_cache: empty root")
+	}
+	if sizeGB < hlsCacheMinBudgetGB {
+		sizeGB = hlsCacheMinBudgetGB
+	}
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		return nil, fmt.Errorf("hls_cache: mkdir root: %w", err)
+	}
+	c := &HLSCache{
+		root:     root,
+		maxBytes: int64(sizeGB) * 1024 * 1024 * 1024,
+		refs:     make(map[string]int),
+		writers:  make(map[string]bool),
+	}
+	// Reap dirs left over from a crashed encode. A dir without .complete that
+	// hasn't been touched recently was almost certainly orphaned by an
+	// ungraceful daemon exit — keeping it just feeds the unbounded growth
+	// pattern the hourly LRU is too slow to contain.
+	if removed, err := c.cleanStartupOrphans(); err != nil {
+		log.Printf("[hls_cache] startup orphan cleanup: %v", err)
+	} else if removed > 0 {
+		log.Printf("[hls_cache] startup: removed %d orphan dir(s) without .complete", removed)
+	}
+	return c, nil
+}
+
+// cleanStartupOrphans removes cache subdirectories that lack a .complete
+// marker AND haven't been modified within hlsCacheStartupOrphanAge. Called
+// once at construction. Safe at startup because no sessions are active yet,
+// so Pin can't race with us.
+func (c *HLSCache) cleanStartupOrphans() (int, error) {
+	entries, err := os.ReadDir(c.root)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, nil
+		}
+		return 0, err
+	}
+	cutoff := time.Now().Add(-hlsCacheStartupOrphanAge)
+	removed := 0
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		dir := filepath.Join(c.root, e.Name())
+		if _, err := os.Stat(filepath.Join(dir, hlsCacheCompleteMarker)); err == nil {
+			continue // sealed, keep
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		if info.ModTime().After(cutoff) {
+			continue // too recent — might be a daemon that just restarted mid-encode
+		}
+		if err := os.RemoveAll(dir); err == nil {
+			removed++
+		}
+	}
+	return removed, nil
+}
+
+// TryAcquireWriter attempts to claim exclusive ffmpeg-write access to a key.
+// Returns true on success — the caller is then responsible for ReleaseWriter
+// when ffmpeg exits / fails. Returns false if another session is already
+// writing this key, in which case the caller must fall back to a private
+// per-session tmpdir (no caching for that session).
+func (c *HLSCache) TryAcquireWriter(key string) bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.writers[key] {
+		return false
+	}
+	c.writers[key] = true
+	return true
+}
+
+// ReleaseWriter releases the writer claim acquired via TryAcquireWriter.
+// Idempotent on unknown keys.
+func (c *HLSCache) ReleaseWriter(key string) {
+	c.mu.Lock()
+	delete(c.writers, key)
+	c.mu.Unlock()
+}
+
+// KeyFor derives a stable cache key for (source, quality, audioIndex). Using
+// the absolute source path means renaming a file invalidates the cache, which
+// is correct — segment content is tied to the encoded source.
+func (c *HLSCache) KeyFor(sourcePath, quality string, audioIndex int) string {
+	abs, err := filepath.Abs(sourcePath)
+	if err != nil {
+		abs = sourcePath
+	}
+	h := sha256.Sum256([]byte(fmt.Sprintf("%s|%s|%d", abs, quality, audioIndex)))
+	return hex.EncodeToString(h[:8]) // 16 hex chars — collision-safe enough for per-host cache
+}
+
+// DirFor returns the on-disk directory for a cache key. Caller is responsible
+// for creating it.
+func (c *HLSCache) DirFor(key string) string {
+	return filepath.Join(c.root, key)
+}
+
+// HasComplete returns true when the .complete marker is present, meaning the
+// directory holds a full set of segments from a successful encode.
+func (c *HLSCache) HasComplete(key string) bool {
+	if _, err := os.Stat(filepath.Join(c.DirFor(key), hlsCacheCompleteMarker)); err == nil {
+		return true
+	}
+	return false
+}
+
+// MarkComplete writes the .complete marker. Call only after verifying ffmpeg
+// exited cleanly AND every expected segment is on disk. The dir must already
+// exist — StartHLSSession created it on the writer path.
+func (c *HLSCache) MarkComplete(key string) error {
+	return os.WriteFile(filepath.Join(c.DirFor(key), hlsCacheCompleteMarker), nil, 0o644)
+}
+
+// RecordHit increments the hit counter; called by StartHLSSession on a
+// cache-HIT path.
+func (c *HLSCache) RecordHit() { c.hits.Add(1) }
+
+// RecordMiss increments the miss counter; called when a session has to
+// encode from scratch (or fails an integrity check on a stale HIT).
+func (c *HLSCache) RecordMiss() { c.misses.Add(1) }
+
+// CacheStats is a snapshot of the cache's runtime counters + on-disk size.
+// The size fields are best-effort (computed via dirSize) so callers paying
+// for them should cache the result, not poll in a hot loop.
+type CacheStats struct {
+	Hits       uint64
+	Misses     uint64
+	EntryCount int
+	TotalBytes int64
+}
+
+// Stats returns a snapshot of the cache counters and size. Walks the root
+// to total disk usage — O(N segments). Call at most every few minutes.
+func (c *HLSCache) Stats() CacheStats {
+	s := CacheStats{
+		Hits:   c.hits.Load(),
+		Misses: c.misses.Load(),
+	}
+	entries, err := os.ReadDir(c.root)
+	if err != nil {
+		return s
+	}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		size, err := dirSize(filepath.Join(c.root, e.Name()))
+		if err != nil {
+			continue
+		}
+		s.EntryCount++
+		s.TotalBytes += size
+	}
+	return s
+}
+
+// hitRatePercent returns the current hit/(hit+miss) percentage rounded to
+// the nearest int; 0 when no calls have been recorded.
+func (c *HLSCache) hitRatePercent() int {
+	h := c.hits.Load()
+	m := c.misses.Load()
+	total := h + m
+	if total == 0 {
+		return 0
+	}
+	return int((h*100 + total/2) / total)
+}
+
+// VerifyComplete checks that the .complete marker is present AND the
+// essential files (init.mp4 + last segment) exist with non-zero size. A
+// dir that passes HasComplete but fails VerifyComplete is treated as
+// corrupted — typically external `rm` or a partial-disk-failure scenario.
+// When it returns false, callers should Invalidate and re-encode.
+func (c *HLSCache) VerifyComplete(key string, segmentCount int) bool {
+	if !c.HasComplete(key) {
+		return false
+	}
+	dir := c.DirFor(key)
+	if fi, err := os.Stat(filepath.Join(dir, "video", "init.mp4")); err != nil || fi.Size() == 0 {
+		return false
+	}
+	if segmentCount > 0 {
+		lastSeg := filepath.Join(dir, "video", fmt.Sprintf("seg-%d.m4s", segmentCount-1))
+		if fi, err := os.Stat(lastSeg); err != nil || fi.Size() == 0 {
+			return false
+		}
+	}
+	return true
+}
+
+// Pin increments the ref counter for a key. The sweeper checks this before
+// evicting, so a pinned dir is safe even if its mtime is old.
+func (c *HLSCache) Pin(key string) {
+	c.mu.Lock()
+	c.refs[key]++
+	c.mu.Unlock()
+}
+
+// Unpin decrements; safe to call on unknown keys (no-op).
+func (c *HLSCache) Unpin(key string) {
+	c.mu.Lock()
+	if c.refs[key] > 0 {
+		c.refs[key]--
+		if c.refs[key] == 0 {
+			delete(c.refs, key)
+		}
+	}
+	c.mu.Unlock()
+}
+
+func (c *HLSCache) isPinned(key string) bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.refs[key] > 0
+}
+
+// Touch updates the directory mtime so LRU picks fresher entries as recently
+// used. Called when a session starts reading from a cached dir.
+func (c *HLSCache) Touch(key string) error {
+	dir := c.DirFor(key)
+	now := time.Now()
+	return os.Chtimes(dir, now, now)
+}
+
+// Sweep enforces the size budget by deleting the least-recently-used cache
+// dirs (ignoring pinned ones) until the total size is at or below maxBytes.
+// Returns the number of bytes freed.
+func (c *HLSCache) Sweep() (int64, error) {
+	entries, err := os.ReadDir(c.root)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, nil
+		}
+		return 0, fmt.Errorf("hls_cache: read root: %w", err)
+	}
+
+	type item struct {
+		key   string
+		path  string
+		size  int64
+		mtime time.Time
+	}
+	items := make([]item, 0, len(entries))
+	var total, pinned int64
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		key := e.Name()
+		path := filepath.Join(c.root, key)
+		size, err := dirSize(path)
+		if err != nil {
+			continue
+		}
+		items = append(items, item{key: key, path: path, size: size, mtime: info.ModTime()})
+		total += size
+		if c.isPinned(key) {
+			pinned += size
+		}
+	}
+
+	if total <= c.maxBytes {
+		return 0, nil
+	}
+	if pinned >= c.maxBytes {
+		// Every pinned byte already exceeds the budget — even evicting
+		// every unpinned dir won't bring us under. Warn loudly so the
+		// operator knows to bump size_gb (or kill the long-running session).
+		log.Printf("[hls_cache] warn: pinned bytes (%.1f MB) exceed budget (%.1f MB) — cannot enforce limit until sessions release",
+			float64(pinned)/(1024*1024), float64(c.maxBytes)/(1024*1024))
+		return 0, nil
+	}
+
+	// Oldest first.
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].mtime.Before(items[j].mtime)
+	})
+
+	var freed int64
+	for _, it := range items {
+		if total-freed <= c.maxBytes {
+			break
+		}
+		if c.isPinned(it.key) {
+			continue
+		}
+		if err := os.RemoveAll(it.path); err != nil {
+			log.Printf("[hls_cache] evict %s failed: %v", it.key, err)
+			continue
+		}
+		log.Printf("[hls_cache] evicted %s (%.1f MB, age %s)",
+			it.key, float64(it.size)/(1024*1024), time.Since(it.mtime).Round(time.Second))
+		freed += it.size
+	}
+	return freed, nil
+}
+
+// StartSweeper kicks off the LRU sweeper goroutine. Cancels on ctx done.
+// In addition to enforcing the size budget, logs a daily summary of hit-rate
+// + disk usage so operators can see the cache's value at a glance.
+func (c *HLSCache) StartSweeper(ctx context.Context, interval time.Duration) {
+	if interval <= 0 {
+		interval = time.Hour
+	}
+	go func() {
+		t := time.NewTicker(interval)
+		defer t.Stop()
+		statsTick := time.NewTicker(24 * time.Hour)
+		defer statsTick.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				if _, err := c.Sweep(); err != nil {
+					log.Printf("[hls_cache] sweep error: %v", err)
+				}
+			case <-statsTick.C:
+				s := c.Stats()
+				log.Printf("[hls_cache] day-stats: hits=%d misses=%d ratio=%d%% entries=%d size=%.1fMB",
+					s.Hits, s.Misses, c.hitRatePercent(), s.EntryCount,
+					float64(s.TotalBytes)/(1024*1024))
+			}
+		}
+	}()
+}
+
+// Invalidate removes a cache entry — used when ffmpeg fails to encode the
+// source so we don't reuse a half-written dir next time.
+func (c *HLSCache) Invalidate(key string) error {
+	return os.RemoveAll(c.DirFor(key))
+}
+

internal/engine/hls_cache_smoke_test.go

@@ -0,0 +1,134 @@
+//go:build smoke
+
+package engine
+
+import (
+	"context"
+	"os/exec"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// TestHLSCacheSmoke exercises the end-to-end cache flow against real ffmpeg:
+//   - First session encodes a 5s test pattern; expect MISS, ffmpeg runs,
+//     .complete written, MarkComplete logs.
+//   - Second session for identical (source, quality, audio); expect HIT,
+//     no ffmpeg, instant Start.
+//
+// Build tag `smoke` keeps it out of the default `go test ./...` run because
+// it depends on a working ffmpeg/ffprobe and takes ~5–10 s.
+//
+//	go test -tags=smoke -run TestHLSCacheSmoke -v ./internal/engine/
+func TestHLSCacheSmoke(t *testing.T) {
+	ffmpeg, err := exec.LookPath("ffmpeg")
+	if err != nil {
+		t.Skipf("ffmpeg not on PATH: %v", err)
+	}
+	ffprobe, err := exec.LookPath("ffprobe")
+	if err != nil {
+		t.Skipf("ffprobe not on PATH: %v", err)
+	}
+
+	tmp := t.TempDir()
+	source := filepath.Join(tmp, "source.mp4")
+	t.Logf("generating 5 s test pattern → %s", source)
+	if out, err := exec.Command(ffmpeg,
+		"-y", "-loglevel", "error",
+		"-f", "lavfi", "-i", "testsrc=duration=5:size=640x480:rate=30",
+		"-f", "lavfi", "-i", "sine=frequency=1000:duration=5",
+		"-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p",
+		"-c:a", "aac",
+		source,
+	).CombinedOutput(); err != nil {
+		t.Fatalf("ffmpeg generate: %v\n%s", err, out)
+	}
+
+	cacheRoot := filepath.Join(tmp, "cache")
+	cache, err := NewHLSCache(cacheRoot, 1)
+	if err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+
+	cfg := HLSSessionConfig{
+		SessionID:  "smoke1",
+		SourcePath: source,
+		FileName:   "source.mp4",
+		Quality:    "720p",
+		AudioIndex: 0,
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  ffmpeg,
+			FFprobePath: ffprobe,
+			Preset:      "ultrafast",
+		},
+		Cache: cache,
+	}
+
+	// First run — expect MISS, ffmpeg runs.
+	t.Log("session 1: expect MISS")
+	t0 := time.Now()
+	s1, err := StartHLSSession(context.Background(), cfg)
+	if err != nil {
+		t.Fatalf("StartHLSSession #1: %v", err)
+	}
+	if s1.fromCache {
+		t.Fatal("session 1 reported cache HIT on a fresh cache")
+	}
+
+	// Wait for all segments to land. 5 s source @ 4 s segments → 2 segments.
+	deadline := time.Now().Add(60 * time.Second)
+	for {
+		s1.readyMu.Lock()
+		ready := s1.readyMax
+		exited := s1.exited
+		s1.readyMu.Unlock()
+		if ready >= s1.segmentCount-1 && exited {
+			break
+		}
+		if time.Now().After(deadline) {
+			_ = s1.Close()
+			t.Fatalf("session 1 didn't finish in 60 s (readyMax=%d/%d, exited=%v)",
+				ready, s1.segmentCount-1, exited)
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	if err := s1.Close(); err != nil {
+		t.Fatalf("Close #1: %v", err)
+	}
+	encodeDur := time.Since(t0)
+	t.Logf("session 1: MISS completed in %s", encodeDur.Round(time.Millisecond))
+
+	key := cache.KeyFor(source, "720p", 0)
+	if !cache.HasComplete(key) {
+		t.Fatalf("cache.HasComplete(%s) is false after successful encode", key)
+	}
+
+	// Second run — expect HIT, no ffmpeg.
+	t.Log("session 2: expect HIT")
+	cfg.SessionID = "smoke2"
+	t1 := time.Now()
+	s2, err := StartHLSSession(context.Background(), cfg)
+	if err != nil {
+		t.Fatalf("StartHLSSession #2: %v", err)
+	}
+	if !s2.fromCache {
+		t.Fatal("session 2 should have reported cache HIT")
+	}
+	if s2.cmd != nil {
+		t.Fatal("session 2 should not have spawned ffmpeg (s.cmd != nil)")
+	}
+	hitDur := time.Since(t1)
+	t.Logf("session 2: HIT in %s (%.1f×  faster than MISS)",
+		hitDur.Round(time.Millisecond), float64(encodeDur)/float64(hitDur))
+	if hitDur > 500*time.Millisecond {
+		t.Errorf("HIT path too slow: %s — expected <500 ms", hitDur)
+	}
+	if err := s2.Close(); err != nil {
+		t.Fatalf("Close #2: %v", err)
+	}
+
+	// After the HIT session closes, the cache dir + .complete must still exist.
+	if !cache.HasComplete(key) {
+		t.Fatal(".complete disappeared after HIT session closed")
+	}
+}

internal/engine/hls_cache_test.go

@@ -0,0 +1,361 @@
+package engine
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+func newTestCache(t *testing.T, sizeGB int) *HLSCache {
+	t.Helper()
+	root := t.TempDir()
+	c, err := NewHLSCache(root, sizeGB)
+	if err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+	return c
+}
+
+func TestKeyForStable(t *testing.T) {
+	c := newTestCache(t, 1)
+	k1 := c.KeyFor("/a/b/movie.mkv", "1080p", 0)
+	k2 := c.KeyFor("/a/b/movie.mkv", "1080p", 0)
+	if k1 != k2 {
+		t.Fatalf("expected stable keys, got %q vs %q", k1, k2)
+	}
+	if c.KeyFor("/a/b/movie.mkv", "720p", 0) == k1 {
+		t.Fatal("quality should change key")
+	}
+	if c.KeyFor("/a/b/movie.mkv", "1080p", 1) == k1 {
+		t.Fatal("audio index should change key")
+	}
+	if c.KeyFor("/x/y/other.mkv", "1080p", 0) == k1 {
+		t.Fatal("path should change key")
+	}
+}
+
+func TestMarkCompleteAndHas(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "abc123"
+	if c.HasComplete(key) {
+		t.Fatal("fresh cache should not report complete")
+	}
+	// Production callers create the dir during StartHLSSession; MarkComplete
+	// trusts that invariant and fails if the dir was wiped meanwhile.
+	if err := os.MkdirAll(c.DirFor(key), 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := c.MarkComplete(key); err != nil {
+		t.Fatalf("MarkComplete: %v", err)
+	}
+	if !c.HasComplete(key) {
+		t.Fatal("after MarkComplete, HasComplete must be true")
+	}
+}
+
+func TestMarkCompleteFailsWithoutDir(t *testing.T) {
+	c := newTestCache(t, 1)
+	if err := c.MarkComplete("never-created"); err == nil {
+		t.Fatal("MarkComplete should error when dir doesn't exist")
+	}
+}
+
+func TestPinPreventsEviction(t *testing.T) {
+	c := newTestCache(t, 1) // 1 GB budget, but min clamp keeps it usable
+	c.maxBytes = 1024       // squeeze budget for the test
+
+	// Write two entries past the budget.
+	for i, key := range []string{"old", "new"} {
+		dir := c.DirFor(key)
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatalf("mkdir %s: %v", dir, err)
+		}
+		path := filepath.Join(dir, "seg.bin")
+		if err := os.WriteFile(path, make([]byte, 800), 0o644); err != nil {
+			t.Fatalf("write %s: %v", path, err)
+		}
+		now := time.Now().Add(time.Duration(i) * time.Hour) // "old" mtime < "new"
+		_ = os.Chtimes(dir, now, now)
+	}
+
+	c.Pin("old") // protect the older one
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep: %v", err)
+	}
+	if freed == 0 {
+		t.Fatal("expected some eviction")
+	}
+	if _, err := os.Stat(c.DirFor("old")); err != nil {
+		t.Fatal("pinned 'old' was evicted")
+	}
+	if _, err := os.Stat(c.DirFor("new")); err == nil {
+		t.Fatal("'new' should have been evicted to make room")
+	}
+}
+
+func TestSweepNoOpUnderBudget(t *testing.T) {
+	c := newTestCache(t, 1)
+	dir := c.DirFor("small")
+	_ = os.MkdirAll(dir, 0o755)
+	_ = os.WriteFile(filepath.Join(dir, "x"), []byte("tiny"), 0o644)
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep: %v", err)
+	}
+	if freed != 0 {
+		t.Fatalf("expected 0 freed under budget, got %d", freed)
+	}
+	if _, err := os.Stat(dir); err != nil {
+		t.Fatal("under-budget entry was wrongly evicted")
+	}
+}
+
+func TestSweepEmptyRoot(t *testing.T) {
+	c := newTestCache(t, 1)
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep empty: %v", err)
+	}
+	if freed != 0 {
+		t.Fatalf("freed=%d, want 0", freed)
+	}
+}
+
+func TestInvalidateRemovesDir(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "drop"
+	dir := c.DirFor(key)
+	_ = os.MkdirAll(dir, 0o755)
+	_ = os.WriteFile(filepath.Join(dir, "x"), []byte("y"), 0o644)
+	if err := c.Invalidate(key); err != nil {
+		t.Fatalf("Invalidate: %v", err)
+	}
+	if _, err := os.Stat(dir); err == nil {
+		t.Fatal("dir still present after Invalidate")
+	}
+}
+
+func TestTouchUpdatesMtime(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "touch"
+	dir := c.DirFor(key)
+	_ = os.MkdirAll(dir, 0o755)
+	old := time.Now().Add(-2 * time.Hour)
+	_ = os.Chtimes(dir, old, old)
+
+	if err := c.Touch(key); err != nil {
+		t.Fatalf("Touch: %v", err)
+	}
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if !info.ModTime().After(old.Add(time.Minute)) {
+		t.Fatalf("mtime not refreshed: %v", info.ModTime())
+	}
+}
+
+func TestPinUnpinSymmetry(t *testing.T) {
+	c := newTestCache(t, 1)
+	c.Pin("k")
+	c.Pin("k")
+	if !c.isPinned("k") {
+		t.Fatal("Pin twice should leave pinned")
+	}
+	c.Unpin("k")
+	if !c.isPinned("k") {
+		t.Fatal("Unpin once should keep pinned (refs=1)")
+	}
+	c.Unpin("k")
+	if c.isPinned("k") {
+		t.Fatal("Unpin twice should drop pin")
+	}
+	c.Unpin("k") // safe no-op
+}
+
+func TestConcurrentPinUnpin(t *testing.T) {
+	c := newTestCache(t, 1)
+	var wg sync.WaitGroup
+	for i := 0; i < 100; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			c.Pin("race")
+			time.Sleep(time.Microsecond)
+			c.Unpin("race")
+		}()
+	}
+	wg.Wait()
+	if c.isPinned("race") {
+		t.Fatal("refs leaked")
+	}
+}
+
+func TestSweeperLoopExits(t *testing.T) {
+	c := newTestCache(t, 1)
+	ctx, cancel := context.WithCancel(context.Background())
+	c.StartSweeper(ctx, 10*time.Millisecond)
+	time.Sleep(30 * time.Millisecond)
+	cancel()
+	// If StartSweeper doesn't exit on cancel the test would leak a goroutine;
+	// the leak detector in the test runner will surface it.
+	time.Sleep(20 * time.Millisecond)
+}
+
+func TestMinBudgetClamp(t *testing.T) {
+	root := t.TempDir()
+	c, err := NewHLSCache(root, 0) // below floor
+	if err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+	if c.maxBytes != int64(hlsCacheMinBudgetGB)*1024*1024*1024 {
+		t.Fatalf("budget not clamped to min: got %d", c.maxBytes)
+	}
+}
+
+func TestTryAcquireWriterExclusive(t *testing.T) {
+	c := newTestCache(t, 1)
+	if !c.TryAcquireWriter("k") {
+		t.Fatal("first acquire should succeed")
+	}
+	if c.TryAcquireWriter("k") {
+		t.Fatal("second acquire for same key must fail")
+	}
+	if !c.TryAcquireWriter("other") {
+		t.Fatal("different key should not conflict")
+	}
+	c.ReleaseWriter("k")
+	if !c.TryAcquireWriter("k") {
+		t.Fatal("acquire after release should succeed")
+	}
+	c.ReleaseWriter("k")
+	c.ReleaseWriter("k") // idempotent
+}
+
+func TestStartupOrphanCleanup(t *testing.T) {
+	root := t.TempDir()
+
+	// Pre-seed: one sealed dir + one orphan old enough + one orphan fresh.
+	sealed := filepath.Join(root, "sealed")
+	_ = os.MkdirAll(sealed, 0o755)
+	_ = os.WriteFile(filepath.Join(sealed, hlsCacheCompleteMarker), nil, 0o644)
+
+	staleOrphan := filepath.Join(root, "stale_orphan")
+	_ = os.MkdirAll(staleOrphan, 0o755)
+	old := time.Now().Add(-2 * hlsCacheStartupOrphanAge)
+	_ = os.Chtimes(staleOrphan, old, old)
+
+	freshOrphan := filepath.Join(root, "fresh_orphan")
+	_ = os.MkdirAll(freshOrphan, 0o755)
+
+	if _, err := NewHLSCache(root, 1); err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+
+	if _, err := os.Stat(sealed); err != nil {
+		t.Fatal("sealed dir was wrongly removed")
+	}
+	if _, err := os.Stat(staleOrphan); err == nil {
+		t.Fatal("stale orphan should have been removed at startup")
+	}
+	if _, err := os.Stat(freshOrphan); err != nil {
+		t.Fatal("fresh orphan should be kept (might be a mid-restart encode)")
+	}
+}
+
+func TestHitMissCounters(t *testing.T) {
+	c := newTestCache(t, 1)
+	if s := c.Stats(); s.Hits != 0 || s.Misses != 0 {
+		t.Fatalf("fresh cache stats not zero: %+v", s)
+	}
+	c.RecordHit()
+	c.RecordHit()
+	c.RecordMiss()
+	s := c.Stats()
+	if s.Hits != 2 || s.Misses != 1 {
+		t.Fatalf("counters wrong: %+v", s)
+	}
+	// 2/3 = 67%
+	if got := c.hitRatePercent(); got != 67 {
+		t.Fatalf("hitRatePercent=%d, want 67", got)
+	}
+}
+
+func TestStatsEntryCount(t *testing.T) {
+	c := newTestCache(t, 1)
+	for _, k := range []string{"a", "b", "c"} {
+		dir := c.DirFor(k)
+		_ = os.MkdirAll(dir, 0o755)
+		_ = os.WriteFile(filepath.Join(dir, "x"), []byte("hello"), 0o644)
+	}
+	s := c.Stats()
+	if s.EntryCount != 3 {
+		t.Fatalf("EntryCount=%d, want 3", s.EntryCount)
+	}
+	if s.TotalBytes != 15 {
+		t.Fatalf("TotalBytes=%d, want 15", s.TotalBytes)
+	}
+}
+
+func TestVerifyCompleteRejectsMissingFiles(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "v"
+	dir := c.DirFor(key)
+	_ = os.MkdirAll(filepath.Join(dir, "video"), 0o755)
+
+	// No .complete yet → reject.
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject without .complete")
+	}
+
+	// Mark complete but no files → reject.
+	if err := c.MarkComplete(key); err != nil {
+		t.Fatalf("MarkComplete: %v", err)
+	}
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject when init.mp4 missing")
+	}
+
+	// Write init.mp4, last seg missing → reject.
+	_ = os.WriteFile(filepath.Join(dir, "video", "init.mp4"), []byte("..."), 0o644)
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject when last segment missing")
+	}
+
+	// Write last seg → pass.
+	_ = os.WriteFile(filepath.Join(dir, "video", "seg-1.m4s"), []byte("..."), 0o644)
+	if !c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should pass with all files present")
+	}
+
+	// Zero-size last seg → reject.
+	_ = os.WriteFile(filepath.Join(dir, "video", "seg-1.m4s"), nil, 0o644)
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject zero-size last segment")
+	}
+}
+
+func TestSweepRespectsPinnedExceedsBudget(t *testing.T) {
+	c := newTestCache(t, 1)
+	c.maxBytes = 256 // squeeze
+
+	pinned := c.DirFor("pinned")
+	_ = os.MkdirAll(pinned, 0o755)
+	_ = os.WriteFile(filepath.Join(pinned, "x"), make([]byte, 1024), 0o644)
+	c.Pin("pinned")
+
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep: %v", err)
+	}
+	if freed != 0 {
+		t.Fatalf("nothing should have been freed: got %d", freed)
+	}
+	if _, err := os.Stat(pinned); err != nil {
+		t.Fatal("pinned dir wrongly removed despite over-budget pin")
+	}
+}

internal/engine/hls_test.go

@@ -115,10 +115,11 @@ func TestRenderVideoPlaylist(t *testing.T) {
 }
 
 func TestRenderVideoPlaylistShortFinalSegment(t *testing.T) {
-	// 9.5s total, 4s segments → 3 segs of 4/4/1.5
+	// 9.5s total, 2s segments → 5 segs of 2/2/2/2/1.5
-	out := renderVideoPlaylist(9.5, 3)
+	segCount := segmentCountForDuration(9.5)
+	out := renderVideoPlaylist(9.5, segCount)
 	if !strings.Contains(out, "#EXTINF:1.500,") {
-		t.Errorf("expected final segment 1.5s in playlist, got:\n%s", out)
+		t.Errorf("expected final segment 1.5s in playlist (segCount=%d), got:\n%s", segCount, out)
 	}
 }
 

internal/engine/hwaccel.go

@@ -86,6 +86,117 @@ func listFFmpegEncoders(ctx context.Context, ffmpegPath string) string {
 	return string(out)
 }
 
+// HWAccelDiagnostic bundles what we know about the host's ffmpeg + HW encode
+// capabilities so the daemon can log a single coherent line at startup and the
+// web side can surface "this agent is software-only" without re-running probes.
+type HWAccelDiagnostic struct {
+	Pick          HWAccel  // backend selected by DetectHWAccel
+	FFmpegPath    string   // resolved ffmpeg binary
+	FFmpegVersion string   // first line of `ffmpeg -version` (e.g. "ffmpeg version 6.1.1")
+	Encoders      []string // HW + libsvtav1/libvpx9-class encoders found in -encoders output
+	Devices       []string // device files / drivers detected at probe time
+}
+
+// DetectHWAccelDiagnostic returns the full diagnostic picture for the host's
+// transcode pipeline. Unlike DetectHWAccel, this is NOT cached — callers pay
+// for an ffmpeg subprocess on each call (one `-encoders`, one `-version`).
+// Daemon startup is the natural caller; per-session lookups should keep using
+// DetectHWAccel (cached) and only re-probe diagnostics if the user runs an
+// explicit doctor command.
+func DetectHWAccelDiagnostic(ctx context.Context, ffmpegPath string) HWAccelDiagnostic {
+	d := HWAccelDiagnostic{Pick: HWAccelNone, FFmpegPath: ffmpegPath}
+	if ffmpegPath == "" {
+		return d
+	}
+	d.FFmpegVersion = ffmpegVersionLine(ctx, ffmpegPath)
+	encoders := listFFmpegEncoders(ctx, ffmpegPath)
+	for _, name := range hwEncoderNames {
+		if strings.Contains(encoders, name) {
+			d.Encoders = append(d.Encoders, name)
+		}
+	}
+	// Device-file checks mirror the picks below so the log line tells the
+	// reader why a present encoder might still have been rejected (e.g. NVENC
+	// compiled in but /dev/nvidia0 missing inside a container).
+	if fileExists("/dev/nvidia0") {
+		d.Devices = append(d.Devices, "/dev/nvidia0")
+	}
+	if fileExists("/dev/dri/renderD128") {
+		d.Devices = append(d.Devices, "/dev/dri/renderD128")
+	}
+	if hasNvidiaDriver() {
+		d.Devices = append(d.Devices, "nvidia-smi")
+	}
+	d.Pick = DetectHWAccel(ctx, ffmpegPath)
+	return d
+}
+
+// LogLine returns a one-line human-readable summary of the diagnostic,
+// suitable for daemon startup output. Format:
+//
+//	"[transcode] ffmpeg 6.1.1 at /usr/bin/ffmpeg, HW=nvenc (h264_nvenc), devices=/dev/nvidia0,nvidia-smi"
+//	"[transcode] ffmpeg 6.1.1 at /home/linuxbrew/.../ffmpeg, HW=none (software libx264) — no HW encoders compiled in"
+func (d HWAccelDiagnostic) LogLine() string {
+	var b strings.Builder
+	b.WriteString("[transcode] ")
+	if d.FFmpegVersion != "" {
+		b.WriteString(d.FFmpegVersion)
+	} else {
+		b.WriteString("ffmpeg")
+	}
+	if d.FFmpegPath != "" {
+		b.WriteString(" at ")
+		b.WriteString(d.FFmpegPath)
+	}
+	b.WriteString(", HW=")
+	b.WriteString(string(d.Pick))
+	if d.Pick == HWAccelNone {
+		if len(d.Encoders) == 0 {
+			b.WriteString(" (software libx264) — no HW encoders compiled in")
+		} else {
+			b.WriteString(" (software libx264) — encoders found but no matching device: ")
+			b.WriteString(strings.Join(d.Encoders, ","))
+		}
+	} else {
+		b.WriteString(" (")
+		b.WriteString(d.Pick.FFmpegVideoCodec("h264"))
+		b.WriteString(")")
+		if len(d.Devices) > 0 {
+			b.WriteString(", devices=")
+			b.WriteString(strings.Join(d.Devices, ","))
+		}
+	}
+	return b.String()
+}
+
+// hwEncoderNames lists the HW-accelerated encoders we care about for the
+// startup log. Kept in lookup order so the output reads predictably across
+// hosts.
+var hwEncoderNames = []string{
+	"h264_nvenc", "hevc_nvenc",
+	"h264_qsv", "hevc_qsv",
+	"h264_vaapi", "hevc_vaapi",
+	"h264_videotoolbox", "hevc_videotoolbox",
+}
+
+// ffmpegVersionLine extracts the "ffmpeg version X.Y.Z" prefix from
+// `ffmpeg -version`. Bounded to avoid hanging the daemon on a misbehaving
+// binary.
+func ffmpegVersionLine(ctx context.Context, ffmpegPath string) string {
+	cmd := exec.CommandContext(ctx, ffmpegPath, "-hide_banner", "-version")
+	out, err := cmd.CombinedOutput()
+	if err != nil || len(out) == 0 {
+		return ""
+	}
+	line, _, _ := strings.Cut(string(out), "\n")
+	// "ffmpeg version 6.1.1-some-build-suffix Copyright..." → keep up to first
+	// space after "version 6.x" to avoid spamming build flags into the log.
+	if idx := strings.Index(line, "Copyright"); idx > 0 {
+		line = strings.TrimSpace(line[:idx])
+	}
+	return strings.TrimSpace(line)
+}
+
 func fileExists(path string) bool {
 	_, err := os.Stat(path)
 	return err == nil
@@ -129,12 +240,13 @@ func (h HWAccel) FFmpegVideoCodec(target string) string {
 	}
 }
 
-// H264LevelForHeight returns the lowest H.264 profile level capable of encoding
+// H264LevelForHeight returns the lowest H.264 profile level capable of
-// a stream at the given output pixel height (assumes ~16:9, ≤30 fps). The
+// encoding a stream at the given output pixel height. Each tier carries
-// previous code used a fixed "4.0" which silently rejects anything above 1080p
+// enough macroblock headroom to handle ANAMORPHIC content (up to ~2.4:1
-// — libx264 logs "frame MB size > level limit" and emits a corrupt stream.
+// cinemascope) at 30 fps — a fixed 16:9 assumption used to silently bust
-// Returning a tighter level on smaller outputs keeps player compatibility on
+// the level on a 720p movie shot in 2.4:1 (1728×720 = 4860 MBs > 3.1's
-// older devices where the encoder can't auto-pick.
+// 3600 limit; libx264 logs "frame MB size > level limit" and emits a
+// corrupt stream).
 func H264LevelForHeight(height int) string {
 	switch {
 	case height <= 0:
@@ -142,11 +254,14 @@ func H264LevelForHeight(height int) string {
 		// re-introduce the silent-failure mode that motivated this helper.
 		return "5.1"
 	case height <= 480:
-		return "3.0"
-	case height <= 720:
 		return "3.1"
-	case height <= 1080:
+	case height <= 720:
+		// 4.0 instead of 3.1: covers 720p anamorphic (e.g. 1728×720) +
+		// MB rate up to 245k/s (3.1 caps at 108k/s — broken at 24 fps).
 		return "4.0"
+	case height <= 1080:
+		// 4.1 instead of 4.0: covers 1080p anamorphic + 30 fps (~245k MBs/s).
+		return "4.1"
 	case height <= 1440:
 		return "5.0"
 	case height <= 2160:

internal/engine/hwaccel_test.go

@@ -1,6 +1,9 @@
 package engine
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestHWAccelFFmpegVideoCodec(t *testing.T) {
 	cases := []struct {
@@ -32,3 +35,122 @@ func TestDetectHWAccelEmptyPathReturnsNone(t *testing.T) {
 		t.Errorf("got %s, want %s", got, HWAccelNone)
 	}
 }
+
+func TestResolveEncoderProfileDefaults(t *testing.T) {
+	cases := []struct {
+		hw         HWAccel
+		configured string
+		wantCodec  string
+		wantPreset string
+		wantHint   string
+	}{
+		// Empty configured preset → pick latency-biased default per backend.
+		// DecodeHwAccel matches the encoder family for HW encoders; libx264 +
+		// VideoToolbox have no demuxer hint.
+		{HWAccelNone, "", "libx264", "superfast", ""},
+		{HWAccelNVENC, "", "h264_nvenc", "p3", "cuda"},
+		{HWAccelQSV, "", "h264_qsv", "veryfast", "qsv"},
+		// VAAPI: decoder hint set, no preset, no `-hwaccel_output_format vaapi`
+		// (so the CPU filter chain can consume the decoded frames).
+		{HWAccelVAAPI, "", "h264_vaapi", "", "vaapi"},
+		// VideoToolbox has no preset knob — Preset should be "" regardless of input.
+		// VideoToolbox uses per-encoder flags, not a demuxer `-hwaccel` hint.
+		{HWAccelVideoToolbox, "p4", "h264_videotoolbox", "", ""},
+		{HWAccelVideoToolbox, "", "h264_videotoolbox", "", ""},
+	}
+	for _, tc := range cases {
+		got := ResolveEncoderProfile(tc.hw, tc.configured)
+		if got.Codec != tc.wantCodec || got.Preset != tc.wantPreset || got.DecodeHwAccel != tc.wantHint {
+			t.Errorf("ResolveEncoderProfile(%s, %q) = {codec=%s preset=%s hint=%s}, want {codec=%s preset=%s hint=%s}",
+				tc.hw, tc.configured,
+				got.Codec, got.Preset, got.DecodeHwAccel,
+				tc.wantCodec, tc.wantPreset, tc.wantHint)
+		}
+	}
+}
+
+func TestResolveEncoderProfileHonoursConfiguredPreset(t *testing.T) {
+	// Only libx264 honours the configured preset — the libx264 vocabulary
+	// (ultrafast…veryslow) doesn't apply to vendor encoders. NVENC has its
+	// own p1-p7 scale; QSV uses a different subset; VideoToolbox has no
+	// preset knob. Passing a libx264 preset to them would have ffmpeg reject
+	// the argv, so ResolveEncoderProfile always falls back to the hardcoded
+	// vendor preset for non-libx264 codecs.
+	cases := []struct {
+		hw         HWAccel
+		configured string
+		wantPreset string
+	}{
+		{HWAccelNone, "ultrafast", "ultrafast"},  // libx264 honours
+		{HWAccelNone, "medium", "medium"},        // libx264 honours
+		{HWAccelNVENC, "p1", "p3"},               // NVENC ignores, sticks to p3
+		{HWAccelNVENC, "veryfast", "p3"},         // NVENC ignores libx264 vocab
+		{HWAccelQSV, "veryslow", "veryfast"},     // QSV ignores, sticks to veryfast
+		{HWAccelVideoToolbox, "veryfast", ""},    // VideoToolbox has no preset
+	}
+	for _, tc := range cases {
+		got := ResolveEncoderProfile(tc.hw, tc.configured)
+		if got.Preset != tc.wantPreset {
+			t.Errorf("ResolveEncoderProfile(%s, %q).Preset = %q, want %q",
+				tc.hw, tc.configured, got.Preset, tc.wantPreset)
+		}
+	}
+}
+
+func TestHWAccelDiagnosticLogLineNone(t *testing.T) {
+	d := HWAccelDiagnostic{
+		Pick:          HWAccelNone,
+		FFmpegPath:    "/usr/local/bin/ffmpeg",
+		FFmpegVersion: "ffmpeg version 6.1.1",
+		Encoders:      nil,
+		Devices:       nil,
+	}
+	line := d.LogLine()
+	wantSubstrings := []string{
+		"ffmpeg version 6.1.1",
+		"/usr/local/bin/ffmpeg",
+		"HW=none",
+		"software libx264",
+		"no HW encoders compiled in",
+	}
+	for _, want := range wantSubstrings {
+		if !strings.Contains(line, want) {
+			t.Errorf("expected substring %q in log line; got %q", want, line)
+		}
+	}
+}
+
+func TestHWAccelDiagnosticLogLineNVENCWithDevices(t *testing.T) {
+	d := HWAccelDiagnostic{
+		Pick:          HWAccelNVENC,
+		FFmpegPath:    "/usr/bin/ffmpeg",
+		FFmpegVersion: "ffmpeg version 6.0",
+		Encoders:      []string{"h264_nvenc", "hevc_nvenc", "h264_qsv"},
+		Devices:       []string{"/dev/nvidia0", "nvidia-smi"},
+	}
+	line := d.LogLine()
+	for _, want := range []string{"HW=nvenc", "h264_nvenc", "/dev/nvidia0", "nvidia-smi"} {
+		if !strings.Contains(line, want) {
+			t.Errorf("expected substring %q in log line; got %q", want, line)
+		}
+	}
+}
+
+func TestHWAccelDiagnosticLogLineSoftwareButEncodersFound(t *testing.T) {
+	// Edge case: ffmpeg compiled WITH nvenc but no /dev/nvidia0 (container w/o GPU).
+	// LogLine should flag the encoders so the user knows where the gap is.
+	d := HWAccelDiagnostic{
+		Pick:          HWAccelNone,
+		FFmpegPath:    "/usr/bin/ffmpeg",
+		FFmpegVersion: "ffmpeg version 6.0",
+		Encoders:      []string{"h264_nvenc"},
+		Devices:       nil,
+	}
+	line := d.LogLine()
+	for _, want := range []string{"HW=none", "encoders found but no matching device", "h264_nvenc"} {
+		if !strings.Contains(line, want) {
+			t.Errorf("expected substring %q in log line; got %q", want, line)
+		}
+	}
+}
+

internal/engine/probe.go

@@ -9,7 +9,7 @@ import (
 )
 
 // StreamProbe summarises the codec / container shape of a file as it relates
-// to the WebRTC streaming pipeline. It tells the transcoder whether bytes can
+// to the HLS streaming pipeline. It tells the transcoder whether bytes can
 // be streamed as-is, just remuxed to fragmented MP4, or fully transcoded.
 type StreamProbe struct {
 	// VideoCodec lowercased — e.g. "h264", "hevc", "av1", "vp9", "mpeg4".
@@ -88,7 +88,15 @@ const (
 )
 
 // ProbeFile runs ffprobe and returns a StreamProbe view of the file.
+//
+// Result is memoised by (path, mtime, size) for probeCacheTTL — repeat plays
+// of the same file at the same quality (the HLS cache HIT path) skip ffprobe
+// entirely. ffprobe on a 50 GB MKV can cost 1-3 s; first-segment latency
+// shrinks by the same amount on the second play.
 func ProbeFile(ctx context.Context, ffprobePath, filePath string) (*StreamProbe, error) {
+	if cached, ok := lookupProbeCache(filePath); ok {
+		return cached, nil
+	}
 	mi, err := mediainfo.ExtractMediaInfo(ctx, ffprobePath, filePath)
 	if err != nil {
 		return nil, fmt.Errorf("probe: %w", err)
@@ -136,6 +144,7 @@ func ProbeFile(ctx context.Context, ffprobePath, filePath string) (*StreamProbe,
 			})
 		}
 	}
+	storeProbeCache(filePath, probe)
 	return probe, nil
 }
 

internal/engine/probe_cache.go

@@ -0,0 +1,141 @@
+package engine
+
+import (
+	"os"
+	"sync"
+	"time"
+)
+
+// probeCacheTTL is how long a cached probe stays usable. The cache key
+// already incorporates mtime + size, so the TTL is a defense against
+// runaway memory growth from stale paths, not a freshness guarantee — a
+// rename + recreate at the same inode (rare) would still be caught by the
+// mtime delta.
+const probeCacheTTL = 30 * time.Minute
+
+// probeCacheJanitorInterval is how often the background sweeper wakes to
+// drop expired entries. Lookup-time eviction handles hot paths, but a
+// user who browses 5k files and then stops would leak entries until each
+// is individually re-touched. 5 min ≈ 6 sweeps per TTL window — enough
+// to keep memory bounded without burning CPU.
+const probeCacheJanitorInterval = 5 * time.Minute
+
+type probeCacheEntry struct {
+	probe   *StreamProbe
+	expires time.Time
+}
+
+type probeCacheKey struct {
+	path  string
+	mtime int64 // ModTime().UnixNano()
+	size  int64
+}
+
+var (
+	probeCacheMu      sync.RWMutex
+	probeCache        = make(map[probeCacheKey]probeCacheEntry)
+	probeCacheJanitor sync.Once
+)
+
+// startProbeCacheJanitor launches the background sweeper exactly once per
+// process. Lazy — fired on first storeProbeCache. Drops expired entries
+// every probeCacheJanitorInterval. Idempotent (sync.Once).
+func startProbeCacheJanitor() {
+	probeCacheJanitor.Do(func() {
+		go func() {
+			ticker := time.NewTicker(probeCacheJanitorInterval)
+			defer ticker.Stop()
+			for range ticker.C {
+				sweepProbeCache(time.Now())
+			}
+		}()
+	})
+}
+
+// sweepProbeCache removes every entry whose expiry is at or before `now`.
+// Exposed for tests; production code calls it indirectly via the janitor
+// goroutine.
+func sweepProbeCache(now time.Time) int {
+	probeCacheMu.Lock()
+	defer probeCacheMu.Unlock()
+	removed := 0
+	for k, e := range probeCache {
+		if !now.Before(e.expires) {
+			delete(probeCache, k)
+			removed++
+		}
+	}
+	return removed
+}
+
+// lookupProbeCache returns the cached StreamProbe for the given path if its
+// mtime + size still match the value recorded at insert time, AND the cache
+// entry hasn't expired. Any stat failure / mismatch returns (nil, false) so
+// the caller falls through to a fresh ffprobe run.
+func lookupProbeCache(path string) (*StreamProbe, bool) {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return nil, false
+	}
+	key := probeCacheKey{
+		path:  path,
+		mtime: fi.ModTime().UnixNano(),
+		size:  fi.Size(),
+	}
+	probeCacheMu.RLock()
+	entry, ok := probeCache[key]
+	probeCacheMu.RUnlock()
+	if !ok {
+		return nil, false
+	}
+	if time.Now().After(entry.expires) {
+		// Re-check under the write lock so a concurrent re-insert (same key,
+		// fresh expiry) isn't accidentally evicted.
+		probeCacheMu.Lock()
+		if cur, stillThere := probeCache[key]; stillThere && time.Now().After(cur.expires) {
+			delete(probeCache, key)
+		}
+		probeCacheMu.Unlock()
+		return nil, false
+	}
+	return entry.probe, true
+}
+
+// storeProbeCache stashes a fresh probe result under the (path, mtime, size)
+// key. A subsequent ffprobe-skipping HIT requires the file to still have the
+// same mtime + size — anything else (re-encoded, renamed+recreated at the
+// same path, truncated) misses and triggers a re-probe.
+func storeProbeCache(path string, probe *StreamProbe) {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return
+	}
+	key := probeCacheKey{
+		path:  path,
+		mtime: fi.ModTime().UnixNano(),
+		size:  fi.Size(),
+	}
+	probeCacheMu.Lock()
+	probeCache[key] = probeCacheEntry{
+		probe:   probe,
+		expires: time.Now().Add(probeCacheTTL),
+	}
+	probeCacheMu.Unlock()
+	// Lazy janitor — fires once per process. No-op after first call.
+	startProbeCacheJanitor()
+}
+
+// ResetProbeCache clears the in-memory probe cache. Test-only.
+func ResetProbeCache() {
+	probeCacheMu.Lock()
+	probeCache = make(map[probeCacheKey]probeCacheEntry)
+	probeCacheMu.Unlock()
+}
+
+// ProbeCacheSize returns the number of entries currently cached. Exposed
+// for diagnostics + tests.
+func ProbeCacheSize() int {
+	probeCacheMu.RLock()
+	defer probeCacheMu.RUnlock()
+	return len(probeCache)
+}

internal/engine/probe_cache_test.go

@@ -0,0 +1,202 @@
+package engine
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestProbeCache_LookupMissNonexistent(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	if _, ok := lookupProbeCache("/path/that/does/not/exist"); ok {
+		t.Fatal("expected MISS for non-existent path")
+	}
+}
+
+func TestProbeCache_StoreThenLookupHit(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("fake content"), 0o644); err != nil {
+		t.Fatalf("write tmp file: %v", err)
+	}
+
+	probe := &StreamProbe{VideoCodec: "h264", Width: 1920, Height: 1080, DurationSec: 5400}
+	storeProbeCache(path, probe)
+
+	got, ok := lookupProbeCache(path)
+	if !ok {
+		t.Fatal("expected HIT after store")
+	}
+	if got != probe {
+		t.Fatalf("expected pointer-identical probe; got different")
+	}
+}
+
+func TestProbeCache_MtimeChangeInvalidates(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("original"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	probe := &StreamProbe{VideoCodec: "h264", DurationSec: 100}
+	storeProbeCache(path, probe)
+
+	// Force mtime change. WriteFile doesn't guarantee a different mtime if
+	// the filesystem timestamp resolution is coarse, so set it explicitly
+	// to a value 1 hour in the future.
+	future := time.Now().Add(1 * time.Hour)
+	if err := os.Chtimes(path, future, future); err != nil {
+		t.Fatalf("chtimes: %v", err)
+	}
+
+	if _, ok := lookupProbeCache(path); ok {
+		t.Fatal("expected MISS after mtime change")
+	}
+}
+
+func TestProbeCache_SizeChangeInvalidates(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("aaaaa"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	originalMtime := time.Now().Add(-1 * time.Hour) // stable, in the past
+	if err := os.Chtimes(path, originalMtime, originalMtime); err != nil {
+		t.Fatalf("chtimes original: %v", err)
+	}
+
+	probe := &StreamProbe{VideoCodec: "h264", DurationSec: 100}
+	storeProbeCache(path, probe)
+
+	// Truncate to a different size, then reset mtime to the original so
+	// only `size` differs between store and lookup keys — isolates the
+	// size-check path. Without the Chtimes, WriteFile bumps mtime and the
+	// test would pass via mtime invalidation regardless of size logic.
+	if err := os.WriteFile(path, []byte("a"), 0o644); err != nil {
+		t.Fatalf("rewrite: %v", err)
+	}
+	if err := os.Chtimes(path, originalMtime, originalMtime); err != nil {
+		t.Fatalf("chtimes restore: %v", err)
+	}
+
+	if _, ok := lookupProbeCache(path); ok {
+		t.Fatal("expected MISS after size change")
+	}
+}
+
+func TestProbeCache_ExpiryDropsEntry(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("content"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	// Stash an entry whose expires is already in the past — simulates TTL
+	// having elapsed without sleeping for 30 min.
+	fi, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	key := probeCacheKey{path: path, mtime: fi.ModTime().UnixNano(), size: fi.Size()}
+	probeCacheMu.Lock()
+	probeCache[key] = probeCacheEntry{
+		probe:   &StreamProbe{VideoCodec: "h264"},
+		expires: time.Now().Add(-1 * time.Minute),
+	}
+	probeCacheMu.Unlock()
+
+	if _, ok := lookupProbeCache(path); ok {
+		t.Fatal("expected MISS for expired entry")
+	}
+	// Side-effect: lookup should have evicted the stale entry.
+	if ProbeCacheSize() != 0 {
+		t.Fatalf("expected cache size 0 after expiry eviction; got %d", ProbeCacheSize())
+	}
+}
+
+func TestProbeCache_ResetClears(t *testing.T) {
+	ResetProbeCache()
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("x"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	storeProbeCache(path, &StreamProbe{VideoCodec: "h264"})
+	if ProbeCacheSize() != 1 {
+		t.Fatalf("expected size 1 after store; got %d", ProbeCacheSize())
+	}
+
+	ResetProbeCache()
+	if ProbeCacheSize() != 0 {
+		t.Fatalf("expected size 0 after reset; got %d", ProbeCacheSize())
+	}
+}
+
+func TestProbeCache_StoreNonexistentNoOp(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	// Store on a non-existent path should silently do nothing (stat fails),
+	// not panic, and not poison the cache with a zero key.
+	storeProbeCache("/nope/never/exists.mkv", &StreamProbe{VideoCodec: "h264"})
+	if ProbeCacheSize() != 0 {
+		t.Fatalf("expected 0 entries; got %d", ProbeCacheSize())
+	}
+}
+
+func TestProbeCache_SweepDropsExpired(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	// Two entries: one expired, one fresh.
+	expiredPath := filepath.Join(dir, "old.mkv")
+	freshPath := filepath.Join(dir, "new.mkv")
+	if err := os.WriteFile(expiredPath, []byte("a"), 0o644); err != nil {
+		t.Fatalf("write expired: %v", err)
+	}
+	if err := os.WriteFile(freshPath, []byte("b"), 0o644); err != nil {
+		t.Fatalf("write fresh: %v", err)
+	}
+
+	now := time.Now()
+	fiExp, _ := os.Stat(expiredPath)
+	fiFresh, _ := os.Stat(freshPath)
+
+	probeCacheMu.Lock()
+	probeCache[probeCacheKey{path: expiredPath, mtime: fiExp.ModTime().UnixNano(), size: fiExp.Size()}] = probeCacheEntry{
+		probe:   &StreamProbe{VideoCodec: "h264"},
+		expires: now.Add(-1 * time.Minute), // expired
+	}
+	probeCache[probeCacheKey{path: freshPath, mtime: fiFresh.ModTime().UnixNano(), size: fiFresh.Size()}] = probeCacheEntry{
+		probe:   &StreamProbe{VideoCodec: "h264"},
+		expires: now.Add(10 * time.Minute), // fresh
+	}
+	probeCacheMu.Unlock()
+
+	removed := sweepProbeCache(now)
+	if removed != 1 {
+		t.Fatalf("expected 1 expired entry removed; got %d", removed)
+	}
+	if ProbeCacheSize() != 1 {
+		t.Fatalf("expected 1 fresh entry kept; got %d", ProbeCacheSize())
+	}
+}

internal/engine/seed_file.go

@@ -1,138 +0,0 @@
-package engine
-
-import (
-	"errors"
-	"fmt"
-	"os"
-	"path/filepath"
-	"time"
-
-	"github.com/anacrolix/torrent"
-	"github.com/anacrolix/torrent/bencode"
-	"github.com/anacrolix/torrent/metainfo"
-)
-
-// SeedFile builds a single-file torrent from an arbitrary on-disk file
-// and adds it to an existing torrent client so the WebRTC peer wire
-// (already configured on the client) can serve the file to a browser
-// that knows the resulting info-hash.
-//
-// Returns the generated info-hash. The torrent is left attached to the
-// client — caller is responsible for keeping it alive while a browser
-// is watching. Drop it via Client.RemoveTorrent / Torrent.Drop when
-// idle to free resources.
-//
-// Behaviour notes:
-//   - The file must already exist; no download is attempted.
-//   - Piece length follows the libtorrent ladder (16 KiB → 4 MiB).
-//   - The torrent is "complete" from the agent's POV — it has every
-//     piece — so the upload-only flow kicks in immediately.
-//   - WebRTC peer behaviour comes from the client config the caller
-//     constructed; SeedFile does not toggle DisableWebtorrent itself.
-//     If the operator's [downloads.webrtc].enabled = false, the file
-//     is still added but no browser will discover it via WSS tracker.
-func SeedFile(client *torrent.Client, filePath string, trackerURLs []string) (metainfo.Hash, error) {
-	if client == nil {
-		return metainfo.Hash{}, errors.New("seed_file: torrent client is nil")
-	}
-	if filePath == "" {
-		return metainfo.Hash{}, errors.New("seed_file: filePath is empty")
-	}
-
-	abs, err := filepath.Abs(filePath)
-	if err != nil {
-		return metainfo.Hash{}, fmt.Errorf("seed_file: resolve path: %w", err)
-	}
-	st, err := os.Stat(abs)
-	if err != nil {
-		return metainfo.Hash{}, fmt.Errorf("seed_file: stat: %w", err)
-	}
-	if st.IsDir() {
-		return metainfo.Hash{}, fmt.Errorf("seed_file: only single files are supported, %s is a directory", abs)
-	}
-
-	info := metainfo.Info{
-		PieceLength: chooseSeedPieceLength(st.Size()),
-		Name:        filepath.Base(abs),
-	}
-	if err := info.BuildFromFilePath(abs); err != nil {
-		return metainfo.Hash{}, fmt.Errorf("seed_file: build info: %w", err)
-	}
-	infoBytes, err := bencode.Marshal(info)
-	if err != nil {
-		return metainfo.Hash{}, fmt.Errorf("seed_file: marshal info: %w", err)
-	}
-
-	mi := &metainfo.MetaInfo{
-		InfoBytes:    infoBytes,
-		AnnounceList: makeAnnounceList(trackerURLs),
-		CreatedBy:    "unarr-seed-file",
-		CreationDate: time.Now().Unix(),
-	}
-	ih := mi.HashInfoBytes()
-
-	t, err := client.AddTorrent(mi)
-	if err != nil {
-		return metainfo.Hash{}, fmt.Errorf("seed_file: add torrent: %w", err)
-	}
-	// Mark every piece as needed so the client treats us as a complete
-	// seeder right away — anacrolix's verifier will hash the file
-	// asynchronously and flip pieces to "have" as it goes.
-	t.DownloadAll()
-
-	return ih, nil
-}
-
-// makeAnnounceList shapes the tracker URL slice into the bencoded
-// AnnounceList format anacrolix expects.
-func makeAnnounceList(urls []string) metainfo.AnnounceList {
-	if len(urls) == 0 {
-		return nil
-	}
-	tier := make([]string, 0, len(urls))
-	for _, u := range urls {
-		if u == "" {
-			continue
-		}
-		tier = append(tier, u)
-	}
-	if len(tier) == 0 {
-		return nil
-	}
-	return metainfo.AnnounceList{tier}
-}
-
-// chooseSeedPieceLength picks the piece size for a single-file torrent
-// based on the libtorrent / qBittorrent ladder. Mirrored from the
-// wstracker-probe seeder so generated torrents are interoperable.
-func chooseSeedPieceLength(size int64) int64 {
-	switch {
-	case size < 4*1024*1024:
-		return 16 * 1024
-	case size < 64*1024*1024:
-		return 64 * 1024
-	case size < 512*1024*1024:
-		return 256 * 1024
-	case size < 4*1024*1024*1024:
-		return 1024 * 1024
-	default:
-		return 4 * 1024 * 1024
-	}
-}
-
-// SeedFileOnDownloader is a convenience wrapper that pulls the
-// underlying anacrolix client out of a TorrentDownloader and forwards
-// to SeedFile. trackerURLs default to the downloader's WebRTC
-// trackers when nil/empty.
-func SeedFileOnDownloader(d *TorrentDownloader, filePath string) (metainfo.Hash, error) {
-	if d == nil {
-		return metainfo.Hash{}, errors.New("seed_file: downloader is nil")
-	}
-	trackers := d.cfg.WebRTCTrackers
-	if !d.cfg.WebRTCEnabled {
-		// We could still build the torrent, but no browser would find
-		// it via the WSS tracker — bail loud so the operator notices.
-		return metainfo.Hash{}, errors.New("seed_file: WebRTC peer disabled in config; set [downloads.webrtc].enabled = true to use this feature")
-	}
-	return SeedFile(d.client, filePath, trackers)
-}

internal/engine/seed_file_test.go

@@ -1,164 +0,0 @@
-package engine
-
-import (
-	"context"
-	"os"
-	"path/filepath"
-	"testing"
-)
-
-// TestSeedFile_RejectsMissingFile — explicit error rather than crashing
-// inside anacrolix when the path doesn't exist.
-func TestSeedFile_RejectsMissingFile(t *testing.T) {
-	dir := t.TempDir()
-	dl, err := NewTorrentDownloader(TorrentConfig{
-		DataDir:        dir,
-		ListenPort:     0,
-		WebRTCEnabled:  true,
-		WebRTCTrackers: []string{"wss://tracker.torrentclaw.com"},
-	})
-	if err != nil {
-		t.Fatalf("NewTorrentDownloader: %v", err)
-	}
-	defer dl.Shutdown(context.Background())
-
-	if _, err := SeedFile(dl.client, "/nonexistent/path", nil); err == nil {
-		t.Fatal("expected error for missing file")
-	}
-}
-
-// TestSeedFile_RejectsDirectory — single-file torrents only for now.
-func TestSeedFile_RejectsDirectory(t *testing.T) {
-	dir := t.TempDir()
-	dl, err := NewTorrentDownloader(TorrentConfig{
-		DataDir:        dir,
-		ListenPort:     0,
-		WebRTCEnabled:  true,
-		WebRTCTrackers: []string{"wss://tracker.torrentclaw.com"},
-	})
-	if err != nil {
-		t.Fatalf("NewTorrentDownloader: %v", err)
-	}
-	defer dl.Shutdown(context.Background())
-
-	subDir := filepath.Join(dir, "sub")
-	if err := os.Mkdir(subDir, 0o755); err != nil {
-		t.Fatalf("mkdir: %v", err)
-	}
-
-	if _, err := SeedFile(dl.client, subDir, nil); err == nil {
-		t.Fatal("expected error for directory path")
-	}
-}
-
-// TestSeedFile_BuildsDeterministicInfoHash — the same file should yield
-// the same info_hash on every call so the web client can poll for it.
-func TestSeedFile_BuildsDeterministicInfoHash(t *testing.T) {
-	dir := t.TempDir()
-	file := filepath.Join(dir, "data.bin")
-	payload := []byte("hello world — torrentclaw seed_file test")
-	if err := os.WriteFile(file, payload, 0o644); err != nil {
-		t.Fatalf("write file: %v", err)
-	}
-
-	mkClient := func() *TorrentDownloader {
-		dl, err := NewTorrentDownloader(TorrentConfig{
-			DataDir:        t.TempDir(),
-			ListenPort:     0,
-			WebRTCEnabled:  true,
-			WebRTCTrackers: []string{"wss://tracker.torrentclaw.com"},
-		})
-		if err != nil {
-			t.Fatalf("NewTorrentDownloader: %v", err)
-		}
-		return dl
-	}
-
-	dl1 := mkClient()
-	defer dl1.Shutdown(context.Background())
-	hash1, err := SeedFile(dl1.client, file, []string{"wss://tracker.torrentclaw.com"})
-	if err != nil {
-		t.Fatalf("first SeedFile: %v", err)
-	}
-
-	dl2 := mkClient()
-	defer dl2.Shutdown(context.Background())
-	hash2, err := SeedFile(dl2.client, file, []string{"wss://tracker.torrentclaw.com"})
-	if err != nil {
-		t.Fatalf("second SeedFile: %v", err)
-	}
-
-	if hash1 != hash2 {
-		t.Fatalf("info_hash not deterministic: %s vs %s", hash1.HexString(), hash2.HexString())
-	}
-	if hash1.HexString() == "" || len(hash1.HexString()) != 40 {
-		t.Fatalf("info_hash is not 40 hex chars: %q", hash1.HexString())
-	}
-}
-
-// TestSeedFileOnDownloader_RequiresWebRTC — silent failure mode is the
-// worst UX; bail loud when the operator hasn't opted into WebRTC.
-func TestSeedFileOnDownloader_RequiresWebRTC(t *testing.T) {
-	dir := t.TempDir()
-	dl, err := NewTorrentDownloader(TorrentConfig{
-		DataDir:       dir,
-		ListenPort:    0,
-		WebRTCEnabled: false,
-	})
-	if err != nil {
-		t.Fatalf("NewTorrentDownloader: %v", err)
-	}
-	defer dl.Shutdown(context.Background())
-
-	file := filepath.Join(dir, "data.bin")
-	if err := os.WriteFile(file, []byte("x"), 0o644); err != nil {
-		t.Fatalf("write file: %v", err)
-	}
-
-	if _, err := SeedFileOnDownloader(dl, file); err == nil {
-		t.Fatal("expected error when WebRTC disabled")
-	}
-}
-
-// TestChooseSeedPieceLength_LadderShape — sanity-check the breakpoints
-// stay aligned with the libtorrent reference (16 KiB → 4 MiB).
-func TestChooseSeedPieceLength_LadderShape(t *testing.T) {
-	cases := []struct {
-		size   int64
-		expect int64
-	}{
-		{1, 16 * 1024},
-		{4 * 1024 * 1024, 64 * 1024},
-		{64 * 1024 * 1024, 256 * 1024},
-		{512 * 1024 * 1024, 1024 * 1024},
-		{4 * 1024 * 1024 * 1024, 4 * 1024 * 1024},
-	}
-	for _, c := range cases {
-		if got := chooseSeedPieceLength(c.size); got != c.expect {
-			t.Errorf("chooseSeedPieceLength(%d) = %d want %d", c.size, got, c.expect)
-		}
-	}
-}
-
-// TestMakeAnnounceList_HandlesEmpty — nil/empty in → nil out, so
-// AddTorrent doesn't see a dangling tier with no URLs.
-func TestMakeAnnounceList_HandlesEmpty(t *testing.T) {
-	if got := makeAnnounceList(nil); got != nil {
-		t.Errorf("nil input should yield nil announce list, got %+v", got)
-	}
-	if got := makeAnnounceList([]string{}); got != nil {
-		t.Errorf("empty input should yield nil announce list, got %+v", got)
-	}
-	if got := makeAnnounceList([]string{"", " ", ""}); got != nil {
-		// Empty strings should be filtered; if everything is empty,
-		// nil is the right answer.
-		// (We do NOT trim whitespace today — only literal "".)
-		if len(got) != 1 || len(got[0]) != 1 {
-			t.Errorf("expected 1 single-element tier, got %+v", got)
-		}
-	}
-	got := makeAnnounceList([]string{"wss://a", "", "wss://b"})
-	if len(got) != 1 || len(got[0]) != 2 {
-		t.Fatalf("expected 1 tier of 2 URLs, got %+v", got)
-	}
-}

internal/engine/stream_source.go

@@ -12,7 +12,7 @@ import (
 	"time"
 )
 
-// streamSource abstracts the byte source served over the WebRTC DataChannel.
+// streamSource abstracts the byte source consumed by the HLS transcoder.
 // Two implementations:
 //   - diskFileSource — direct passthrough of the on-disk file.
 //   - transcodeSource — ffmpeg writes a fragmented MP4 to a temp file in

internal/engine/torrent.go

@@ -16,7 +16,6 @@ import (
 	alog "github.com/anacrolix/log"
 	"github.com/anacrolix/torrent"
 	"github.com/anacrolix/torrent/storage"
-	"github.com/pion/webrtc/v4"
 	"github.com/torrentclaw/unarr/internal/config"
 	"github.com/torrentclaw/unarr/internal/vpn"
 	"golang.org/x/term"
@@ -73,14 +72,6 @@ type TorrentConfig struct {
 	SeedRatio       float64       // target seed ratio (default 0, meaning seed until SeedTime)
 	SeedTime        time.Duration // min seed time after completion (default 0)
 
-	// WebRTC peer (WebTorrent protocol) for browser ↔ unarr P2P streaming.
-	// When enabled, anacrolix/torrent's built-in webtorrent package handles
-	// the WSS signaling + WebRTC data channels. Implies upload allowed for
-	// every torrent in the client (browsers can't pull pieces otherwise).
-	WebRTCEnabled  bool
-	WebRTCTrackers []string           // wss://… signaling trackers added to every magnet
-	ICEServers     []webrtc.ICEServer // STUN + TURN servers for NAT traversal
-
 	// VPNTunnel, when set, split-tunnels the torrent client's peer + tracker
 	// traffic through an in-process userspace WireGuard tunnel (managed-VPN
 	// add-on). nil = downloads in the clear. Brought up by the daemon.
@@ -111,26 +102,11 @@ func NewTorrentDownloader(cfg TorrentConfig) (*TorrentDownloader, error) {
 	tcfg := torrent.NewDefaultClientConfig()
 	tcfg.DataDir = cfg.DataDir
 	tcfg.Seed = cfg.SeedEnabled
-	// WebRTC peers (browsers) can only pull pieces from us if upload is
+	tcfg.NoUpload = !cfg.SeedEnabled
-	// enabled. We honour SeedEnabled for the long-tail seed-after-complete
+	tcfg.Logger = alog.Default.FilterLevel(alog.Warning)
-	// behaviour but unconditionally allow upload while WebRTC is on so an
-	// active download can still serve to a watching browser.
-	tcfg.NoUpload = !cfg.SeedEnabled && !cfg.WebRTCEnabled
-	tcfg.Logger = alog.Default.FilterLevel(alog.Warning) // bumped from Critical for WebRTC peer + tracker announce visibility
 
-	// WebRTC / WebTorrent peer: anacrolix auto-routes ws://+wss:// trackers
+	// No browser-facing WebTorrent peer; daemon never seeds via WSS.
-	// to the bundled webtorrent.TrackerClient. We only need to populate the
+	tcfg.DisableWebtorrent = true
-	// ICE server list so the SDP offers we send carry usable candidates.
-	if cfg.WebRTCEnabled {
-		tcfg.DisableWebtorrent = false
-		if len(cfg.ICEServers) > 0 {
-			tcfg.ICEServerList = cfg.ICEServers
-		}
-		log.Printf("[torrent] WebRTC peer enabled (trackers=%d ice_servers=%d)",
-			len(cfg.WebRTCTrackers), len(cfg.ICEServers))
-	} else {
-		tcfg.DisableWebtorrent = true
-	}
 
 	// --- Performance optimizations ---
 
@@ -657,30 +633,17 @@ func (d *TorrentDownloader) selectFiles(t *torrent.Torrent, taskID string) (tota
 	return totalBytes, fileName
 }
 
-// buildMagnet composes a magnet URI for the info hash. extraTrackers (e.g.
+// buildMagnet composes a magnet URI for the info hash with the static
-// wss://… for WebRTC peer signaling) are prepended so anacrolix's
+// tracker list.
-// webtorrent.TrackerClient picks them up first; the static UDP list
+func buildMagnet(infoHash string) string {
-// follows. Empty / whitespace entries in extraTrackers are skipped.
-func buildMagnet(infoHash string, extraTrackers ...string) string {
 	params := []string{"xt=urn:btih:" + infoHash}
-	for _, t := range extraTrackers {
-		t = strings.TrimSpace(t)
-		if t == "" {
-			continue
-		}
-		params = append(params, "tr="+url.QueryEscape(t))
-	}
 	for _, tracker := range defaultTrackers {
 		params = append(params, "tr="+url.QueryEscape(tracker))
 	}
 	return "magnet:?" + strings.Join(params, "&")
 }
 
-// buildMagnet on the downloader injects its WebRTC trackers when enabled.
 func (d *TorrentDownloader) buildMagnet(infoHash string) string {
-	if d != nil && d.cfg.WebRTCEnabled {
-		return buildMagnet(infoHash, d.cfg.WebRTCTrackers...)
-	}
 	return buildMagnet(infoHash)
 }
 

internal/engine/transcode_quality.go

@@ -0,0 +1,64 @@
+package engine
+
+// TranscodeRuntime carries the resolved ffmpeg/ffprobe paths + tunables so
+// each session can decide whether to passthrough or pipe through ffmpeg.
+type TranscodeRuntime struct {
+	FFmpegPath   string
+	FFprobePath  string
+	HWAccel      HWAccel
+	Preset       string
+	VideoBitrate string
+	AudioBitrate string
+	MaxHeight    int
+	// Disabled forces passthrough for every file even when codecs are not
+	// browser-friendly. Useful when the user explicitly turns transcoding
+	// off in config.
+	Disabled bool
+}
+
+// qualityCap maps a session's Quality label to a (MaxHeight, VideoBitrate)
+// pair. An empty label or "original" returns zero-values, signalling "no
+// override" to the caller.
+type qualityCap struct {
+	MaxHeight    int
+	VideoBitrate string // ffmpeg -b:v string, e.g. "3500k"
+}
+
+func resolveQualityCap(label string) qualityCap {
+	switch label {
+	case "2160p":
+		return qualityCap{MaxHeight: 2160, VideoBitrate: "25000k"}
+	case "1080p":
+		return qualityCap{MaxHeight: 1080, VideoBitrate: "6000k"}
+	case "720p":
+		return qualityCap{MaxHeight: 720, VideoBitrate: "3500k"}
+	case "480p":
+		return qualityCap{MaxHeight: 480, VideoBitrate: "1500k"}
+	default:
+		// "original", "auto", "" → defer to config.
+		return qualityCap{}
+	}
+}
+
+// capForHeight returns the bitrate-cap pair appropriate for an effective
+// output height. Used after clamping outputHeight to the source's resolution:
+// asking ffmpeg for "2160p" bitrate (25 Mbps) on a 1080p source overshoots
+// the H.264 level we derived from the EFFECTIVE height (4.0, max 20 Mbps) and
+// makes libx264 refuse with "VBV bitrate > level limit". This helper picks
+// the bitrate that matches the level libx264 will actually accept.
+func capForHeight(height int) qualityCap {
+	switch {
+	case height <= 0:
+		return qualityCap{}
+	case height <= 480:
+		return qualityCap{MaxHeight: 480, VideoBitrate: "1500k"}
+	case height <= 720:
+		return qualityCap{MaxHeight: 720, VideoBitrate: "3500k"}
+	case height <= 1080:
+		return qualityCap{MaxHeight: 1080, VideoBitrate: "6000k"}
+	case height <= 1440:
+		return qualityCap{MaxHeight: 1440, VideoBitrate: "12000k"}
+	default:
+		return qualityCap{MaxHeight: 2160, VideoBitrate: "25000k"}
+	}
+}

internal/engine/transcoder.go

@@ -11,10 +11,9 @@ import (
 	"time"
 )
 
-// TranscodeOpts steers how Transcoder builds its ffmpeg command line. Defaults
+// TranscodeOpts steers how Transcoder builds its ffmpeg command line.
-// match the project's plan/clever-weaving-dove.md (Fase 2.5):
 //
-//   - Output: fragmented MP4 readable by browser <video> via MSE-less Range.
+//   - Output: fragmented MP4 chunked into HLS segments by the muxer.
 //   - Audio: AAC stereo @ 192kbps unless source already AAC (then -c:a copy).
 //   - Video: copy when h264 8-bit; otherwise transcode to h264 with HW encode
 //     when available, software fallback at "veryfast" preset.
@@ -31,11 +30,11 @@ type TranscodeOpts struct {
 }
 
 // Transcoder wraps a long-running ffmpeg child process whose stdout streams
-// fragmented MP4 bytes for the WebRTC pump to forward to the browser.
+// fragmented MP4 bytes; the HLS muxer slices them into segments served over HTTP.
 //
 // One Transcoder == one playback position. A seek beyond the buffered window
 // requires Close()ing this transcoder and starting a new one with a higher
-// StartSeconds (handled in webrtc_stream.go).
+// StartSeconds (handled by the HLS session at ffmpeg start time).
 //
 // A single internal goroutine owns cmd.Wait() — never call cmd.Wait()
 // directly from outside (os/exec forbids concurrent Wait callers). Use
@@ -269,12 +268,9 @@ func buildFFmpegArgs(filePath string, opts TranscodeOpts) []string {
 			filterChain = "format=yuv420p,setparams=colorspace=bt709:color_trc=bt709:color_primaries=bt709:range=tv"
 		}
 		args = append(args, "-vf", filterChain)
-		// Force AAC-LC stereo 48 kHz so MSE's CHUNK_DEMUXER accepts the moov.
+		// Force AAC-LC stereo 48 kHz so the hls.js demuxer accepts the moov.
-		// 5.1 / 7.1 source streams produce a moov shape that MSE refuses to
+		// 5.1 / 7.1 source streams produce a moov shape the demuxer refuses
-		// parse (the <video src=blob:> demuxer is more forgiving), so we
+		// to parse, so always downmix to stereo + resample to 48 kHz here.
-		// always downmix to stereo and resample to 48 kHz here. Source
-		// material that's already stereo passes through losslessly aside
-		// from the re-encode.
 		args = append(args,
 			"-c:a", "aac",
 			"-b:a", coalesce(opts.AudioBitrate, "192k"),
@@ -285,13 +281,12 @@ func buildFFmpegArgs(filePath string, opts TranscodeOpts) []string {
 
 	// Common output flags — fragmented MP4 to a single pipe.
 	//
-	//   * empty_moov + default_base_moof: write a header-only init segment
+	//   * empty_moov + default_base_moof: header-only init segment up front
-	//     up front so MSE can start decoding before the file is finished.
+	//     so the demuxer can start decoding before the file is finished.
-	//   * frag_duration=1s: cap each moof+mdat at ~1 second of media. Without
+	//   * frag_duration=1s: cap each moof+mdat at ~1 second of media.
-	//     this, ffmpeg only splits at keyframes, which on a high-bitrate
+	//     Without it ffmpeg only splits at keyframes; a high-bitrate 1080p
-	//     1080p stream produces 8 MiB+ mdat boxes — MSE refuses to parse
+	//     stream produces 8 MiB+ mdat boxes that delay the first fragment
-	//     the first fragment until the whole mdat lands, so playback never
+	//     until the whole mdat lands and playback never starts.
-	//     starts.
 	//   * negative_cts_offsets: lets b-frames carry the right pts/dts so
 	//     decoders don't reset the playhead to 0 every fragment.
 	args = append(args,

internal/engine/vaapi_args_test.go

@@ -0,0 +1,97 @@
+package engine
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestBuildHLSFFmpegArgsVAAPI(t *testing.T) {
+	cfg := HLSSessionConfig{
+		SessionID:  "test",
+		SourcePath: "/tmp/test.mkv",
+		Quality:    "720p",
+		AudioIndex: 0,
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelVAAPI,
+		},
+	}
+	probe := &StreamProbe{Width: 1920, Height: 1080, DurationSec: 100}
+	args := buildHLSFFmpegArgsAt(cfg, probe, "/tmp/tmpdir", 0, 0)
+	got := strings.Join(args, " ")
+
+	wants := []string{
+		"-hwaccel vaapi",
+		"-vaapi_device /dev/dri/renderD128",
+		"-c:v h264_vaapi",
+		"format=nv12",
+		"hwupload",
+	}
+	for _, want := range wants {
+		if !strings.Contains(got, want) {
+			t.Errorf("argv missing %q\n%s", want, got)
+		}
+	}
+	if strings.Contains(got, "scale_vaapi") {
+		t.Errorf("argv unexpectedly contains scale_vaapi (mesa bug): %s", got)
+	}
+	if strings.Contains(got, "format=yuv420p") {
+		t.Errorf("argv contains format=yuv420p (libx264 path) for VAAPI codec: %s", got)
+	}
+}
+
+func TestBuildHLSFFmpegArgsLibx264NoRegression(t *testing.T) {
+	cfg := HLSSessionConfig{
+		SessionID:  "test",
+		SourcePath: "/tmp/test.mkv",
+		Quality:    "720p",
+		AudioIndex: 0,
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelNone,
+		},
+	}
+	probe := &StreamProbe{Width: 1920, Height: 1080, DurationSec: 100}
+	args := buildHLSFFmpegArgsAt(cfg, probe, "/tmp/tmpdir", 0, 0)
+	got := strings.Join(args, " ")
+	for _, want := range []string{"-c:v libx264", "format=yuv420p", "setparams=colorspace=bt709"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("libx264 argv missing %q: %s", want, got)
+		}
+	}
+	for _, bad := range []string{"-vaapi_device", "format=nv12", "hwupload"} {
+		if strings.Contains(got, bad) {
+			t.Errorf("libx264 argv unexpectedly contains %q: %s", bad, got)
+		}
+	}
+}
+
+// TestBuildHLSFFmpegArgsVAAPIDump prints the full argv buildHLSFFmpegArgsAt
+// emits for a typical VAAPI session. Mimics the daemon spawn step so the
+// operator can verify the ffmpeg command-line shape without booting the
+// stack — equivalent to `journalctl --user -u unarr-dev | grep ffmpeg`
+// but without waiting for a real player session.
+func TestBuildHLSFFmpegArgsVAAPIDump(t *testing.T) {
+	cfg := HLSSessionConfig{
+		SessionID:  "vaapi-smoke",
+		SourcePath: "/mnt/nas/peliculas/sample.mkv",
+		Quality:    "720p",
+		AudioIndex: -1,
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelVAAPI,
+		},
+	}
+	probe := &StreamProbe{
+		VideoCodec:  "hevc",
+		Width:       3840,
+		Height:      2160,
+		DurationSec: 5400,
+		AudioTracks: []ProbeAudioTrack{{Index: 0, Lang: "en", Codec: "ac3"}},
+	}
+	args := buildHLSFFmpegArgsAt(cfg, probe, "/tmp/smoke-tmpdir", 0, 0)
+	t.Logf("ffmpeg %s", strings.Join(args, " "))
+}

internal/engine/validate.go

@@ -21,12 +21,27 @@ var validSessionID = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,128}$`)
 // 127.0.0.1 is listed in addition to localhost because some browsers treat
 // them as distinct origins for CORS.
 //
+// Mirrors (`.to`, `staging.torrentclaw.com`, `www.`) are listed so a user
+// playing from any official mirror succeeds the HEAD probe; without these
+// the browser drops the response for "missing ACAO" and the player reports
+// "404 todos los canales" even though the daemon returned 200.
+//
 // Note: media tags (<video src>, <audio src>) do not send the Origin
 // header so they are not gated by CORS at all; this allowlist only
 // affects fetch()/XHR.
 var defaultCORSAllowedOrigins = []string{
 	"https://torrentclaw.com",
+	"https://www.torrentclaw.com",
 	"https://app.torrentclaw.com",
+	"https://staging.torrentclaw.com",
+	"https://torrentclaw.to",
+	"https://www.torrentclaw.to",
+	// Tor mirror — Tor Browser sends `Origin: http://<addr>.onion` (plain
+	// http, no port). Mirror address is the BUILT_IN_ONION constant from
+	// torrentclaw-web/src/lib/mirrors-config.ts; rotates rarely, kept in
+	// sync by hand. Daemon also dynamically merges /api/mirrors at startup
+	// (see daemon.go) so a new key doesn't need a CLI rebuild.
+	"http://torrentf3aifidcsaaanmnmuhv2s53r6hqsl3zkmfidiaxainkeqk5id.onion",
 	"http://localhost:3030",
 	"http://127.0.0.1:3030",
 }

internal/engine/webrtc.go

@@ -1,36 +0,0 @@
-package engine
-
-import (
-	"github.com/pion/webrtc/v4"
-	"github.com/torrentclaw/unarr/internal/config"
-)
-
-// BuildICEServers converts a config.WebRTCConfig into the
-// []webrtc.ICEServer slice that anacrolix/torrent's webtorrent client
-// needs. STUN entries become bare URLs; TURN entries inherit the shared
-// TURNUser / TURNPass credentials. Returns nil when WebRTC is disabled.
-func BuildICEServers(cfg config.WebRTCConfig) []webrtc.ICEServer {
-	if !cfg.Enabled {
-		return nil
-	}
-	var servers []webrtc.ICEServer
-	for _, s := range cfg.STUNServers {
-		if s == "" {
-			continue
-		}
-		servers = append(servers, webrtc.ICEServer{URLs: []string{s}})
-	}
-	for _, t := range cfg.TURNServers {
-		if t == "" {
-			continue
-		}
-		entry := webrtc.ICEServer{URLs: []string{t}}
-		if cfg.TURNUser != "" {
-			entry.Username = cfg.TURNUser
-			entry.Credential = cfg.TURNPass
-			entry.CredentialType = webrtc.ICECredentialTypePassword
-		}
-		servers = append(servers, entry)
-	}
-	return servers
-}

internal/engine/webrtc_stream.go

@@ -1,807 +0,0 @@
-// Package engine — webrtc_stream.go implements the daemon side of the custom
-// WebRTC byte-streaming protocol. The browser opens an RTCDataChannel via
-// SDP exchange (signalled over the web's HTTP + SSE relay); this code:
-//
-//   1. Parses the browser's SDP offer.
-//   2. Creates a pion PeerConnection bound to the configured ICE servers.
-//   3. Answers + trickles its own ICE candidates back through the signal client.
-//   4. On DataChannel open, sends a HELLO frame describing the file.
-//   5. Services RangeReq frames by reading from disk and emitting RangeData
-//      chunks (16 KiB each) followed by a RangeEnd.
-//   6. Honours app-level backpressure via SetBufferedAmountLowThreshold +
-//      OnBufferedAmountLow — Chromium closes a DataChannel when bufferedAmount
-//      exceeds 16 MiB, so we MUST pause the writer.
-//
-// No anacrolix, no torrent metadata. Just a peer-to-peer file server over
-// WebRTC. Pass-through path; transcoding lives in transcoder.go (Fase 2.5).
-
-package engine
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"math"
-	"path/filepath"
-	"sync"
-	"sync/atomic"
-	"time"
-
-	"github.com/pion/webrtc/v4"
-
-	"github.com/torrentclaw/unarr/internal/agent"
-	"github.com/torrentclaw/unarr/internal/engine/wire"
-)
-
-// Tunables — values match the protocol spec in plan/clever-weaving-dove.md.
-const (
-	// dcChunkPayload is the per-frame application payload size. Must match
-	// wire.MaxChunkPayload so RangeData frames fit one SCTP message.
-	dcChunkPayload = wire.MaxChunkPayload
-	// dcHighWatermark is the bufferedAmount cap above which the writer pauses.
-	// Chromium closes DCs above 16 MiB; pause well below.
-	dcHighWatermark = 8 << 20
-	// dcLowWatermark triggers OnBufferedAmountLow → resume the writer.
-	dcLowWatermark = 1 << 20
-	// rangeReqConcurrency is the cap on in-flight range responses per session.
-	rangeReqConcurrency = 4
-	// helloDeadline is the max wait for the DataChannel to open after answer.
-	helloDeadline = 30 * time.Second
-)
-
-// WebRTCStreamConfig describes a single browser ↔ daemon stream session.
-type WebRTCStreamConfig struct {
-	SessionID  string
-	FilePath   string
-	FileName   string
-	FileSize   int64
-	ICEServers []webrtc.ICEServer
-	Signal     *agent.Client
-	// Logger receives diagnostic events; a nil logger swallows everything.
-	Logger StreamLogger
-	// Transcode steers on-the-fly transcoding when source codecs are not
-	// browser-decodable (HEVC/AV1/AC3/DTS). Empty FFmpegPath disables it.
-	Transcode TranscodeRuntime
-	// Quality overrides the cap from Transcode for this session. One of
-	// "2160p" | "1080p" | "720p" | "480p" | "original" | "" (= defer to
-	// Transcode defaults).
-	Quality string
-}
-
-// TranscodeRuntime carries the resolved ffmpeg/ffprobe paths + tunables so
-// each session can decide whether to passthrough or pipe through ffmpeg.
-type TranscodeRuntime struct {
-	FFmpegPath   string
-	FFprobePath  string
-	HWAccel      HWAccel
-	Preset       string
-	VideoBitrate string
-	AudioBitrate string
-	MaxHeight    int
-	// Disabled forces passthrough for every file even when codecs are not
-	// browser-friendly. Useful when the user explicitly turns transcoding
-	// off in config.
-	Disabled bool
-}
-
-// StreamLogger is an injectable logger so tests can capture events.
-type StreamLogger interface {
-	Infof(format string, args ...any)
-	Warnf(format string, args ...any)
-	Errorf(format string, args ...any)
-}
-
-type nopLogger struct{}
-
-func (nopLogger) Infof(string, ...any)  {}
-func (nopLogger) Warnf(string, ...any)  {}
-func (nopLogger) Errorf(string, ...any) {}
-
-func logger(l StreamLogger) StreamLogger {
-	if l == nil {
-		return nopLogger{}
-	}
-	return l
-}
-
-// qualityCap maps a session's Quality label to a (MaxHeight, VideoBitrate)
-// pair. An empty label or "original" returns zero-values, signalling "no
-// override" to the caller.
-type qualityCap struct {
-	MaxHeight    int
-	VideoBitrate string // ffmpeg -b:v string, e.g. "3500k"
-}
-
-func resolveQualityCap(label string) qualityCap {
-	switch label {
-	case "2160p":
-		return qualityCap{MaxHeight: 2160, VideoBitrate: "25000k"}
-	case "1080p":
-		return qualityCap{MaxHeight: 1080, VideoBitrate: "6000k"}
-	case "720p":
-		return qualityCap{MaxHeight: 720, VideoBitrate: "3500k"}
-	case "480p":
-		return qualityCap{MaxHeight: 480, VideoBitrate: "1500k"}
-	default:
-		// "original", "auto", "" → defer to config.
-		return qualityCap{}
-	}
-}
-
-// capForHeight returns the bitrate-cap pair appropriate for an effective
-// output height. Used after clamping outputHeight to the source's resolution:
-// asking ffmpeg for "2160p" bitrate (25 Mbps) on a 1080p source overshoots
-// the H.264 level we derived from the EFFECTIVE height (4.0, max 20 Mbps) and
-// makes libx264 refuse with "VBV bitrate > level limit". This helper picks
-// the bitrate that matches the level libx264 will actually accept.
-func capForHeight(height int) qualityCap {
-	switch {
-	case height <= 0:
-		return qualityCap{}
-	case height <= 480:
-		return qualityCap{MaxHeight: 480, VideoBitrate: "1500k"}
-	case height <= 720:
-		return qualityCap{MaxHeight: 720, VideoBitrate: "3500k"}
-	case height <= 1080:
-		return qualityCap{MaxHeight: 1080, VideoBitrate: "6000k"}
-	case height <= 1440:
-		return qualityCap{MaxHeight: 1440, VideoBitrate: "12000k"}
-	default:
-		return qualityCap{MaxHeight: 2160, VideoBitrate: "25000k"}
-	}
-}
-
-// buildStreamSource picks between passthrough and transcoded source. ffprobe
-// failure or missing ffmpeg falls back to passthrough — the browser surfaces
-// a clearer codec error than us refusing to start.
-//
-// Quality override (cfg.Quality) can force a downscale even when the source
-// codec is browser-friendly: a 4K h264 file watched on a phone with quality
-// "720p" must transcode (otherwise we'd ship 4K bytes for a 6" screen).
-func buildStreamSource(
-	ctx context.Context,
-	abs string,
-	displayName string,
-	cfg WebRTCStreamConfig,
-	log StreamLogger,
-) (streamSource, error) {
-	tc := cfg.Transcode
-	qcap := resolveQualityCap(cfg.Quality)
-
-	if tc.Disabled || tc.FFmpegPath == "" || tc.FFprobePath == "" {
-		return newDiskFileSource(abs)
-	}
-
-	probe, err := ProbeFile(ctx, tc.FFprobePath, abs)
-	if err != nil {
-		log.Warnf("[wrtc %s] probe failed (%v) — passthrough", agent.ShortID(cfg.SessionID), err)
-		return newDiskFileSource(abs)
-	}
-	action := DecideAction(probe)
-
-	// Quality cap can promote a passthrough/remux decision into a full video
-	// transcode when the source resolution exceeds the requested cap.
-	if qcap.MaxHeight > 0 && probe.Height > 0 && probe.Height > qcap.MaxHeight && action != ActionTranscodeVideo {
-		log.Infof("[wrtc %s] quality=%s caps height %d→%d — forcing video transcode",
-			agent.ShortID(cfg.SessionID), cfg.Quality, probe.Height, qcap.MaxHeight)
-		action = ActionTranscodeVideo
-	}
-
-	if action == ActionPassthrough {
-		log.Infof("[wrtc %s] codec passthrough (%s + %s in %s)",
-			agent.ShortID(cfg.SessionID), probe.VideoCodec, probe.AudioCodec, probe.Container)
-		return newDiskFileSource(abs)
-	}
-
-	log.Infof("[wrtc %s] transcoding %s/%s/%s → h264+aac (%s, quality=%s)",
-		agent.ShortID(cfg.SessionID), probe.Container, probe.VideoCodec, probe.AudioCodec,
-		action, coalesce(cfg.Quality, "default"))
-
-	maxHeight := tc.MaxHeight
-	videoBitrate := tc.VideoBitrate
-	if qcap.MaxHeight > 0 {
-		maxHeight = qcap.MaxHeight
-		videoBitrate = qcap.VideoBitrate
-	}
-
-	opts := TranscodeOpts{
-		Action:       action,
-		HWAccel:      tc.HWAccel,
-		Preset:       tc.Preset,
-		VideoBitrate: videoBitrate,
-		AudioBitrate: tc.AudioBitrate,
-		MaxHeight:    maxHeight,
-		SourceHeight: probe.Height,
-		FFmpegPath:   tc.FFmpegPath,
-	}
-	return newTranscodeSource(ctx, abs, probe, action, opts, displayName)
-}
-
-// RunWebRTCStream blocks until the session ends — either the DataChannel
-// closes, the peer connection drops, or ctx is cancelled. Always returns a
-// non-nil error explaining the termination reason.
-func RunWebRTCStream(ctx context.Context, cfg WebRTCStreamConfig) error {
-	log := logger(cfg.Logger)
-
-	if cfg.SessionID == "" {
-		return errors.New("webrtc_stream: empty SessionID")
-	}
-	if cfg.FilePath == "" {
-		return errors.New("webrtc_stream: empty FilePath")
-	}
-
-	abs, err := filepath.Abs(cfg.FilePath)
-	if err != nil {
-		return fmt.Errorf("webrtc_stream: resolve path: %w", err)
-	}
-
-	displayName := cfg.FileName
-	if displayName == "" {
-		displayName = filepath.Base(abs)
-	}
-
-	// Decide passthrough vs transcoding. Probe is best-effort: if ffprobe
-	// is missing or fails we fall back to passthrough (the browser will
-	// surface a clearer error than us guessing wrong).
-	source, err := buildStreamSource(ctx, abs, displayName, cfg, log)
-	if err != nil {
-		return fmt.Errorf("webrtc_stream: build source: %w", err)
-	}
-	defer source.Close()
-
-	// 1. Build PeerConnection.
-	api := webrtc.NewAPI()
-	pc, err := api.NewPeerConnection(webrtc.Configuration{
-		ICEServers: cfg.ICEServers,
-	})
-	if err != nil {
-		return fmt.Errorf("webrtc_stream: new peer connection: %w", err)
-	}
-	defer pc.Close()
-
-	sessionCtx, cancelSession := context.WithCancel(ctx)
-	defer cancelSession()
-
-	// Stop the session when ICE drops permanently. "Disconnected" is
-	// transient per RFC 8445 (NAT rebind, brief packet loss) — wait for
-	// "Failed" or "Closed" before tearing down.
-	pc.OnICEConnectionStateChange(func(state webrtc.ICEConnectionState) {
-		log.Infof("[wrtc %s] ice=%s", agent.ShortID(cfg.SessionID), state.String())
-		switch state {
-		case webrtc.ICEConnectionStateFailed,
-			webrtc.ICEConnectionStateClosed:
-			cancelSession()
-		case webrtc.ICEConnectionStateUnknown,
-			webrtc.ICEConnectionStateNew,
-			webrtc.ICEConnectionStateChecking,
-			webrtc.ICEConnectionStateConnected,
-			webrtc.ICEConnectionStateCompleted,
-			webrtc.ICEConnectionStateDisconnected:
-			// Disconnected is transient (RFC 8445 — NAT rebind / packet loss);
-			// the others are normal progress states. Don't tear the session down.
-		}
-	})
-
-	// Trickle our ICE candidates back to the browser.
-	// PostSignal runs on its own goroutine so a slow signal server can't
-	// stall pion's ICE-gathering thread.
-	pc.OnICECandidate(func(c *webrtc.ICECandidate) {
-		if c == nil {
-			go func() {
-				_ = cfg.Signal.PostSignal(sessionCtx, cfg.SessionID, agent.SignalMessage{
-					Type:    agent.SignalMsgCandidateEnd,
-					Payload: "",
-				})
-			}()
-			return
-		}
-		init := c.ToJSON()
-		payload, _ := json.Marshal(init)
-		go func() {
-			_ = cfg.Signal.PostSignal(sessionCtx, cfg.SessionID, agent.SignalMessage{
-				Type:    agent.SignalMsgCandidate,
-				Payload: string(payload),
-			})
-		}()
-	})
-
-	// Browser is the offerer — we react to the DataChannel it creates.
-	dcReady := make(chan *webrtc.DataChannel, 1)
-	pc.OnDataChannel(func(dc *webrtc.DataChannel) {
-		log.Infof("[wrtc %s] data channel '%s' open", agent.ShortID(cfg.SessionID), dc.Label())
-		select {
-		case dcReady <- dc:
-		default:
-			// Browser opened a second DC — ignore, we only serve one.
-			log.Warnf("[wrtc %s] extra data channel ignored", agent.ShortID(cfg.SessionID))
-		}
-	})
-
-	// 2. Drive the SDP exchange. Any error from the loop (browser sent
-	// "bye", signal stream closed, etc.) cancels the session so we don't
-	// dangle on the DC waiting for a peer that's already gone.
-	sdpDone := make(chan error, 1)
-	go func() {
-		err := runSDPExchange(sessionCtx, pc, cfg)
-		sdpDone <- err
-		if err != nil && sessionCtx.Err() == nil {
-			log.Infof("[wrtc %s] signal loop ended: %v", agent.ShortID(cfg.SessionID), err)
-			cancelSession()
-		}
-	}()
-
-	// 3. Wait for either SDP error or DataChannel open.
-	var dc *webrtc.DataChannel
-	select {
-	case err := <-sdpDone:
-		if err != nil {
-			return fmt.Errorf("sdp exchange: %w", err)
-		}
-		// SDP complete — wait for the DC.
-		select {
-		case dc = <-dcReady:
-		case <-time.After(helloDeadline):
-			return errors.New("webrtc_stream: data channel never opened")
-		case <-sessionCtx.Done():
-			return sessionCtx.Err()
-		}
-	case dc = <-dcReady:
-		// DC opened before SDP loop reported done (typical: the loop keeps
-		// running to ferry remote ICE candidates).
-	case <-sessionCtx.Done():
-		return sessionCtx.Err()
-	}
-
-	// 4. Wire up the data channel pump.
-	pump := newDataChannelPump(dc, source, log, cancelSession)
-	dc.OnOpen(pump.onOpen)
-	dc.OnMessage(pump.onMessage)
-	dc.OnClose(func() {
-		log.Infof("[wrtc %s] data channel closed", agent.ShortID(cfg.SessionID))
-		cancelSession()
-	})
-
-	<-sessionCtx.Done()
-	pump.shutdown()
-	return sessionCtx.Err()
-}
-
-// runSDPExchange consumes signal events from the browser and answers the SDP
-// offer. Keeps running for the lifetime of sessionCtx so trickle candidates
-// flow in both directions. Reopens the SSE stream on every clean close — the
-// server caps each response at ~25 s.
-func runSDPExchange(ctx context.Context, pc *webrtc.PeerConnection, cfg WebRTCStreamConfig) error {
-	gotOffer := false
-	for ctx.Err() == nil {
-		stream, err := cfg.Signal.OpenSignalStream(ctx, cfg.SessionID)
-		if err != nil {
-			if ctx.Err() != nil {
-				return ctx.Err()
-			}
-			return fmt.Errorf("open signal stream: %w", err)
-		}
-		err = consumeSignalStream(ctx, pc, cfg, stream, &gotOffer)
-		stream.Close()
-		if err != nil {
-			return err
-		}
-	}
-	return ctx.Err()
-}
-
-// consumeSignalStream drains a single SSE connection until it closes or
-// produces a hard error. Returns nil on a clean server-side disconnect so the
-// caller can reopen.
-func consumeSignalStream(
-	ctx context.Context,
-	pc *webrtc.PeerConnection,
-	cfg WebRTCStreamConfig,
-	stream *agent.SignalEventStream,
-	gotOffer *bool,
-) error {
-	for {
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case msg, ok := <-stream.Events():
-			if !ok {
-				if err := stream.Err(); err != nil {
-					return fmt.Errorf("signal stream: %w", err)
-				}
-				return nil
-			}
-			if err := handleSignal(ctx, pc, cfg, msg, gotOffer); err != nil {
-				return err
-			}
-		}
-	}
-}
-
-func handleSignal(
-	ctx context.Context,
-	pc *webrtc.PeerConnection,
-	cfg WebRTCStreamConfig,
-	msg agent.SignalMessage,
-	gotOffer *bool,
-) error {
-	switch msg.Type {
-	case agent.SignalMsgAnswer:
-		// Browser is the offerer in our protocol — we never expect an answer
-		// from the other side. Drop silently (also satisfies exhaustive lint).
-		return nil
-	case agent.SignalMsgOffer:
-		if *gotOffer {
-			return nil // ignore duplicates
-		}
-		var offer webrtc.SessionDescription
-		if err := json.Unmarshal([]byte(msg.Payload), &offer); err != nil {
-			return fmt.Errorf("decode offer: %w", err)
-		}
-		if err := pc.SetRemoteDescription(offer); err != nil {
-			return fmt.Errorf("set remote description: %w", err)
-		}
-		answer, err := pc.CreateAnswer(nil)
-		if err != nil {
-			return fmt.Errorf("create answer: %w", err)
-		}
-		if err := pc.SetLocalDescription(answer); err != nil {
-			return fmt.Errorf("set local description: %w", err)
-		}
-		// Send back the local description *with* gathered candidates so far —
-		// remaining candidates trickle separately via OnICECandidate.
-		ld := pc.LocalDescription()
-		payload, _ := json.Marshal(ld)
-		if err := cfg.Signal.PostSignal(ctx, cfg.SessionID, agent.SignalMessage{
-			Type:    agent.SignalMsgAnswer,
-			Payload: string(payload),
-		}); err != nil {
-			return fmt.Errorf("post answer: %w", err)
-		}
-		*gotOffer = true
-
-	case agent.SignalMsgCandidate:
-		if !*gotOffer {
-			// Browser may trickle candidates before we've seen the offer in
-			// rare race conditions — drop. Browser will retransmit.
-			return nil
-		}
-		var init webrtc.ICECandidateInit
-		if err := json.Unmarshal([]byte(msg.Payload), &init); err != nil {
-			return fmt.Errorf("decode candidate: %w", err)
-		}
-		if err := pc.AddICECandidate(init); err != nil {
-			return fmt.Errorf("add ice candidate: %w", err)
-		}
-
-	case agent.SignalMsgCandidateEnd:
-		// No-op — pion gathers complete on its own.
-
-	case agent.SignalMsgBye:
-		return errors.New("browser sent bye")
-	}
-	return nil
-}
-
-// dataChannelPump owns the DC + stream source and serves wire-protocol frames.
-type dataChannelPump struct {
-	dc     *webrtc.DataChannel
-	source streamSource
-	log    StreamLogger
-	cancel context.CancelFunc
-
-	// Flow control: writers wait on resumeCh when bufferedAmount goes high.
-	paused   atomic.Bool
-	resumeCh chan struct{}
-
-	// Active range responses keyed by stream_id so CANCEL frames can stop them.
-	activeMu sync.Mutex
-	active   map[uint32]context.CancelFunc
-
-	// Bound concurrent in-flight responses.
-	sem chan struct{}
-
-	// closed once shutdown() has been called.
-	closed atomic.Bool
-}
-
-func newDataChannelPump(
-	dc *webrtc.DataChannel,
-	source streamSource,
-	log StreamLogger,
-	cancel context.CancelFunc,
-) *dataChannelPump {
-	p := &dataChannelPump{
-		dc:       dc,
-		source:   source,
-		log:      log,
-		cancel:   cancel,
-		resumeCh: make(chan struct{}, 1),
-		active:   make(map[uint32]context.CancelFunc),
-		sem:      make(chan struct{}, rangeReqConcurrency),
-	}
-	dc.SetBufferedAmountLowThreshold(dcLowWatermark)
-	dc.OnBufferedAmountLow(p.onBufferedAmountLow)
-	return p
-}
-
-func (p *dataChannelPump) onOpen() {
-	// Use estimated size for transcoded streams so the browser scrubber has
-	// something to anchor on. Real size is reflected by Range responses as
-	// ffmpeg writes more bytes; the estimate just bootstraps the UI.
-	announceSize := p.source.EstimatedSize()
-	transcoding := p.source.Transcoded()
-	// Browsers refuse to start playback when Content-Length is 0. If we don't
-	// have a duration estimate (e.g. ffprobe couldn't tag the source), declare
-	// a large sentinel so the browser issues range requests; the Transcoding
-	// flag tells it the value is provisional.
-	if transcoding && announceSize <= 0 {
-		announceSize = math.MaxInt64
-	}
-	// Seekable=true even for transcoded sources because we read from a tmp
-	// file (random access). Seek backwards just works; seek forward beyond
-	// what ffmpeg has produced will block briefly inside ReadAt.
-	seekable := true
-	hello := wire.HelloPayload{
-		FileSize:    uint64(announceSize),
-		Transcoding: transcoding,
-		Seekable:    seekable,
-		FileName:    p.source.FileName(),
-	}
-	payload := wire.EncodeHello(hello)
-	frame := wire.EncodeFrame(wire.Header{
-		Type:     wire.FrameHello,
-		Flags:    wire.HelloFlags(transcoding, seekable),
-		StreamID: 0,
-		Length:   uint32(len(payload)),
-	}, payload)
-	if err := p.dc.Send(frame); err != nil {
-		p.log.Errorf("send hello: %v", err)
-		p.cancel()
-	}
-}
-
-func (p *dataChannelPump) onMessage(msg webrtc.DataChannelMessage) {
-	if len(msg.Data) < wire.HeaderSize {
-		p.log.Warnf("dc: short frame %d bytes", len(msg.Data))
-		return
-	}
-	hdr, err := wire.DecodeHeader(msg.Data[:wire.HeaderSize])
-	if err != nil {
-		p.log.Warnf("dc: bad header: %v", err)
-		return
-	}
-	payload := msg.Data[wire.HeaderSize:]
-	if uint32(len(payload)) != hdr.Length {
-		p.log.Warnf("dc: payload length mismatch: hdr=%d got=%d", hdr.Length, len(payload))
-		return
-	}
-
-	switch hdr.Type {
-	case wire.FrameRangeReq:
-		req, err := wire.DecodeRangeReq(payload)
-		if err != nil {
-			p.log.Warnf("dc: bad range_req: %v", err)
-			return
-		}
-		go p.serveRange(hdr.StreamID, req)
-	case wire.FrameCancel:
-		p.cancelStream(hdr.StreamID)
-	case wire.FramePing:
-		p.sendSimpleFrame(wire.FramePong, hdr.StreamID, nil)
-	case wire.FramePong:
-		// no-op
-	default:
-		p.log.Warnf("dc: unknown frame type 0x%02x", hdr.Type)
-	}
-}
-
-func (p *dataChannelPump) cancelStream(streamID uint32) {
-	p.activeMu.Lock()
-	cancel, ok := p.active[streamID]
-	delete(p.active, streamID)
-	p.activeMu.Unlock()
-	if ok {
-		cancel()
-	}
-}
-
-func (p *dataChannelPump) sendSimpleFrame(t wire.FrameType, streamID uint32, payload []byte) {
-	frame := wire.EncodeFrame(wire.Header{
-		Type:     t,
-		StreamID: streamID,
-		Length:   uint32(len(payload)),
-	}, payload)
-	if err := p.dc.Send(frame); err != nil {
-		p.log.Warnf("dc: send type=0x%02x: %v", t, err)
-	}
-}
-
-func (p *dataChannelPump) serveRange(streamID uint32, req wire.RangeReqPayload) {
-	if p.closed.Load() {
-		return
-	}
-	// Bound concurrency.
-	select {
-	case p.sem <- struct{}{}:
-	case <-time.After(5 * time.Second):
-		p.log.Warnf("dc: range_req sid=%d dropped (concurrency cap)", streamID)
-		p.sendRangeEnd(streamID, 1)
-		return
-	}
-	defer func() { <-p.sem }()
-
-	// Reject offsets above MaxInt64 — uint64→int64 narrowing would wrap to a
-	// negative value and bypass the bounds check, then ReadAt would be called
-	// with a negative offset.
-	currentSize := p.source.Size()
-	finalSize := p.source.EstimatedSize()
-	if req.Offset > math.MaxInt64 {
-		p.sendRangeEnd(streamID, 2) // out of range
-		return
-	}
-	// For transcoded streams `currentSize` grows over time; only reject when
-	// the offset is past the *estimated* final size.
-	if int64(req.Offset) >= finalSize && p.source.Final() {
-		p.sendRangeEnd(streamID, 2)
-		return
-	}
-
-	want := int64(req.Length)
-	if req.Length > math.MaxInt64 {
-		want = 0 // treat absurd length as "remainder of file"
-	}
-	// Cap by *final* size, not currentSize. For a still-transcoding stream
-	// currentSize grows over time and ReadAt below already blocks until
-	// ffmpeg produces the requested bytes (with a deadline). If we cap
-	// `want` by currentSize here we'll send an empty RangeEnd whenever the
-	// browser asks for bytes faster than ffmpeg writes them — which is
-	// always true on the first few seconds — and the browser then aborts
-	// playback with "Format error".
-	cap := finalSize
-	if !p.source.Final() && cap < int64(req.Offset)+1 {
-		// Estimate too small: serve as much as the browser asked for and
-		// let ReadAt block.
-		cap = int64(req.Offset) + want
-	}
-	if int64(req.Offset) >= cap && p.source.Final() {
-		// Past true end of a finished file.
-		p.sendRangeEnd(streamID, 0)
-		return
-	}
-	remaining := cap - int64(req.Offset)
-	if remaining < 0 {
-		remaining = 0
-	}
-	if want <= 0 || want > remaining {
-		want = remaining
-	}
-	p.log.Infof("dc: range_req sid=%d offset=%d wantReq=%d wantServe=%d currentSize=%d final=%v",
-		streamID, req.Offset, req.Length, want, currentSize, p.source.Final())
-	if want <= 0 {
-		// Only happens for a finished file when offset is at/past EOF.
-		p.sendRangeEnd(streamID, 0)
-		return
-	}
-
-	ctx, cancel := context.WithCancel(context.Background())
-	p.activeMu.Lock()
-	if p.active == nil {
-		p.activeMu.Unlock()
-		cancel()
-		p.sendRangeEnd(streamID, 3)
-		return
-	}
-	p.active[streamID] = cancel
-	p.activeMu.Unlock()
-	defer func() {
-		p.activeMu.Lock()
-		delete(p.active, streamID)
-		p.activeMu.Unlock()
-		cancel()
-	}()
-
-	buf := make([]byte, dcChunkPayload)
-	offset := int64(req.Offset)
-	end := offset + want
-	for offset < end {
-		if ctx.Err() != nil || p.closed.Load() {
-			return
-		}
-		// Wait if the DC is buffering too much.
-		if err := p.waitForLowWater(ctx); err != nil {
-			return
-		}
-		chunkLen := int64(len(buf))
-		if end-offset < chunkLen {
-			chunkLen = end - offset
-		}
-		n, rerr := p.source.ReadAt(buf[:chunkLen], offset)
-		if n > 0 {
-			// EOF on a short read means this is the final chunk — flag it so the
-			// browser doesn't wait for more data before processing RangeEnd.
-			isLast := offset+int64(n) >= end || rerr == io.EOF
-			if err := p.sendRangeData(streamID, buf[:n], isLast); err != nil {
-				p.log.Warnf("dc: send range_data sid=%d: %v", streamID, err)
-				return
-			}
-			offset += int64(n)
-		}
-		if rerr != nil {
-			if rerr == io.EOF {
-				break
-			}
-			p.log.Errorf("dc: read sid=%d: %v", streamID, rerr)
-			p.sendRangeEnd(streamID, 3)
-			return
-		}
-	}
-	p.sendRangeEnd(streamID, 0)
-}
-
-func (p *dataChannelPump) sendRangeData(streamID uint32, data []byte, last bool) error {
-	var flags uint8
-	if last {
-		flags |= wire.FlagLastChunk
-	}
-	frame := wire.EncodeFrame(wire.Header{
-		Type:     wire.FrameRangeData,
-		Flags:    flags,
-		StreamID: streamID,
-		Length:   uint32(len(data)),
-	}, data)
-	return p.dc.Send(frame)
-}
-
-func (p *dataChannelPump) sendRangeEnd(streamID uint32, status uint32) {
-	payload := wire.EncodeRangeEnd(wire.RangeEndPayload{Status: status})
-	p.sendSimpleFrame(wire.FrameRangeEnd, streamID, payload)
-}
-
-func (p *dataChannelPump) waitForLowWater(ctx context.Context) error {
-	if p.dc.BufferedAmount() < dcHighWatermark {
-		return nil
-	}
-	p.paused.Store(true)
-	for {
-		// Drain any stale resume signal first.
-		select {
-		case <-p.resumeCh:
-		default:
-		}
-		if p.dc.BufferedAmount() < dcHighWatermark {
-			p.paused.Store(false)
-			return nil
-		}
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-p.resumeCh:
-		case <-time.After(500 * time.Millisecond):
-			// Belt-and-braces poll in case OnBufferedAmountLow misses a fire.
-		}
-	}
-}
-
-func (p *dataChannelPump) onBufferedAmountLow() {
-	if !p.paused.Load() {
-		return
-	}
-	select {
-	case p.resumeCh <- struct{}{}:
-	default:
-	}
-}
-
-func (p *dataChannelPump) shutdown() {
-	if !p.closed.CompareAndSwap(false, true) {
-		return
-	}
-	p.activeMu.Lock()
-	for _, cancel := range p.active {
-		cancel()
-	}
-	p.active = nil
-	p.activeMu.Unlock()
-}

internal/engine/webrtc_test.go

@@ -1,177 +0,0 @@
-package engine
-
-import (
-	"context"
-	"net/url"
-	"strings"
-	"testing"
-
-	"github.com/pion/webrtc/v4"
-	"github.com/torrentclaw/unarr/internal/config"
-)
-
-const validHash = "aaf2c71b0e0a03d3f9b2a3e1d5c6b7a8f0e1d2c3"
-
-// TestBuildMagnet_NoExtras verifies the legacy free-function path keeps
-// emitting only the static defaultTrackers list.
-func TestBuildMagnet_NoExtras(t *testing.T) {
-	got := buildMagnet(validHash)
-	if !strings.HasPrefix(got, "magnet:?xt=urn:btih:"+validHash) {
-		t.Fatalf("magnet missing xt: %s", got)
-	}
-	if !strings.Contains(got, url.QueryEscape("udp://tracker.opentrackr.org:1337/announce")) {
-		t.Fatal("expected default UDP tracker absent")
-	}
-	if strings.Contains(got, "wss%3A") {
-		t.Fatalf("unexpected WSS tracker leaked when none requested: %s", got)
-	}
-}
-
-// TestBuildMagnet_WithExtraTrackers verifies extraTrackers (e.g. WebRTC
-// WSS endpoints) are prepended before the defaults and properly URL-encoded.
-func TestBuildMagnet_WithExtraTrackers(t *testing.T) {
-	got := buildMagnet(validHash, "wss://tracker.torrentclaw.com")
-	encWss := url.QueryEscape("wss://tracker.torrentclaw.com")
-	encUDP := url.QueryEscape("udp://tracker.opentrackr.org:1337/announce")
-	if !strings.Contains(got, "tr="+encWss) {
-		t.Fatalf("WSS tracker missing: %s", got)
-	}
-	wssIdx := strings.Index(got, encWss)
-	udpIdx := strings.Index(got, encUDP)
-	if wssIdx < 0 || udpIdx < 0 || wssIdx > udpIdx {
-		t.Fatalf("WSS tracker should appear BEFORE UDP defaults: wss=%d udp=%d", wssIdx, udpIdx)
-	}
-}
-
-// TestBuildMagnet_TrimsAndSkipsEmpty makes sure callers passing config-derived
-// slices with stray whitespace or empty strings don't get malformed magnets.
-func TestBuildMagnet_TrimsAndSkipsEmpty(t *testing.T) {
-	got := buildMagnet(validHash, "  wss://tracker.torrentclaw.com  ", "", "  ")
-	encWss := url.QueryEscape("wss://tracker.torrentclaw.com")
-	if !strings.Contains(got, "tr="+encWss) {
-		t.Fatalf("trimmed WSS tracker missing: %s", got)
-	}
-	if strings.Contains(got, "tr=&") || strings.HasSuffix(got, "tr=") {
-		t.Fatalf("empty tracker emitted: %s", got)
-	}
-}
-
-// TestTorrentDownloader_buildMagnet_WebRTCDisabled confirms the downloader
-// method does NOT inject WebRTCTrackers when WebRTCEnabled is false.
-func TestTorrentDownloader_buildMagnet_WebRTCDisabled(t *testing.T) {
-	d := &TorrentDownloader{cfg: TorrentConfig{
-		WebRTCEnabled:  false,
-		WebRTCTrackers: []string{"wss://tracker.torrentclaw.com"},
-	}}
-	got := d.buildMagnet(validHash)
-	if strings.Contains(got, "wss%3A") {
-		t.Fatalf("WSS tracker leaked while WebRTCEnabled=false: %s", got)
-	}
-}
-
-// TestTorrentDownloader_buildMagnet_WebRTCEnabled confirms the WSS trackers
-// are present when WebRTCEnabled is true.
-func TestTorrentDownloader_buildMagnet_WebRTCEnabled(t *testing.T) {
-	d := &TorrentDownloader{cfg: TorrentConfig{
-		WebRTCEnabled:  true,
-		WebRTCTrackers: []string{"wss://tracker.torrentclaw.com", "wss://tracker2.example.com"},
-	}}
-	got := d.buildMagnet(validHash)
-	for _, want := range []string{
-		"wss://tracker.torrentclaw.com",
-		"wss://tracker2.example.com",
-	} {
-		if !strings.Contains(got, url.QueryEscape(want)) {
-			t.Fatalf("expected tracker %q missing in magnet: %s", want, got)
-		}
-	}
-}
-
-// TestBuildICEServers_DisabledReturnsNil ensures we don't leak STUN/TURN
-// configuration into the torrent client when the user has WebRTC off.
-func TestBuildICEServers_DisabledReturnsNil(t *testing.T) {
-	got := BuildICEServers(config.WebRTCConfig{
-		Enabled:     false,
-		STUNServers: []string{"stun:stun.l.google.com:19302"},
-	})
-	if got != nil {
-		t.Fatalf("expected nil ICE servers when disabled, got %+v", got)
-	}
-}
-
-// TestBuildICEServers_STUNOnly converts STUN entries to bare ICEServer
-// records with no credentials.
-func TestBuildICEServers_STUNOnly(t *testing.T) {
-	got := BuildICEServers(config.WebRTCConfig{
-		Enabled:     true,
-		STUNServers: []string{"stun:stun.l.google.com:19302", "", "stun:stun1.l.google.com:19302"},
-	})
-	if len(got) != 2 {
-		t.Fatalf("expected 2 STUN servers (empty skipped), got %d (%+v)", len(got), got)
-	}
-	if got[0].URLs[0] != "stun:stun.l.google.com:19302" {
-		t.Fatalf("first server unexpected: %+v", got[0])
-	}
-	if got[0].Username != "" || got[0].Credential != nil {
-		t.Fatalf("STUN entry should have no credentials, got %+v", got[0])
-	}
-}
-
-// TestNewTorrentDownloader_WebRTCEnabled creates a downloader with the
-// WebRTC peer fully wired up and confirms the constructor doesn't error
-// (anacrolix accepts the ICE server list, port binds, etc.).
-func TestNewTorrentDownloader_WebRTCEnabled(t *testing.T) {
-	dir := t.TempDir()
-	dl, err := NewTorrentDownloader(TorrentConfig{
-		DataDir:        dir,
-		ListenPort:     0, // let the OS pick — avoid clashes in CI
-		WebRTCEnabled:  true,
-		WebRTCTrackers: []string{"wss://tracker.torrentclaw.com"},
-		ICEServers: BuildICEServers(config.WebRTCConfig{
-			Enabled:     true,
-			STUNServers: []string{"stun:stun.l.google.com:19302"},
-		}),
-	})
-	if err != nil {
-		t.Fatalf("WebRTC-enabled downloader failed to start: %v", err)
-	}
-	defer func() {
-		if err := dl.Shutdown(context.Background()); err != nil {
-			t.Logf("shutdown: %v", err)
-		}
-	}()
-
-	// Magnet for any task should now contain the WSS tracker.
-	got := dl.buildMagnet(validHash)
-	if !strings.Contains(got, "wss%3A%2F%2Ftracker.torrentclaw.com") {
-		t.Fatalf("WebRTC magnet missing WSS tracker: %s", got)
-	}
-}
-
-// TestBuildICEServers_TURNWithCreds applies TURNUser/TURNPass to every TURN
-// entry so the operator only specifies them once.
-func TestBuildICEServers_TURNWithCreds(t *testing.T) {
-	got := BuildICEServers(config.WebRTCConfig{
-		Enabled:     true,
-		STUNServers: []string{"stun:stun.l.google.com:19302"},
-		TURNServers: []string{"turn:turn.example.com:3478"},
-		TURNUser:    "alice",
-		TURNPass:    "s3cr3t",
-	})
-	if len(got) != 2 {
-		t.Fatalf("expected 1 STUN + 1 TURN, got %d", len(got))
-	}
-	turn := got[1]
-	if turn.URLs[0] != "turn:turn.example.com:3478" {
-		t.Fatalf("TURN URL wrong: %+v", turn)
-	}
-	if turn.Username != "alice" {
-		t.Fatalf("TURN username wrong: %s", turn.Username)
-	}
-	if turn.Credential != "s3cr3t" {
-		t.Fatalf("TURN credential wrong: %v", turn.Credential)
-	}
-	if turn.CredentialType != webrtc.ICECredentialTypePassword {
-		t.Fatalf("TURN credential type wrong: %v", turn.CredentialType)
-	}
-}

internal/engine/wire/proto.go

@@ -1,254 +0,0 @@
-// Package wire implements the binary frame format used over the WebRTC
-// DataChannel between the unarr daemon and the browser stream player.
-//
-// Header (12 bytes, big-endian):
-//
-//	u8  Type
-//	u8  Flags
-//	u16 _reserved
-//	u32 StreamID  -- multiplex range requests
-//	u32 Length    -- payload bytes following the header
-//
-// Each side encodes one Frame at a time and writes it as a single SCTP
-// message (DataChannel send). Browsers cap message size at 64 KiB-ish, so
-// callers MUST split RANGE_DATA payloads into chunks <= MaxChunkPayload.
-package wire
-
-import (
-	"encoding/binary"
-	"errors"
-	"fmt"
-	"io"
-)
-
-// FrameType identifies the wire message kind.
-type FrameType uint8
-
-const (
-	FrameHello     FrameType = 0x00
-	FrameRangeReq  FrameType = 0x01
-	FrameRangeData FrameType = 0x02
-	FrameRangeEnd  FrameType = 0x03
-	FrameCancel    FrameType = 0x04
-	FramePing      FrameType = 0x05
-	FramePong      FrameType = 0x06
-	FrameSeekHint  FrameType = 0x07
-)
-
-// Flag bits — interpretation depends on FrameType.
-const (
-	// FlagLastChunk on a RangeData frame marks the final chunk for a stream_id.
-	FlagLastChunk uint8 = 1 << 0
-	// FlagTranscoding on a Hello frame indicates the daemon will transcode.
-	FlagTranscoding uint8 = 1 << 1
-	// FlagSeekable on a Hello frame indicates random-access is supported.
-	FlagSeekable uint8 = 1 << 2
-)
-
-// HeaderSize is the fixed length of every frame header.
-const HeaderSize = 12
-
-// MaxChunkPayload is the safe per-frame payload cap that works on every
-// browser implementation (Chromium fragments at 16 KiB internally above).
-// Callers MUST chunk RangeData payloads to <= this size.
-const MaxChunkPayload = 16 * 1024
-
-// MaxFrameSize is the largest frame the parser will accept. Anything bigger
-// is treated as a corrupted stream — close the channel.
-const MaxFrameSize = HeaderSize + 64*1024
-
-// Header is the parsed 12-byte frame header.
-type Header struct {
-	Type     FrameType
-	Flags    uint8
-	StreamID uint32
-	Length   uint32
-}
-
-// EncodeHeader writes h to dst (must be at least HeaderSize bytes).
-func EncodeHeader(dst []byte, h Header) {
-	if len(dst) < HeaderSize {
-		panic("wire: dst too small for header")
-	}
-	dst[0] = byte(h.Type)
-	dst[1] = h.Flags
-	dst[2] = 0
-	dst[3] = 0
-	binary.BigEndian.PutUint32(dst[4:8], h.StreamID)
-	binary.BigEndian.PutUint32(dst[8:12], h.Length)
-}
-
-// DecodeHeader parses src (must be at least HeaderSize bytes) into h.
-func DecodeHeader(src []byte) (Header, error) {
-	if len(src) < HeaderSize {
-		return Header{}, fmt.Errorf("wire: header needs %d bytes, got %d", HeaderSize, len(src))
-	}
-	h := Header{
-		Type:     FrameType(src[0]),
-		Flags:    src[1],
-		StreamID: binary.BigEndian.Uint32(src[4:8]),
-		Length:   binary.BigEndian.Uint32(src[8:12]),
-	}
-	if h.Length > MaxFrameSize-HeaderSize {
-		return Header{}, fmt.Errorf("wire: payload length %d exceeds max %d", h.Length, MaxFrameSize-HeaderSize)
-	}
-	return h, nil
-}
-
-// EncodeFrame allocates and returns a complete frame (header + payload).
-// Use this for one-shot sends; for hot-path RangeData prefer EncodeHeader
-// into a pre-allocated buffer to avoid per-frame allocations.
-func EncodeFrame(h Header, payload []byte) []byte {
-	if int(h.Length) != len(payload) {
-		panic(fmt.Sprintf("wire: header length %d != payload len %d", h.Length, len(payload)))
-	}
-	buf := make([]byte, HeaderSize+len(payload))
-	EncodeHeader(buf[:HeaderSize], h)
-	copy(buf[HeaderSize:], payload)
-	return buf
-}
-
-// ReadFrame reads one full frame from r. Returns the parsed header and a
-// freshly allocated payload slice. On any size violation the connection
-// must be closed — the protocol has no resync.
-func ReadFrame(r io.Reader) (Header, []byte, error) {
-	headerBuf := make([]byte, HeaderSize)
-	if _, err := io.ReadFull(r, headerBuf); err != nil {
-		return Header{}, nil, err
-	}
-	h, err := DecodeHeader(headerBuf)
-	if err != nil {
-		return Header{}, nil, err
-	}
-	if h.Length == 0 {
-		return h, nil, nil
-	}
-	payload := make([]byte, h.Length)
-	if _, err := io.ReadFull(r, payload); err != nil {
-		return Header{}, nil, err
-	}
-	return h, payload, nil
-}
-
-// HelloPayload describes the file the daemon is about to serve. It is the
-// first frame the daemon writes after the DataChannel opens.
-type HelloPayload struct {
-	FileSize    uint64
-	Transcoding bool
-	Seekable    bool
-	FileName    string
-}
-
-// EncodeHello marshals h into a payload byte slice.
-//
-// Layout: u64 file_size | u32 name_len | name_bytes
-func EncodeHello(h HelloPayload) []byte {
-	nameBytes := []byte(h.FileName)
-	buf := make([]byte, 8+4+len(nameBytes))
-	binary.BigEndian.PutUint64(buf[0:8], h.FileSize)
-	binary.BigEndian.PutUint32(buf[8:12], uint32(len(nameBytes)))
-	copy(buf[12:], nameBytes)
-	return buf
-}
-
-// DecodeHello parses a Hello payload. The transcoding/seekable bits live in
-// the frame Flags byte, not the payload — pass them in.
-func DecodeHello(payload []byte, flags uint8) (HelloPayload, error) {
-	if len(payload) < 12 {
-		return HelloPayload{}, errors.New("wire: hello payload too short")
-	}
-	size := binary.BigEndian.Uint64(payload[0:8])
-	nameLen := binary.BigEndian.Uint32(payload[8:12])
-	if int(nameLen) > len(payload)-12 {
-		return HelloPayload{}, fmt.Errorf("wire: hello name_len %d exceeds payload", nameLen)
-	}
-	return HelloPayload{
-		FileSize:    size,
-		Transcoding: flags&FlagTranscoding != 0,
-		Seekable:    flags&FlagSeekable != 0,
-		FileName:    string(payload[12 : 12+nameLen]),
-	}, nil
-}
-
-// HelloFlags returns the flag byte for a Hello frame given the booleans.
-func HelloFlags(transcoding, seekable bool) uint8 {
-	var f uint8
-	if transcoding {
-		f |= FlagTranscoding
-	}
-	if seekable {
-		f |= FlagSeekable
-	}
-	return f
-}
-
-// RangeReqPayload is the browser → daemon request for bytes [Offset, Offset+Length).
-type RangeReqPayload struct {
-	Offset uint64
-	Length uint64
-}
-
-// EncodeRangeReq marshals p. Layout: u64 offset | u64 length.
-func EncodeRangeReq(p RangeReqPayload) []byte {
-	buf := make([]byte, 16)
-	binary.BigEndian.PutUint64(buf[0:8], p.Offset)
-	binary.BigEndian.PutUint64(buf[8:16], p.Length)
-	return buf
-}
-
-// DecodeRangeReq parses a 16-byte range request payload.
-func DecodeRangeReq(payload []byte) (RangeReqPayload, error) {
-	if len(payload) != 16 {
-		return RangeReqPayload{}, fmt.Errorf("wire: range_req payload must be 16 bytes, got %d", len(payload))
-	}
-	return RangeReqPayload{
-		Offset: binary.BigEndian.Uint64(payload[0:8]),
-		Length: binary.BigEndian.Uint64(payload[8:16]),
-	}, nil
-}
-
-// RangeEndPayload signals end-of-response for a stream_id with a status code.
-// Status 0 == OK; non-zero values are app-defined error codes.
-type RangeEndPayload struct {
-	Status uint32
-}
-
-// EncodeRangeEnd marshals p.
-func EncodeRangeEnd(p RangeEndPayload) []byte {
-	buf := make([]byte, 4)
-	binary.BigEndian.PutUint32(buf[0:4], p.Status)
-	return buf
-}
-
-// DecodeRangeEnd parses a 4-byte range_end payload.
-func DecodeRangeEnd(payload []byte) (RangeEndPayload, error) {
-	if len(payload) != 4 {
-		return RangeEndPayload{}, fmt.Errorf("wire: range_end payload must be 4 bytes, got %d", len(payload))
-	}
-	return RangeEndPayload{
-		Status: binary.BigEndian.Uint32(payload[0:4]),
-	}, nil
-}
-
-// SeekHintPayload tells the daemon a seek to timestamp_ms is imminent so it
-// can pre-warm a transcoder pipeline before bytes are requested.
-type SeekHintPayload struct {
-	TimestampMs uint64
-}
-
-// EncodeSeekHint marshals p.
-func EncodeSeekHint(p SeekHintPayload) []byte {
-	buf := make([]byte, 8)
-	binary.BigEndian.PutUint64(buf[0:8], p.TimestampMs)
-	return buf
-}
-
-// DecodeSeekHint parses an 8-byte seek_hint payload.
-func DecodeSeekHint(payload []byte) (SeekHintPayload, error) {
-	if len(payload) != 8 {
-		return SeekHintPayload{}, fmt.Errorf("wire: seek_hint payload must be 8 bytes, got %d", len(payload))
-	}
-	return SeekHintPayload{
-		TimestampMs: binary.BigEndian.Uint64(payload[0:8]),
-	}, nil
-}

internal/engine/wire/proto_test.go

@@ -1,193 +0,0 @@
-package wire
-
-import (
-	"bytes"
-	"testing"
-)
-
-func TestHeaderRoundtrip(t *testing.T) {
-	cases := []Header{
-		{Type: FrameHello, Flags: FlagSeekable, StreamID: 0, Length: 32},
-		{Type: FrameRangeReq, Flags: 0, StreamID: 7, Length: 16},
-		{Type: FrameRangeData, Flags: FlagLastChunk, StreamID: 4242, Length: 16380},
-		{Type: FrameRangeEnd, Flags: 0, StreamID: 1, Length: 4},
-		{Type: FrameCancel, Flags: 0, StreamID: 9, Length: 0},
-		{Type: FramePing, Flags: 0, StreamID: 0, Length: 0},
-	}
-	for _, want := range cases {
-		buf := make([]byte, HeaderSize)
-		EncodeHeader(buf, want)
-		got, err := DecodeHeader(buf)
-		if err != nil {
-			t.Fatalf("decode: %v (want %+v)", err, want)
-		}
-		if got != want {
-			t.Errorf("roundtrip mismatch: got %+v want %+v", got, want)
-		}
-	}
-}
-
-func TestDecodeHeaderShort(t *testing.T) {
-	if _, err := DecodeHeader([]byte{0, 0, 0}); err == nil {
-		t.Fatal("expected error on short header")
-	}
-}
-
-func TestDecodeHeaderRejectsHugeLength(t *testing.T) {
-	// Synthesize a header with payload length above MaxFrameSize.
-	buf := make([]byte, HeaderSize)
-	buf[0] = byte(FrameRangeData)
-	buf[8] = 0xff
-	buf[9] = 0xff
-	buf[10] = 0xff
-	buf[11] = 0xff
-	if _, err := DecodeHeader(buf); err == nil {
-		t.Fatal("expected error on oversized payload length")
-	}
-}
-
-func TestEncodeFramePanicsOnLengthMismatch(t *testing.T) {
-	defer func() {
-		if r := recover(); r == nil {
-			t.Fatal("expected panic on header length / payload mismatch")
-		}
-	}()
-	EncodeFrame(Header{Type: FrameRangeData, Length: 5}, []byte{1, 2, 3})
-}
-
-func TestReadFrameRoundtrip(t *testing.T) {
-	want := Header{Type: FrameRangeData, Flags: FlagLastChunk, StreamID: 99, Length: 5}
-	payload := []byte{0xde, 0xad, 0xbe, 0xef, 0x42}
-	frame := EncodeFrame(want, payload)
-
-	r := bytes.NewReader(frame)
-	got, gotPayload, err := ReadFrame(r)
-	if err != nil {
-		t.Fatalf("read: %v", err)
-	}
-	if got != want {
-		t.Errorf("header mismatch: %+v want %+v", got, want)
-	}
-	if !bytes.Equal(gotPayload, payload) {
-		t.Errorf("payload mismatch: %x want %x", gotPayload, payload)
-	}
-}
-
-func TestReadFrameZeroPayload(t *testing.T) {
-	want := Header{Type: FrameCancel, StreamID: 7}
-	frame := EncodeFrame(want, nil)
-	got, payload, err := ReadFrame(bytes.NewReader(frame))
-	if err != nil {
-		t.Fatalf("read: %v", err)
-	}
-	if got != want {
-		t.Errorf("header mismatch: %+v want %+v", got, want)
-	}
-	if len(payload) != 0 {
-		t.Errorf("expected empty payload, got %d bytes", len(payload))
-	}
-}
-
-func TestHelloRoundtrip(t *testing.T) {
-	want := HelloPayload{
-		FileSize:    1<<32 + 12345,
-		Transcoding: false,
-		Seekable:    true,
-		FileName:    "Tangled.Ever.After.2025.1080p.WEB-DL.h264.mp4",
-	}
-	flags := HelloFlags(want.Transcoding, want.Seekable)
-	payload := EncodeHello(want)
-	got, err := DecodeHello(payload, flags)
-	if err != nil {
-		t.Fatalf("decode: %v", err)
-	}
-	if got != want {
-		t.Errorf("hello mismatch: %+v want %+v", got, want)
-	}
-}
-
-func TestHelloRejectsTruncatedPayload(t *testing.T) {
-	if _, err := DecodeHello([]byte{1, 2, 3}, 0); err == nil {
-		t.Fatal("expected error on truncated hello")
-	}
-}
-
-func TestHelloRejectsNameLenOverrun(t *testing.T) {
-	// file_size + name_len=999 but no name bytes → should fail.
-	buf := make([]byte, 12)
-	buf[8], buf[9], buf[10], buf[11] = 0, 0, 0x03, 0xe7 // 999
-	if _, err := DecodeHello(buf, 0); err == nil {
-		t.Fatal("expected error on name_len overrun")
-	}
-}
-
-func TestRangeReqRoundtrip(t *testing.T) {
-	want := RangeReqPayload{Offset: 1 << 30, Length: 1 << 20}
-	got, err := DecodeRangeReq(EncodeRangeReq(want))
-	if err != nil {
-		t.Fatalf("decode: %v", err)
-	}
-	if got != want {
-		t.Errorf("range_req mismatch: %+v want %+v", got, want)
-	}
-}
-
-func TestRangeReqRejectsWrongLength(t *testing.T) {
-	if _, err := DecodeRangeReq(make([]byte, 15)); err == nil {
-		t.Fatal("expected error on 15-byte payload")
-	}
-	if _, err := DecodeRangeReq(make([]byte, 17)); err == nil {
-		t.Fatal("expected error on 17-byte payload")
-	}
-}
-
-func TestRangeEndRoundtrip(t *testing.T) {
-	want := RangeEndPayload{Status: 42}
-	got, err := DecodeRangeEnd(EncodeRangeEnd(want))
-	if err != nil {
-		t.Fatalf("decode: %v", err)
-	}
-	if got != want {
-		t.Errorf("range_end mismatch: %+v want %+v", got, want)
-	}
-	if _, err := DecodeRangeEnd(make([]byte, 3)); err == nil {
-		t.Fatal("expected error on short range_end payload")
-	}
-}
-
-func TestSeekHintRoundtrip(t *testing.T) {
-	want := SeekHintPayload{TimestampMs: 123_456}
-	got, err := DecodeSeekHint(EncodeSeekHint(want))
-	if err != nil {
-		t.Fatalf("decode: %v", err)
-	}
-	if got != want {
-		t.Errorf("seek_hint mismatch: %+v want %+v", got, want)
-	}
-	if _, err := DecodeSeekHint(make([]byte, 7)); err == nil {
-		t.Fatal("expected error on short seek_hint payload")
-	}
-}
-
-func TestHelloFlagsHelper(t *testing.T) {
-	if HelloFlags(false, false) != 0 {
-		t.Error("expected 0 for both false")
-	}
-	if HelloFlags(true, false) != FlagTranscoding {
-		t.Error("expected FlagTranscoding only")
-	}
-	if HelloFlags(false, true) != FlagSeekable {
-		t.Error("expected FlagSeekable only")
-	}
-	if HelloFlags(true, true) != (FlagTranscoding | FlagSeekable) {
-		t.Error("expected both flags")
-	}
-}
-
-// Sanity check that MaxChunkPayload + HeaderSize fits inside MaxFrameSize so
-// callers can rely on the chunk cap without their own bookkeeping.
-func TestMaxChunkFitsInMaxFrame(t *testing.T) {
-	if MaxChunkPayload+HeaderSize > MaxFrameSize {
-		t.Fatalf("chunk %d + hdr %d > max frame %d", MaxChunkPayload, HeaderSize, MaxFrameSize)
-	}
-}

internal/funnel/funnel.go

@@ -0,0 +1,199 @@
+// Package funnel manages the optional CloudFlare Quick Tunnel subprocess
+// that gives the daemon a public HTTPS hostname for cross-network playback
+// from browser-based clients (web player on torrentclaw.com / torrentclaw.to).
+//
+// Why: HTTPS pages can't fetch HTTP resources (mixed content). Without a
+// tunnel the daemon is only reachable from the same machine (localhost is
+// exempt) or via Tailscale (which users can install themselves but most
+// won't). CF Quick Tunnels are anonymous — no CF account, no DNS, no port
+// forwarding — and assign a one-shot `https://<random>.trycloudflare.com`
+// URL. Bytes flow through CF, never through our infra (legal posture: we
+// don't relay; CF does).
+//
+// Lifecycle:
+//
+//   t, err := funnel.Start(ctx, funnel.Config{Port: 11819})
+//   defer t.Close()
+//   url, err := t.WaitURL(30 * time.Second)  // blocks until cloudflared emits the URL
+//
+// The tunnel runs until the context is cancelled or t.Close() is called.
+package funnel
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os/exec"
+	"regexp"
+	"sync"
+	"time"
+)
+
+// urlPattern matches the `https://<random>.trycloudflare.com` URL cloudflared
+// prints when a Quick Tunnel is registered. The hostname has a random
+// hyphen-separated label followed by .trycloudflare.com.
+var urlPattern = regexp.MustCompile(`https://[a-z0-9-]+\.trycloudflare\.com`)
+
+// Config controls how the tunnel is launched.
+type Config struct {
+	// Port is the local upstream port cloudflared will tunnel to. Required.
+	Port int
+	// Binary is the cloudflared executable path. When empty the package looks
+	// it up via $PATH.
+	Binary string
+}
+
+// Tunnel is a handle on a running cloudflared Quick Tunnel.
+type Tunnel struct {
+	cmd     *exec.Cmd
+	cancel  context.CancelFunc
+	urlCh   chan string
+	exitCh  chan error
+	mu      sync.Mutex
+	url     string
+	stopped bool
+}
+
+// Start launches cloudflared as a subprocess. The returned *Tunnel exposes the
+// public URL via WaitURL once cloudflared registers it (usually 2–5 s).
+//
+// The subprocess inherits the cancellation of the supplied context. Closing
+// the *Tunnel sends SIGTERM and waits for the subprocess to exit.
+func Start(ctx context.Context, cfg Config) (*Tunnel, error) {
+	if cfg.Port <= 0 {
+		return nil, fmt.Errorf("funnel: invalid Port %d", cfg.Port)
+	}
+	binary := cfg.Binary
+	if binary == "" {
+		resolved, err := ResolveBinary()
+		if err != nil {
+			return nil, err
+		}
+		binary = resolved
+	}
+
+	subCtx, cancel := context.WithCancel(ctx)
+	// `--no-autoupdate` disables cloudflared's daily self-update check (the
+	// daemon manages binary rotation). `--metrics 127.0.0.1:0` suppresses the
+	// default `:9090` listener that would collide on a shared box.
+	cmd := exec.CommandContext(subCtx, binary,
+		"tunnel",
+		"--no-autoupdate",
+		"--metrics", "127.0.0.1:0",
+		"--url", fmt.Sprintf("http://localhost:%d", cfg.Port),
+	)
+
+	// cloudflared writes the connect log + assigned URL to stderr.
+	stderr, err := cmd.StderrPipe()
+	if err != nil {
+		cancel()
+		return nil, fmt.Errorf("funnel: pipe stderr: %w", err)
+	}
+	cmd.Stdout = io.Discard // quick tunnels print nothing useful on stdout
+
+	if err := cmd.Start(); err != nil {
+		cancel()
+		return nil, fmt.Errorf("funnel: start cloudflared: %w", err)
+	}
+
+	t := &Tunnel{
+		cmd:    cmd,
+		cancel: cancel,
+		urlCh:  make(chan string, 1),
+		exitCh: make(chan error, 1),
+	}
+
+	// Reader goroutine: scan cloudflared's stderr for the URL, surface the
+	// rest as a single string we don't try to interpret.
+	go t.scanStderr(stderr)
+
+	// Waiter goroutine: signal exit so callers can react (e.g. restart).
+	go func() {
+		t.exitCh <- cmd.Wait()
+	}()
+
+	return t, nil
+}
+
+// WaitURL blocks until cloudflared has registered the tunnel and emitted the
+// public URL, or `timeout` elapses, or the subprocess exits. The returned URL
+// has the form `https://<random>.trycloudflare.com`.
+func (t *Tunnel) WaitURL(timeout time.Duration) (string, error) {
+	t.mu.Lock()
+	if t.url != "" {
+		u := t.url
+		t.mu.Unlock()
+		return u, nil
+	}
+	t.mu.Unlock()
+
+	select {
+	case u := <-t.urlCh:
+		return u, nil
+	case err := <-t.exitCh:
+		if err == nil {
+			return "", errors.New("funnel: cloudflared exited before URL")
+		}
+		return "", fmt.Errorf("funnel: cloudflared exited: %w", err)
+	case <-time.After(timeout):
+		return "", fmt.Errorf("funnel: timed out waiting for URL after %s", timeout)
+	}
+}
+
+// URL returns the assigned tunnel URL, or "" if not yet emitted.
+func (t *Tunnel) URL() string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.url
+}
+
+// Done returns a channel that closes once the subprocess exits. The error sent
+// before close describes the exit reason (nil = clean shutdown via Close).
+func (t *Tunnel) Done() <-chan error {
+	return t.exitCh
+}
+
+// Close terminates the subprocess and waits for it to exit. Safe to call
+// multiple times.
+func (t *Tunnel) Close() error {
+	t.mu.Lock()
+	if t.stopped {
+		t.mu.Unlock()
+		return nil
+	}
+	t.stopped = true
+	t.mu.Unlock()
+	t.cancel()
+	// Drain the exit channel so the Wait goroutine doesn't leak.
+	select {
+	case <-t.exitCh:
+	case <-time.After(5 * time.Second):
+	}
+	return nil
+}
+
+func (t *Tunnel) scanStderr(r io.Reader) {
+	scanner := bufio.NewScanner(r)
+	// Some cloudflared lines exceed the default 64KiB scanner buffer (when it
+	// prints connection diagnostics). Bump to 1MiB.
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if t.URL() == "" {
+			if m := urlPattern.FindString(line); m != "" {
+				t.mu.Lock()
+				t.url = m
+				t.mu.Unlock()
+				// Non-blocking send: if no one is listening, just drop —
+				// the URL field carries the value for any later WaitURL call.
+				select {
+				case t.urlCh <- m:
+				default:
+				}
+			}
+		}
+	}
+}
+

internal/funnel/install.go

@@ -0,0 +1,167 @@
+package funnel
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+// ResolveBinary returns the path to a usable cloudflared executable, downloading
+// one into the unarr data dir if neither $PATH nor the cached location has it.
+// This makes the funnel feature usable on headless installs (NAS / Docker)
+// where the user can't easily install cloudflared via the OS package manager.
+//
+// Resolution order:
+//
+//  1. cloudflared on $PATH (operator already installed it)
+//  2. <data-dir>/bin/cloudflared (we cached it on a previous run)
+//  3. download from GitHub releases (Linux-only fallback; macOS / Windows
+//     return a clear error pointing at brew / winget)
+func ResolveBinary() (string, error) {
+	if p, err := exec.LookPath("cloudflared"); err == nil {
+		return p, nil
+	}
+	cached := cachedBinaryPath()
+	if _, err := os.Stat(cached); err == nil {
+		return cached, nil
+	}
+	return downloadCloudflared(cached)
+}
+
+func cachedBinaryPath() string {
+	name := "cloudflared"
+	if runtime.GOOS == "windows" {
+		name += ".exe"
+	}
+	return filepath.Join(config.DataDir(), "bin", name)
+}
+
+// downloadCloudflared fetches the latest cloudflared release asset matching
+// the current GOOS/GOARCH into `dest`. Linux only — macOS/Windows return a
+// pointer at the OS package manager.
+//
+// Supply-chain caveat: we trust GitHub-over-TLS + cloudflare/cloudflared
+// repo integrity. The fetch is over HTTPS to api.github.com's release-asset
+// redirector, so a network MITM is bounded by Let's Encrypt + GitHub's cert
+// chain. We additionally verify the file is an ELF binary (Linux magic
+// bytes) so a generic 404 HTML page or a wrong-arch tarball is rejected at
+// rest. We do NOT verify a signature because Cloudflare doesn't sign release
+// assets at the moment — if you need stricter integrity, install cloudflared
+// from your distro's package manager (apt/brew/winget) and unarr will use
+// the PATH copy.
+func downloadCloudflared(dest string) (string, error) {
+	if runtime.GOOS != "linux" {
+		return "", fmt.Errorf("funnel: auto-download not supported on %s — install cloudflared manually or drop a binary at %s", runtime.GOOS, dest)
+	}
+
+	var asset string
+	switch runtime.GOARCH {
+	case "amd64":
+		asset = "cloudflared-linux-amd64"
+	case "arm64":
+		asset = "cloudflared-linux-arm64"
+	case "arm":
+		asset = "cloudflared-linux-armhf"
+	case "386":
+		asset = "cloudflared-linux-386"
+	default:
+		return "", fmt.Errorf("funnel: unsupported linux arch %q — install cloudflared manually", runtime.GOARCH)
+	}
+
+	url := "https://github.com/cloudflare/cloudflared/releases/latest/download/" + asset
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("funnel: create bin dir: %w", err)
+	}
+
+	// O_EXCL so concurrent unarr-dev / prod daemons don't clobber each
+	// other's partial download. The loser gets EEXIST → falls back to
+	// polling for the winner to finish.
+	tmp := dest + ".partial"
+	out, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o755)
+	if err != nil {
+		if errors.Is(err, os.ErrExist) {
+			// Another process is downloading. Wait briefly for them to finish.
+			for range 60 {
+				time.Sleep(time.Second)
+				if _, statErr := os.Stat(dest); statErr == nil {
+					return dest, nil
+				}
+			}
+			return "", fmt.Errorf("funnel: another download in progress at %s (timed out)", tmp)
+		}
+		return "", fmt.Errorf("funnel: open dest: %w", err)
+	}
+
+	client := &http.Client{Timeout: 5 * time.Minute}
+	resp, err := client.Get(url)
+	if err != nil {
+		_ = out.Close()
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: download cloudflared: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		_ = out.Close()
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: download cloudflared: HTTP %d from %s", resp.StatusCode, url)
+	}
+
+	if _, err := io.Copy(out, resp.Body); err != nil {
+		_ = out.Close()
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: write dest: %w", err)
+	}
+	if err := out.Close(); err != nil {
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: close dest: %w", err)
+	}
+
+	// Sanity check before promoting <partial> to <dest>: must be a Linux
+	// ELF executable (rejects 404 HTML pages or wrong-arch payloads) and at
+	// least 1 MB (real cloudflared is ~50 MB; anything smaller is corrupt).
+	if err := verifyLinuxElf(tmp); err != nil {
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: downloaded file failed sanity check: %w", err)
+	}
+
+	if err := os.Rename(tmp, dest); err != nil {
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: rename dest: %w", err)
+	}
+	return dest, nil
+}
+
+// verifyLinuxElf returns nil when the file at `path` starts with the ELF
+// magic bytes and is at least 1 MB. Used as a low-cost guard against
+// downloading an HTML error page or a wrong-arch payload.
+func verifyLinuxElf(path string) error {
+	st, err := os.Stat(path)
+	if err != nil {
+		return err
+	}
+	if st.Size() < 1024*1024 {
+		return errors.New("file is suspiciously small (<1 MB)")
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	head := make([]byte, 4)
+	if _, err := io.ReadFull(f, head); err != nil {
+		return fmt.Errorf("read magic bytes: %w", err)
+	}
+	if !bytes.Equal(head, []byte{0x7f, 'E', 'L', 'F'}) {
+		return errors.New("not an ELF binary")
+	}
+	return nil
+}

internal/library/mediainfo/ffmpeg.go

@@ -18,7 +18,7 @@ import (
 //  5. Previously downloaded in the unarr cache dir
 //  6. Auto-download static binary as last resort (~50MB, slow start)
 //
-// ffmpeg is required for the WebRTC streaming pipeline; ffprobe alone can't
+// ffmpeg is required for the HLS streaming pipeline; ffprobe alone can't
 // transcode HEVC/MKV to browser-friendly H.264/MP4 fragments.
 func ResolveFFmpeg(explicit string) (string, error) {
 	if explicit != "" {

internal/library/resolve.go

@@ -13,8 +13,17 @@ var (
 	altEpRegex  = regexp.MustCompile(`(?i)(\d{1,2})x(\d{2})`)
 )
 
-// ResolveResolution maps a pixel height to a standard resolution label.
+// ResolveResolution maps video dimensions to a standard resolution label.
-func ResolveResolution(height int) string {
+// Uses both width and height so cinematic aspect ratios (2.35:1, 2.39:1, 21:9)
+// are not misclassified — e.g. a 1080p source presented as 1920×804 letterboxed
+// would fall to 720p if classified by height alone.
+func ResolveResolution(width, height int) string {
+	byHeight := resolutionByHeight(height)
+	byWidth := resolutionByWidth(width)
+	return maxResolution(byHeight, byWidth)
+}
+
+func resolutionByHeight(height int) string {
 	switch {
 	case height >= 2000:
 		return "2160p"
@@ -29,6 +38,36 @@ func ResolveResolution(height int) string {
 	}
 }
 
+func resolutionByWidth(width int) string {
+	switch {
+	case width >= 3400:
+		return "2160p"
+	case width >= 1800:
+		return "1080p"
+	case width >= 1200:
+		return "720p"
+	case width >= 800:
+		return "480p"
+	default:
+		return ""
+	}
+}
+
+var resolutionRank = map[string]int{
+	"":      0,
+	"480p":  1,
+	"720p":  2,
+	"1080p": 3,
+	"2160p": 4,
+}
+
+func maxResolution(a, b string) string {
+	if resolutionRank[a] >= resolutionRank[b] {
+		return a
+	}
+	return b
+}
+
 // DeriveContentType guesses "movie" or "show" from parsed metadata.
 func DeriveContentType(item LibraryItem) string {
 	if item.Season > 0 || item.Episode > 0 {

internal/library/resolve_test.go

@@ -8,28 +8,31 @@ import (
 
 func TestResolveResolution(t *testing.T) {
 	tests := []struct {
+		name   string
+		width  int
 		height int
 		want   string
 	}{
-		{2160, "2160p"},
+		{"4K square", 3840, 2160, "2160p"},
-		{2000, "2160p"},
+		{"4K low height", 3840, 1600, "2160p"},
-		{1080, "1080p"},
+		{"1080p square", 1920, 1080, "1080p"},
-		{1920, "1080p"}, // 1920 is width, not height — height for 1080p is ~1080
+		{"1080p cinematic 2.39:1", 1920, 804, "1080p"}, // anamorphic widescreen — must not fall to 720p
-		{900, "1080p"},
+		{"1080p cinematic 2.35:1", 1920, 818, "1080p"},
-		{720, "720p"},
+		{"1080p 21:9", 2560, 1080, "1080p"},
-		{600, "720p"},
+		{"720p square", 1280, 720, "720p"},
-		{576, "480p"},
+		{"720p widescreen", 1280, 540, "720p"},
-		{480, "480p"},
+		{"480p", 854, 480, "480p"},
-		{400, "480p"},
+		{"sub-480", 640, 360, ""},
-		{360, ""},
+		{"zero", 0, 0, ""},
-		{0, ""},
 	}
 
 	for _, tt := range tests {
-		got := ResolveResolution(tt.height)
+		t.Run(tt.name, func(t *testing.T) {
-		if got != tt.want {
+			got := ResolveResolution(tt.width, tt.height)
-			t.Errorf("ResolveResolution(%d) = %q, want %q", tt.height, got, tt.want)
+			if got != tt.want {
-		}
+				t.Errorf("ResolveResolution(%d, %d) = %q, want %q", tt.width, tt.height, got, tt.want)
+			}
+		})
 	}
 }
 

internal/library/sync.go

@@ -23,7 +23,7 @@ func BuildSyncItems(cache *LibraryCache) []agent.LibrarySyncItem {
 
 		if item.MediaInfo != nil {
 			if item.MediaInfo.Video != nil {
-				si.Resolution = ResolveResolution(item.MediaInfo.Video.Height)
+				si.Resolution = ResolveResolution(item.MediaInfo.Video.Width, item.MediaInfo.Video.Height)
 				si.VideoCodec = item.MediaInfo.Video.Codec
 				si.HDR = item.MediaInfo.Video.HDR
 				si.BitDepth = item.MediaInfo.Video.BitDepth

internal/sentry/sentry.go

@@ -1,12 +1,14 @@
 package sentry
 
 import (
+	"errors"
 	"os"
 	"runtime"
 	"strings"
 	"time"
 
 	gosentry "github.com/getsentry/sentry-go"
+	"github.com/spf13/pflag"
 )
 
 // dsn is injected at build time via ldflags. If empty, Sentry is disabled.
@@ -44,9 +46,16 @@ func Close() {
 	gosentry.Flush(flushTimeout)
 }
 
+// daemonNotRunningMarker matches the message of agent.ErrDaemonNotRunning
+// without importing the agent package — avoids a sentry → agent dependency
+// that would risk a cycle if agent ever needed to report errors itself.
+const daemonNotRunningMarker = "daemon does not appear to be running"
+
 // CaptureError sends a non-fatal error to Sentry with optional command context.
+// Expected non-bug errors (bad CLI input, daemon not running) are skipped to
+// keep the issue feed signal-heavy.
 func CaptureError(err error, command string) {
-	if err == nil {
+	if err == nil || shouldSkipSentry(err) {
 		return
 	}
 
@@ -58,6 +67,21 @@ func CaptureError(err error, command string) {
 	})
 }
 
+func shouldSkipSentry(err error) bool {
+	var notExist *pflag.NotExistError
+	var valueReq *pflag.ValueRequiredError
+	var invalidVal *pflag.InvalidValueError
+	var invalidSyn *pflag.InvalidSyntaxError
+	if errors.As(err, &notExist) || errors.As(err, &valueReq) ||
+		errors.As(err, &invalidVal) || errors.As(err, &invalidSyn) {
+		return true
+	}
+	msg := err.Error()
+	return strings.HasPrefix(msg, "unknown command ") ||
+		strings.HasPrefix(msg, "required flag(s)") ||
+		strings.Contains(msg, daemonNotRunningMarker)
+}
+
 // RecoverPanic captures a panic and re-panics after reporting.
 // Usage: defer sentry.RecoverPanic()
 func RecoverPanic() {

internal/sentry/sentry_test.go

@@ -1,6 +1,10 @@
 package sentry
 
-import "testing"
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
 
 func TestEnvironment(t *testing.T) {
 	tests := []struct {
@@ -45,3 +49,16 @@ func TestSetUser(t *testing.T) {
 	// Should not panic without initialization
 	SetUser("agent-123")
 }
+
+func TestShouldSkipSentryDaemonNotRunning(t *testing.T) {
+	// String must stay in sync with agent.ErrDaemonNotRunning. If that sentinel
+	// is reworded, this test fails loudly so the marker can be updated.
+	err := errors.New("daemon does not appear to be running (state file not found)")
+	if !shouldSkipSentry(err) {
+		t.Error("ErrDaemonNotRunning message should be skipped")
+	}
+	wrapped := fmt.Errorf("read daemon state: %w", err)
+	if !shouldSkipSentry(wrapped) {
+		t.Error("wrapped ErrDaemonNotRunning message should be skipped")
+	}
+}

scripts/release.sh

@@ -55,6 +55,17 @@ fi
 CURRENT_BRANCH=$(git branch --show-current)
 [ "$CURRENT_BRANCH" = "main" ] || warn "Not on main branch (current: $CURRENT_BRANCH)"
 
+HEAD_SUBJECT=$(git log -1 --pretty=%s)
+if [[ "$HEAD_SUBJECT" =~ \(([0-9]+\.[0-9]+\.[0-9]+)\) ]]; then
+  die "HEAD commit subject contains inline version bump: \"$HEAD_SUBJECT\"
+Release contract: version bumps MUST live in a dedicated 'chore(release): X.Y.Z' commit.
+Revert the inline bump and re-run this script — it will create the proper commit."
+fi
+if [[ "$HEAD_SUBJECT" =~ ^chore\(release\): ]]; then
+  die "HEAD is already a chore(release) commit: \"$HEAD_SUBJECT\"
+Nothing new to release. Add commits since the last release or amend intentionally outside this script."
+fi
+
 # ── Resolve version ────────────────────────────────────────────────
 LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
 LATEST_VERSION="${LATEST_TAG#v}"

scripts/ship.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+#
+# ship.sh — End-to-end CLI release pipeline.
+#
+# Standalone backup for when GitHub Actions is unavailable (org shadow-ban,
+# CI outage, etc). Mirrors what release.yml + docker job in CI would do.
+#
+# Pre-requisites:
+#   - scripts/release.sh already ran → version.go bumped + tag created locally
+#   - SENTRY_DSN exported (Sentry disabled in build if missing)
+#   - docker logged in to docker.io as the org user
+#   - SSH key for Hetzner publishing (see publish-cli-release.sh)
+#
+# Pipeline:
+#   1. Sanity: clean tree, tag at HEAD, version.go matches
+#   2. goreleaser build (skip GH publish — produces dist/*)
+#   3. Rsync to Hetzner via web/scripts/publish-cli-release.sh
+#   4. Multi-arch Docker build + push (amd64 + arm64) to Docker Hub
+#   5. Smoke checks (torrentclaw.com/version + docker run image version)
+#   6. Prune Forgejo releases older than FORGEJO_PRUNE_DAYS (default 90)
+#   7. Optional `git push --follow-tags`
+#
+# Usage:
+#   scripts/ship.sh                  Detect version from internal/cmd/version.go
+#   scripts/ship.sh 0.9.12           Explicit version
+#   scripts/ship.sh --dry-run        Preview steps, no side effects
+#   scripts/ship.sh --push 0.9.12    Also git-push tag to GH afterwards
+#
+# Env knobs:
+#   SENTRY_DSN              telemetry DSN injected at build time
+#   RELEASE_SIGNING_PUBKEY  ed25519 pubkey (base64) for self-update signature check
+#   DOCKER_IMAGE            default torrentclaw/unarr
+#   PUBLISH_SCRIPT          default ../torrentclaw-web/scripts/publish-cli-release.sh
+#   SKIP_DOCKER=1           skip Docker build/push
+#   SKIP_HETZNER=1          skip Hetzner publish
+#   SKIP_SMOKE=1            skip smoke checks
+#   SKIP_FORGEJO_PRUNE=1    skip Forgejo retention prune
+#   FORGEJO_TOKEN           PAT with write:repository for prune (no token = skip + warn)
+#   FORGEJO_PRUNE_DAYS      retention window, default 90 days
+#   FORGEJO_REPO            default torrentclaw/unarr
+#
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_DIR"
+
+DOCKER_IMAGE="${DOCKER_IMAGE:-torrentclaw/unarr}"
+PUBLISH_SCRIPT="${PUBLISH_SCRIPT:-$REPO_DIR/../torrentclaw-web/scripts/publish-cli-release.sh}"
+SKIP_DOCKER="${SKIP_DOCKER:-0}"
+SKIP_HETZNER="${SKIP_HETZNER:-0}"
+SKIP_SMOKE="${SKIP_SMOKE:-0}"
+SKIP_FORGEJO_PRUNE="${SKIP_FORGEJO_PRUNE:-0}"
+FORGEJO_PRUNE_DAYS="${FORGEJO_PRUNE_DAYS:-90}"
+FORGEJO_REPO="${FORGEJO_REPO:-torrentclaw/unarr}"
+FORGEJO_BASE="${FORGEJO_BASE:-https://git.torrentclaw.com}"
+
+DRY_RUN=false
+PUSH_TAG=false
+VERSION=""
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'
+info()  { echo -e "${CYAN}▸${NC} $*"; }
+ok()    { echo -e "${GREEN}✓${NC} $*"; }
+warn()  { echo -e "${YELLOW}⚠${NC} $*"; }
+die()   { echo -e "${RED}✗${NC} $*" >&2; exit 1; }
+
+for a in "$@"; do
+  case "$a" in
+    --dry-run) DRY_RUN=true ;;
+    --push)    PUSH_TAG=true ;;
+    -h|--help)
+      sed -n '2,/^set /p' "$0" | sed 's/^#\s\?//;$d'
+      exit 0 ;;
+    [0-9]*)    VERSION="$a" ;;
+    *)         die "unknown arg: $a (use --help)" ;;
+  esac
+done
+
+read_version_go() {
+  grep 'var Version' internal/cmd/version.go | sed 's/.*"\(.*\)".*/\1/'
+}
+
+REPO_VERSION="$(read_version_go)"
+[ -z "$VERSION" ] && VERSION="$REPO_VERSION"
+[ -n "$VERSION" ] || die "cannot detect version (pass explicit X.Y.Z)"
+TAG="v$VERSION"
+MINOR="${VERSION%.*}"
+
+echo ""
+echo -e "  ${BOLD}Ship Plan${NC}"
+echo -e "  ─────────────────────────────"
+echo -e "  Version:        ${GREEN}$TAG${NC}"
+echo -e "  Docker image:   $DOCKER_IMAGE:{$VERSION,$MINOR,latest}"
+echo -e "  Skip Hetzner:   $SKIP_HETZNER"
+echo -e "  Skip Docker:    $SKIP_DOCKER"
+echo -e "  Push to GH:     $PUSH_TAG"
+echo -e "  Dry run:        $DRY_RUN"
+echo ""
+
+# Sanity
+[ "$REPO_VERSION" = "$VERSION" ] || die "version.go=$REPO_VERSION ≠ requested $VERSION (bump with make release-* first)"
+
+if [ "$DRY_RUN" = false ]; then
+  [ -z "$(git status --porcelain)" ] || die "working tree dirty"
+  git rev-parse "$TAG" >/dev/null 2>&1 || die "tag $TAG missing — run scripts/release.sh first"
+
+  HEAD_SHA="$(git rev-parse HEAD)"
+  TAG_SHA="$(git rev-parse "$TAG^{commit}")"
+  [ "$HEAD_SHA" = "$TAG_SHA" ] || die "HEAD ($HEAD_SHA) ≠ tag commit ($TAG_SHA) — checkout $TAG first"
+
+  command -v goreleaser >/dev/null || die "goreleaser not installed"
+  [ "$SKIP_DOCKER" = "1" ] || command -v docker >/dev/null || die "docker not installed"
+  [ "$SKIP_HETZNER" = "1" ] || [ -x "$PUBLISH_SCRIPT" ] || die "publish script missing or not executable: $PUBLISH_SCRIPT"
+
+  if [ -z "${SENTRY_DSN:-}" ]; then
+    warn "SENTRY_DSN unset — built binaries will have Sentry disabled"
+  fi
+fi
+
+if [ "$DRY_RUN" = true ]; then
+  ok "Dry run complete — no changes made"
+  exit 0
+fi
+
+# 1. Build
+info "goreleaser build ($TAG)"
+SENTRY_DSN="${SENTRY_DSN:-}" RELEASE_SIGNING_PUBKEY="${RELEASE_SIGNING_PUBKEY:-}" \
+  goreleaser release --clean --skip=publish
+ok "dist/ ready"
+
+# 2. Hetzner
+if [ "$SKIP_HETZNER" != "1" ]; then
+  info "publishing to Hetzner releases volume"
+  "$PUBLISH_SCRIPT" "$VERSION"
+  ok "Hetzner version.txt flipped to $VERSION"
+fi
+
+# 3. Docker
+if [ "$SKIP_DOCKER" != "1" ]; then
+  info "docker buildx multi-arch push ($DOCKER_IMAGE:$VERSION, :$MINOR, :latest)"
+  docker buildx build \
+    --platform linux/amd64,linux/arm64 \
+    --build-arg VERSION="$TAG" \
+    -t "$DOCKER_IMAGE:$VERSION" \
+    -t "$DOCKER_IMAGE:$MINOR" \
+    -t "$DOCKER_IMAGE:latest" \
+    --push .
+  ok "Docker Hub: $DOCKER_IMAGE:{$VERSION,$MINOR,latest}"
+fi
+
+# 4. Smoke
+if [ "$SKIP_SMOKE" != "1" ]; then
+  info "smoke checks"
+  if [ "$SKIP_HETZNER" != "1" ]; then
+    LIVE_VERSION="$(curl -fsSL https://torrentclaw.com/version 2>/dev/null | tr -d '[:space:]' || echo '')"
+    if [ "$LIVE_VERSION" = "$VERSION" ]; then
+      ok "torrentclaw.com/version = $LIVE_VERSION"
+    else
+      warn "torrentclaw.com/version = '$LIVE_VERSION' (expected $VERSION)"
+    fi
+  fi
+
+  if [ "$SKIP_DOCKER" != "1" ]; then
+    DOCKER_VERSION="$(docker run --rm "$DOCKER_IMAGE:$VERSION" version 2>/dev/null | grep -oE 'v[0-9.]+' | head -1)"
+    if [ "$DOCKER_VERSION" = "$TAG" ]; then
+      ok "docker image $DOCKER_IMAGE:$VERSION reports $DOCKER_VERSION"
+    else
+      warn "docker image reports '$DOCKER_VERSION' (expected $TAG)"
+    fi
+  fi
+fi
+
+# 6. Forgejo retention prune
+if [ "$SKIP_FORGEJO_PRUNE" != "1" ]; then
+  if [ -z "${FORGEJO_TOKEN:-}" ]; then
+    warn "FORGEJO_TOKEN not set — skipping Forgejo prune (set it to enable >${FORGEJO_PRUNE_DAYS}-day cleanup)"
+  else
+    info "pruning Forgejo releases older than $FORGEJO_PRUNE_DAYS days"
+    FORGEJO_API="$FORGEJO_BASE/api/v1/repos/$FORGEJO_REPO/releases"
+    RELEASES_JSON="$(curl -fsSL -H "Authorization: token $FORGEJO_TOKEN" "$FORGEJO_API?limit=50" || echo '[]')"
+    PRUNE_IDS="$(echo "$RELEASES_JSON" | python3 -c "
+import json, sys
+from datetime import datetime, timedelta, timezone
+days = int('${FORGEJO_PRUNE_DAYS}')
+cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+for r in json.load(sys.stdin):
+    created = datetime.fromisoformat(r['created_at'].replace('Z', '+00:00'))
+    if created < cutoff:
+        print(f\"{r['id']}\t{r['tag_name']}\t{r['created_at']}\")
+" 2>/dev/null || true)"
+    DELETED=0
+    FAILED=0
+    if [ -n "$PRUNE_IDS" ]; then
+      while IFS=$'\t' read -r REL_ID REL_TAG REL_CREATED; do
+        [ -z "$REL_ID" ] && continue
+        CODE="$(curl -s -o /dev/null -w '%{http_code}' -X DELETE -H "Authorization: token $FORGEJO_TOKEN" "$FORGEJO_API/$REL_ID")"
+        if [ "$CODE" = "204" ]; then
+          echo "    deleted $REL_TAG (created $REL_CREATED)"
+          DELETED=$((DELETED + 1))
+        else
+          warn "    failed to delete $REL_TAG (id=$REL_ID, http=$CODE)"
+          FAILED=$((FAILED + 1))
+        fi
+      done <<< "$PRUNE_IDS"
+    fi
+    if [ "$FAILED" -gt 0 ]; then
+      warn "Forgejo prune: $DELETED removed, $FAILED failed"
+    else
+      ok "Forgejo prune: $DELETED release(s) removed (>${FORGEJO_PRUNE_DAYS} days old)"
+    fi
+  fi
+fi
+
+# 7. Optional push
+if [ "$PUSH_TAG" = true ]; then
+  info "git push origin main --follow-tags"
+  git push origin main --follow-tags
+  ok "tag $TAG pushed to GitHub"
+fi
+
+echo ""
+ok "${BOLD}$TAG shipped${NC}"