From e056f1a40047e94f4090d528f948c8a9b0086494 Mon Sep 17 00:00:00 2001 From: mouldybread <38598858+mouldybread@users.noreply.github.com> Date: Sat, 21 Nov 2026 13:42:21 +0800 Subject: [PATCH] Document v0.2.2 export setup, modes and verified CI evidence --- README.md | 38 ++++++++++-- docs/EXPORT_API_MODES.md | 22 ++++--- docs/EXPORT_RENDERING.md | 30 ++++++---- docs/LARGE_MEDIA_EXPORTS.md | 89 ++++++++++++++++++++-------- docs/PREPARED_EXPORT_VERIFICATION.md | 36 +++++++++-- 5 files changed, 163 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index f4061f3..f8c7d88 100644 --- a/README.md +++ b/README.md @@ -4,30 +4,40 @@ SimpleNVR records RTSP cameras with FFmpeg. Use the web interface to manage came ## Install with Docker Compose -Use the published image from GitHub Container Registry. This example requires an image release with built-in authentication. The `v0.1.0` release predates that feature. Until a compatible tag is published, this example is not runnable as written. +Use the image from GitHub Container Registry. The example defaults to `v0.2.2`, which includes built-in authentication and server-prepared exports. An image's release workflow must finish publishing before it can be pulled. Save as `compose.yaml`: ```yaml services: simplenvr: - image: ghcr.io/mouldybread/simplenvr:latest + image: ghcr.io/mouldybread/simplenvr:${SIMPLENVR_VERSION:-v0.2.2} restart: unless-stopped ports: - "127.0.0.1:8443:443" + environment: + NVR_EXPORT_SCRATCH_DIR: /exports volumes: - type: bind source: ./recordings target: /recordings bind: create_host_path: false + - type: bind + source: ./exports + target: /exports + bind: + create_host_path: false - ./certs:/certs ``` -Set `SIMPLENVR_VERSION` in `.env` to a published tag that includes built-in authentication. Then run: +Optionally set `SIMPLENVR_VERSION` in `.env` to another published version that supports these features. Unlike the old example, this Compose file actually uses that setting. + +For a new installation, run: ```sh -mkdir -p recordings certs +mkdir -p recordings certs exports +chmod 700 exports docker compose pull && docker compose run --rm simplenvr auth set-password admin && docker compose up -d @@ -35,6 +45,12 @@ docker compose up -d Use a password of at least 15 characters. On the Docker host, open `https://localhost:8443/auth/login` and sign in as `admin`. The default self-signed certificate triggers a browser warning. Set the password once; skip that step on later starts. The example listens only on localhost. For a first test, use a fresh recordings directory, not production storage. +The `exports` directory holds temporary prepared video files. Keep it private, writable by the container user, and on disk-backed storage with enough free space. It must be outside `recordings` and every camera directory, with no symlinks in the configured container path. Do not use a tmpfs or the container's writable layer for large exports. Without `NVR_EXPORT_SCRATCH_DIR`, prepared video exports are unavailable. See [large-media exports](docs/LARGE_MEDIA_EXPORTS.md) for limits and settings. + +### Upgrading to v0.2.2 + +Keep your existing recordings, certificates, and credentials. Add the `/exports` mount and `NVR_EXPORT_SCRATCH_DIR` setting to your existing Compose service, create the host export directory with suitable permissions, then pull the image and recreate the service. Do not reset the password as part of a routine upgrade. Prepared export jobs are lost on restart; recording files are not export scratch storage. + ## Session timeouts A session ends after 20 minutes without a request, or 8 hours after sign-in, whichever comes first. To change either limit, click the lock button in the dashboard header, enter the new values in minutes, and choose Save and restart (click twice to confirm). SimpleNVR saves the values to `settings.json` in the same directory as the credentials file (`/recordings/.auth/settings.json` by default), shuts down gracefully, and relies on the container's restart policy to start it again. Keep `restart: unless-stopped` (or `always`) in your Compose file: with `on-failure` or no policy the container stays stopped until you start it. The restart stops live views and exports, pauses recording until SimpleNVR is back, and ends all current sessions. Nothing restarts if the saved values already match the running ones. @@ -45,9 +61,21 @@ The idle timeout must be between 1 minute and 24 hours, and the maximum session - In Camera Settings, add an RTSP URL or import streams from go2rtc. Choose continuous recording, event-based recording with a prebuffer, or no recording. Adding a camera does not start recording. - Live preview requires go2rtc on the host in the camera's RTSP URL, with its HTTP API on port `1984`. The camera name must be unique and match the go2rtc stream name. Direct-camera preview and custom go2rtc HTTP ports are not supported. -- Use the timeline to find recordings and events. Playback does not automatically skip gaps. Use Downloads to select cameras and a time range for MP4 export. +- Use the timeline to find recordings and events. Playback does not automatically skip gaps. Use Downloads to export video; see below. +- Known continuous-recording failures appear as "Recording failed" or "Recording failed — retrying", with the recording setting and reason shown separately. "Recording enabled" is a setting, not proof that footage is being captured. - Removing a camera can delete its published recordings. If removal fails or the result is unclear, refresh and check the camera and its recordings before retrying. +## Export video + +In Downloads, choose cameras, adjust the start and end times, and choose a mode: + +- Copy (default) preserves the encoded media without re-encoding. A single complete recording is copied byte for byte; compatible complete recordings can be joined without re-encoding. For part of a recording, SimpleNVR shows the proposed video range and audio packet allowance and waits for approval before creating a job. An unsupported copy is refused, never silently converted to Accurate. +- Accurate re-encodes supported video and audio to cut within frame and packet limits at the selected times. It is not lossless and can require more processing. + +Choose Prepare exports on server. SimpleNVR prepares one camera's file at a time. When ready, choose Download prepared video. Once your browser has accepted the download, release the prepared file to continue to the next camera; an already-started transfer may continue. The page cannot verify that your browser saved the file to disk. + +Prepared files expire, normally 30 minutes after preparation finishes, and do not survive a restart. Exports require complete recording coverage: gaps are never skipped silently. See [export rendering](docs/EXPORT_RENDERING.md) for supported media and timing limitations. + ## Home Assistant events Create an event token with the same Compose service and recordings directory: diff --git a/docs/EXPORT_API_MODES.md b/docs/EXPORT_API_MODES.md index c345d6d..cf4bd80 100644 --- a/docs/EXPORT_API_MODES.md +++ b/docs/EXPORT_API_MODES.md @@ -1,13 +1,21 @@ -# Export modes: integration and verification status +# Export modes -The HTTP planner and browser are wired to prepared copy/accurate exports. Copy is the default and never silently switches to re-encoding. Whole single-source copies preserve original bytes in prepared storage; compatible multiple sources preserve compressed A/V payloads when remuxed. This is not zero-copy original-file HTTP delivery. +The HTTP planner and browser use prepared Copy and Accurate exports. Copy is the default and never silently changes to re-encoding. A single complete source is copied byte for byte into prepared storage. Compatible complete sources are remuxed with compressed audio/video payloads preserved. This is not zero-copy original-file delivery. -Subsection copy supports non-reordered video with usable decoded keyframe timestamps. The server proposes video boundaries at keyframe/file boundaries, reinspects expanded coverage and returns copy_range_approval_required before admitting a job. The UI shows the requested/proposed intervals and AAC packet allowance and waits for explicit approval. Canceling a proposal creates no job. Approval retains the original selection and sends accepted_start/end for fresh server checks. Changed proposals require another click. Unsupported copy must be changed to Accurate explicitly. +## Subsection copy and approval -AAC packet edges may extend outside the video-aligned interval by the disclosed allowance. Timing is metadata/frame/packet granular, not calibrated camera-clock time. Candidate copy outputs are duration-probed and externally decoded before readiness; this is not a proof of every source frame/sample or colour value. +Copy of part of a recording supports non-reordered video with usable keyframe timestamps. The server proposes video boundaries at keyframe or file boundaries and rechecks the expanded range for gaps/overlaps. It returns `copy_range_approval_required` before creating a job. The browser shows requested/proposed video intervals and the AAC packet allowance and waits for explicit approval. Cancelling the proposal creates no job. -Accurate explicitly re-encodes video with libx264 CRF 18 and audio with AAC. Both tracks share the video/cut origin; supported audio offsets are preserved. Full-range input becomes limited-range yuv420p, so accurate exports are not lossless or byte-identical. Leading/trailing silence can maintain the selected window without stretching audio. Mixed audio configurations, extra tracks, rotation and higher bit depths remain unsupported. +Approval retains the original selection and sends `accepted_start`/`accepted_end` for fresh server checks; changed video boundaries need another approval. Unsupported copy must be changed to Accurate explicitly. AAC packet edges may extend outside the video-aligned interval by the disclosed allowance. -The live-container browser acceptance harness has been migrated to prepared jobs, real downloads and server release. Its container now mounts private export scratch. Branch-triggered Go and two-attempt Chrome workflows test the same pushed commit. See PREPARED_EXPORT_VERIFICATION.md for assertions and the distinction between local helper checks and actual CI results. The older routed-fixture browser script remains separate and unmigrated. +## Accurate and timing -Release readiness is NOT established until both workflows pass on the final commit and failures are resolved. Nothing in this change merges, deploys or certifies real-camera/full-resolution/multi-GiB operation. Scratch settings, quotas, session isolation and leases remain described in LARGE_MEDIA_EXPORTS.md. +Accurate uses libx264 CRF 18 and AAC encoding, sharing the video/cut origin between tracks and preserving supported audio offsets. Full-range input becomes limited-range `yuv420p`, so the result is neither byte-identical nor lossless. Leading/trailing silence can maintain the selected window without stretching audio. Mixed audio configurations, extra tracks, rotation and higher bit depths are unsupported. + +Timing is frame/packet-granular, not calibrated camera-clock time. Duration probes and candidate copy decode do not prove completeness or fidelity of every frame/sample. + +## Setup and evidence + +The live-container browser harness now uses prepared jobs, normal downloads and server release with private export scratch configured. Go and Chrome checks passed on PR #8's recorded combined head; see [prepared export verification](PREPARED_EXPORT_VERIFICATION.md) for the exact result and scope. The older routed-fixture browser script remains separate and unmigrated. + +See [large-media exports](LARGE_MEDIA_EXPORTS.md) for scratch settings, quotas, session isolation, leases and request fields, and [export rendering](EXPORT_RENDERING.md) for implementation limits. Synthetic CI results do not qualify real-camera/full-resolution/multi-GiB or heavy-load operation. A new release or deployment still needs checks appropriate to its exact candidate and storage. diff --git a/docs/EXPORT_RENDERING.md b/docs/EXPORT_RENDERING.md index 06763d5..95b2d72 100644 --- a/docs/EXPORT_RENDERING.md +++ b/docs/EXPORT_RENDERING.md @@ -1,23 +1,33 @@ -# Prepared export rendering backend: implementation status +# Export rendering -This is a staged backend implementation, not a completed integration. export_media.go adds copy/accurate rendering primitives and export_media_test.go adds media integration tests. The HTTP planner still calls the legacy renderer and the browser does not yet send a mode choice. These paths are NOT yet selectable through the app. Do not release the branch as complete. +Copy and Accurate are connected to the HTTP job planner and selectable in the browser. Neither mode silently falls back to the other. [Large-media exports](LARGE_MEDIA_EXPORTS.md) describes storage, limits, job lifetime and the API. ## Copy -A single complete source is copied byte for byte into bounded prepared-output storage. It is not yet the planned zero-copy original-file HTTP delivery. Several complete sources are remuxed with explicit audio/video mapping, stream copy, and matching codec configuration/extradata checks. No nominal/average frame-rate equality test is used. Packet conversion is disabled for compatible concatenation, preserving compressed payloads. Additional tracks or incompatible configurations are refused, never silently selected/dropped or transcoded. +A single complete source is copied byte for byte into bounded prepared-output storage. Multiple complete sources are remuxed with explicit video/audio mapping and matching codec configuration/extradata checks. Packet conversion is disabled for compatible concatenation, preserving compressed payloads. Nominal or average frame-rate equality is not used as a substitute for actual configuration compatibility. Extra tracks and incompatible configurations are refused, never silently selected, dropped or transcoded. -Subsections in copy mode currently return a boundary error. Keyframe probing, actual-range preview and explicit consent are still required before adjusted-boundary copy is enabled. No intervals are widened automatically. +### Part of a recording + +Subsection copy supports non-reordered video with usable decoded keyframe timestamps. The server plans an earlier video start and later video end at available keyframe or file boundaries and reinspects expanded coverage for gaps/overlaps. It returns a proposal before creating a job or reserving output storage. The browser displays the requested/proposed video intervals and AAC packet allowance and waits for explicit approval. Cancelling that proposal creates no job. + +Approval keeps the original requested selection and adds the accepted video boundaries. The server recomputes the plan and requires a new approval when those video boundaries change. Reordered video, missing keyframe information, incompatible tracks or undecodable candidate output are refused; the user must explicitly choose Accurate instead. + +AAC packet boundaries can extend outside the video-aligned interval by the disclosed allowance. Candidate copy output is duration-probed and externally decoded before readiness. A prepared copy is not zero-copy HTTP delivery of the original recording. ## Accurate -Audio/video windows use the same video timestamp origin and cut reference, preserving relative audio offset rather than independently resetting tracks. AAC is retained by re-encoding in accurate mode; its sample rate/channel count are validated. Leading/trailing missing audio in an accepted input window is represented as silence to maintain the window duration, without stretching audio. Mixed audio presence or mismatched audio configurations across parts are currently refused. +Audio/video windows share the video timestamp origin and cut reference, preserving supported relative audio offset rather than independently resetting each track. AAC is re-encoded; sample rate and channel count are validated. Missing leading/trailing audio within an accepted input window is represented as silence to keep its duration without stretching audio. Mixed audio presence or mismatched audio configurations across parts are refused. + +8-bit `yuv420p` and full-range `yuvj420p` are supported within the renderer's dimension bounds. Full-range input is explicitly converted to limited-range `yuv420p`. Video is encoded with libx264 CRF 18, so accurate output is not byte-identical or lossless. Copy does not perform that conversion. Extra tracks, rotation and higher bit depths remain unsupported. + +Video timing is frame-granular, not calibrated camera wall-clock time. Accurate fragmented MP4 uses delayed `moov`/edit-list handling and permits negative timestamps for AAC encoder priming so encoder delay is not treated as source timing. -8-bit yuv420p and full-range yuvj420p are supported within existing dimension bounds. Accurate full-range input is explicitly converted to limited-range yuv420p output. Video is re-encoded with libx264 CRF 18; accurate exports are not byte-identical or lossless. Copy does not perform this conversion. Rotation and higher-bit-depth profiles remain unsupported. Frame-rate strings are not used as a proxy for valid timestamps. Video is frame-granular, not exact camera wall-clock timing. +## Safeguards -Fragmented MP4 accurate output uses delayed moov/edit-list handling with negative timestamps enabled for AAC encoder priming; this avoids treating encoder delay as source timing. Output must be a fresh empty regular file. Sources are pinned and revalidated, output writes are bounded, output tracks/durations are probed, and all subprocesses are joined before return. Checks do not by themselves certify every frame, colour value or audio sample. +Output must be a fresh empty regular file, never an existing recording. Inputs are pinned and revalidated, output writes are bounded, track configuration/durations are probed, and subprocesses are joined before return. These checks do not certify every frame, colour value or audio sample. -## Evidence and remaining work +## Evidence and remaining qualification -Local FFmpeg command experiments (not execution of the Go implementation) produced decodable H.264/AAC single/multi-part accurate output, preserved a deliberately delayed audio onset at approximately 250 ms, and preserved compressed video/AAC packet hashes when copying complete identical-profile clips. Go integration tests cover the camera metadata profile, original-byte copying, copied-packet hashes, multi-part accurate output, external A/V decode, delayed audio onset, source digests, cancellation and output limits. Go is unavailable in the assistant environment, so these Go tests have NOT been executed or compilation-verified. +GitHub reported all 11 check runs successful on PR #8 head `b8a6178136f620d88f82099ddc7a3a91cdd5cff7`, including Go build/race/vet, the prepared-job Chrome runs and safety verification. The Go tests include original-byte copy, copied packet hashes, accurate audio offset, external decode, source immutability and resource/cancellation checks. The live-browser harness uses real authenticated HTTPS jobs and browser downloads. See [prepared export verification](PREPARED_EXPORT_VERIFICATION.md). -Still required: HTTP job renderer wiring; API and UI explicit mode selection; keyframe-adjusted copy planning/consent; original descriptor delivery; real-camera and fractional/B-frame boundary timing validation; colour-range validation; large-file and cancellation-under-load tests; migration and execution of the real Chrome acceptance suite. +That synthetic evidence is not full-resolution real-camera, multi-GiB, colour-fidelity or heavy-load qualification. Representative fractional/B-frame timing and real-camera colour behaviour still need deployment-specific validation. Original-file delivery without a prepared copy is not implemented. The older routed-fixture browser script remains separate from the migrated live-runtime harness. diff --git a/docs/LARGE_MEDIA_EXPORTS.md b/docs/LARGE_MEDIA_EXPORTS.md index 839373d..37ea51c 100644 --- a/docs/LARGE_MEDIA_EXPORTS.md +++ b/docs/LARGE_MEDIA_EXPORTS.md @@ -1,38 +1,77 @@ -# Large-media exports: work in progress +# Large-media exports -Do not release this branch as the completed export redesign. +SimpleNVR prepares exports on the server and serves finished files through authenticated downloads. Page JavaScript does not buffer video or impose the old 64 MiB limit. Server output limits still apply. -## Implemented +## How it works -- Bounded disk-backed job store, random IDs, owner checks, independent seekable readers, cancellation, expiry and shutdown joining. -- Authenticated POST /api/exports/create and /api/exports/cancel, plus GET/HEAD /api/exports/status?id=ID and /api/exports/download?id=ID. Event tokens cannot access these routes; jobs are bound to session and credential version. -- Startup and shutdown integration. Download responses use ServeContent with Range support. -- Browser UI creates jobs, polls state, and offers a normal same-origin download. Page JavaScript does not fetch/buffer video or impose the old 64 MiB cap. Control responses are bounded to 8 KiB. -- Range controls are retained. Cameras are processed sequentially; the next job starts after release or expiry of the prepared file. -- Cancel/release requires server acknowledgement; failures remain visible with a retry control. Lost creation responses are not retried automatically. Navigation leaves jobs to server expiry rather than canceling a download during handoff. +- Disk-backed jobs have random IDs, session ownership, independent seekable readers, cancellation, expiry, and shutdown joining. +- The browser creates a job, polls its status, then offers a normal same-origin download with HTTP Range support. Control responses are bounded to 8 KiB. +- The UI processes cameras sequentially. The next job starts after the previous prepared file is released or expires. +- Cancel/release requires server acknowledgement. Failures remain visible with a retry control. A lost creation response is not retried automatically. +- Navigation leaves jobs to expire rather than cancelling a download during browser handoff. Jobs do not survive restart. +- Copy and Accurate are explicit choices. Copy never silently falls back to re-encoding. See [export rendering](EXPORT_RENDERING.md). -## Configuration +## Configure export storage -Mount trusted disk-backed scratch storage outside /recordings and camera directories (for example /exports) and set NVR_EXPORT_SCRATCH_DIR=/exports. It must exist and must not resolve through symlinks. Without it the new endpoints return 503; the job UI reports that configuration is required and does not fall back to the old Blob path. Invalid configured limits/storage fail startup. Do not put GiB exports in a tmpfs or container writable layer. +Mount a trusted, private, disk-backed directory outside `/recordings` and every camera directory, for example `/exports`, and set: + +```text +NVR_EXPORT_SCRATCH_DIR=/exports +``` + +The configured container path must be absolute, already exist, and not resolve through symlinks. The container user must be able to write it. Camera storage and export scratch must not overlap in either direction. Do not place multi-GiB exports in tmpfs or the container's writable layer. The [README Compose example](../README.md#install-with-docker-compose) includes the mount and setting. + +When the setting is absent, the application can start but prepared export endpoints return 503. There is no browser-memory fallback. Invalid configured limits or unsuitable configured storage cause startup to fail. | Setting | Default | Meaning | | --- | --- | --- | -| NVR_EXPORT_MAX_BYTES | 8589934592 | Per-job prepared output (8 GiB) | -| NVR_EXPORT_TOTAL_BYTES | 17179869184 | Aggregate job-output reservation (16 GiB) | -| NVR_EXPORT_MAX_JOBS | 8 | Retained records | -| NVR_EXPORT_PARALLEL | 1 | Concurrent preparations | -| NVR_EXPORT_TTL | 30m | Processing expiry; retention resets on completion | -| NVR_EXPORT_PREPARE_TIMEOUT | 30m | Preparation deadline including queue wait | +| `NVR_EXPORT_MAX_BYTES` | 8589934592 | Maximum prepared output per job (8 GiB) | +| `NVR_EXPORT_TOTAL_BYTES` | 17179869184 | Aggregate job-output reservation (16 GiB) | +| `NVR_EXPORT_MAX_JOBS` | 8 | Maximum retained job records | +| `NVR_EXPORT_PARALLEL` | 1 | Concurrent preparations | +| `NVR_EXPORT_TTL` | 30m | Initial job expiry; retention resets when preparation finishes | +| `NVR_EXPORT_PREPARE_TIMEOUT` | 30m | Preparation deadline, including queue wait | + +Byte limits are positive integers in bytes. Counts must be positive; maximum jobs cannot exceed 64 and parallel preparations cannot exceed maximum jobs. Total bytes must be at least the per-job limit. Durations use Go duration syntax such as `30m` or `1h`, must be positive, and cannot exceed 24 hours. + +Each admitted job reserves its maximum output, including queued jobs, so the default byte budget permits at most two concurrent reservations. This does not mean two renders run in parallel: the default parallel setting is one. Retained records also count toward the job limit. + +Expired or released outputs with active readers stay charged until their readers finish. Reservations are accounting limits, not preallocated physical disk space or a bound on every filesystem allocation. Monitor free space and underlying storage health. + +## API + +All routes require the creating authenticated dashboard session; event tokens cannot use them. Jobs are bound to session and credential version. + +- `POST /api/exports/create` +- `GET` or `HEAD /api/exports/status?id=JOB_ID` +- `GET` or `HEAD /api/exports/download?id=JOB_ID` +- `POST /api/exports/cancel` + +POST requests use `Content-Type: application/json`. Create accepts these fields; unknown fields are rejected: + +| Field | Meaning | +| --- | --- | +| `camera_id` | Camera to export | +| `start_time`, `end_time` | Ordered RFC 3339 timestamps; end is exclusive | +| `mode` | `copy` (default) or `accurate` | +| `accepted_start`, `accepted_end` | Copy only: the proposed video interval explicitly approved by the user | + +A `202` response returns `id`, `state`, `message`, `bytes`, and `expires_at`, with a `Location` header pointing to status. Ready status adds `download_url`. Wait for ready before downloading; a queued or failed job has no ready download. + +### Copy range approval + +Subsection copy returns `409` JSON with `code: copy_range_approval_required` before job admission or output reservation. It contains `requested_start`, `requested_end`, `export_start`, `export_end`, and `audio_allowance_ms`. Show the proposed video interval and possible AAC packet overhang to the user, even when the video boundaries already match keyframes. + +After explicit approval, repeat the original camera, start/end and mode with `accepted_start` and `accepted_end` set to the proposed `export_start` and `export_end`. Do not replace the original requested start/end. The server recomputes the proposal and refuses stale video boundaries; a changed proposal needs fresh approval. + +Other common outcomes include `409` with `X-Export-Plan-Status: gap` or `overlap` for missing/ambiguous coverage, `413` for too many clips, `422` for an unsupported mode/profile combination, `429` for exhausted job capacity, and `503` for unavailable export service or metadata. No gap is silently skipped or overlapping source selected automatically. -Each admitted job reserves its maximum output; defaults allow at most two reservations. Active expired downloads remain charged until their leases end. Legacy trim intermediates retain separate existing bounds. Reservations are not physical disk reservations or a bound on all filesystem allocations. Monitor free space. Jobs do not survive restart. +### Cancel, release and expiry -POST create JSON contains camera_id, start_time and end_time (ordered RFC3339 timestamps). A 202 response has id, state, message, bytes, expires_at and a Location status URL. Ready status adds download_url. POST cancel uses {"id":"JOB_ID"} and confirms with 204. Subsequent requests require the creating session. Cancellation/expiry prevent new leases; already-started responses may continue. Logout and credential changes block subsequent requests, not necessarily existing responses. +Cancel takes `{"id":"JOB_ID"}` and confirms with `204`. Cancellation/expiry prevents new download leases. An already-started response can continue until its lease ends. Logout and credential changes block subsequent requests, not necessarily already-started responses. A new sign-in session cannot inherit an older session's jobs. -## Still required before release +## Verification and limitations -- Original-file delivery, compatible audio/video stream-copy assembly, and consent for adjusted keyframe ranges. The current renderer and its audio/pixel-format/frame-rate restrictions are unchanged. -- Optional accurate audio-preserving trimming and representative media validation. -- Migrate the real Chrome and routed browser acceptance harnesses from Blob URLs to job create/status/download/release semantics; enable scratch mounts in runtime fixtures. Existing browser harnesses still contain old assumptions and are not expected to pass this intermediate branch. Do not delete their media, hash, duration, playback or cancellation checks. -- Real large-file, slow-client, media, Range, authenticated-session and shutdown runtime checks. +The prepared-job Go and live-browser checks passed on PR #8's recorded integration head. See [verification evidence](PREPARED_EXPORT_VERIFICATION.md) for the exact commit and scope. -JavaScript syntax and the updated Node export UI/range regressions passed locally in UTC and America/Chicago. The 5 GiB test uses reported size metadata, not an actual 5 GiB transfer. Go and real-browser tests have not been run here. +Prepared copies are written to scratch; this is not zero-copy original-file delivery. Subsection copy requires non-reordered video with usable keyframe timestamps. Representative real-camera timing/colour behaviour, full-resolution media, multi-GiB transfers, and heavy-load cancellation remain outside the recorded synthetic qualification. Do not treat an 8 GiB configured limit or a metadata-only large-file test as evidence of an actual 8 GiB transfer. diff --git a/docs/PREPARED_EXPORT_VERIFICATION.md b/docs/PREPARED_EXPORT_VERIFICATION.md index 8f3e60b..54f2ed2 100644 --- a/docs/PREPARED_EXPORT_VERIFICATION.md +++ b/docs/PREPARED_EXPORT_VERIFICATION.md @@ -1,11 +1,37 @@ # Prepared export verification -Both prepared-export workflows trigger on pushes to fix/large-media-exports, pull requests and manual dispatch. A push runs the full Go build/race/vet workflow and two independent Chrome acceptance attempts against the same event commit. Require both workflows to pass on that exact commit before completion is claimed. No tests were replaced by an export-only Go subset. +## Recorded CI result -The live HTTPS browser harness now uses create/status/download/cancel endpoints. It checks anonymous access refusal, whole-copy compressed video packet hashes, external decode/duration, HEAD and Range, missing-coverage refusal, accurate AAC output and duration, copy proposal cancellation and explicit approval, active accurate-render cancellation and child reaping, browser-saved SHA-256/duration/decode, and HTTP 404 after server release. It no longer expects Blob URL revocation or fetches video into page JavaScript for hashing. Test-directed range/seek state is retained; application functions and response bodies are not replaced. +[Pull request #8](https://github.com/mouldybread/SimpleNVR/pull/8) was checked after the recording-status fix from PR #7 was brought into the export branch. On its head commit `b8a6178136f620d88f82099ddc7a3a91cdd5cff7`, GitHub reported all 11 check runs completed successfully: -The container has a private scratch bind mount at /exports, outside /recordings, with explicit small test quotas. Non-reordered fixtures exercise supported subsection copy; reordered inputs remain covered by Go refusal tests. Native playback, real login/navigation diagnostics and the expanded playback-edge suite are retained. Reports include the commit, image identity, browser version, media and network evidence. Passing synthetic acceptance is not production-camera or multi-GiB qualification. +- Full Go build, race-enabled suite and `go vet` (push and pull-request runs). +- Prepared jobs/native playback Chrome attempts 1 and 2 (push and pull-request runs). +- Safety verification: core build/race/storage/lifecycle, both isolated Chrome runs, bounded synthetic resource measurements, and the required-checks gate. -Local checks: Python/shell/YAML syntax; all 30 embedded browser-JavaScript expressions parsed by Node; media helper check copied 160 video packets without hash changes and externally decoded a 16-second fixture. The earlier six protocol regressions passed. These are not a live-backend or browser pass. Go and Docker are unavailable locally; actual Go/Chrome/container results must come from CI after this commit is pushed. +This records those specific check results, not a new test run on later commits. The count includes duplicate push/pull-request executions, not 11 independent test suites. See the [PR check results](https://github.com/mouldybread/SimpleNVR/pull/8) and its linked Actions runs. -The older routed-response tests/browser-export-acceptance.py is a separate legacy harness, not the real-runtime acceptance entrypoint. It has not been migrated or reported as passing here. Do not confuse that script with the migrated tests/runtime-browser-acceptance.py executed by both browser workflows. +## Automated scope + +The prepared-export workflows trigger on pushes to `fix/large-media-exports`, pull requests and manual dispatch. The Go workflow uses the complete race-enabled suite, not an export-only subset. The browser workflow makes two independent Chrome attempts against a runtime container built from the exact checkout. + +The live HTTPS browser harness checks: + +- Anonymous requests to prepared-job routes and private media are refused. +- Whole-copy compressed video packet hashes, external decode and duration, plus HEAD and Range behaviour. +- Missing-coverage refusal without a download. +- Accurate export with one AAC track and the expected audio/video durations. +- Copy proposal cancellation before a job, and explicit approval before preparation. +- Active accurate-render cancellation and FFmpeg child reaping. +- Browser-saved SHA-256 matching, external decode/duration, and HTTP 404 for new requests after server release. + +Native playback, real login/navigation diagnostics and the expanded playback-edge suite are retained. The container mounts private export scratch at `/exports`, outside `/recordings`, with small test quotas. Non-reordered fixtures exercise supported subsection copy; Go tests cover reordered-video refusal. + +## Local preparation checks + +Before the browser migration was committed, Python/shell/YAML syntax checks and parsing of 30 embedded JavaScript expressions passed. A separate media-helper check preserved 160 compressed video packet hashes and externally decoded a 16-second fixture. Six protocol regressions also passed. Those local checks were not live-backend/browser execution; the CI result above supplies the recorded Go/container/Chrome execution evidence. + +## Limits + +Passing synthetic acceptance is not production-camera, full-resolution, multi-GiB-transfer, colour-fidelity or heavy-load qualification. The metadata-only large-file UI regression is not an actual multi-GiB transfer. + +`tests/browser-export-acceptance.py` is an older routed-response harness. It remains unmigrated and is not the live-runtime entrypoint invoked by these browser workflows. Do not report it as migrated or passing based on the live-runtime results. The migrated entrypoint is `tests/runtime-browser-acceptance.py`, invoked through the expanded playback runner.