Add proposal for support for init segments in Flows

api/examples/flow-get-200-video-h264-fmp4.json

@@ -0,0 +1,54 @@
+{
+    "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
+    "source_id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f",
+    "generation": 0,
+    "created": "2008-05-27T18:51:00Z",
+    "metadata_updated": "2023-09-14T09:45:26Z",
+    "segments_updated": "2023-09-14T09:45:26Z",
+    "description": "Big Buck Bunny",
+    "label": "bbb",
+    "format": "urn:x-nmos:format:video",
+    "created_by": "tams-dev",
+    "updated_by": "tams-dev",
+    "tags": {
+        "input_quality": "contribution"
+    },
+    "codec": "video/h264",
+    "container": "video/iso.segment",
+    "avg_bit_rate": 2479,
+    "segment_duration": {
+        "numerator": 10
+    },
+    "essence_parameters": {
+        "init_segments": true,
+        "frame_rate": {
+            "numerator": 24,
+            "denominator": 1
+        },
+        "frame_width": 1280,
+        "frame_height": 720,
+        "bit_depth": 8,
+        "interlace_mode": "progressive",
+        "colorspace": "BT709",
+        "transfer_characteristic": "SDR",
+        "aspect_ratio": {
+            "numerator": 16,
+            "denominator": 9
+        },
+        "pixel_aspect_ratio": {
+            "numerator": 1,
+            "denominator": 1
+        },
+        "component_type": "YCbCr",
+        "vert_chroma_subs": 2,
+        "horiz_chroma_subs": 2,
+        "avc_parameters": {
+            "profile": 100,
+            "level": 31,
+            "flags": 0
+        }
+    },
+    "collected_by": [
+        "e85efab4-993b-4ad6-9af3-4cd8d0d38860"
+    ]
+}

api/examples/flow-segments-get-200-init.json

@@ -0,0 +1,53 @@
+[
+    {
+        "object_id": "846023d3-612d-5014-bc47-88f6eb2d04bb",
+        "timerange": "[0:0_10:0)",
+        "get_urls": [
+            {
+                "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/846023d3-612d-5014-bc47-88f6eb2d04bb"
+            }
+        ],
+        "init_object": {
+            "object_id": "9ef06e23-b882-4a93-b005-480de42ef4e9",
+            "get_urls": [
+                {
+                    "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/9ef06e23-b882-4a93-b005-480de42ef4e9"
+                }
+            ]
+        }
+    },
+    {
+        "object_id": "25be83fc-11d1-5743-9d47-6865cef5ea35",
+        "timerange": "[10:0_20:0)",
+        "get_urls": [
+            {
+                "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/25be83fc-11d1-5743-9d47-6865cef5ea35"
+            }
+        ],
+        "init_object": {
+            "object_id": "9ef06e23-b882-4a93-b005-480de42ef4e9",
+            "get_urls": [
+                {
+                    "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/9ef06e23-b882-4a93-b005-480de42ef4e9"
+                }
+            ]
+        }
+    },
+    {
+        "object_id": "8b785422-6a82-5d60-b25a-f77e0a748321",
+        "timerange": "[20:0_30:0)",
+        "get_urls": [
+            {
+                "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/8b785422-6a82-5d60-b25a-f77e0a748321"
+            }
+        ],
+        "init_object": {
+            "object_id": "192472f1-55fd-45dc-b355-e6833a3a140c",
+            "get_urls": [
+                {
+                    "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/192472f1-55fd-45dc-b355-e6833a3a140c"
+                }
+            ]
+        }
+    }
+]

api/examples/objects-get-200-init.json

@@ -0,0 +1,22 @@
+{
+    "id": "846023d3-612d-5014-bc47-88f6eb2d04bb",
+    "referenced_by_flows": [
+        "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
+        "0fde9c11-da9d-434a-a113-d3b20a2cf251"
+    ],
+    "first_referenced_by_flow": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
+    "timerange": "[150:0_200:0)",
+    "get_urls": [
+        {
+            "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/846023d3-612d-5014-bc47-88f6eb2d04bb"
+        }
+    ],
+    "init_object": {
+        "id": "9ef06e23-b882-4a93-b005-480de42ef4e9",
+        "get_urls": [
+            {
+                "url": "https://store.example.com/tams-e2b89b02-21e7-5f9d-aa2d-db38b01453c9/9ef06e23-b882-4a93-b005-480de42ef4e9"
+            }
+        ]
+    }
+}

api/schemas/flow-audio.json

@@ -78,6 +78,10 @@
                                     ]
                                 }
                             }
+                        },
+                        "init_segments": {
+                            "description": "Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted.",
+                            "type": "boolean"
                         }
                     }
                 }

api/schemas/flow-core.json

