Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 33 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,53 @@ 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
```

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.
Expand All @@ -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:
Expand Down
22 changes: 15 additions & 7 deletions docs/EXPORT_API_MODES.md
Original file line number Diff line number Diff line change
@@ -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.
30 changes: 20 additions & 10 deletions docs/EXPORT_RENDERING.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading