TAMS and Time-Range Search
TAMS and Time-Range Search
TAMS and Time-Range Search
TAMS (Time-Addressable Media Store) is BBC R&D’s open spec for media archives. The core idea: media is addressed by time, not by file path. Content is organized as a three-level hierarchy. A Source is a logical piece of content (a match, a show, an asset). A Flow is one specific rendition of that source (720p H.264 video, or 48kHz stereo audio). A Segment is a time-bounded chunk of a flow, with a timerange_start and timerange_end in seconds.
Compass models this hierarchy using doc_type, parent_ref, and group_id. You control the structure at ingest time.
Your agent asks “what’s at second 47” more often than it runs open-ended similarity search. Your agent retrieving bounding box positions, active speakers, or shot types needs to pin results to exact time windows before ranking by relevance. Without time-range filters, every query scans the whole collection.
TAMS search in Compass works in two steps: filter to the segments in the time window, then rank those segments by query relevance. The filter step uses Compass’s precomputed bitset facets and runs in microseconds.
Use client_id and parent_ref to link chunks within a single batch. group_id groups all segments that belong to the same source:
timerange_start and timerange_end are numeric seconds as float64 values. Do not pass ISO date strings. The filter engine treats them as numeric range fields. Passing "2026-03-15T00:34:00Z" instead of 2040.0 will produce no results.
Filter to segments in a specific time range, then rank by query:
This returns segments matching “goal celebration” within the 2040-2100 second window. relationship_boost gives a score bump to segments whose parent source also matches, and to sibling segments in the same group.
relationship_boost surfaces context around the matching segment. Fields:
A parent_weight of 0.3 means: if the segment’s parent source also scored well, add 30% to this segment’s score. This surfaces segments that are doubly relevant: the specific moment matches, and the broader context matches too.
Available in v0.3.
To retrieve segments that contain a specific timestamp on a known asset, use the /segments/at endpoint:
asset is required. It matches the segment’s group_id (which in the TAMS model equals the source’s client_id). time, time_start, and time_end are all optional. If time is set it takes precedence and returns segments where timerange_start <= time <= timerange_end. Otherwise the range parameters define an overlap window: a segment matches if timerange_start <= time_end and timerange_end >= time_start.
The response includes the full chunks sorted ascending by timerange_start, plus a took_ms field:
No query string is required, no vector scoring runs. Useful when your agent has an exact timestamp on an asset and needs the metadata for that moment (bounding boxes, active speaker, shot type) without running a similarity search.
timerange_start, timerange_end, time, time_start, and time_end are all numeric seconds as float64 values. Do not use ISO date strings. Passing a string in any of these will return no results.
These filters operators work on timerange_start and timerange_end, and on any numeric metadata field:
Multiple filters combine as AND. A segment must match every filter to be scored.
Compass doesn’t fetch from cloud storage, sign URIs, or hold storage credentials. It treats URIs as opaque strings on the chunk’s metadata block. Put your gs://, s3://, or https:// URIs in metadata at ingest time, and they come back on every search hit. Your application layer pre-signs them with your own SDK before handing them to a user or downstream agent.
Search responses include these URIs in chunk.metadata. Pair them with parent_metadata (on segment hits) to resolve back to the source asset’s URIs without a second round trip.
Whatever you put in a chunk’s text field gets embedded by the active vector space and indexed for full-text search. For sidecar-driven workflows there are two patterns.
Quick: stringify the sidecar and pass it as text. Compass embeds the literal JSON. Recall is decent for short sidecars but the embedding model spends tokens on {, ", and , syntax instead of actual content.
Better: flatten to prose in your ingest pipeline, then embed. Walk the sidecar JSON, produce a short natural-language description, and pass that as text. Keep the structured fields in metadata so you can still filter on them. About thirty lines of code in any language, and recall improves materially because the embedding model sees content instead of syntax.
Both patterns ship text to whatever embedding model your collection’s vector space uses (BGE-small by default, or your embed_endpoint for larger models). If you want full control over the embedding step, skip both and ship pre-computed vectors directly via the vector_space_embeddings field on the chunk.