Video tags & events

Beyond the in-training tag_rendering / mark_rendering_event helpers, metrana exposes the full video annotation API for working with videos after the fact — from a notebook, an eval job, or a post-processing script.

There are three concepts:

• Video tag — a workspace-level label (e.g. "personal-best") you attach to whole videos.
• Event type — a workspace-level named condition (e.g. "collision", "goal_reached").
• Event — one occurrence of an event type on a video, over a [from_frame, to_frame] range.

Tags and event types are workspace-scoped and reusable; events are per-video.

Authentication & resolution

Every function resolves the same way as the artifact functions:

• workspace defaults to the active run’s workspace from init().
• api_key falls back to METRANA_API_KEY.
• base_url falls back to artifact_api_url from init(), then METRANA_ARTIFACT_API_URL, then the built-in default (see Service endpoints).

Errors surface as the shared MetranaArtifact* hierarchy.

Tags

create_video_tag is idempotent on (workspace, tag_name) — it creates the tag or returns the existing one:

tag = metrana.create_video_tag("personal-best", description="Best return so far")

tag.tag_id       # str
tag.tag_name     # str
tag.description  # str | None

metrana.list_video_tags()                              # -> list[VideoTag] (all pages)
metrana.update_video_tag(tag.tag_id, tag_name="pb")    # patch name and/or description
metrana.delete_video_tag(tag.tag_id)                   # cascade-detaches from all videos

Attach and detach a tag on a specific video (apply_video_tag is idempotent):

metrana.apply_video_tag(video_id, tag.tag_id)
metrana.remove_video_tag(video_id, tag.tag_id)

Event types

create_video_event_type is idempotent on (workspace, condition_name):

et = metrana.create_video_event_type("collision", description="Agent hit an obstacle")

et.event_type_id   # str
et.condition_name  # str
et.description     # str | None

metrana.list_video_event_types()                                     # -> list[VideoEventType]
metrana.update_video_event_type(et.event_type_id, condition_name="crash")
metrana.delete_video_event_type(et.event_type_id)                    # cascade-deletes its occurrences

Events (occurrences)

Mark an occurrence of an event type on a video over an inclusive frame range:

event = metrana.apply_video_event(
    video_id, event_type_id=et.event_type_id, from_frame=120, to_frame=138,
)

event.event_id        # str
event.event_type_id   # str
event.video_id        # str
event.from_frame      # int
event.to_frame        # int

metrana.list_video_events(video_id)                         # -> list[VideoEvent], by start frame
metrana.update_video_event(event.event_id, to_frame=142)    # patch either side of the range
metrana.delete_video_event(event.event_id)

One occurrence per start frame

An event type can hold at most one occurrence starting at a given from_frame on a video. Re-applying at the same start frame raises MetranaArtifactConflictError, and to_frame must be >= from_frame.

When to use these vs. the in-training helpers

Reach for tag_rendering / mark_rendering_event when you’re generating the video in a training loop and already know what’s happening frame-by-frame — they buffer against the encoding rendering and apply automatically once it uploads, and drive upload_renderings="triggered".

Reach for the functions on this page when you’re annotating existing videos — labelling a batch after an eval, correcting an occurrence, or curating tags across a workspace.