Create Flow Segments

Register either a single new Flow Segment or an array of Segments, attaching the Object id given to a point in the Flow timeline.

The Segment may use a newly-written Media Object, or re-use an existing Media Object from another Flow.

For newly-written Media Objects, the client is responsible for ensuring that the Segment written to the TAMS service instance obeys the following restrictions:

• All samples in the Object SHOULD be used by the Segment.
• If the Segment does not use all samples in the Object, object_timerange MUST be set to the timerange of media in the object, on the Media Object's timeline
• The timestamps of each sample in the Media Object MUST equal its position on the Flow timeline, OR ts_offset MUST be set such that media_object_ts + ts_offset = segment_ts
• The timerange of the Segment MUST NOT overlap any other Segment in the same Flow. The behaviour is undefined if there is an overlap with existing Segments and a service may return a 400 error response.

A service instance SHOULD reject registrations of Flow Segments with a 400 error response if it references a newly created Media Object in the local TAMS storage that was not intended to be used for the Flow. A service instance SHOULD accept Flow Segments that reference an existing Media Object in the local TAMS storage that was originally created for another Flow.

A service instance MAY support Media Objects that are held in external storage in another TAMS or other media storage system. The Flow Segment may in that case require the get_urls property to provide the information needed by clients to access the Media Object.

The list of instances of an object (and associated get_urls entries) can be modified via the /objects endpoints, which provides a mechanism to register new instances of an object.

Clients MAY modify Flow Segments, but this should only be done in exceptional circumstances to correct metadata such as key_frame_count, as such operations will likely break the idempotency of Segments. If a client needs to modify a Flow Segment, then the client SHOULD first delete the existing Segment and then write a new one. The behaviour is undefined if the Segment exists and the service may return a 400 error response.

For successful creation of all Segments in the request a 201 response should be provided. If an error is detected when processing a list of Segments then processing should continue to try and process the remaining Segments. A 200 response should be returned listing the failed Segments.

Clients are expected to decide how to break content into Media Objects, however those Objects SHOULD be large enough to avoid excessive round trip overheads in the underlying store (e.g. of the order of several megabytes) and where codecs with temporal re-ordering are used, Object SHOULD contain complete GOPs or decodable units.

For Media Objects that have been re-used from other Flows, the timerange MAY specify only part of the duration of the object:

• The timerange field indicates the new Segment's position in the Flow
• The timerange of the Segment MUST NOT overlap any other Segment in the same Flow.
• The Flow Segment's timerange start and end, once offset by ts_offset, MUST be contained entirely within the Media Object's timerange

When re-using Media Objects, requests which change object properties (e.g. key_frame_count, object_timerange, or init_object_id) SHOULD be rejected.

If an Object has previously been registered as an initialisation segment (i.e. via init_object_id), Service implementations SHOULD reject its use as a media segment (i.e. via object_id). If an Object has previously been registered as a media segment (i.e. via object_id), Service implementations SHOULD reject its use as an initialisation segment (i.e. via init_object_id).