openvibers/openvibe.cam README.md

README.md

main 18.3 KB · 265 lines · markdown

Raw HistoryBlame Repository

OpenVibe.Cam

Your camera, your cameras, and the moment Live's cam button takes.

Live site: https://openvibe.cam · API docs: https://openvibe.services · For AI: https://openvibe.cam/llms.txt
Run it: npm ci && npm run dev (Node 22 or newer) · Tests: npm test

Status: v1 written and tested (see [STATUS.json](STATUS.json)).
Domain: openvibe.cam · Port: 5160 · Service id: cam · Env prefix: CAM
License: AGPL-3.0-only (same as every OpenVibe service).

OpenVibe.Cam is the camera app, the private wall for cameras you own, and the API Live's cam button calls. A photo
or a still is saved to OpenVibe.Pics; Cam keeps the link, the filter and the caption, never the bytes. A camera is
private to its owner, and a viewer sees it only while the grant the owner gave is active and not revoked.

Purpose

  • The camera app. A browser preview with a timer, a 3-shot burst, a grid and on-device colour, light and
    softness. The filter runs on the canvas in the person's browser; the server never applies an effect. The picture
    is posted to Cam, which forwards it to OpenVibe.Pics with the person's own Network token. There is no server-side
    image analysis and no face recognition.
  • Edit in Studio. A photo you saved opens in Studio with GET /edit?pics=<Pics slug>&from=cam on
    openvibe.studio; Studio asks OpenVibe.Pics, with your own token, whether you may read it, then loads it into
    Photo with From OpenVibe.Cam beside it. The link is on each of your photo cards and on the capture result; a
    photo of someone else's answers 404. CAM_STUDIO_URL moves the link for a drill.
  • My cameras. Pair an old phone, a browser, a Pi or an IP camera you own. If a Live stream id is given, Cam
    reads it from OpenVibe.Live's public API and refuses a stream on somebody else's channel; the slot defaults to the
    stream's managed slot. Its wall is private: /w/<id> answers its owner and an active grantee, and 404 to
    everyone else, including staff.
  • Revocable viewer grants. A grant names one canonical subject and an expiry: seven days by default, ninety at
    most. @username is resolved through OpenVibe.Network (identity.subject.resolve); a subject id works without
    it. A re-grant extends the active grant instead of making a second one. Revocation writes a timestamp, and the
    wall checks it on every read, so the next request is refused.
  • The camera element. <ov-camera> puts the same preview, filters, timer and burst on any site: one script from
    https://openvibe.cam/embed/ov-camera.js, a capture event with the blob, and no upload unless the site asks for it.
  • The Live cam button. Live calls POST /api/v1/stills with the viewer's own Network token. Cam fetches
    OpenVibe.Media's public GET /live/:slot/frame.jpg (only image/jpeg is accepted), uploads the JPEG to
    OpenVibe.Pics as that person, and returns the still and the exact line Live posts in the stream chat.

Owns

| Table | Holds | Migration |
|---|---|---|
| cam_cameras | cam_ + ULID, owner usr_…, owner username, name, source browser\|phone\|pi\|ip, status paired\|live\|offline, Live stream_id (unique per owner), slot, the owner's note, paired/last-seen times | migrations/0001_initial.sql |
| cam_grants | cmg_ + ULID, camera, owner, viewer_subject, viewer username, granted_at, expires_at, revoked_at, revoked_by; one unrevoked grant per camera and viewer | 0001_initial.sql |
| cam_photos | cmp_ + ULID, subject, optional camera, filter label, caption, visibility private\|unlisted, Pics slug, page URL, direct URL | 0001_initial.sql |
| cam_stills | cms_ + ULID, subject, stream id, slot, caption, visibility unlisted\|private, Pics slug, page URL, direct URL | 0001_initial.sql |
| account_data_events | openvibe-sdk/account-data's export/deletion receipts | 0001_initial.sql |
| telemetry_samples | aggregated request telemetry, pruned after 14 days | 0001_initial.sql |

There is no image, blob or byte column in any Cam table. The pics_slug and links are the picture's address in
OpenVibe.Pics; neither Cam nor its database can serve the bytes.

Does not own

  • The picture bytes, resizing, metadata stripping and takedowns — OpenVibe.Pics (OpenVibe.MediaHub). Cam reads
    its 201 and stores the slug and links.
  • The live frame — OpenVibe.Media's /live/:sel/frame.jpg. Cam never runs ffmpeg or caches a frame.
  • Streams, chat and the streamer's second camera — OpenVibe.Live and OpenVibe.Chat. The OVCamPip streamer
    camera is Live's; Live also posts the returned still line to the stream's chat with its own chat authority.
  • Identity, usernames and accounts — OpenVibe.Network. Cam verifies sessions against its JWKS and resolves a
    viewer's @username with identity.subject.resolve.
  • Search — OpenVibe.Search. v1 makes nothing public, so Cam queues no Search document.
  • Events, the host and the database — OpenVibe.Events, OpenVibe.Host.