@@ -68,7 +68,7 @@
             "$ref": "mime-type.json"
         },
         "container": {
-            "description": "The container MIME type for Flow Segments. Note that the `type` component of the container MIME type (i.e. the component before the `/`) may be different to the `type` component of the codec MIME type. e.g. An audio Flow may have `audio/aac` coded content may be wrapped in a `video/mp2t` container. Where multiple types exist for a subtype (e.g. `video/mp4`, `audio/mp4`, `application/mp4`), the closest MIME type to the Flow `format` should be used (e.g. `audio/mp4` for a Flow `format` of `urn:x-nmos:format:audio`). Mime types from the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml) should be preferred. Where multiple MIME types are possible, the most common should be preferred. Where this is insufficient, the maintainers of the TAMS repository may create an application note advising which MIME type to use. Where the Flow does not reference any Media Object(s) directly (e.g. an empty Multi Flow that serves only to collect related mono-essence Flows that do reference Media Objects), this property MUST NOT be set.",
+            "description": "The container MIME type for Flow Segments. Where the media format employs initialisation segments, this is the mime type of the media segments and NOT the initialisation segment(s). Note that the `type` component of the container MIME type (i.e. the component before the `/`) may be different to the `type` component of the codec MIME type. e.g. An audio Flow may have `audio/aac` coded content may be wrapped in a `video/mp2t` container. Where multiple types exist for a subtype (e.g. `video/mp4`, `audio/mp4`, `application/mp4`), the closest MIME type to the Flow `format` should be used (e.g. `audio/mp4` for a Flow `format` of `urn:x-nmos:format:audio`). Mime types from the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml) should be preferred. Where multiple MIME types are possible, the most common should be preferred. Where this is insufficient, the maintainers of the TAMS repository may create an application note advising which MIME type to use. Where the Flow does not reference any Media Object(s) directly (e.g. an empty Multi Flow that serves only to collect related mono-essence Flows that do reference Media Objects), this property MUST NOT be set.",
             "$ref": "mime-type.json"
         },
         "avg_bit_rate": {

api/schemas/flow-data.json

@@ -30,6 +30,10 @@
                         "data_type": {
                             "description": "The type of information encoded in the Flow, identified using a URN. e.g. The data_type may be urn:x-tams:data:bounding-box, and the codec `application/json`.",
                             "type": "string"
+                        },
+                        "init_segments": {
+                            "description": "Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted.",
+                            "type": "boolean"
                         }
                     }
                 }

api/schemas/flow-multi.json

@@ -18,6 +18,18 @@
                     "enum": [
                         "urn:x-nmos:format:multi"
                     ]
+                },
+                "essence_parameters": {
+                    "title": "Multi Flow Essence Parameters",
+                    "description": "Describes the parameters of the essence inside this multi Flow",
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "init_segments": {
+                            "description": "Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted.",
+                            "type": "boolean"
+                        }
+                    }
                 }
             }
         }

api/schemas/flow-segment-post.json

@@ -8,7 +8,11 @@
     ],
     "properties": {
         "object_id": {
-            "description": "The Object identifier for the Media Object.",
+            "description": "The Object identifier for the Media Object. The `content-type` of the Media Object MUST match the `container` mime-type of the Flow. Service implementations SHOULD reject Objects IDs which have previously been registered as an `init_object_id` on other Flow Segments. i.e. init segments may not be used as media segments.",
+            "type": "string"
+        },
+        "init_object_id": {
+            "description": "The Object identifier for the initialisation segment Object required to decode the Media Object. The `content-type` of the initialisation segment Object MAY differ from the `container` mime-type of the Flow. This parameter MUST only be set where the media format makes use of initialisation segments. Initialisation Objects SHOULD be re-used where possible. This parameter SHOULD be omitted where the Object `object_id` already exists and is being re-used. Service implementations SHOULD reject Objects IDs which have previously been registered as an `id` on other Flow Segments. i.e. media segments may not be used as init segments.",
             "type": "string"
         },
         "ts_offset": {

api/schemas/flow-segment.json

@@ -39,11 +39,33 @@
                     "description": "The count of samples in the Segment (which may be fewer than in the Media Object). The count could be less than expected given the Segment duration and rate if there are gaps. If not set, every sample from sample_offset onwards is used. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.",
                     "type": "integer",
                     "deprecated": true
+                },
+                "init_object": {
+                    "title": "Initialisation Object",
+                    "description": "The Object containing the initialisation segment required to decode the parent Media Object.",
+                    "unevaluatedProperties": false,
+                    "allOf": [
+                        {
+                            "type": "object",
+                            "required": [
+                                "object_id"
+                            ],
+                            "properties": {
+                                "object_id": {
+                                    "description": "The identifier of the initialisation Object.",
+                                    "type": "string"
+                                }
+                            }
+                        },
+                        {
+                            "$ref": "object-core.json"
+                        }
+                    ]
                 }
             }
         },
         {
-            "$ref": "object-core.json"
+            "$ref": "object-media-core.json"
         }
     ]
 }

