.env.example

@@ -29,6 +29,9 @@ EXCLUDED_DIRS=
 # ── Video / HLS ─────────────────────────────────────────────────────────
 HLS_CONCURRENCY=2
 HLS_TIMEOUT_SECONDS=900
+# Sources above this bitrate (bits/s) or 1080p are transcoded instead of
+# stream-copied, so HLS segments stay small enough to start and seek quickly.
+HLS_COPY_MAX_BITRATE=20000000
 PLAYLIST_CLEANUP_INTERVAL_SECONDS=86400
 
 # ── Telemetry ────────────────────────────────────────────────────────────

CLAUDE.md

@@ -708,6 +708,7 @@ Optional:
 WATCH_QUICK_INTERVAL_SECONDS=60        # Quick scan interval
 WATCH_FULL_INTERVAL_SECONDS=3600       # Full scan interval
 DATE_BACKFILL_MAX_PER_TICK=500         # Cap on canonical-date drain per watcher tick
+HLS_COPY_MAX_BITRATE=20000000          # Max source bits/s to stream-copy into HLS; above it (or >1080p) transcodes
 OTLP_OTLS_ENDPOINT=http://...          # OTLP collector for span export (any build; unset = no export)
 
 # AI Insights Configuration

README.md

@@ -69,6 +69,7 @@ They should be defined where the binary is located or above it in an `.env` file
   skip them. Delete the `*.unsupported` files to force retries (for example
   after upgrading ffmpeg or adding libheif)
 - `VIDEO_PATH` is a path where HLS playlists and video parts should be stored
+- `HLS_COPY_MAX_BITRATE` (optional) is the highest source bitrate, in bits/s, that is stream-copied into HLS as-is. Higher-bitrate sources, and any with a short side over 1080 px, are transcoded down to 1080p [default: `20000000`]
 - `GIFS_DIRECTORY` is a path where generated video GIF thumbnails should be stored
 - `BIND_URL` is the url and port to bind to (typically your own IP address)
 - `LOCAL_BIND_URL` (optional) is a second, loopback listener [default: `localhost:8088`]. Set it to an empty string to skip it, e.g. to run a second instance such as the `dev/e2e` harness alongside one that already owns 8088