DreamLake

Annotations

An annotation is where your labeled data lives — your workflow does the labeling, the annotation stores its output. One episode is one raw video plus any number of annotation layers: anything you can pin to that video's clock. Layers are independent and open-ended — send what you have, add the rest later.

one annotationep-001ep-002ep-003…one clock — every layer is pinned to itvideoper-frame valueslabeled intervalsepisode-wide facts…and morethe next layer lands here — same video, same clockmany episodes per annotation — each one a video plus every layer you have for it

Titles and share links

Open an annotation and click its title to edit it. Press Enter or leave the field to save. Titles can contain spaces and are limited to 200 characters; the annotation name, URL, SDK address, and stored data stay the same. Namespace members can also edit the title from the annotation list's Edit menu.

The Share control uses the same menu as Memos. Choose can view or can edit, then copy the link. Recipients must sign in to DreamLake. A view link allows opening the annotation and playing its videos. An edit link also allows saving title changes and using the existing annotation labeling preview. Timeline, caption, and review edits in that preview are still in memory and are not saved.

Only namespace members can manage annotation links, change visibility, or delete the annotation. Changing a link from edit to view affects existing holders; no access revokes the link. Re-enabling sharing creates a new token. Revoking a link blocks new reads and video signatures; already issued video URLs remain usable until their short expiry. Sharing an annotation does not grant access to its namespace or other resources.

Rename an annotation URL

Namespace members can choose Rename URL in the annotation header. The new slug uses 1–64 lowercase letters, digits, dots, underscores or hyphens, starting with a letter or digit. Existing links keep working, and data, history, sharing and the storage name stay unchanged. Copying a share link uses the current slug. If another rename wins while the dialog is open, the save reports a conflict; refresh the annotation before trying again. Title editing remains independent. See the API and SDK reference.

Public catalog reads

GET /namespaces/:slug/annotations accepts requests without an Authorization header. Anonymous callers and authenticated nonmembers receive only live public annotation rows; namespace members retain access to their private rows. A supplied invalid or expired token returns 401.

Public annotation details (GET /namespaces/:slug/annotations/:name) and content reads (POST /namespaces/:slug/annotations/:name/presign-read) also accept anonymous requests. Both check the annotation's current visibility. Private, missing and deleted annotations return 404 to callers without access; namespace members can still read their private annotations. Presigned reads retain the existing path validation and expiry limits. Upload credentials, creation, editing and deletion still require authentication and membership.

Browsing in the app

/<namespace>/profile?tab=annotations and /<namespace>/annotations share the same catalog. Personal owners and organization members see the resources and operations permitted to them; anonymous visitors and visitors to someone else's namespace see public annotations only. Profile has an identity rail, while the application has resource navigation for the URL's namespace.

Public details open without a sign-in redirect and retain the namespace sidebar. The detail header returns anonymous readers to the Profile annotations tab and signed-in readers to /<namespace>/annotations. Embedded viewers return to their containing project. See Profiles and workspaces.

Prerequisites

bash
curl -fsSL https://dl.dreamlake.ai/install.sh | bash   # the dreamlake CLI
pip install dreamlake dreamdb   # SDK + storage engine
brew install ffmpeg             # transcoding (any install method works)
dl login                 # browser sign-in; CI uses DREAMLAKE_API_KEY

Windows, what the installer puts where, release channels, and auto-update: Install.

Upload it

your videoany formatannotationswhatever you haveone uploadyou wait, it worksstreaming videoplays in any browseraligned layerson the video's clockone episodenothing to convert by hand — the upload transcodes and aligns for you

One call. The video is transcoded for the browser, each layer is stored against its clock, and adding a layer later just means passing one more argument. Give the episode an id you'll recognise — that's the handle for coming back.

Keep adding

Open an annotation by name on any day and add to it. Revisions never overwrite — newest wins, history stays.

one episode, filled in over time — newest wins, nothing is overwrittenvideo+ one layer+ a layerdays later+ a cameradays later+ next layerwhenever it shipsevery revision stays in history — the episode never has to be re-uploaded
Later, you canEffect
add another episodethe annotation grows
revise a layernewest wins, old versions kept
add a layer you skippedit shows up on an episode you already uploaded
add a layer type that ships latersame thing — just another revision
add a camera angleviews share one clock; video is add-only
make it publicanyone can open it, no login

Nothing you upload today has to be re-uploaded to benefit from what ships tomorrow.

Watch it

Open the web app → Annotations → your annotation → your episode.

your-annotation / your-episodeEPISODES124SEGMENTS3① per-frame layers — drawn on the picture    ② spatial layers — the 3D view③ interval layers — the segment list    ④ the same intervals, on the clockthe video stays raw — new layer types slot into surfaces like these

How a layer is drawn follows from how it's pinned — which is why the list can grow without the picture changing:

A layer pinned toIs drawnShipping today
a frameon the picture, tracking playbackjoint skeletons, 3D reconstruction
an intervalas labeled bars on the timeline; click to seekaction segments
the whole episodeas episode metadatatask labels

Each is optional. The player shows what you have and skips what you don't — a bare video simply streams.

Search it

An annotation is searchable once its episodes have search vectors. With pip install "dreamlake[search]":

python
ann.embed_episodes()                  # frame vectors (CLIP ViT-B/32) + segment-label vectors (BGE-small)
ann.search("picking up thread snips") # -> [{"episode_id", "time_sec", "score", "source", ...}]

Frame vectors come from each camera's source video. Run embed_episodes() where those files are, or pass video_path= per episode.