Depends on

Environment variable names are in [.env.example](.env.example); no value is committed.

  • OpenVibe.Network — sign-in (OAuth client cam, PKCE S256, cookies cam_at/cam_rt/cam_oauth), JWKS,
    token exchange/refresh/revoke, account export/deletion, and identity.subject.resolve for @username:
    OV_NETWORK_URL, OV_NETWORK_INTERNAL_URL, OV_NETWORK_ISSUER, OV_OAUTH_CLIENT_ID,
    OV_OAUTH_CLIENT_SECRET, OV_OAUTH_REDIRECT_URI, OV_SESSION_AUDIENCE, CAM_AUDIENCE.
  • OpenVibe.Media — the public live frame, GET /live/:sel/frame.jpg?w=640 (media.derivative.read is the
    planned capability; the route needs no token today): OV_MEDIA_URL.
  • OpenVibe.Live — GET /api/streams/:id, the public read used to check that a paired stream is on the owner's
    channel (live.stream.read: OV_LIVE_URL).
  • OpenVibe.Pics (OpenVibe.MediaHub) — POST /api/v1/images, called with the signed-in person's own Network
    token; Cam never holds a service token for Pics (OV_PICS_URL). The route is pics.image.upload in the person's
    own right; MediaHub refuses an app or service token there.
  • OpenVibe.Events — account deliveries: CAM_EVENTS_SECRET, CAM_EVENTS_URL, CAM_EVENTS_ENDPOINT.
  • PostgreSQL — DATABASE_URL (through PgBouncer) and DATABASE_DIRECT_URL (migrations); embedded PGlite in
    CAM_PGLITE_DIR for development.
  • Valkey — optional VALKEY_URL, VALKEY_PREFIX (readiness lists it; the limits in v1 count in-process).
  • Packages — openvibe-contracts v0.234.0, openvibe-sdk v0.161.0, openvibe-shared v4.100.1, the same tags
    OpenVibe.Meme pins.

API

Everything is JSON under /api/v1; errors are application/problem+json with a code. A person is the cam_at
session cookie or Authorization: Bearer <Network user token>, verified offline with the Network JWKS. A write made
with the session cookie must come from https://openvibe.cam (403 cam.cross_site). A signed-in account also gets
per-actor minute/hour limits (CAM_LIMITS_MINUTE, CAM_LIMITS_HOUR).

| Route | What it does |
|---|---|
| POST /photos | a person; raw picture body (image/jpeg, image/png, image/webp), optional X-Filter, X-Caption, X-Camera, X-Filename (URI-encoded); forwarded to Pics |
| GET /photos · GET /photos/:id | your photos |
| GET /cameras | your cameras with active grant counts |
| POST /cameras | { name, source, stream_id?, slot?, notes? }; a stream_id is read from Live and must be yours |
| GET /cameras/:id · PATCH /cameras/:id · DELETE /cameras/:id | the owner: read, change name/source/status/slot/notes, unpair |
| GET /cameras/:id/wall | the owner or an active grantee; a stranger gets 404 |
| GET /cameras/:id/grants | the owner: every grant, including expired and revoked |
| POST /cameras/:id/grants | the owner: { viewer_username } or { viewer_subject }, { days } 1–90 |
| DELETE /cameras/:id/grants/:grantId | the owner: revoke at once |
| POST /stills | a person; { slot, caption?, stream_id?, w?, visibility? }; Media's frame → Pics → a still and the chat line |
| GET /stills | your stills |
| GET /stills/:id | an unlisted still by its link; a private one only for its owner |
| GET/PUT/DELETE /cameras/:id/familiar-faces | the owner: turn Familiar faces on/off, set its region and quiet hours; on creates the owner's Vision library |
| POST /cameras/:id/familiar-faces/enroll · /match · GET /people | the owner, proxied to Vision with the owner's own token; Cam keeps no template or crop |
| PATCH/DELETE /cameras/:id/familiar-faces/people/:personId · POST …/request · POST …/consent-check | the owner: mute/rename/delete a name, or send/re-check its consent request |
| POST /cameras/:id/events | the owner or camera: { kind, at?, still_url?, clip_url?, face_image?, face_image_url?, place?, lat?, lng?, linger_seconds? }; one timeline event |
| GET /cameras/:id/events · GET /events | the owner's timeline, newest first (limit, kind, since) |
| GET/PATCH /events/:id · POST /events/:id/share · POST /events/:id/police · GET /events/:id/export | read, mark "this is X", a private link, or the police download (time, place, still and clip references) |
| GET /events/shared/:token | anyone with the private token; the event, never the owner's account |
| GET/PUT /presence | the owner's own home/away, from the browser, phone or Node |

