Video Sharing
Rule
Recording sharing uses the framework sharing system — not a custom share table. Recordings are registered via registerShareableResource({ type: "recording", ... }) in server/db/index.ts. The share-resource, unshare-resource, list-resource-shares, and set-resource-visibility actions are auto-mounted and handle per-user grants, per-org grants, and the three visibility levels (private / org / public).
Unlike the framework-wide private default, normal Clips recordings and uploaded
videos default to public so their copied share links work immediately.
Embedded bug-report recordings are the exception and default to organization
visibility. Callers can still explicitly create a private or organization-only
recording, and owners/admins can change visibility from the Share dialog.
Organization admins can use set-organization-branding with
defaultVisibility=public|org|private to choose the visibility applied when new
recordings omit an explicit visibility. The default remains public, and an
explicit visibility always wins — which is why bug-report recordings still land
on org.
Clips adds two things on top of the framework system:
- Password — an optional encrypted string on the
recordings row. For public recordings, non-owner viewers must enter it to play the recording. Private and organization access use the framework ACL; a stored password is retained and applies again if the recording becomes public.
expiresAt — an optional ISO timestamp on the recordings row. After this time, all non-owner access is denied (even to principals with explicit grants). Existing values remain enforced, although the Share panel no longer edits expiry.
These are additive — they never grant access the framework denies, only tighten it.
When to use
Read this skill before:
- Wiring the Share dialog on a recording page
- Adding a password or expiry UI
- Building embed URLs (
?t=, ?autoplay=, ?hideControls=)
- Building AI-readable public clip URLs or transcript/frame endpoints
- Debugging "why can't Alice see this video?"
- Touching
server/routes/video/[id].ts or server/routes/share/[id].ts
Data model touched
recordings.password (nullable text) — encrypted password value.
hasPassword reports whether a password is stored, including dormant passwords on private or organization recordings; it does not by itself indicate an active password gate.
recordings.expires_at (nullable ISO string).
recording_shares — framework-managed. Do not insert directly — use share-resource.
recordings.visibility — framework-managed column from ownableColumns().
recording_viewers + recording_events — view counting.
recording_views — append-only per-view log (who viewed, when) backing the owner-facing "Viewed by" popover. See "View counting" below.
recording_agent_views — outside agents reading a clip through its public agent APIs, counted separately from humans. See "Agent views" below.
recording_content_bindings — the Agent-Native Content documents a Clip is placed in. See "Clips in Content documents" below.
Dropping in the share UI
Recordings and meetings use Toolkit ShareButton for the standard access,
copy-link, and Send to controls. Public recordings can set, change, or remove a
password under General access. Existing expiry values remain enforced, but are
not edited in this panel. Meeting transcript visibility remains a
meeting-specific control. Pending redactions block sharing until they are burned
into the recording. Private and password-protected recording agent handoffs use
scoped recording agent links; a password-protected viewer cannot mint one.
Embed URLs remain available through build-embed-url; embedding does not change
access. Public share pages emit link-preview metadata, while an iframe is a
separate playback integration.
Shared with me
Use list-recordings --view=shared to list recordings the current user can
access but does not own. The filter composes with accessFilter, so it includes
direct user/org grants and organization-visible recordings while excluding
public-link-only clips. The UI exposes the same collection at /shared; use
navigate --view=shared to open it. view-screen returns the recordings
currently visible in that collection.
Changing many clips at once
For a request over many of the user's own clips, such as "make my clips older
than a week private unless I've shared them with someone", find them with one
list-recordings call and change them with one call per 100:
list-recordings takes createdBefore / createdAfter (an ISO date such
as 2026-10-25, or a date-time with its offset such as 2026-10-25T12:00:00Z),
visibility (a list, such as ["public", "org"]) and hasShares
(false for clips whose share list names no person, group or org; it
reads that list, not visibility, and only ever matches the user's own
clips).
set-resource-visibility takes resourceIds with resourceType: "recording". Making any clip public asks for one approval for the call.
archive-recording, trash-recording, restore-recording and
delete-recording-permanent take ids; tag-recording and
add-recording-to-space take recordingIds.
Every clip in the call is checked first; if the user can't change one, none
change and the error names it. The result lists each clip as changed,
unchanged (already that way) or skipped with a reason. Report the counts
back, not the clips one by one. A long delete-recording-permanent batch
can stop early and list the clips it didn't reach as skipped; call it again
with those ids.
Discovery boundary for public clips
Public recordings are unlisted-by-link for agent purposes: an agent may discover
only recordings the current user owns or has already viewed. Do not use
list-recordings or search-recordings to discover another user's public clips,
to answer a time/date question about the clip already in context, or to recover
from a failed direct lookup. If the user supplies another clip's share URL or id,
use that explicit reference; otherwise stop and report the lookup failure.
Access resolution
The player and /api/video/:id route check access in this exact order:
async function canAccess(
recordingId: string,
requester: Session | null,
providedPassword?: string,
) {
// 1. Framework check — owner, shared, or meets visibility.
const access = await resolveAccess("recording", recordingId, requester);
if (!access.allowed) return false;
const rec = await getRecordingOrThrow(recordingId);
// 2. Expiry — non-owner only.
if (rec.expiresAt && requester?.email !== rec.ownerEmail) {
if (new Date(rec.expiresAt) < new Date()) return false;
}
// 3. Password — public links, non-owner only.
if (rec.visibility === "public" && rec.password && requester?.email !== rec.ownerEmail) {
if (!providedPassword) return false;
if (!verifySharePassword(providedPassword, rec.password)) return false;
}
return true;
}
Framework first, Clips additions second. Don't invert this — the framework owns the "is this row visible at all" question.
Clips in Content documents
A Clip placed in a Content document has one recording_content_bindings row per (recording, Content app, document). origin is upload (made in the document) or link (pasted); state is active or trashed. A duplicated document adds its own row.
- Only an active
upload binding grants access: a Content reader with no access of their own becomes a viewer of that one recording (server/lib/content-doc-grant.ts, a host access resolver registered with includeSignedOut: true so it is asked about signed-out readers of a public document too). A reader's own Clips sharing, in their active workspace, still applies and is never lowered. A link binding, or none, leaves the Clip's own sharing in charge. When every binding is trashed, document readers lose access; the owner never does.
- The Clip's own rules still apply on top: Trash, takedown and expiry refuse document readers, a password-protected Clip does not play through a document, and with comments off document readers see no comments and cannot write.
- Content calls
/api/content-clips/:recordingId/playback and /comments (GET ?limit=<n> to list the first n thread starts, at most CONTENT_CLIP_MAX_COMMENT_THREADS, which is also what a request with no limit gets, with truncated when there are more and each thread's text and author cut to CONTENT_CLIP_COMMENT_PREVIEW_CHARS and CONTENT_CLIP_COMMENT_AUTHOR_CHARS, so Content can cap what it reads (playback likewise cuts the title to CONTENT_CLIP_RECORDING_TITLE_CHARS); POST to add, reply, edit, delete, resolve or react) server to server with a one-minute A2A token. shared/content-clip-contract.ts is the contract: audience <Clips URL>/content-clips, one scope, and document_id + recording_id claims. A signed-out reader of a public document gets the content-clip:public-read scope: playback and the comment list, never a write.
- The token is signed with
CONTENT_CLIPS_PEER_SECRET (clips.contentPeerSecret, read with resolveContentClipsPeerSecret), a secret only the Content and Clips deployments hold, and Clips verifies it with that secret alone. That is what makes the token's issuer trustworthy as the Content app: a token signed with the deployment A2A_SECRET or a workspace secret is refused, because other apps hold those. While the secret is unset, shorter than 32 characters, or equal to A2A_SECRET, every route answers 503 with code content_clips_not_configured; set it on both deployments.
- Playback returns Clips media URLs with a five-minute
content_grant that names the reader, not a role. The grant is signed with a key derived from CONTENT_CLIPS_PEER_SECRET, never the app's own server secret (which a workspace derives from A2A_SECRET), and a media request carrying a grant while the secret is unusable gets the same 503. /api/video and /api/thumbnail re-run every gate on each request, so trashing the binding stops a URL already handed out. An expired grant is a 403 with code content_grant_expired; Content's player then asks Content for playback again, which re-checks document access.
- Each reader's reads and writes of one Clip through one document are rate-limited per process. A request counts against the Clip's bucket only once Clips has opened it: Content mints a token for any recording id a page reader names, so counting earlier would let a reader name made-up ids until their own spent bucket dropped out. A full map drops its oldest bucket rather than refuse a new one. A request whose Clip doesn't open counts as a miss against that reader's misses for that Clip and document; once they are spent, the Clip is refused before any database read. Misses are kept per Clip so made-up ids can't use up a real Clip's, which leaves a caller who keeps naming new made-up ids unbounded here: each costs one lookup, and Content's own per-visitor limit has to bound it. Every signed-out reader of a document shares the public reader's buckets.
- A Content editor's upload uses the
content-clip:upload scope, whose token carries document_id, the editor's name, and the browser's client_ip when Content knows it, never a recording_id. Content checks that the reader can edit the page before minting it. GET /api/content-clips/upload-status answers the editor's storage state (ready, free with what's left, used_up, none, or account_required when the email has no Clips account or workspace; Clips never makes either). POST /api/content-clips/uploads adds the upload binding first, then a private recording the editor owns, and returns a ticketed chunkUrl and cancelUrl; a state that can't take the file is a 409 storage_required with that storage. The start carries the uploadKey Content makes once per picked file, kept on the binding with the file's type and size: a start repeated with the same key, page, and editor never makes a second Clip. It answers that upload with another ticket and the first start's plan while it is uploading, a 409 upload_already_finished with recordingId and status once a final chunk holds it or Clips is making the Clip, a 409 upload_starting while the latest start is still making its recording (Content repeats it after a few seconds), or a 409 upload_key_used when it was cancelled or failed, is parked until storage is connected, began in another block, or describes a file of another type or size. A start that fails deletes its binding only when nothing can be left: a refusal raised before any recording or free clip (refusedStart), or an error with cleanupConfirmed: true. Any other failure keeps the binding and marks upload_start_failed_at, and a repeat that finds no recording under a marked binding, or one whose latest attempt is RESERVATION_GRACE_MS old, takes the start over with a compare-and-swap on the binding (takeOverStart) and makes the recording under the binding's own recording id, so the free clip reserved per recording id is never held twice; of repeats that overlap, the rest get upload_starting. A kept binding whose start left a recording answers from where that upload stands, so one whose recording failed answers upload_key_used like a cancelled one; that key's upload ended, and Content starts the file again under a new key. Earlier tickets keep working, since overlapping repeats each hand one back: a recording keeps its four newest (addRecordingUploadTicket) and still holds one upload slot, while an agent's create-recording-upload keeps one. A repeat skips the storage check, since its first start may have taken the last free clip.
- The editor's browser posts the file to
/api/uploads/:recordingId/content-chunk with the ticket in the query, no cookie, and no custom headers, so the request is a CORS simple request and no preflight reaches the auth guard. Only the paired built-in Content's origin (pairedContentOrigin) gets Access-Control-Allow-Origin, never the request's own Origin, and the answer never allows credentials.
- When the page gives an upload up (its block is gone, the editor can no longer edit, or a chunk failed for good), the browser POSTs
cancelUrl (/api/uploads/:recordingId/content-cancel?ticket=…) the same way. Clips' own abort fails the recording and releases its free clip, as the lease reaper would an hour later; the upload binding stays. Where an upload stands is one answer, readUploadPhase in server/lib/final-chunk-claim.ts: uploading, finishing (a final chunk holds it), parked (Clips has the whole file and waits for storage), finished (processing or ready) or ended (cancelled or failed). The repeated start, the cancel and the Content chunk route all use it, and nothing else reads its three stores (the final chunk's claim, the upload state and the recording row) together. It reads the claim first, then the upload state, then the row. Before Clips takes the final chunk's bytes, on the buffered and the resumable path alike, the Content chunk route renews the row's lease to outlast its claim, only while the row is uploading, then claims the upload, changing its upload state with the same compare-and-swap the abort claims with; once Clips accepts the chunk it writes parked or finished into the upload state, and only then gives the claim up, so a reader that finds no claim finds where the upload went. A final chunk that fails gives the claim up with the upload still uploading. A claim older than FINAL_CHUNK_CLAIM_TTL_MS (a little over Clips' 75 s function timeout) was left by a request that was cut off, so the upload reads uploading again and the next final chunk or cancel takes it over. A live claim is never taken over: a cancel or another send of the final chunk changes nothing while the upload is finishing and answers 409 upload_finishing (CONTENT_CLIP_CHUNK_FINISHING for the chunk), which Content repeats every few seconds, the chunk for a little longer than the claim lasts. A final chunk sent once the upload is parked or finished answers the first one's success (202 waitingForStorage, or 200 with status) and Clips takes no bytes; one that finds the upload ended is refused (409). The answer's outcome comes from the phase read after the abort, never from the abort's ok: cancelled (200) once it is ended, a repeat included and a parked upload too, or already_finished (409, with status) once it is finished. Any other answer means it wasn't cancelled; an upload whose cancels keep finding finishing is left to the reaper. The reaper reads only the row's lease, never the phase: it fails a row whose lease ran out in one conditional update, so it either failed the row before the final chunk renewed it, and the chunk finds it ended, or it leaves the row. A page in Trash can still cancel. A closed tab is still left to the reaper.
- Upload-origin Clips are listed under From Content (
list-recordings view from-content, each with contentPageUrl back to its page), and Library's own list leaves them out. A folder someone moved one into still lists it, and linked Clips stay in Library.
isActiveUploadBinding / activeUploadBinding() in server/lib/content-uploads.ts is the one test for an active upload binding. Playback's grant, the chunk route, From Content and its page links all use it, so an upload whose page is in Trash plays for no document reader, takes no chunks (409), and lists in neither From Content nor Library.
- Create and change binding rows only through Content's upload and lifecycle flows.
Embed URLs
Embeds live at /embed/:shareId (a share-scoped anonymous route). Supported query params:
| Param |
Meaning |
?t=80 |
Start playback at 80 seconds |
?autoplay=1 |
Autoplay (muted — browsers block unmuted autoplay) |
?hideControls=1 |
Hide the player chrome |
?loop=1 |
Loop playback |
Build embed URLs via the build-embed-url action:
const { url } = await callAction("build-embed-url", {
id: recording.id,
t: 80,
autoplay: true,
});
// -> /embed/<shareId>?t=80&autoplay=1
Slack unfurls
Clips can render Loom-style Slack previews through Slack App Unfurling. Configure
the Slack app's link_shared event to call /api/slack/unfurl; the route
verifies SLACK_SIGNING_SECRET, acknowledges Slack URL verification, and calls
chat.unfurl with a Block Kit video block using the existing /embed/:id
player URL.
For installable workspaces, use the Clips Settings OAuth flow. connect-slack
opens Slack OAuth, /api/slack/oauth/callback stores the bot token encrypted in
app_secrets, and slack_installations stores only the Slack team/app metadata
plus the secret ref. The unfurl webhook resolves the token by Slack team_id
and api_app_id; only if no OAuth install exists should it fall back to the
legacy SLACK_BOT_TOKEN path.
The playable Slack embed is deliberately narrower than the share page:
- Only
ready recordings with visibility === "public" can produce a video block.
- Password-protected, expired, archived, trashed, private, org-only, or still-processing clips must not produce a playable Slack block.
- Slack thumbnails use the same-origin proxy for stored thumbnails and the branded social image while one is unavailable. The proxy redirects to that image if stored content cannot be served; normal share-page metadata remains the fallback when no Slack app is installed.
- Do not put passwords, short-lived share tokens, raw provider URLs, or transcript text in Slack unfurl payloads.
Required Slack app setup:
- Bot scopes:
links:read, links:write, links.embed:write
- Event subscription:
link_shared
- App unfurl domains: the public Clips share domain, for example
clips.agent-native.com
- Request URL:
https://<clips-host>/api/slack/unfurl
- OAuth redirect URL:
https://<clips-host>/api/slack/oauth/callback
- Deploy secrets:
SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, and
SLACK_SIGNING_SECRET
Agent-readable clips
When a user supplies a Clips link, read the clip through its published agent
context instead of stopping at the share page or transcript preview:
- Use the exact
agentContextUrl in the page's agent-readable instructions or
application/agent-native+json discovery payload. Preserve its id and any
agent_access query parameter on every related request.
- Fetch
apis.transcript for the complete transcript. Fetch each
recommendedFrames[].url as an image and inspect the returned pixels; when
more visual context is needed, request apis.frame.urlTemplate with an
atMs timestamp. To watch motion (an animation, a transition, a cursor
path), request apis.frames.urlTemplate with startMs, endMs and fps:
one JPEG contact sheet of up to 36 consecutive frames from a range of at
most 60 seconds. Cells read left to right, then top to bottom; cell i
shows the frame on screen at startMs + i * 1000 / fps, and solid black
cells at the end of the grid hold no frame. Without fps the sheet uses
the video's own frame rate, and without endMs it takes up to 36 frames
from startMs, stopping at 60 seconds or the end of the clip. A
failureKind: request response names a request that fits in nextStep.
- On an error, inspect the JSON
failureKind, error, and nextStep. If a
context or transcript request has failureKind: access, explain that the
link does not grant access. For a private clip, ask its owner to open the
Clips Share menu, choose Share with agents, and send the generated link.
If a frame request has failureKind: media while the transcript works,
report that the stored media could not be retrieved; another link will not
fix it. If it has failureKind: processing, follow nextStep: extraction,
size-limit, and temporary storage errors do not prove that media is missing
or that the link lacks access.
If failureKind: expired, ask the owner to extend or remove the clip expiry
through update-recording, then create and send a new Share with agents
link. Never claim to have seen frames that were not returned as images.
The JSON discovery payload and HTTP endpoints work without browser tools. An
agent that cannot open frame URLs as images (claude.ai, a ChatGPT custom
connector) calls the get-recording-frames MCP tool instead, once Clips is
connected as an MCP connector (apis.mcp.connectUrl). It takes the
recordingId plus up to four atMs values, and returns the frames as image
blocks; without atMs it returns the first four recommended frames and lists
all of them. It checks only the connected user's own access (owner, share,
organization, public); an agent_access token does not grant it. A
public password-protected clip fails with password_required for anyone but its
owner.
Recordings can expose URLs meant for external agents without handing over raw
video bytes:
| Endpoint |
Meaning |
/api/agent-context.json?id=<recordingId> |
Clip metadata, transcript summary, recommended frames, and API discovery links |
/api/agent-transcript.json?id=<recordingId> |
Timestamped transcript segments with startMs, endMs, timestamp, range, text, and optional source; add maxSegments to page and continue with the returned nextStartIndex |
/api/agent-frame.jpg?id=<recordingId>&atMs=<ms> |
JPEG frame extracted from the video at the requested original-video timestamp |
/api/agent-frames.jpg?id=<recordingId>&startMs=<ms>&endMs=<ms>&fps=<n> |
One JPEG contact sheet of up to 36 consecutive frames from a range; the X-Clips-Frame-Sheet-Fps, -Grid and -Times headers describe the cells |
These endpoints follow the same access model as /api/public-recording, plus a
temporary agent-link path:
- Non-public clips return not found to anonymous callers.
create-recording-agent-link resolves normal recording access, rejects
archived or trashed recordings, then mints a two-hour agent_access URL for
/share/:recordingId. The share page SSR advertises the agent context URL,
and the JSON endpoints accept the same scoped token.
- Expired clips return expired.
- Public password-protected clips require
password=<pw> once; successful JSON
responses include short-lived tokenized links so the plaintext password is not
copied into downstream agent prompts, browser history, or logs.
- If a discovery, context, or transcript payload reports
agentReadiness.state
as "preparing" (the clip is "uploading" or "processing"), wait 15 seconds
and retry agentContextUrl. Do not open the share page, fetch frames, or draw
conclusions until the recording status is "ready".
- If the context or transcript response reports
transcript.status as
"pending", wait 15-30 seconds and retry the context/transcript URL a few
times before falling back to frames or telling the user no transcript exists.
Long recordings are the common case here.
- If transcription failed because Builder transcription credits are exhausted,
tell the user to upgrade or connect Builder.io credits, or configure a Groq
key for backup speech-to-text. Generic OpenAI or Anthropic chat keys do not
transcribe Clips recordings.
- Frame extraction must use the checked recording media path and must not expose
raw provider URLs.
Downloading the video file
The agent APIs above never hand out the video itself. When another app or
tool needs the owner's own file (a private recording, say),
create-recording-download-link returns a link to /api/video/:id with a
download_access token:
- Owner-only. Admins, editors and viewers are refused; a viewer of a shared
clip uses its share link.
- One recording, one owner. The token signs the recording id and its
owner's email, so it works for nothing else and stops working if the clip
changes hands. A share-with-agents token or a share-password token is not a
download token, and the reverse.
- Minutes, not hours. Ten minutes by default,
ttlSeconds 60 to 3600.
The route checks expiry on every request, Range requests included, so a
long download fetched in ranges needs a fresh link if it outlives the first.
- Checked again on use. A recording that has gone to Trash, is no longer
ready, plays only in an embedded player, or has redactions not yet burned
in is refused when the link is made and when it is used. Earlier-screen-time
footage is refused too.
- No fallback. A bad or expired
download_access answers 403 or 410; the
route never retries it as the caller's session.
Public agent context also exposes the recording's redacted browser diagnostics:
the bounded relative event sequence as browserDiagnostics.timeline, including
navigation, click/input targets, console events, and request/response markers;
the console stream (all levels) as browserDiagnostics.consoleLogs and the
fetch/XHR stream as browserDiagnostics.networkRequests (method, sanitized URL
with query values redacted, status, duration), plus consoleIssues and
failedNetworkRequests highlights. All of it is bounded, and page URL, headers,
bodies, and cookies stay omitted. When a list is trimmed, failures and
pre-recording entries are kept before the newest.
When the clip carries app activity from an agent-native app, the context adds
appActivity (counts, recorder coverage windows, up to 20 failures with
elapsedMs). For the owner, or a Share with agents link made by someone who
can still edit the clip, it also lists apis.appActivity
(/api/agent-app-activity.json, filtered by fromMs, toMs, maxEvents,
continued with start=nextStart). An open public link, a share password, or a
link made by a viewer gets the summary only, because event data is more
sensitive than the summary.
Public password-protected clips require the password once to mint a short-lived token,
which is returned inside the agent-context links.
Use the @agent-native/core/server and @agent-native/core/shared agent-access
helpers for scoped token mint/verify and bot-visible URL construction. Keep
Clips-specific visibility, password, transcript, frame, and player behavior in
Clips. New URLs should use agent_access; existing agent API routes should keep
accepting legacy t tokens so already-copied links do not break.
The share popover's "Share with agents" field should copy an agent context URL
or tokenized share page URL, not raw transcript text. Its "Copy agent prompt"
field may wrap that URL with instructions to fetch transcripts, frames, and
browser diagnostics, but it should still point agents at the context response so
they can fetch only the visual context they need.
HTTP access is the default browser-independent path: fetch the agent context
URL and then use its advertised transcript and frame URLs. It works for
URL-only clients without loading the share page.
When a /share/:id, /embed/:id, or public /r/:id page is open in a
WebMCP-capable browser, the page also registers these read-only tools:
| WebMCP tool |
Purpose |
clips-get-context |
Clip metadata, readiness, transcript status, and HTTP API URLs |
clips-get-transcript |
Bounded timestamped segments, with optional time bounds and stable-index pagination; may omit fullText |
clips-get-frame |
An existing authenticated JPEG frame URL for atMs |
For any client, fetch the agent context URL and use its HTTP API URLs. For
complete transcript text, use apis.transcript. If the page is already open
in a WebMCP-capable browser, list its current page tools and use them for
bounded inspection; clips-get-transcript may omit fullText or return a
truncated result, so follow its sourceUrl for the complete HTTP transcript.
The transcript tool returns nextStartIndex when another page exists; pass
that value back as startIndex so overlapping transcript segments are not
skipped.
The URL endpoint accepts the same startIndex, maxSegments, startMs, and
endMs parameters, and keeps nextStartMs for older clients. The frame tool
returns an image URL and mimeType: image/jpeg; fetch that URL as an image,
or call get-recording-frames when the client cannot. WebMCP is optional
progressive enhancement and page-local. HTTP access remains first-class and
browser-independent: use the existing agentContextUrl, apis.transcript,
and apis.frame URLs above. These URLs, password handling, scoped
agent_access tokens, and legacy t token support remain the primary URL
contract.
View counting
Clips counts human views and agent views separately. The two live in
different tables and never mix — see "Agent views" below before touching either.
Human views
A view counts when any of these is true:
- The viewer has watched ≥ 5 seconds of total real playback time
- The viewer has hit ≥ 75% completion
- The viewer has scrubbed to the very end
The canonical predicate is shouldCountView(totalWatchMs, completedPct, scrubbedToEnd) from server/lib/recordings.ts. Always go through it — do not recompute inline.
import { shouldCountView } from "../server/lib/recordings.js";
if (
!viewer.countedView &&
shouldCountView(viewer.totalWatchMs, viewer.completedPct, scrubbedToEnd)
) {
await db
.update(schema.recordingViewers)
.set({ countedView: true })
.where(eq(schema.recordingViewers.id, viewer.id));
}
Events feeding this live in recording_events. The /api/view-event route receives view-start, watch-progress (every 5s), seek, pause, resume, cta-click, reaction. Aggregate into recording_viewers on write to keep get-insights fast.
Agent views
An agent view is an outside agent reading a clip through its public agent
APIs — /api/agent-context.json, /api/agent-transcript.json,
/api/agent-frame.jpg, /api/agent-frames.jpg. Those routes are agent-only surfaces (a human watching a
clip never hits them), so a request on one is the signal.
- Table:
recording_agent_views — one row per (recordingId, agentKey, viewSessionId).
agentKey is a sha256 of user-agent + request IP, so an agent is countable
across polls without ever storing its IP. agentLabel resolves in that order:
the label the agent link was minted with (a signed agentLabel claim on the
agent_access token, set via create-recording-agent-link --agentLabel), then
the product name parsed from the user-agent (Claude, ChatGPT, Perplexity, …),
then NULL. NULL means unnamed, not a name — render it as "Unknown agent" and
never write a placeholder string, or an agent we could not identify becomes
indistinguishable from one that identified itself. userAgent keeps the raw
(truncated) string so unnamed agents stay identifiable and new AGENT_LABELS
patterns come from real traffic.
- Where it's written:
recordAgentView in server/lib/agent-views.ts,
called from loadPublicAgentAccess — the one choke point all three agent
routes share. Owner requests are skipped (they're previews, not views), and the
write is best-effort so view accounting can never fail an agent's read.
- Dedup: one agent's burst of context + transcript + frame polls collapses
into a single view via a 30-minute window (
AGENT_VIEW_SESSION_MS), with
requestCount recording how many polls that view covered.
- Reads:
countRecordingAgentViews and listRecordingAgentViewers. Surfaced
as agentViews / agentViewers on get-recording-insights, agentViewCount
on get-recording-player-data, list-recordings, and the public
/api/public-recording payload. The count renders inline — on the views pill
itself (RecordingViewsBadge, watch and share headers) and on library cards —
so agent reads are visible without opening the popover. It is always a
separate icon-prefixed number, never summed into the human view total.
Keeping this in its own table is deliberate: no human-view query can pick agents
up by forgetting a filter. Do not add agent rows to recording_viewers or
recording_views.
Per-viewer view records ("Viewed by")
On top of the aggregate viewCount shown in the library and the views stat in the insights panel, Clips records individual view records — who viewed a clip and when — so the owner can see a timeline, not just a number.
- Table:
recording_views (server/db/schema.ts) — id, recordingId, viewerId (FK to recording_viewers.id), denormalized viewerEmail / viewerName, viewedAt. Append-only; never updated after insert.
- Where it's written:
server/routes/api/view-event.post.ts, in the same handler that already upserts recording_viewers and inserts recording_events. A recording_views row is inserted exactly once per viewer, at the moment countedView transitions from false to true (i.e. the same instant that viewer starts contributing to the aggregate views count in get-recording-insights). This keeps the per-viewer log and the aggregate count always consistent — a returning viewer who is already counted does not create a second row.
- Anonymous viewers still get a row —
viewerEmail is null and viewerName holds the anon:<sessionId> key, same convention as recording_viewers. The UI renders these as "Someone".
- Read surface:
list-clip-views action — { recordingId, limit? }, owner-only (assertAccess("recording", recordingId, "editor")), returns { views: [{ id, viewerEmail, viewerName, viewedAt }] } sorted most-recent-first. Use this instead of scanning recording_viewers/recording_events when you need a real per-visit timeline.
- UI: clicking the view count (library card or the insights panel's Views stat) opens
<ViewedByPopover recordingId> (app/components/sharing/viewed-by-popover.tsx), which lazily queries list-clip-views only while the popover is open.
- Privacy: viewer identities in
recording_views are visible only to principals who already pass the owner-only assertAccess check on the recording — never surfaced on the public share page itself, which never fetches or renders other viewers' data.
Anonymous viewers
recording_viewers.viewer_email is nullable — anonymous viewers (public link, no account) still get a row keyed by a cookie id. Never require login to watch a public recording; require it only when the share grant is user-scoped.
Rules
- Never write to
recording_shares directly. Always go through share-resource / unshare-resource.
- Never store a plaintext password. Use the share-password helper to encrypt and verify it.
- Never bypass the access check on
/api/video/:id. Streaming routes are the #1 data-leak vector. The only thing that stands in for a signed-in owner there is a download_access token, verified against the recording's current owner.
- Password + expiry are additions, not replacements — the framework's
accessFilter still runs first.
- The embed route (
/embed/:shareId) is anonymous by default — don't require auth, but still go through canAccess.
build-embed-url is the single source of truth for embed URLs — keep it in sync with the query params the player accepts.
- Never expose
recording_views rows (or any other viewer's identity) from the public share/embed page — only list-clip-views, which is owner-only via assertAccess, may return them.
Related skills
sharing — framework-level primitive Clips composes with. Read this first.
security — password handling, token storage, anonymous viewer cookies.
video-editing — exports honor recordings.enableDownloads.
storing-data — why password / expiresAt live on the recordings row instead of a parallel table.
1---2name: video-sharing3description: >-4 How Clips shares recordings — composes with the framework sharing skill and5 adds password, expiry, embed URLs, view-counting, and per-viewer "Viewed by"6 records. Use when wiring the share dialog, building embed links, adding a7 password, showing who viewed a clip and when, debugging who can see a8 recording, or when an agent receives a Clips link and needs its transcript or9 video frames.10metadata:11 source: https://skillmd.com/skills/builderio/video-sharing12---1314# Video Sharing1516## Rule1718Recording sharing uses the framework `sharing` system — not a custom share table. Recordings are registered via `registerShareableResource({ type: "recording", ... })` in `server/db/index.ts`. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted and handle per-user grants, per-org grants, and the three visibility levels (`private` / `org` / `public`).1920Unlike the framework-wide private default, normal Clips recordings and uploaded21videos default to **public** so their copied share links work immediately.22Embedded bug-report recordings are the exception and default to organization23visibility. Callers can still explicitly create a private or organization-only24recording, and owners/admins can change visibility from the Share dialog.2526Organization admins can use `set-organization-branding` with27`defaultVisibility=public|org|private` to choose the visibility applied when new28recordings omit an explicit visibility. The default remains `public`, and an29explicit visibility always wins — which is why bug-report recordings still land30on `org`.3132Clips **adds two things** on top of the framework system:33341. **Password** — an optional encrypted string on the `recordings` row. For public recordings, non-owner viewers must enter it to play the recording. Private and organization access use the framework ACL; a stored password is retained and applies again if the recording becomes public.352. **`expiresAt`** — an optional ISO timestamp on the `recordings` row. After this time, all non-owner access is denied (even to principals with explicit grants). Existing values remain enforced, although the Share panel no longer edits expiry.3637These are **additive** — they never grant access the framework denies, only tighten it.3839## When to use4041Read this skill before:4243- Wiring the Share dialog on a recording page44- Adding a password or expiry UI45- Building embed URLs (`?t=`, `?autoplay=`, `?hideControls=`)46- Building AI-readable public clip URLs or transcript/frame endpoints47- Debugging "why can't Alice see this video?"48- Touching `server/routes/video/[id].ts` or `server/routes/share/[id].ts`4950## Data model touched5152- **`recordings.password`** (nullable text) — encrypted password value.53- **`hasPassword`** reports whether a password is stored, including dormant passwords on private or organization recordings; it does not by itself indicate an active password gate.54- **`recordings.expires_at`** (nullable ISO string).55- **`recording_shares`** — framework-managed. Do not insert directly — use `share-resource`.56- **`recordings.visibility`** — framework-managed column from `ownableColumns()`.57- **`recording_viewers`** + **`recording_events`** — view counting.58- **`recording_views`** — append-only per-view log (who viewed, when) backing the owner-facing "Viewed by" popover. See "View counting" below.59- **`recording_agent_views`** — outside agents reading a clip through its public agent APIs, counted separately from humans. See "Agent views" below.60- **`recording_content_bindings`** — the Agent-Native Content documents a Clip is placed in. See "Clips in Content documents" below.6162## Dropping in the share UI6364Recordings and meetings use Toolkit `ShareButton` for the standard access,65copy-link, and Send to controls. Public recordings can set, change, or remove a66password under General access. Existing expiry values remain enforced, but are67not edited in this panel. Meeting transcript visibility remains a68meeting-specific control. Pending redactions block sharing until they are burned69into the recording. Private and password-protected recording agent handoffs use70scoped recording agent links; a password-protected viewer cannot mint one.7172Embed URLs remain available through `build-embed-url`; embedding does not change73access. Public share pages emit link-preview metadata, while an iframe is a74separate playback integration.7576## Shared with me7778Use `list-recordings --view=shared` to list recordings the current user can79access but does not own. The filter composes with `accessFilter`, so it includes80direct user/org grants and organization-visible recordings while excluding81public-link-only clips. The UI exposes the same collection at `/shared`; use82`navigate --view=shared` to open it. `view-screen` returns the recordings83currently visible in that collection.8485## Changing many clips at once8687For a request over many of the user's own clips, such as "make my clips older88than a week private unless I've shared them with someone", find them with one89`list-recordings` call and change them with one call per 100:9091- `list-recordings` takes `createdBefore` / `createdAfter` (an ISO date such92 as `2026-10-25`, or a date-time with its offset such as `2026-10-25T12:00:00Z`),93 `visibility` (a list, such as `["public", "org"]`) and `hasShares`94 (`false` for clips whose share list names no person, group or org; it95 reads that list, not visibility, and only ever matches the user's own96 clips).97- `set-resource-visibility` takes `resourceIds` with `resourceType:98 "recording"`. Making any clip public asks for one approval for the call.99- `archive-recording`, `trash-recording`, `restore-recording` and100 `delete-recording-permanent` take `ids`; `tag-recording` and101 `add-recording-to-space` take `recordingIds`.102103Every clip in the call is checked first; if the user can't change one, none104change and the error names it. The result lists each clip as `changed`,105`unchanged` (already that way) or `skipped` with a reason. Report the counts106back, not the clips one by one. A long `delete-recording-permanent` batch107can stop early and list the clips it didn't reach as skipped; call it again108with those ids.109110## Discovery boundary for public clips111112Public recordings are unlisted-by-link for agent purposes: an agent may discover113only recordings the current user owns or has already viewed. Do not use114`list-recordings` or `search-recordings` to discover another user's public clips,115to answer a time/date question about the clip already in context, or to recover116from a failed direct lookup. If the user supplies another clip's share URL or id,117use that explicit reference; otherwise stop and report the lookup failure.118119## Access resolution120121The player and `/api/video/:id` route check access in this exact order:122123```ts124async function canAccess(125 recordingId: string,126 requester: Session | null,127 providedPassword?: string,128) {129 // 1. Framework check — owner, shared, or meets visibility.130 const access = await resolveAccess("recording", recordingId, requester);131 if (!access.allowed) return false;132133 const rec = await getRecordingOrThrow(recordingId);134135 // 2. Expiry — non-owner only.136 if (rec.expiresAt && requester?.email !== rec.ownerEmail) {137 if (new Date(rec.expiresAt) < new Date()) return false;138 }139140 // 3. Password — public links, non-owner only.141 if (rec.visibility === "public" && rec.password && requester?.email !== rec.ownerEmail) {142 if (!providedPassword) return false;143 if (!verifySharePassword(providedPassword, rec.password)) return false;144 }145146 return true;147}148```149150Framework first, Clips additions second. Don't invert this — the framework owns the "is this row visible at all" question.151152## Clips in Content documents153154A Clip placed in a Content document has one `recording_content_bindings` row per (recording, Content app, document). `origin` is `upload` (made in the document) or `link` (pasted); `state` is `active` or `trashed`. A duplicated document adds its own row.155156- Only an active `upload` binding grants access: a Content reader with no access of their own becomes a viewer of that one recording (`server/lib/content-doc-grant.ts`, a host access resolver registered with `includeSignedOut: true` so it is asked about signed-out readers of a public document too). A reader's own Clips sharing, in their active workspace, still applies and is never lowered. A `link` binding, or none, leaves the Clip's own sharing in charge. When every binding is trashed, document readers lose access; the owner never does.157- The Clip's own rules still apply on top: Trash, takedown and expiry refuse document readers, a password-protected Clip does not play through a document, and with comments off document readers see no comments and cannot write.158- Content calls `/api/content-clips/:recordingId/playback` and `/comments` (GET `?limit=<n>` to list the first n thread starts, at most `CONTENT_CLIP_MAX_COMMENT_THREADS`, which is also what a request with no `limit` gets, with `truncated` when there are more and each thread's text and author cut to `CONTENT_CLIP_COMMENT_PREVIEW_CHARS` and `CONTENT_CLIP_COMMENT_AUTHOR_CHARS`, so Content can cap what it reads (playback likewise cuts the title to `CONTENT_CLIP_RECORDING_TITLE_CHARS`); POST to add, reply, edit, delete, resolve or react) server to server with a one-minute A2A token. `shared/content-clip-contract.ts` is the contract: audience `<Clips URL>/content-clips`, one scope, and `document_id` + `recording_id` claims. A signed-out reader of a public document gets the `content-clip:public-read` scope: playback and the comment list, never a write.159- The token is signed with `CONTENT_CLIPS_PEER_SECRET` (`clips.contentPeerSecret`, read with `resolveContentClipsPeerSecret`), a secret only the Content and Clips deployments hold, and Clips verifies it with that secret alone. That is what makes the token's issuer trustworthy as the Content app: a token signed with the deployment `A2A_SECRET` or a workspace secret is refused, because other apps hold those. While the secret is unset, shorter than 32 characters, or equal to `A2A_SECRET`, every route answers 503 with code `content_clips_not_configured`; set it on both deployments.160- Playback returns Clips media URLs with a five-minute `content_grant` that names the reader, not a role. The grant is signed with a key derived from `CONTENT_CLIPS_PEER_SECRET`, never the app's own server secret (which a workspace derives from `A2A_SECRET`), and a media request carrying a grant while the secret is unusable gets the same 503. `/api/video` and `/api/thumbnail` re-run every gate on each request, so trashing the binding stops a URL already handed out. An expired grant is a 403 with code `content_grant_expired`; Content's player then asks Content for playback again, which re-checks document access.161- Each reader's reads and writes of one Clip through one document are rate-limited per process. A request counts against the Clip's bucket only once Clips has opened it: Content mints a token for any recording id a page reader names, so counting earlier would let a reader name made-up ids until their own spent bucket dropped out. A full map drops its oldest bucket rather than refuse a new one. A request whose Clip doesn't open counts as a miss against that reader's misses for that Clip and document; once they are spent, the Clip is refused before any database read. Misses are kept per Clip so made-up ids can't use up a real Clip's, which leaves a caller who keeps naming new made-up ids unbounded here: each costs one lookup, and Content's own per-visitor limit has to bound it. Every signed-out reader of a document shares the public reader's buckets.162- A Content editor's upload uses the `content-clip:upload` scope, whose token carries `document_id`, the editor's `name`, and the browser's `client_ip` when Content knows it, never a `recording_id`. Content checks that the reader can edit the page before minting it. `GET /api/content-clips/upload-status` answers the editor's `storage` state (`ready`, `free` with what's left, `used_up`, `none`, or `account_required` when the email has no Clips account or workspace; Clips never makes either). `POST /api/content-clips/uploads` adds the `upload` binding first, then a private recording the editor owns, and returns a ticketed `chunkUrl` and `cancelUrl`; a state that can't take the file is a 409 `storage_required` with that `storage`. The start carries the `uploadKey` Content makes once per picked file, kept on the binding with the file's type and size: a start repeated with the same key, page, and editor never makes a second Clip. It answers that upload with another ticket and the first start's plan while it is uploading, a 409 `upload_already_finished` with `recordingId` and `status` once a final chunk holds it or Clips is making the Clip, a 409 `upload_starting` while the latest start is still making its recording (Content repeats it after a few seconds), or a 409 `upload_key_used` when it was cancelled or failed, is parked until storage is connected, began in another block, or describes a file of another type or size. A start that fails deletes its binding only when nothing can be left: a refusal raised before any recording or free clip (`refusedStart`), or an error with `cleanupConfirmed: true`. Any other failure keeps the binding and marks `upload_start_failed_at`, and a repeat that finds no recording under a marked binding, or one whose latest attempt is `RESERVATION_GRACE_MS` old, takes the start over with a compare-and-swap on the binding (`takeOverStart`) and makes the recording under the binding's own recording id, so the free clip reserved per recording id is never held twice; of repeats that overlap, the rest get `upload_starting`. A kept binding whose start left a recording answers from where that upload stands, so one whose recording failed answers `upload_key_used` like a cancelled one; that key's upload ended, and Content starts the file again under a new key. Earlier tickets keep working, since overlapping repeats each hand one back: a recording keeps its four newest (`addRecordingUploadTicket`) and still holds one upload slot, while an agent's `create-recording-upload` keeps one. A repeat skips the storage check, since its first start may have taken the last free clip.163- The editor's browser posts the file to `/api/uploads/:recordingId/content-chunk` with the ticket in the query, no cookie, and no custom headers, so the request is a CORS simple request and no preflight reaches the auth guard. Only the paired built-in Content's origin (`pairedContentOrigin`) gets `Access-Control-Allow-Origin`, never the request's own `Origin`, and the answer never allows credentials.164- When the page gives an upload up (its block is gone, the editor can no longer edit, or a chunk failed for good), the browser POSTs `cancelUrl` (`/api/uploads/:recordingId/content-cancel?ticket=…`) the same way. Clips' own abort fails the recording and releases its free clip, as the lease reaper would an hour later; the `upload` binding stays. Where an upload stands is one answer, `readUploadPhase` in `server/lib/final-chunk-claim.ts`: `uploading`, `finishing` (a final chunk holds it), `parked` (Clips has the whole file and waits for storage), `finished` (`processing` or `ready`) or `ended` (cancelled or failed). The repeated start, the cancel and the Content chunk route all use it, and nothing else reads its three stores (the final chunk's claim, the upload state and the recording row) together. It reads the claim first, then the upload state, then the row. Before Clips takes the final chunk's bytes, on the buffered and the resumable path alike, the Content chunk route renews the row's lease to outlast its claim, only while the row is `uploading`, then claims the upload, changing its upload state with the same compare-and-swap the abort claims with; once Clips accepts the chunk it writes `parked` or `finished` into the upload state, and only then gives the claim up, so a reader that finds no claim finds where the upload went. A final chunk that fails gives the claim up with the upload still `uploading`. A claim older than `FINAL_CHUNK_CLAIM_TTL_MS` (a little over Clips' 75 s function timeout) was left by a request that was cut off, so the upload reads `uploading` again and the next final chunk or cancel takes it over. A live claim is never taken over: a cancel or another send of the final chunk changes nothing while the upload is `finishing` and answers 409 `upload_finishing` (`CONTENT_CLIP_CHUNK_FINISHING` for the chunk), which Content repeats every few seconds, the chunk for a little longer than the claim lasts. A final chunk sent once the upload is `parked` or `finished` answers the first one's success (202 `waitingForStorage`, or 200 with `status`) and Clips takes no bytes; one that finds the upload `ended` is refused (409). The answer's `outcome` comes from the phase read after the abort, never from the abort's `ok`: `cancelled` (200) once it is `ended`, a repeat included and a parked upload too, or `already_finished` (409, with `status`) once it is `finished`. Any other answer means it wasn't cancelled; an upload whose cancels keep finding `finishing` is left to the reaper. The reaper reads only the row's lease, never the phase: it fails a row whose lease ran out in one conditional update, so it either failed the row before the final chunk renewed it, and the chunk finds it `ended`, or it leaves the row. A page in Trash can still cancel. A closed tab is still left to the reaper.165- Upload-origin Clips are listed under From Content (`list-recordings` view `from-content`, each with `contentPageUrl` back to its page), and Library's own list leaves them out. A folder someone moved one into still lists it, and linked Clips stay in Library.166- `isActiveUploadBinding` / `activeUploadBinding()` in `server/lib/content-uploads.ts` is the one test for an active upload binding. Playback's grant, the chunk route, From Content and its page links all use it, so an upload whose page is in Trash plays for no document reader, takes no chunks (409), and lists in neither From Content nor Library.167- Create and change binding rows only through Content's upload and lifecycle flows.168169## Embed URLs170171Embeds live at `/embed/:shareId` (a share-scoped anonymous route). Supported query params:172173| Param | Meaning |174| ----------------- | -------------------------------------------------- |175| `?t=80` | Start playback at 80 seconds |176| `?autoplay=1` | Autoplay (muted — browsers block unmuted autoplay) |177| `?hideControls=1` | Hide the player chrome |178| `?loop=1` | Loop playback |179180Build embed URLs via the `build-embed-url` action:181182```ts183const { url } = await callAction("build-embed-url", {184 id: recording.id,185 t: 80,186 autoplay: true,187});188// -> /embed/<shareId>?t=80&autoplay=1189```190191## Slack unfurls192193Clips can render Loom-style Slack previews through Slack App Unfurling. Configure194the Slack app's `link_shared` event to call `/api/slack/unfurl`; the route195verifies `SLACK_SIGNING_SECRET`, acknowledges Slack URL verification, and calls196`chat.unfurl` with a Block Kit `video` block using the existing `/embed/:id`197player URL.198199For installable workspaces, use the Clips Settings OAuth flow. `connect-slack`200opens Slack OAuth, `/api/slack/oauth/callback` stores the bot token encrypted in201`app_secrets`, and `slack_installations` stores only the Slack team/app metadata202plus the secret ref. The unfurl webhook resolves the token by Slack `team_id`203and `api_app_id`; only if no OAuth install exists should it fall back to the204legacy `SLACK_BOT_TOKEN` path.205206The playable Slack embed is deliberately narrower than the share page:207208- Only `ready` recordings with `visibility === "public"` can produce a video block.209- Password-protected, expired, archived, trashed, private, org-only, or still-processing clips must not produce a playable Slack block.210- Slack thumbnails use the same-origin proxy for stored thumbnails and the branded social image while one is unavailable. The proxy redirects to that image if stored content cannot be served; normal share-page metadata remains the fallback when no Slack app is installed.211- Do not put passwords, short-lived share tokens, raw provider URLs, or transcript text in Slack unfurl payloads.212213Required Slack app setup:214215- Bot scopes: `links:read`, `links:write`, `links.embed:write`216- Event subscription: `link_shared`217- App unfurl domains: the public Clips share domain, for example `clips.agent-native.com`218- Request URL: `https://<clips-host>/api/slack/unfurl`219- OAuth redirect URL: `https://<clips-host>/api/slack/oauth/callback`220- Deploy secrets: `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and221 `SLACK_SIGNING_SECRET`222223## Agent-readable clips224225When a user supplies a Clips link, read the clip through its published agent226context instead of stopping at the share page or transcript preview:2272281. Use the exact `agentContextUrl` in the page's agent-readable instructions or229 `application/agent-native+json` discovery payload. Preserve its `id` and any230 `agent_access` query parameter on every related request.2312. Fetch `apis.transcript` for the complete transcript. Fetch each232 `recommendedFrames[].url` as an image and inspect the returned pixels; when233 more visual context is needed, request `apis.frame.urlTemplate` with an234 `atMs` timestamp. To watch motion (an animation, a transition, a cursor235 path), request `apis.frames.urlTemplate` with `startMs`, `endMs` and `fps`:236 one JPEG contact sheet of up to 36 consecutive frames from a range of at237 most 60 seconds. Cells read left to right, then top to bottom; cell `i`238 shows the frame on screen at `startMs + i * 1000 / fps`, and solid black239 cells at the end of the grid hold no frame. Without `fps` the sheet uses240 the video's own frame rate, and without `endMs` it takes up to 36 frames241 from `startMs`, stopping at 60 seconds or the end of the clip. A242 `failureKind: request` response names a request that fits in `nextStep`.2433. On an error, inspect the JSON `failureKind`, `error`, and `nextStep`. If a244 context or transcript request has `failureKind: access`, explain that the245 link does not grant access. For a private clip, ask its owner to open the246 Clips Share menu, choose **Share with agents**, and send the generated link.247 If a frame request has `failureKind: media` while the transcript works,248 report that the stored media could not be retrieved; another link will not249 fix it. If it has `failureKind: processing`, follow `nextStep`: extraction,250 size-limit, and temporary storage errors do not prove that media is missing251 or that the link lacks access.252 If `failureKind: expired`, ask the owner to extend or remove the clip expiry253 through `update-recording`, then create and send a new **Share with agents**254 link. Never claim to have seen frames that were not returned as images.255256The JSON discovery payload and HTTP endpoints work without browser tools. An257agent that cannot open frame URLs as images (claude.ai, a ChatGPT custom258connector) calls the `get-recording-frames` MCP tool instead, once Clips is259connected as an MCP connector (`apis.mcp.connectUrl`). It takes the260`recordingId` plus up to four `atMs` values, and returns the frames as image261blocks; without `atMs` it returns the first four recommended frames and lists262all of them. It checks only the connected user's own access (owner, share,263organization, public); an `agent_access` token does not grant it. A264public password-protected clip fails with `password_required` for anyone but its265owner.266267Recordings can expose URLs meant for external agents without handing over raw268video bytes:269270| Endpoint | Meaning |271| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |272| `/api/agent-context.json?id=<recordingId>` | Clip metadata, transcript summary, recommended frames, and API discovery links |273| `/api/agent-transcript.json?id=<recordingId>` | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source`; add `maxSegments` to page and continue with the returned `nextStartIndex` |274| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp |275| `/api/agent-frames.jpg?id=<recordingId>&startMs=<ms>&endMs=<ms>&fps=<n>` | One JPEG contact sheet of up to 36 consecutive frames from a range; the `X-Clips-Frame-Sheet-Fps`, `-Grid` and `-Times` headers describe the cells |276277These endpoints follow the same access model as `/api/public-recording`, plus a278temporary agent-link path:279280- Non-public clips return not found to anonymous callers.281- `create-recording-agent-link` resolves normal recording access, rejects282 archived or trashed recordings, then mints a two-hour `agent_access` URL for283 `/share/:recordingId`. The share page SSR advertises the agent context URL,284 and the JSON endpoints accept the same scoped token.285- Expired clips return expired.286- Public password-protected clips require `password=<pw>` once; successful JSON287 responses include short-lived tokenized links so the plaintext password is not288 copied into downstream agent prompts, browser history, or logs.289- If a discovery, context, or transcript payload reports `agentReadiness.state`290 as `"preparing"` (the clip is `"uploading"` or `"processing"`), wait 15 seconds291 and retry `agentContextUrl`. Do not open the share page, fetch frames, or draw292 conclusions until the recording status is `"ready"`.293- If the context or transcript response reports `transcript.status` as294 `"pending"`, wait 15-30 seconds and retry the context/transcript URL a few295 times before falling back to frames or telling the user no transcript exists.296 Long recordings are the common case here.297- If transcription failed because Builder transcription credits are exhausted,298 tell the user to upgrade or connect Builder.io credits, or configure a Groq299 key for backup speech-to-text. Generic OpenAI or Anthropic chat keys do not300 transcribe Clips recordings.301- Frame extraction must use the checked recording media path and must not expose302 raw provider URLs.303304### Downloading the video file305306The agent APIs above never hand out the video itself. When another app or307tool needs the owner's own file (a private recording, say),308`create-recording-download-link` returns a link to `/api/video/:id` with a309`download_access` token:310311- **Owner-only.** Admins, editors and viewers are refused; a viewer of a shared312 clip uses its share link.313- **One recording, one owner.** The token signs the recording id and its314 owner's email, so it works for nothing else and stops working if the clip315 changes hands. A share-with-agents token or a share-password token is not a316 download token, and the reverse.317- **Minutes, not hours.** Ten minutes by default, `ttlSeconds` 60 to 3600.318 The route checks expiry on every request, Range requests included, so a319 long download fetched in ranges needs a fresh link if it outlives the first.320- **Checked again on use.** A recording that has gone to Trash, is no longer321 `ready`, plays only in an embedded player, or has redactions not yet burned322 in is refused when the link is made and when it is used. Earlier-screen-time323 footage is refused too.324- **No fallback.** A bad or expired `download_access` answers 403 or 410; the325 route never retries it as the caller's session.326327Public agent context also exposes the recording's redacted browser diagnostics:328the bounded relative event sequence as `browserDiagnostics.timeline`, including329navigation, click/input targets, console events, and request/response markers;330the console stream (all levels) as `browserDiagnostics.consoleLogs` and the331fetch/XHR stream as `browserDiagnostics.networkRequests` (method, sanitized URL332with query values redacted, status, duration), plus `consoleIssues` and333`failedNetworkRequests` highlights. All of it is bounded, and page URL, headers,334bodies, and cookies stay omitted. When a list is trimmed, failures and335pre-recording entries are kept before the newest.336337When the clip carries app activity from an agent-native app, the context adds338`appActivity` (counts, recorder coverage windows, up to 20 failures with339`elapsedMs`). For the owner, or a Share with agents link made by someone who340can still edit the clip, it also lists `apis.appActivity`341(`/api/agent-app-activity.json`, filtered by `fromMs`, `toMs`, `maxEvents`,342continued with `start=nextStart`). An open public link, a share password, or a343link made by a viewer gets the summary only, because event data is more344sensitive than the summary.345346Public password-protected clips require the password once to mint a short-lived token,347which is returned inside the agent-context links.348349Use the `@agent-native/core/server` and `@agent-native/core/shared` agent-access350helpers for scoped token mint/verify and bot-visible URL construction. Keep351Clips-specific visibility, password, transcript, frame, and player behavior in352Clips. New URLs should use `agent_access`; existing agent API routes should keep353accepting legacy `t` tokens so already-copied links do not break.354355The share popover's "Share with agents" field should copy an agent context URL356or tokenized share page URL, not raw transcript text. Its "Copy agent prompt"357field may wrap that URL with instructions to fetch transcripts, frames, and358browser diagnostics, but it should still point agents at the context response so359they can fetch only the visual context they need.360361HTTP access is the default browser-independent path: fetch the agent context362URL and then use its advertised transcript and frame URLs. It works for363URL-only clients without loading the share page.364365When a `/share/:id`, `/embed/:id`, or public `/r/:id` page is open in a366WebMCP-capable browser, the page also registers these read-only tools:367368| WebMCP tool | Purpose |369| ---------------------- | ------------------------------------------------------------------------------------------------------ |370| `clips-get-context` | Clip metadata, readiness, transcript status, and HTTP API URLs |371| `clips-get-transcript` | Bounded timestamped segments, with optional time bounds and stable-index pagination; may omit fullText |372| `clips-get-frame` | An existing authenticated JPEG frame URL for `atMs` |373374For any client, fetch the agent context URL and use its HTTP API URLs. For375complete transcript text, use `apis.transcript`. If the page is already open376in a WebMCP-capable browser, list its current page tools and use them for377bounded inspection; `clips-get-transcript` may omit `fullText` or return a378truncated result, so follow its `sourceUrl` for the complete HTTP transcript.379The transcript tool returns `nextStartIndex` when another page exists; pass380that value back as `startIndex` so overlapping transcript segments are not381skipped.382The URL endpoint accepts the same `startIndex`, `maxSegments`, `startMs`, and383`endMs` parameters, and keeps `nextStartMs` for older clients. The frame tool384returns an image URL and `mimeType: image/jpeg`; fetch that URL as an image,385or call `get-recording-frames` when the client cannot. WebMCP is optional386progressive enhancement and page-local. HTTP access remains first-class and387browser-independent: use the existing `agentContextUrl`, `apis.transcript`,388and `apis.frame` URLs above. These URLs, password handling, scoped389`agent_access` tokens, and legacy `t` token support remain the primary URL390contract.391392## View counting393394Clips counts **human views** and **agent views** separately. The two live in395different tables and never mix — see "Agent views" below before touching either.396397### Human views398399A view counts when **any** of these is true:400401- The viewer has watched **≥ 5 seconds** of total real playback time402- The viewer has hit **≥ 75% completion**403- The viewer has scrubbed to the very end404405The canonical predicate is `shouldCountView(totalWatchMs, completedPct, scrubbedToEnd)` from `server/lib/recordings.ts`. Always go through it — do not recompute inline.406407```ts408import { shouldCountView } from "../server/lib/recordings.js";409410if (411 !viewer.countedView &&412 shouldCountView(viewer.totalWatchMs, viewer.completedPct, scrubbedToEnd)413) {414 await db415 .update(schema.recordingViewers)416 .set({ countedView: true })417 .where(eq(schema.recordingViewers.id, viewer.id));418}419```420421Events feeding this live in `recording_events`. The `/api/view-event` route receives `view-start`, `watch-progress` (every 5s), `seek`, `pause`, `resume`, `cta-click`, `reaction`. Aggregate into `recording_viewers` on write to keep `get-insights` fast.422423### Agent views424425An **agent view** is an outside agent reading a clip through its public agent426APIs — `/api/agent-context.json`, `/api/agent-transcript.json`,427`/api/agent-frame.jpg`, `/api/agent-frames.jpg`. Those routes are agent-only surfaces (a human watching a428clip never hits them), so a request on one is the signal.429430- **Table:** `recording_agent_views` — one row per `(recordingId, agentKey, viewSessionId)`.431 `agentKey` is a sha256 of user-agent + request IP, so an agent is countable432 across polls without ever storing its IP. `agentLabel` resolves in that order:433 the label the agent link was minted with (a signed `agentLabel` claim on the434 `agent_access` token, set via `create-recording-agent-link --agentLabel`), then435 the product name parsed from the user-agent (Claude, ChatGPT, Perplexity, …),436 then NULL. NULL means unnamed, not a name — render it as "Unknown agent" and437 never write a placeholder string, or an agent we could not identify becomes438 indistinguishable from one that identified itself. `userAgent` keeps the raw439 (truncated) string so unnamed agents stay identifiable and new `AGENT_LABELS`440 patterns come from real traffic.441- **Where it's written:** `recordAgentView` in `server/lib/agent-views.ts`,442 called from `loadPublicAgentAccess` — the one choke point all three agent443 routes share. Owner requests are skipped (they're previews, not views), and the444 write is best-effort so view accounting can never fail an agent's read.445- **Dedup:** one agent's burst of context + transcript + frame polls collapses446 into a single view via a 30-minute window (`AGENT_VIEW_SESSION_MS`), with447 `requestCount` recording how many polls that view covered.448- **Reads:** `countRecordingAgentViews` and `listRecordingAgentViewers`. Surfaced449 as `agentViews` / `agentViewers` on `get-recording-insights`, `agentViewCount`450 on `get-recording-player-data`, `list-recordings`, and the public451 `/api/public-recording` payload. The count renders inline — on the views pill452 itself (`RecordingViewsBadge`, watch and share headers) and on library cards —453 so agent reads are visible without opening the popover. It is always a454 separate icon-prefixed number, never summed into the human view total.455456Keeping this in its own table is deliberate: no human-view query can pick agents457up by forgetting a filter. Do not add agent rows to `recording_viewers` or458`recording_views`.459460### Per-viewer view records ("Viewed by")461462On top of the aggregate `viewCount` shown in the library and the `views` stat in the insights panel, Clips records **individual view records** — who viewed a clip and when — so the owner can see a timeline, not just a number.463464- **Table:** `recording_views` (`server/db/schema.ts`) — `id`, `recordingId`, `viewerId` (FK to `recording_viewers.id`), denormalized `viewerEmail` / `viewerName`, `viewedAt`. Append-only; never updated after insert.465- **Where it's written:** `server/routes/api/view-event.post.ts`, in the same handler that already upserts `recording_viewers` and inserts `recording_events`. A `recording_views` row is inserted **exactly once per viewer**, at the moment `countedView` transitions from `false` to `true` (i.e. the same instant that viewer starts contributing to the aggregate `views` count in `get-recording-insights`). This keeps the per-viewer log and the aggregate count always consistent — a returning viewer who is already counted does not create a second row.466- **Anonymous viewers** still get a row — `viewerEmail` is `null` and `viewerName` holds the `anon:<sessionId>` key, same convention as `recording_viewers`. The UI renders these as "Someone".467- **Read surface:** `list-clip-views` action — `{ recordingId, limit? }`, owner-only (`assertAccess("recording", recordingId, "editor")`), returns `{ views: [{ id, viewerEmail, viewerName, viewedAt }] }` sorted most-recent-first. Use this instead of scanning `recording_viewers`/`recording_events` when you need a real per-visit timeline.468- **UI:** clicking the view count (library card or the insights panel's Views stat) opens `<ViewedByPopover recordingId>` (`app/components/sharing/viewed-by-popover.tsx`), which lazily queries `list-clip-views` only while the popover is open.469- **Privacy:** viewer identities in `recording_views` are visible only to principals who already pass the owner-only `assertAccess` check on the recording — never surfaced on the public share page itself, which never fetches or renders other viewers' data.470471## Anonymous viewers472473`recording_viewers.viewer_email` is **nullable** — anonymous viewers (public link, no account) still get a row keyed by a cookie id. Never require login to watch a public recording; require it only when the share grant is user-scoped.474475## Rules476477- **Never** write to `recording_shares` directly. Always go through `share-resource` / `unshare-resource`.478- **Never** store a plaintext password. Use the share-password helper to encrypt and verify it.479- **Never** bypass the access check on `/api/video/:id`. Streaming routes are the #1 data-leak vector. The only thing that stands in for a signed-in owner there is a `download_access` token, verified against the recording's current owner.480- **Password + expiry are additions**, not replacements — the framework's `accessFilter` still runs first.481- The embed route (`/embed/:shareId`) is **anonymous by default** — don't require auth, but still go through `canAccess`.482- `build-embed-url` is the single source of truth for embed URLs — keep it in sync with the query params the player accepts.483- **Never** expose `recording_views` rows (or any other viewer's identity) from the public share/embed page — only `list-clip-views`, which is owner-only via `assertAccess`, may return them.484485## Related skills486487- `sharing` — framework-level primitive Clips composes with. Read this first.488- `security` — password handling, token storage, anonymous viewer cookies.489- `video-editing` — exports honor `recordings.enableDownloads`.490- `storing-data` — why `password` / `expiresAt` live on the `recordings` row instead of a parallel table.