From a7d32cf854d12b2c52234320f2331e556e0d57f5 Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Mon, 29 Sep 2025 14:52:43 +0100 Subject: [PATCH 1/3] appnote: Fix error in deleting object instances --- docs/appnotes/0018-managing-multiple-object-instances.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/appnotes/0018-managing-multiple-object-instances.md b/docs/appnotes/0018-managing-multiple-object-instances.md index b7a50850..e967ead5 100644 --- a/docs/appnotes/0018-managing-multiple-object-instances.md +++ b/docs/appnotes/0018-managing-multiple-object-instances.md @@ -108,12 +108,13 @@ Example POST body to `/objects/{objectId}/instances`: ### Deleting an Object Instance -Specific instances of a Media Object can be deleted by a DELETE request to `/objects/{objectId}/get_urls` with the relevant `storage_id` in the query string. +Specific instances of a Media Object can be deleted by a DELETE request to `/objects/{objectId}/instances` with the relevant `storage_id` in the query string. +However attempting to delete the last instance of a media object should be rejected: this requires deleting the referencing Flow Segments instead. Example DELETE request: ```text -http://tams.example.com/objects/846023d3-612d-5014-bc47-88f6eb2d04bb/get_urls?storage_id=323367fd-21bb-4f2e-ad38-faf048c4ccfc +http://tams.example.com/objects/846023d3-612d-5014-bc47-88f6eb2d04bb/instances?storage_id=323367fd-21bb-4f2e-ad38-faf048c4ccfc ``` Once deleted, this instance will no longer be advertised in `get_urls` on the `/objects/{objectId}` endpoint or on the `/flows/{flowId}/segments` for Flow Segments which use the Media Object. From 343a0506e5cd913c579a9971cc3d727fa05b3254 Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Mon, 29 Sep 2025 15:08:13 +0100 Subject: [PATCH 2/3] api: Fix confusion on modifying segments Reworks description that modifying `key_frame_count` can be achieved by deleting the segment and re-creating if need be, but that the list of instances can be freely modified. --- api/TimeAddressableMediaStore.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index c5284280..b2a6df9d 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -2003,11 +2003,10 @@ paths: 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. - Clients MAY modify Flow Segments, but this should only be done in exceptional circumstances to correct metadata as such operations will likely break the idempotency of Segments. - Properties of Media Objects, such as `get_urls`, SHOULD be modified via the [`/objects`](#/operations/GET_objects) endpoints. - They SHOULD NOT be modified at this endpoint, and TAMS instences SHOULD reject such requests with a `400` error. + The list of instances of an object (and associated `get_urls` entries) can be modified via the [`/objects`](#/operations/GET_objects) endpoints, which provides a mechanism to register new instances of an object. - If a client needs to modify a Flow Segment, e.g. to correct metadata such as the `key_frame_count` or add additional URLs to `get_urls`, then the client SHOULD first delete the existing Segment and then write a new one. + 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. From 742229e232aada9f78cbd422a0145700cf5952ec Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Fri, 10 Oct 2025 16:19:45 +0100 Subject: [PATCH 3/3] api: Clarify key_frame_count behaviour on re-use Makes clear that attempts to modify `key_frame_count` when an object has been re-used elsewhere is not acceptable. Also, trivial wording tweak to make documentation clearer. --- api/TimeAddressableMediaStore.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index b2a6df9d..1d2601cc 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -2015,11 +2015,13 @@ paths: 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 `sample_offset` and `sample_count` MAY be used to specify part of the Media Object to use: + For Media Objects that have been re-used from elsewhere, the `sample_offset` and `sample_count` MAY be used to specify part of the Media Object to use: - The `timerange` field indicates the new Segment's position in the Flow - The sample associated with the start of the `timerange` MUST be the one selected by `sample_offset` - Likewise, the sample associated with the end of the `timerange` MUST be the one selected by `sample_offset + sample_count - 1`, unless `timerange` has an exclusive end, in which case it will be `sample_offset + sample_count`. - The timerange of the Segment MUST NOT overlap any other Segment in the same Flow. + + When re-using Media Objects, requests which change object properties (e.g. `key_frame_count`) SHOULD be rejected. operationId: POST_flows-flowId-segments tags: - FlowSegments