How it works
This page is the map of Aperture’s internals: which processes run, how video gets from a camera to the recorder, the detectors and your browser, how an API request is authenticated and authorized, and which package does what. Each section names the files to open, and the pages linked from it go deeper.
The processes
Section titled “The processes”An installed Aperture is three systemd services, plus the MQTT broker if you use Home Assistant. The unit files are in
deploy/systemd/.
| Unit | Program | Runs as | Job |
|---|---|---|---|
aperture.service |
/usr/bin/nvrd |
root | The daemon: web app, API, recorder, detection, retention, integrations, extension supervisor, database |
aperture-go2rtc.service |
/usr/lib/aperture/bin/go2rtc -config /var/lib/aperture/go2rtc.yaml |
aperture-go2rtc |
The stream broker: the only process that connects to cameras |
aperture-discovery.service |
/usr/lib/aperture/bin/apdiscovery |
a dynamic user | Announces the install over mDNS/DNS-SD, so aperture.local resolves. No state, no database |
mosquitto.service |
the distribution’s broker | its package’s user | MQTT for Home Assistant. aperture.service lists it in Wants=, so Aperture starts without it |
nvrd starts and supervises its own children. They live in the aperture service’s cgroup and share its memory and
CPU limits (MemoryHigh, MemoryMax and CPUQuota in aperture.service):
| Child | How many | Started by |
|---|---|---|
ffmpeg recorder |
one per recording camera | internal/record/recorder.go |
ffmpeg motion decoder |
one per camera with motion detection | internal/motion/detector.go |
ffmpeg audio decoder |
one per camera with audio detection | internal/audio/detector.go |
ffprobe |
one per new segment, briefly | the indexer in internal/record |
ffmpeg on demand |
per export or scrub-preview frame | internal/export, internal/api/recordings_handlers.go |
apdetect |
one worker while object recognition is on | internal/ai/worker.go |
deno |
one per enabled backend extension | internal/ext/supervisor.go |
nvrd runs as root because it starts each extension backend under its own uid and gives it ownership of its folder.
The unit takes most other privileges away: ProtectSystem=strict with /var/lib/aperture as the only writable path,
NoNewPrivileges=yes, RestrictNamespaces=yes, and the kernel-protection switches. The comments in
deploy/systemd/aperture.service explain each setting and the ones left out on purpose.
Four unit settings shape how the daemon behaves:
Restart=alwayswithRestartSec=2, andStartLimitIntervalSec=0in[Unit], so a crash loop never leaves the NVR permanently stopped. The in-app restart button exits the process and relies on this.ExecStartPre=/usr/libexec/aperture/aperture-hardenre-applies file modes and refuses to start when the recordings directory is inside the data directory, or when the database exists withoutsecrets.json(see Data model).KillMode=mixedwithTimeoutStopSec=45: on stop, onlynvrdgetsSIGTERMand runs its ordered shutdown; the rest of the cgroup is killed only if that takes longer than 45 seconds (see Shutdown).OOMPolicy=continue: when the kernel ends a child under memory pressure (extensions and theapdetectworker raise theiroom_score_adjso they go first), the service keeps running.
The unit puts /usr/lib/aperture/bin first on PATH, so a vendored ffmpeg there wins over the distribution’s.
One connection per camera
Section titled “One connection per camera”go2rtc holds the only connection to each camera stream: one for the main stream, and one for the sub stream when you set one and something reads it. Everything else reads from go2rtc. A camera sees the same one or two clients whether nobody is watching or ten people are.
| Consumer | What it reads from go2rtc | Code |
|---|---|---|
| Recorder | RTSP restream rtsp://127.0.0.1:8554/cam_<id> (cam_<id>_sub with low recording quality) |
stream.Manager.RTSPURL, internal/record/recorder.go |
| Motion detection | cam_<id>_sub if the camera has a sub stream, otherwise cam_<id> |
internal/motion/detector.go |
| Audio detection | cam_<id> |
internal/audio/detector.go |
| Object recognition | nothing of its own: frames come from the motion decoder | internal/detect/live.go |
| Browser live view | go2rtc’s WebSocket /api/ws?src=cam_<id>, through nvrd’s authenticated proxy |
stream.Manager.ProxyWS |
| Snapshots and placeholders | GET /api/frame.jpeg?src=cam_<id> on go2rtc’s API |
stream.Manager.Snapshot |
| Test connection | a temporary stream test_<id>, deleted after one frame |
stream.Manager.TestStream |
| Watchdog probe | an RTSP DESCRIBE to the restream, for cameras nothing else reads |
stream.Manager.Probe |
| Home Assistant, VLC, other recorders | the RTSP restream on port 8554, directly | see ONVIF and RTSP |
Aperture talks to a camera directly only for control, never for video: ONVIF picture settings
(internal/onvifclient) and the Reolink HTTP API for spotlight and infrared (internal/reolink).
nvrd registers streams through go2rtc’s HTTP API (PUT /api/streams). go2rtc’s config file,
/var/lib/aperture/go2rtc.yaml, ends up holding the camera links with their passwords, which is why it is owned by
aperture-go2rtc and mode 0600. nvrd does not rely on that file: stream.Manager.Sync runs at start and every
60 seconds (cmd/nvrd/main.go). It registers a stream only when its source changed, because re-registering an
unchanged stream drops every viewer, and it deletes cam_* streams whose camera is gone. A go2rtc that restarted
without its streams is repopulated within a minute.
The picture
Section titled “The picture” cameras | RTSP: one connection per camera stream v+--------------------- aperture-go2rtc.service ---------------------+| go2rtc streams cam_<id>, cam_<id>_sub || HTTP API 127.0.0.1:1984 | RTSP :8554 | WebRTC :8555 |+-------^----------------------^------------------+-----------------+ | | | | register streams, | RTSP restream +--> WebRTC media to browsers | frame.jpeg, /api/ws | +--> RTSP to Home Assistant, VLC, | | other recorders+-------+----------------------+------ aperture.service ------------+| nvrd || HTTP :8971 chi router, /api/v1, embedded web app <-----------+---- browsers, PWA,| recorder ------ ffmpeg per camera --> recordings/<id>/*.ts | nvrctl, scripts| motion, audio - ffmpeg per camera --> events || object recognition ---------------> apdetect worker (ONNX) || indexer, uploader, mirrors, janitor, watchdog || Home Assistant publisher ---------> MQTT (mosquitto) || extension supervisor -------------> deno per extension || store ----------------------------> data/aperture.db (SQLite) |+-------------------------------------------------------------------+Port 8971 is the installed value of APERTURE_HTTP_ADDR; a development build listens on :8080. See
Configuration for every variable.
One request’s journey
Section titled “One request’s journey”Opening a camera tile is a good example: it uses an ordinary JSON route, a WebSocket and go2rtc.
- The web app calls
GET /api/v1/cameras/{id}/stream-token. The browser sends theaperture_sessioncookie. - The request passes the root middleware in
Server.routes(internal/api/server.go), in this order: chi’sRequestID, thenclientip.Resolver.Middleware(the client address, see below), chi’sRecoverer, thenlogRequests(logs every API write and every error response), thenauth.Manager.Context, which turns the cookie into claims (see Principals). - Under
/api/v1,apiVersionHeaderssetsX-Aperture-Api-Version: v1. Then three API-wide guards run:rateLimit,limitBodyandcsrfGuard. - The route’s access spec runs last. This route is declared
scopedCam(ScopeMediaLive), soenforcerequires a signed-in principal, themedia:livescope if the principal is an API token, and access to camera{id}. handleStreamToken(internal/api/stream_handlers.go) signs a stream token for that one camera, valid for 5 minutes (streamTokenTTL), and returns{token, wsUrl, hasSub}.- The browser opens the WebSocket
wsUrl,/api/v1/cameras/{id}/ws?token=…, adding&q=subfor the sub stream. A browser cannot set anAuthorizationheader on a WebSocket, so this route is declaredpubandhandleStreamWSchecks the token itself (authorizeStreamWS).{id}may be the camera id or its handle. stream.Manager.ProxyWSrewrites the request to go2rtc’s/api/ws?src=cam_<id>, removes theOriginheader (go2rtc rejects cross-origin WebSockets, andnvrdis the trusted proxy in front of it) and reverse-proxies the socket.- go2rtc and the browser negotiate WebRTC over that socket. The video then flows directly between the browser and
go2rtc’s port 8555; if WebRTC fails, the player falls back to MSE and the video travels inside a WebSocket through
nvrd.
Live streaming covers steps 5 to 8 in depth: the signalling messages, the fallback and the player’s reconnect logic.
The API layer
Section titled “The API layer”Everything the web app does goes through the same API that scripts and extensions use. The router is
chi, and every route is registered in one function, Server.routes in
internal/api/server.go.
Two mounts
Section titled “Two mounts”The route table is mounted twice, at /api/v1 and at the older unversioned /api. Both run the same handlers. The
/api alias answers with Deprecation: true and Link: </api/v1>; rel="successor-version" and counts its callers
for GET /api/v1/system/metrics. The web app’s client (v1Path in web/src/lib/api.ts) rewrites every /api/… path
to /api/v1/….
Access specs
Section titled “Access specs”A route cannot be registered without saying who may call it. Handlers are added through apiRouter
(internal/api/access.go), whose Get, Post, Put and Delete methods all take an access value:
| Field | Meaning |
|---|---|
public |
No authentication |
admin |
The principal’s role must be admin |
sessionOnly |
API tokens are refused, whatever their scopes |
scopes |
Scopes an API token must hold; sessions and the CLI token pass |
camera |
camScopeParam: the caller must be allowed to see the camera in the {id} path parameter |
The shorthands used in server.go are pub, authed, authedSessionOnly, adminSessionOnly, extSelfOnly, and the functions
scoped(…), scopedCam(…), adminScoped(…) and adminScopedCam(…). apiRouter.method records each route in
declaredRoutes and routeSpecs and wraps the handler in Server.enforce, which answers in this order:
| Check | Response |
|---|---|
| No principal on a non-public route | 401 unauthenticated |
admin and the role is not admin |
403 forbidden |
sessionOnly and the principal is an API token |
403 forbidden |
extSelf (extSelfOnly) and the principal is neither a session nor the {id} extension’s own token |
403 forbidden.extension |
| An API token without a required scope | 403 forbidden.scope |
| Camera-scoped and the camera is not visible to the caller | 403 forbidden.camera |
Operations that could take over an account or the whole system are session-only rather than scoped, so no token can reach them: users, tokens, password, second factor, passkeys, backup, restore, restart, purge, reindex and the extension manager.
The boot-time guard
Section titled “The boot-time guard”After the router is built, assertAllRoutesDeclared walks the whole chi tree. If any route under /api or /api/v1
was registered without going through apiRouter, it panics with fail-closed authorization guard: … registered without an Access descriptor, and nvrd does not start. An unguarded route cannot reach a running server.
TestFailClosed_UndeclaredRouteRefusesBoot and TestRealRouterBootsClean in internal/api/fail_closed_test.go pin
this.
What every response shares
Section titled “What every response shares”- Errors are JSON:
{"error": "<English text>", "code": "<machine code>"}(writeErrorCodeininternal/api/respond.go). Match oncode; the text may change. An unknown path under the API prefix returns a JSON404not_found, and a wrong method a JSON405method_not_allowed, never the web app’s HTML. - Arrays are never
null:writeJSONreplaces nil slices with[]at any depth. - Config resources carry a strong
ETag. An API token must sendIf-Matchon config writes (428without it,412when stale); for sessions it is optional (internal/api/etag.go). POST /exportandPOST /sharesaccept anIdempotency-Key; a repeat within 24 hours replays the first response (internal/api/idempotency.go).GET /events,GET /system/auditandGET /cameras/{id}/segmentsuse cursor pagination.GET /api/v1/openapi.json(any signed-in principal) is generated fromrouteSpecsat request time, so the required scopes it lists (x-required-scopes,x-requires-admin) are the onesenforcechecks.
API-wide guards
Section titled “API-wide guards”| Guard | What it does | Values |
|---|---|---|
rateLimit (limit.go) |
Token bucket per principal; anonymous callers per IP. 429 with Retry-After: 1 |
Sessions and CLI: burst 240, 120 per second. Tokens: burst 40, 20 per second, keyed by owning user. Anonymous: burst 30, 10 per second |
limitBody (limit.go) |
Caps the body; 413 payload_too_large |
1 MiB for JSON, 256 MiB for multipart, 2 GiB for a model upload. A non-multipart POST, PUT or PATCH body must arrive within 30 seconds |
csrfGuard (ext_broker.go) |
Refuses a cookie-authenticated POST, PUT, PATCH or DELETE whose Origin (or Referer) host differs from the request’s Host |
403 cross-origin request blocked |
The HTTP server itself (Server.NewHTTPServer in internal/api/shutdown.go) sets ReadHeaderTimeout to 10 seconds
and IdleTimeout to 120 seconds, and leaves ReadTimeout and WriteTimeout unset so event streams and long exports
are not cut.
The client address comes from internal/clientip. Forwarding headers count only when the direct peer is in
APERTURE_TRUSTED_PROXIES (default 127.0.0.0/8, ::1/128). From such a peer the middleware walks X-Forwarded-For
from the right and takes the first entry that is not a trusted proxy (X-Real-IP when there is no
X-Forwarded-For), rewrites RemoteAddr to it, and reads X-Forwarded-Proto. From any other peer it deletes
X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Real-IP, True-Client-IP and Forwarded before
any handler runs. The anonymous rate-limit key, the activity log, session and trusted-device records, the passkey
origin (clientip.Scheme) and the passkey sign-in cookie’s Secure flag all read the result. See
Client addresses.
Stability
Section titled “Stability”/api/v1 changes only by adding: new routes, new optional fields. The capabilities document
(GET /api/v1/capabilities) reports apiV1FrozenAt, set the first time extensions are enabled or one is installed
(freezeV1 in internal/api/ext_handlers.go); from then on a breaking change needs a v2. The extension machinery
under /api/v1/ext/ is exempt (frozenExempt), because only the web app and the SDK talk to it. The route reference
is at API reference and the scopes at Scopes.
Principals
Section titled “Principals”auth.Manager.Context (internal/auth/middleware.go) never rejects a request. It attaches claims if it can and
leaves the decision to enforce. It tries, in order: the session cookie, then a Bearer header as the CLI token,
then as an API token. The result carries a class:
| Class | Credential | Authority |
|---|---|---|
session |
The aperture_session cookie. A random 256-bit token; the sessions table keeps only its SHA-256 hash. Signed out after 90 days unused or 365 days after sign-in (internal/api/sessions.go) |
The user’s role and camera access, all scopes |
cli |
Authorization: Bearer <cli_token>, the token in data/cli.token, compared in constant time |
A synthetic admin named nvrctl, all scopes. Used by nvrctl |
token |
Authorization: Bearer apt_…, looked up by hash in api_tokens (Store.ResolveAPIToken) |
Acts as its owner, limited to its scopes and camera grants; never more than the owner. Refused if the owner is disabled or the token expired |
A few routes accept narrower credentials of their own, outside these classes:
- The live WebSocket accepts a stream token, an API token with
media:live, or the server-managed live-view key, an integration setting an administrator can reveal and replace (Live streaming). - Share links (
/s/{token}) carry a random token that thesharestable keeps only as a hash (Export and share). Event-thumbnail links in notifications (/api/v1/public/event-thumb) are signed. - Extension UI assets (
/ext/{id}/*) need no credential; the panel reaches data only through the broker (see Extensions).
Users, roles and per-camera access are on Users; sign-in methods on Sign-in and SSO.
Background loops
Section titled “Background loops”cmd/nvrd/main.go wires everything together and starts these loops. The ones marked “waited” are tracked by the
services type in cmd/nvrd/shutdown.go and given time to finish on shutdown.
| Loop | Interval | Waited |
|---|---|---|
go2rtc stream reconciliation (stream.Manager.Sync) |
at start, then 60 s | no |
Snapshot cache warm-up (WarmSnapshots) |
15 s | no |
| Scrub-frame cache prune (files older than 2 h) | 30 min | no |
| Recorder: reconcile ffmpeg set; index, upload, mirror | 60 s; 8 s | yes |
| Retention janitor | 5 min, plus on allocation changes | yes |
| Motion detector, audio detector | continuous | yes |
| Object recognition engine | continuous | yes |
| Home Assistant publisher | continuous | yes |
| Weather poller | while a site location is set | yes |
| Watchdog (recording health, camera online state) | 15 s | yes |
| Rate-limit bucket sweep | 5 min | no |
Storage and retention
Section titled “Storage and retention”The recorder runs one ffmpeg per camera that copies the video without re-encoding (unless you give that camera a
lower recording quality) into 10-second MPEG-TS files named after their start second, <camera id>/<epoch>.ts.
Audio is re-encoded to AAC at 32 kbit/s. Every 8 seconds the indexer probes finished files with ffprobe
and inserts a segments row for each. For an SMB or SFTP destination, ffmpeg writes to a local spool and an uploader
moves finished files to the share. Mirrors copy indexed segments to further destinations and record each copy in
segment_copies. Every 5 minutes the janitor deletes by age, quota, allocation and free space; it deletes the file
first and keeps the row until the file is really gone. Playback builds an HLS playlist from the rows on each request.
The details, with the exact ffmpeg command, are in Recording pipeline. The settings are on Storage and Recording.
Detection
Section titled “Detection”Motion detection decodes a small grayscale copy of each camera’s stream with ffmpeg and compares cells of
consecutive frames in Go. When enough of the picture changes, an event opens; it closes after a quiet period. The same
ffmpeg also writes colour frames to a second pipe, which feed object recognition: the apdetect worker runs an ONNX
model through ONNX Runtime on the CPU or an NVIDIA GPU and returns boxes, which become live overlays, labels on the
event and Home Assistant presence. Instead of the local worker, events can be sent to an external DeepStack-style
server. Audio detection is a separate ffmpeg per camera that measures loudness.
When an event opens, cmd/nvrd/main.go fans it out: object recognition tags it, then notifications, webhooks,
automations and the HomeKit motion sensor get it. Detection pipeline follows every step;
Motion and Object recognition cover the settings.
Extensions
Section titled “Extensions”Extensions are off until an administrator types enable extensions to confirm (POST /api/v1/ext/gate,
admin and session-only). An extension is a bundle with a manifest, optional UI panels and an optional Deno backend.
- Panels are served from
/ext/{id}/*(internal/api/ext_static.go) with a restrictive Content Security Policy into a sandboxed iframe that carries no cookie. A panel calls the API throughPOST /api/v1/ext/{id}/broker, which runs the call with the authority the signed-in user and the extension have in common. - Backends are started by
internal/ext/supervisor.go.nvrdre-executes itself asnvrd __ext-spawn …under the extension’s own uid (allocated from 65600 upwards), applies resource limits and a raisedoom_score_adj, then runs Deno with deny-by-default flags built ininternal/ext/spec.go:--deny-run,--deny-ffi,--deny-sys,--deny-import, reads limited to the extension’s folder and the SDK, writes to its folder, and network access only to the hosts its manifest declares plus the Aperture API. The backend authenticates with its own API token. - Files live in
data/ext/<id>/; per-extension key-value data in theext_kvtable.
On shutdown extensions are stopped first, with SIGTERM and SIGKILL 5 seconds later. See
Extensions and Extension security.
The change feed
Section titled “The change feed”GET /api/v1/feed (internal/api/feed_handlers.go) is a Server-Sent Events stream of envelopes
{id, type, ts, camera, data}, published through notify.Engine.PublishFeed (internal/notify/feed.go). The web
app uses it to update without polling.
There are two kinds of message:
- Durable:
event.createdandevent.closed, whose SSEid:is the event’sseq. On reconnect the browser sendsLast-Event-IDand the server replaysevent.createdfor up to 1,000 events with a higherseq, straight from the database. If the cursor is older than the oldest kept event it sends{"type":"reset"}so the client refetches. - Ephemeral: live state such as
camera.state,motion.state,objects.live,detection.created,storage.updated,config.updated,automation.updated,alarm.stateandexport.progress. They get an in-process id and are not replayed; instead the latest message per type and camera is sent as a snapshot right after connecting.
?types= and ?cameras= (comma-separated) filter server-side. Every message about a camera is checked against the
connection’s camera access, a keep-alive comment goes out every 25 seconds, and an API token is re-checked every 60
seconds so a revoked token stops receiving within a minute. A slow subscriber’s frames are dropped rather than
buffered. GET /api/v1/notify/stream is a second SSE stream that delivers in-app notifications.
Shutdown
Section titled “Shutdown”On SIGTERM or SIGINT, nvrd stops in a fixed order (cmd/nvrd/main.go, budgets in cmd/nvrd/shutdown.go):
- Extension backends, while the API they call is still up: their stop window plus 2 seconds (
extStopSlack). - Background services: the recorder lets every ffmpeg close the segment it is writing, the detectors reap their
ffmpeg, and Home Assistant is told the NVR is going offline. Up to 20 seconds (
bgStopWait). - HTTP: event streams end at once (
CloseStreams), so browsers reconnect to the next instance; other requests get up to 10 seconds (httpStopWait). - Storage backends and the database.
The worst case is about 37 seconds, inside the unit’s TimeoutStopSec=45. The last log line, shutdown complete,
gives the time each phase took and names the slowest service. Recording pipeline
explains what happens to the segment being written.
Languages
Section titled “Languages”The web app uses i18next with react-i18next (web/src/lib/i18n.ts). A translatable string
is written as t("key", "English text"), so English needs no catalog and is the fallback for any key a catalog lacks.
The only other language is German. Its catalog covers the navigation, the sign-in screen, common buttons, parts of
Settings and the personal preferences; the rest of the interface is English in every language setting.
The language is a per-user preference (language: auto, en or de) saved through
PUT /api/v1/users/me/preferences and mirrored in the browser’s localStorage as aperture.lang. auto picks German
when the browser’s language starts with de. The same setting drives date and number formatting
(setLocale in web/src/lib/format.ts). The server does not translate: API error text is English, which is why
clients should match on code.
The embedded web app
Section titled “The embedded web app”The web app is React 18 with TypeScript, Vite, TanStack Query, React Router and Tailwind, in web/. It ships inside
the nvrd binary:
make build-webrunsnpm ci && npm run buildinweb/(tscthenvite build) and copiesweb/disttointernal/webassets/dist.internal/webassets/embed.goembeds that folder with//go:embed all:dist.spaHandler(internal/api/static.go) serves it. Files underassets/have content hashes in their names and are sent withCache-Control: public, max-age=31536000, immutable.index.html, and every path that is not a file so that client-side routes work on reload, is sent withCache-Control: no-cache, no-store, must-revalidate. A new build therefore reaches browsers on the next load.
The service worker (web/public/sw.js) caches nothing; it handles Web Push and notification clicks only.
The embedded folder is a build artifact and is not in git. go build embeds whatever is in it, however old, so
make check-web-fresh exists to catch a stale bundle: it fails if internal/webassets/dist/index.html is missing or
if any file in web/src or web/index.html is newer than it. The make build and make build-native targets always
rebuild the bundle first. With APERTURE_WEB_DIR set, nvrd serves the web app from that folder instead of the
embedded copy (see Development).
Repository map
Section titled “Repository map”| Path | What is there |
|---|---|
cmd/nvrd |
The daemon: wiring, interop services (HomeKit, ONVIF), ordered shutdown |
cmd/nvrctl |
The admin console: full-screen TUI and scriptable subcommands (nvrctl) |
cmd/apdetect |
The object-recognition worker; frames in on stdin, detections out on stdout |
cmd/apdiscovery |
The mDNS/DNS-SD advertiser |
web/ |
The React web app; web/src/screens, components, lib, ext (extension host), ext-sdk |
deploy/ |
Installer, uninstaller, vendoring script, systemd units, sysusers and tmpfiles snippets, aperture-harden, the extension SDK module (aperture-sdk/mod.ts) |
examples/ |
Example extensions, and their built bundles in examples/dist |
tools/mkbundles |
Builds examples/dist/*.zip deterministically (make examples) |
test/fixtures |
Test fixtures, such as an extension that probes its sandbox |
docs/ |
Older Markdown guides (detection, Home Assistant, extensions) |
The internal/ packages:
| Package | What it does |
|---|---|
ai |
Object recognition: pinned downloads of ONNX Runtime and models, the worker protocol, pre- and post-processing, label mapping |
ai/ort |
A minimal ONNX Runtime binding loaded at run time with purego, so no cgo; used only by apdetect |
api |
The HTTP API, access specs, the change feed, the web app handler, playback and export routes |
astro |
Sunrise, sunset, twilight and moon phase, computed locally |
audio |
Loud-sound detection, one ffmpeg per camera |
audit |
The hash-chained activity log |
auth |
Password hashing, session and stream tokens, the request-claims middleware |
automate |
The local automation engine: event conditions to actions |
config |
Environment variables, defaults, directory creation, secrets.json |
detect |
Live object recognition, event tagging, tracks, presence, the package watch, the external detector bridge |
eufy |
The Eufy bridge account and session |
export |
MP4 export: stream-copy concatenation, optional burn-in, multi-camera, timelapse |
ext |
Extension manifests, permissions, Deno launch specs, the backend supervisor |
format |
Human-readable units shared by the API, the audit log and nvrctl |
ha |
Home Assistant over MQTT: discovery, state, presence, inbound control |
homekit |
The HomeKit bridge |
hwinfo |
What the host can do: CPU, cgroup limits, GPU; feeds the capacity estimate |
logbuf |
An in-memory ring of recent log lines for the diagnostics bundle |
motion |
Motion detection and the frame source for object recognition |
notify |
Notification rules and channels (Web Push, ntfy, Telegram, Discord, webhook, email) and the change-feed hub |
oidc |
OpenID Connect sign-in |
onvif |
The ONVIF Profile S provider that lets other recorders use Aperture’s cameras |
onvifclient |
The client that adjusts a camera’s own picture settings over ONVIF |
record |
The recorder, indexer, uploader and mirrors |
reolink |
Reolink spotlight and infrared control over the camera’s HTTP API |
reserve |
The hard-reservation balloon file |
retention |
The janitor: age limits, quotas, allocations, free-space floor |
secret |
AES-256-GCM encryption of stored credentials |
site |
The site profile: location, timezone, units |
storage |
Storage backends: local folder, SMB, SFTP |
store |
SQLite access and the embedded migrations |
stream |
go2rtc orchestration: stream registration, snapshots, the WebSocket proxy |
urlcred |
Keeps the secret part of a camera link on the server |
version |
Build version, injected with -ldflags |
watchdog |
Recording health and camera online state, with recovery |
weather |
The weather time series behind the playback ribbon |
webassets |
The embedded web bundle |
webhook |
Signed outbound webhooks with retry and a delivery log |
Where to read the code
Section titled “Where to read the code”A reading order that builds the picture fastest:
cmd/nvrd/main.go: every subsystem is constructed and connected here, and the shutdown order is at the end.internal/api/server.goandinternal/api/access.go: the complete route table with each route’s access spec, and how it is enforced.internal/stream/manager.go: how cameras become go2rtc streams.internal/record/recorder.go: the recorder, the indexer and the uploader.internal/store/migrations: the schema, one change per file.internal/motion/detector.goandinternal/detect/live.go: from frames to events and boxes.web/src/App.tsxandweb/src/lib/api.ts: the web app’s routes and its API client.
Many files open with a comment that explains why the code is shaped the way it is; read those first.
Related: Recording pipeline, Live streaming, Detection pipeline, Data model, Development.