api/schemas/flow-storage-post.json

@@ -17,6 +17,10 @@
         "storage_id": {
             "description": "The Storage Backend to allocate storage in. A Storage Backend identifier as advertised at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint. If not set the default, as advertised at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint, will be used if available. An invalid Storage Backend identifier will result in a 400 error.",
             "$ref": "uuid.json"
+        },
+        "content_type": {
+            "description": "The `content_type` to use for the Objects. This parameter MUST only be set where requesting storage for initialisation segments in media formats which require them, and where the mime-type of those initialisation segments differs to that of the media segments. Assumed to be the `container` type of the Flow if not set.",
+            "$ref": "mime-type.json"
         }
     },
     "not": {

api/schemas/flow-storage.json

@@ -1,7 +1,7 @@
 {
     "type": "object",
     "title": "Media Bucket Object Store",
-    "description": "Gives information on storage for Media Objects. This schema is for the `http_object_store` Storage Backend type which provides URLs for storing Media Objects in object store buckets, and is the only Storage Backend type currently implemented.  URLs SHOULD support the inclusion of checksums in headers as supported by advertised Storage Backend product. See AppNote 0048 for more details.",
+    "description": "Gives information on storage for Media Objects. This schema is for the `http_object_store` Storage Backend type which provides URLs for storing Media Objects in object store buckets, and is the only Storage Backend type currently implemented.  URLs SHOULD support the inclusion of checksums in headers as supported by advertised Storage Backend product. See AppNote 0048 for more details. Where included in the response, `content-type` MUST match the corresponding value in the request.",
     "properties": {
         "media_objects": {
             "type": "array",

api/schemas/flow-video.json

@@ -212,6 +212,10 @@
                             "description": "If `true`, the frame rate of the Flow is variable and `frame_rate` MUST NOT be set. If `false` or omitted, the frame rate of the Flow is fixed and `frame_rate` MUST be set.",
                             "type": "boolean",
                             "default": false
+                        },
+                        "init_segments": {
+                            "description": "Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted.",
+                            "type": "boolean"
                         }
                     },
                     "if": {

api/schemas/object-core.json

@@ -43,10 +43,6 @@
                     }
                 ]
             }
-        },
-        "key_frame_count": {
-            "description": "The number of key frames in the Media Object. This should be set greater than zero when the Media Object contains key frames that serve as a stream access point",
-            "type": "integer"
         }
     }
 }

api/schemas/object-media-core.json

@@ -0,0 +1,18 @@
+{
+    "type": "object",
+    "description": "Provides the location and metadata of the media files corresponding to a Media Object.",
+    "title": "Object",
+    "allOf": [
+        {
+            "properties": {
+                "key_frame_count": {
+                    "description": "The number of key frames in the Media Object. This should be set greater than zero when the Media Object contains key frames that serve as a stream access point",
+                    "type": "integer"
+                }
+            }
+        },
+        {
+            "$ref": "object-core.json"
+        }
+    ]
+}

api/schemas/object.json

@@ -6,8 +6,7 @@
             "type": "object",
             "required": [
                 "id",
-                "referenced_by_flows",
-                "timerange"
+                "referenced_by_flows"
             ],
             "properties": {
                 "id": {
@@ -26,13 +25,35 @@
                     "$ref": "uuid.json"
                 },
                 "timerange": {
-                    "description": "The timerange covering the sample timestamps embedded in or derived from the Media Object itself, on the Media Object's timeline.",
+                    "description": "The timerange covering the sample timestamps embedded in or derived from the Media Object itself, on the Media Object's timeline. This parameter MUST be set where the Object contains media. It MUST NOT be set where the Object contains an init segment.",
                     "$ref": "timerange.json"
+                },
+                "init_object": {
+                    "title": "Initialisation Object",
+                    "description": "The Object containing the initialisation segment required to decode the parent Media Object.",
+                    "unevaluatedProperties": false,
+                    "allOf": [
+                        {
+                            "type": "object",
+                            "required": [
+                                "id"
+                            ],
+                            "properties": {
+                                "id": {
+                                    "description": "The identifier of the initialisation Object.",
+                                    "type": "string"
+                                }
+                            }
+                        },
+                        {
+                            "$ref": "object-core.json"
+                        }
+                    ]
                 }
             }
         },
         {
-            "$ref": "object-core.json"
+            "$ref": "object-media-core.json"
         }
     ]
 }