Familiar faces and the timeline (F1)

A camera's Familiar faces setting is familiar_faces; when it is on, Cam creates an OpenVibe.Vision library for that camera and stores only its vision_library_id, region and region_mode. The owner's own Network token is forwarded to Vision for every library call, so Vision decides ownership, encryption and consent; Cam holds no template and no crop. Deleting the camera deletes its Vision library first.

An event is one detection: person, package, vehicle, animal, loiter or door. A person event may carry a face crop; only then does Cam ask Vision to match inside that camera's library. The event keeps a still and a clip reference plus clip.before_seconds (default 10) and clip.after_seconds (default 20), the owner's away state at that moment, and priority: "high" for an unknown person or a door while away. Detection without identity — package, vehicle, animal, loitering, door — never needs a face.

One Network notification is pushed per event unless the matched name is muted or the camera's quiet_hours cover the event time; the event is still stored. POST /events/:id/share returns a private link once (only its sha256 is stored), and GET /events/:id/export returns an attachment file with the time and place for "Send to police". OV_VISION_URL, CAM_CLIP_BEFORE_SECONDS, CAM_CLIP_AFTER_SECONDS, CAM_EVENT_MAX_BODY_MB, CAM_EVENT_SHARE_DAYS and CAM_NOTIFICATION_SCOPE configure the path.

Validation refusals are 400 { code: "cam.invalid", message }; a blocked caption is 400 { code: "cam.blocked_words" }. Other codes: cam.sign_in_required, cam.person_required, cam.cross_site,
cam.not_found, cam.camera_exists, cam.camera_limit, cam.grant_limit, cam.grant_not_found,
cam.stream_not_found, cam.not_your_stream, cam.stream_offline, cam.frame_unavailable, cam.frame_busy,
cam.pics.refused, cam.pics.unavailable, cam.too_large, cam.not_an_image, cam.viewer_not_found,
cam.identity_unavailable, cam.rate_limited.

The Live cam button

Live is the caller. It holds the viewer's Network token in its own session; it sends that token to Cam as a Bearer
(server-side), never a Cam service token:

  1. The watch page sends { slot, stream_id, caption } to Live's server.
  2. Live calls POST https://openvibe.cam/api/v1/stills with Authorization: Bearer <viewer's Network token>.
  3. Cam reads GET https://openvibe.media/live/:slot/frame.jpg?w=640; a 404 is cam.stream_offline, and an SVG
    offline card served with 200 is refused as cam.frame_unavailable.
  4. Cam calls POST https://openvibe.pics/api/v1/images with the same token, the JPEG as the body, X-Title and
    X-Filename. Pics re-encodes and strips metadata.
  5. Cam answers 201 { still, frame_url, share: { url, caption, text } }. Live posts share.text to the stream's
    chat and shows share.url (or still.pics_direct).

Cam needs no app/service token for this, and Live needs no new Cam grant. A still is unlisted by default; pass
"visibility": "private" to keep it to its owner. Media caches one frame per slot for five seconds and rate-limits
by address, so a burst of button presses can answer 429 cam.frame_busy.

The camera element

Recording kit

https://openvibe.cam/embed/cam-kit.js opens a camera on the calling page. It uses a full-screen stage on phones and a centred stage on computers. The caller owns the result and any upload; Cam does not store video bytes.

<script src="https://openvibe.cam/embed/cam-kit.js" defer></script>
<button id="record">Record</button>
<script>
  document.getElementById('record').addEventListener('click', async () => {
    const result = await OpenVibeCam.open({ mode: 'video', maxSeconds: 60 });
    if (result) console.log(result.file, result.duration);
  });
</script>

The script can be pinned with the SHA-384 SRI hash shown on /developers. OpenVibeCam.open({ mode: 'video' | 'photo' | 'screen', maxSeconds, timer, onDone }) resolves to { file, mode, mimeType, duration, width, height, maxSeconds } after Use this, or null when closed. onDone(result) may return a promise. Video and screen modes use the browser's MediaRecorder; screen capture appears when available. The review has two trim handles and exports the selected clip when supported. Pass the returned file to the calling site's uploader, using ov-upload's resumable uploader when available.

