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.
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
Windows, what the installer puts where, release channels, and auto-update: Install.
Upload it
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.
| Later, you can | Effect |
|---|---|
| add another episode | the annotation grows |
| revise a layer | newest wins, old versions kept |
| add a layer you skipped | it shows up on an episode you already uploaded |
| add a layer type that ships later | same thing — just another revision |
| add a camera angle | views share one clock; video is add-only |
| make it public | anyone 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.
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 to | Is drawn | Shipping today |
|---|---|---|
| a frame | on the picture, tracking playback | joint skeletons, 3D reconstruction |
| an interval | as labeled bars on the timeline; click to seek | action segments |
| the whole episode | as episode metadata | task 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]":
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.
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 data | You get |
|---|---|
| matches a preset | the rendered view, overlays and all |
| doesn't, or not yet | the raw track view — nothing hidden, nothing lost |
| gets a preset later | the 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.
| Rule | What it means for you |
|---|---|
| append-only, write-once | a value at a given time and column is never rewritten |
| one commit per write | send batches, not one point at a time |
| one writer at a time | parallel 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 |
| 🌐 public | anyone, 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 say | It 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
The manual — every method, argument and data shape, with the code this page leaves out.
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, alongsideproject,note,artifact,envandsource). 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-onlypreserveExternalFilingsoption 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.