List Flow Segments
Returns the Flow Segments.
The Flow Segment provides information about the Media Object. The Storage Backend type, which is indicated in the /service/storage-backends resource, determines the information that is included in the response to allow the Flow Segment's Media Object to be downloaded by the client. The examples provided here are for the "http_object_store" Storage Backend type which MUST include a get_urls property that contains the HTTP URLs for downloading the Media Object - service implementations should generate this internally.
The Flow Segment may include timing adjustment information that the client needs to apply when extracting the samples from the Media Object. The timestamp of a sample on the Flow Segment's timeline (segment_ts) is the timestamp of that sample embedded in or derived from the internal timing of the Media Object (media_object_ts) adjusted by ts_offset: segment_ts = media_object_ts + ts_offset.
It may also use a subset of the samples in the Media Object, and if the include_object_timerange=true parameter is set, the object's timerange will also be returned to aid identifying which samples to skip.
Segments are sorted by timerange, in ascending order by default. As Segments in TAMS do not overlap, either of the start or end timestamp of the timerange may be used as the sort key. Service implementations MUST take clusivity markers of the timerange into account. Service implementations should consider edge cases such as a timerange with an exclusive end [1:0_2:0) followed by an instantaneous timerange of [2:0].
Clients should use the pagination options to limit the results to a timerange and/or count. Service implementations may also limit the results returned. This will be signalled via the paging headers in the response. The list of Flow Segments can be empty. A request for Segments from a non-existent Flow will return an empty list, not a 404.
Note that for codecs with temporal re-ordering, the timerange representes the presentation timeline, and clients may need to check the key_frame_count property and/or read backwards from the start of the requested timerange to retrieve enough reference material to start decoding.
Where Flow Segments reference initialisation segment Objects with the same ID, the initialisation segment is the same. Consuming clients may choose to ignore initialisation segment Objects that haven't changed in subsequent Flow Segments.
When making requests to the provided get_urls, clients should include credentials if the provided URL is on the same origin as the API itself, akin to the same-origin mode in the WhatWG Fetch Standard.
Query parameters
Filter on Object identifier.
A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers.
E.g.
- [0:0_10:0) represents 10 seconds of media starting at timestamp 0:0 and ending before 10:0.
- (5:0_ represents a timerange starting after 5:0 and to eternity.
- _ without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline).
- () without timestamps represents "never" (i.e. a range of zero length in no particular position).
- [1694429247:0_1694429248:0) is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC.
- [1694429247:0] is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to [1694429247:0_1694429247:0]. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. ( or )).
- A [ or ] indicates that bound is inclusive, and a ( or ) indicates that bound is exclusive.
Details of the format can be found in the Timestamps in TAMS application note.
Return only the results that partially or wholly overlap the timerange specified.
Return Segments in reverse time order.
Include storage metadata in get_urls in the response. When verbose_storage is false only url, presigned, and label will be included in get_urls and init_object.get_urls.
A list of Object GET URL Labels, formatted for use in query string parameters
A comma separated list of labels of Flow Segment get_urls and init_object.get_urls to include in the response. Omitting accept_get_urls will result in no filtering of get_urls or init_object.get_urls. An empty accept_get_urls results in get_urls and init_object.get_urls being empty or omitted in the response. Flow Segment get_urls and init_object.get_urls with no label will only be returned if accept_get_urls is omitted. Without get_urls, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned get_urls and init_object.get_urls will match all filters.
A list of Universally Unique Identifiers (UUIDs) as defined in RFC9562, formatted for use in query string parameters
A comma separated list of storage_ids of Flow Segment get_urls and init_object.get_urls to include in the response. Omitting accept_storage_ids, or providing an empty accept_storage_ids will result in no filtering of get_urls or init_object.get_urls. Flow Segment get_urls and init_object.get_urls with no storage ID will only be returned if accept_storage_ids is omitted or empty. A full list of available storage_ids may be found at the /service/storage-backends endpoint. Where multiple filter query parameters are provided, the returned get_urls and init_object.get_urls will match all filters.
If set to true, only presigned URLs (i.e. those whos presigned property is true) will be returned in get_urls and init_object.get_urls. If set to false, only non-presigned URLs (i.e. those whos presigned property is false) will be returned in get_urls and init_object.get_urls. If omitted, both presigned and non-presigned URLs will be returned. If presigned is set to false, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs. Where multiple filter query parameters are provided, the returned get_urls and init_object.get_urls will match all filters.
If set to true, the underlying object's timerange should appear in the response. Assume false if omitted.
Opaque string used by backend to access a specific page of results. Clients should read the next URL from the Link header returned with responses, or use value of the returned X-Paging-NextKey header. If not supplied, the first page is accessed. Service implementations should ensure a consistent sort order is applied to pages of results.
Restrict the response to the specified number of results. Service implementations may specify their own default and maximum for the limit