Photo element

The camera app is also one framework-free custom element, at https://openvibe.cam/embed/ov-camera.js and documented
live at openvibe.cam/developers. It is one script and one tag; with the default
upload="off" the picture never leaves the browser.

<script src="https://openvibe.cam/embed/ov-camera.js" async></script>
<ov-camera id="cam" facing="user" filters="none,mono,warm,cool,fade,vivid,blur" timer="0" mode="photo" upload="off"></ov-camera>
<script>
  document.getElementById('cam').addEventListener('ov-camera:capture', function (e) {
    // e.detail = { blob, width, height, filter }
  });
</script>

| Attribute | Values | Default |
|---|---|---|
| facing | user (front) or environment (back) | user |
| filters | comma list of none, mono, warm, cool, fade, vivid, blur | none |
| timer | 0, 3 or 10 seconds | 0 |
| mode | photo or burst (three, 450 ms apart) | photo |
| upload | off, or openvibe to post to POST /api/v1/photos when the page is openvibe.cam and signed in | off |

Events: ov-camera:capture with { blob, width, height, filter } and ov-camera:error with { code, message }.
Methods: start(), stop(), capture(), flip(). Style with --ov-camera-accent and --ov-camera-radius. The
element never starts the camera on connect; a click (or an explicit start()) does. OpenVibe.SDK wraps the loader as
openvibe-sdk/cam (defineOvCamera()), with the attributes, events and methods typed.

Pages

All server-rendered through the OpenVibe Frame (openvibe-shared/shell), readable without JavaScript, with
semantic HTML and stable cm- ids/classes. Public pages are public, max-age=60 with Vary: Cookie; a page drawn
for a signed-in person, a wall or a still is private, no-store.

| Page | What it is |
|---|---|
| / | the shutter hero, the three scenes, the privacy rules |
| /app | the camera app: preview, timer, burst, grid, filter, caption, and your recent photos |
| /my | pair a camera, your cameras, your photos and stills (signed in) |
| /my/cameras/:id | one camera: its frame, edit form, viewers, revoke buttons, unpair |
| /w/:id | the private wall an owner or an active grantee sees |
| /s/:id | one still of a live stream, with its Pics link |
| /developers | the API and the Live cam button contract |
| 404 | the not-found page |

public/css/cam.css is a one-comment placeholder: the pages are complete without it, and the main session designs
it. public/js/cam.js adds the live preview, the timer, the burst, the grid and the on-device filter. The two
pictures in public/img/ are data-free SVG placeholders. robots.txt, sitemap.xml, llms.txt and
llms-full.txt list the three public pages and never a wall, a grant or a still.

The first proof

scripts/seed-proof.js performs the part that needs no network:

  • pair an owned test camera (Proof camera, slot proof) for CAM_PROOF_OWNER;
  • grant CAM_PROOF_VIEWER for seven days;
  • open the wall as that viewer;
  • revoke the grant;
  • ask for the wall again and assert it is refused.

Re-running reuses the camera and makes a fresh grant. The photo and the still need a signed-in person's Network
token and are done through /app or the API; both go to OpenVibe.Pics.

Run and test

npm install
npm test                 # PGlite; every test file in its own process, no network needed
npm run test:pg          # the same through PostgreSQL + PgBouncer (openvibe-sdk scripts/test-services.sh up)
OV_ALLOW_SUITE=1 npm test
npm start                # PORT 5160, loopback; DATABASE_URL or an embedded PGlite in development
CAM_PROOF_OWNER=usr_… CAM_PROOF_VIEWER=usr_… node scripts/seed-proof.js

The tests boot the app with a mock Network, a Media/Live/Pics fixture server, and a temporary database: the
migration and its constraints, pairing and stream ownership, grants (username resolution, extension, revocation,
expiry, staff have no bypass), the still's Media → Pics path and its refusals, the photo upload and its limits, the
pages and cache headers, sign-in, and account export/deletion.

Deploy

deploy/systemd/openvibe-cam.service (127.0.0.1:5160, /etc/openvibe/cam.env) and
deploy/nginx/openvibe.cam.conf (TLS, www → apex, /auth/me on the API zone, /my/ on the API zone, /internal
and /metrics 404, a 16 MB body cap for a photo). Not deployed by this change.

License

AGPL-3.0-only. See [LICENSE](LICENSE).

<!-- versions:start -->

  • openvibe-contracts: v0.419.0
  • openvibe-sdk: v0.161.0
  • openvibe-shared: v4.238.0

<!-- versions:end -->