In the web app, an annotation shown through an Output Source has Enable semantic search above the viewer:

  • Model download: enabling it downloads the two query models (about 100 MB) into the browser once.
  • What to search: Segments (the default) ranks the labelled segments, Frames ranks the sampled frames, and Both fuses the two rankings the way ann.search(..., kind="both") does. Segments and Frames show each result's similarity score. Clicking a result seeks the player to that time.
  • Complete for small annotations: the browser scores every stored vector, up to 20,000 vectors or 64 MiB per field. Above that, or when the exact scan is unavailable, it falls back to the approximate index and the panel says so, because some matches may be missing.
  • Ranking, not judgement: results are the closest stored matches, best first. A close match is not necessarily the moment you meant.
  • Private reads: the search reads the annotation's stored vectors privately, like the viewer. Nothing is sent to a search service.
  • No vectors yet: if the annotation has none, it says which are missing instead of returning no matches.

When there's no overlay yet

Every annotation page has two views, and the second one always works.

your-annotationvideo.annotation/v2presetraw trackspreset viewwhen the type is one we renderraw tracks viewalways there — every track, whatever it issubtask_labelevent · strjoints_posejsonrecon_handsimage.binframe_vecdim=512no preset for your data yet? it is still stored, listed and readable

Preset view is what the last section showed: the annotation's type label matches a preset, and you get the player with its overlays.

Raw tracks view ignores presets and lists every track straight off the manifest — name, kind, values along the timeline. Label, JSON, embedding, video; it doesn't matter.

If your dataYou get
matches a presetthe rendered view, overlays and all
doesn't, or not yetthe raw track view — nothing hidden, nothing lost
gets a preset laterthe rendered view, with no re-upload

So a new kind of data is useful the day you upload it.

Bring your own schema

The same machinery with the lid off: declare any columns you like — sensor readings, JSON, images, embeddings — anchored to timestamps, or to row numbers when your data has no clock. It's also the escape hatch when the layer you need doesn't exist yet.

not video? declare your own columns and use the same storagedeclare trackstyped columnsappendrows landat a point in timereadbacksame shapesanywhere, any machinenumbersimagesJSON docsembeddings
RuleWhat it means for you
append-only, write-oncea value at a given time and column is never rewritten
one commit per writesend batches, not one point at a time
one writer at a timeparallel writers to the same annotation will clash

Custom annotations appear in the catalog under their own type label; today you read them back through the SDK.

Share it

Annotations are private by default.

Who can view
🔒 private (default)you and members of your namespace
🌐 publicanyone, no login

Names can be scoped to a team, too: a bare name is yours, an organisation prefix targets that org, and membership is checked per request.

Let Claude do it

Install the annotations skill (dl init once, then dl skill install dreamlake-annotations; or copy dreamlake-annotations/ from the latest release tarball into your agent's skills directory) and skip the SDK — describe what you want, it makes the calls:

You sayIt does
"upload this clip with its hand skeletons and action segments"creates the annotation, uploads the episode
"add the 3D reconstruction to ep-001"fills in the missing layer
"add a wrist camera to ep-001"attaches the second view
"make this annotation public"flips visibility

Next steps

Annotations Reference →

The manual — every method, argument and data shape, with the code this page leaves out.

Reference § Annotation formats →

Every layer's exact fields, including 3D reconstruction.

Project attachment access

Explicit user/team Project READ grants content reads for its live Annotation attachments; WRITE/ADMIN permit supported content uploads. Public Project visibility does not open a private Annotation. Independent resource policy remains valid, and detaching or revoking removes only inherited access.

Attaching requires Project content creation and independent sharing-management authority. Project grants do not grant catalog/schema management, resource deletion, ownership transfer or infrastructure credentials. Delegated uploads require resource-scoped temporary credentials; static custom-S3 credentials and unscoped STS fallback are refused with DELEGATED_UPLOAD_UNSUPPORTED (403). An annotation owned by another namespace attaches only through its owner's cross-namespace mount grant.

The Project-sharing backend and Web update are released. CLI Project commands require 0.62.0 or later; Python Project support requires SDK 0.29.0 or later. See the Project resource access contract.

The released whole-Project and owned-Notes transfer supports Project, ordinary Project files/images/videos, owned Memos, and owned Artifact and Env attachments (Artifact/Env members need the matching released clients). In the deployed service, an Annotation attachment blocks the entire transfer rather than silently excluding it. The Annotation's existing independent sharing and released Project-derived content access remain available.

Unreleased — intended design contract, not deployed behavior. A planned expansion of the same whole-Project transfer carries the Project's live Annotation attachments as manifest members (annotation, alongside project, note, artifact, env and source). It is whole-Project only: no standalone Annotation transfer is added. Annotation IDs, storage bindings and pinned catalog identity stay stable; episode, layer and revision payloads retain their existing storage — nothing is copied, moved or re-uploaded — and schemas, versions and raw tracks stay stable, while ownership metadata changes. Catalog placements outside the moved Project detach; the Memo-only preserveExternalFilings option does not retain them. The Annotation becomes private at the destination; preserving a direct share is conditional on the server's eligibility policies and blockers, and signed URLs already issued keep their existing bounded expiry — there is no immediate-invalidation promise. Standalone label datasets have no Project relationship and are not moved by this feature. No released backend or client version supports this yet; the whole-Project contract is authoritative for scope and current blockers.

Related resources and activity

Open the collapsed context panel for Related resources and History. Explicit links, accessible saved sessions, and recent recorded activity remain separate. Links can also be recorded from the Memo editor and through the API or CLI. See relationships, permissions and API identities.