Improve description of object re-use

Relaxes unintentional constraint that POSTed FlowSegments must use
object IDs drawn from that Flow.
Clarifies the use of `sample_offset` and `sample_count`.
Generally improves description of FlowSegment fields.

sem-ver: bugfix

api/TimeAddressableMediaStore.yaml

@@ -549,15 +549,23 @@ paths:
                 $ref: examples/flow-segments-get-200.json
     post:
       description: |
-        Register a new flow segment.
-        
-        The client is responsible for ensuring that the data written to the store this way obeys the following
-        restrictions:
+        Register a new flow segment, attaching the object id given to a point in the flow timeline.
+
+        The segment may use a newly-written object, or re-use an existing object from another flow.
+
+        For newly-written objects, the client is responsible for ensuring that the segment written to the store obeys the following restrictions:
         - The object id provided for a segment MUST be one which was received in a POST from /storage for this flow.
-        - The first timestamp in the actual media data written to the object MUST be located inside the time range
+        - The first media unit written to the object MUST have a timestamp located inside the time range
           that was associated with this object id in the response from the POST request to /storage for this flow.
-        - The start and end timestamps for the flow given in the submitted body MUST be the actual first and last
-          timestamps of the data that has been written into the object.
+        - All media units in the object SHOULD be used by the segment.
+        - The timestamps of each media unit in the file MUST equal its position on the Flow timeline, OR `ts_offset` MUST be set such that `media_unit_ts + ts_offset = segment_ts`
+        - The `sample_offset` SHOULD be zero.
+
+        For objects that have been re-used from other flows, the `sample_offset` and `sample_count` MAY be used to specify part of the object to use:
+        - The `range` (or `first_ts` and `last_ts`) fields indicate the new segment's position in the flow
+        - The sample associated with the start of the range (or `first_ts`) MUST be the one selected by `sample_offset`
+        - Likewise, the sample associated with the end of the range (or `last_ts`) MUST be the one selected by `sample_offset + sample_count`.
+
       operationId: POST_flows-flowId-segments
       tags:
         - FlowSegments

api/schemas/flow-segment.json

@@ -24,7 +24,7 @@
       "type": "string"
     },
     "ts_offset": {
-      "description": "The timestamp offset between the timestamps stored in the media file and the corresponding timestamp in the segment, ie. ts_offset = segment ts - media object ts.",
+      "description": "The timestamp offset between the timestamps stored in the media file and the corresponding timestamp in the segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set.",
       "type": "string",
       "pattern": "^-?\\d+:\\d+$"
     },
@@ -34,17 +34,17 @@
       "pattern": "^(\\[)?-?\\d+:\\d+(_-?\\d+:\\d+)?(\\]|\\))?$"
     },
     "first_ts" : {
-      "description": "The timestamp of the first media unit in the segment (not media file).",
+      "description": "The timestamp of the first media unit in the segment (which may not be the first unit in the object).",
       "type": "string",
       "pattern": "^-?\\d+:\\d+$"
     },
     "last_duration": {
-      "description": "The duration of the last media unit in the segment (not media file). Defaults to 1/rate if a fixed media rate is set.",
+      "description": "The duration of the last media unit in the segment (which may differ from that of the object). Defaults to 1/rate if a fixed media rate is set.",
       "type": "string",
       "pattern": "^\\d+:\\d+$"
     },
     "last_ts" : {
-      "description": "The timestamp of the last media unit or end of the last media unit if exclusive_last_ts is true.",
+      "description": "The timestamp of the start of the last media unit in the segment, or end of the last media unit in the segment if exclusive_last_ts is true.",
       "type": "string",
       "pattern": "^-?\\d+:\\d+$"
     },
@@ -54,11 +54,12 @@
       "default": false
     },
     "sample_offset": {
-      "description": "The start of the segment represented as a count of audio samples, video frames or data items from the start of the media file.",
-      "type": "integer"
+      "description": "The start of the segment represented as a count of audio samples, video frames or data items from the start of the object.",
+      "type": "integer",
+      "default": 0
     },
     "sample_count": {
-      "description": "The count of media units in the segment (not media file). The count could be less than expected given the segment duration is there are gaps.",
+      "description": "The count of media units in the segment (which may be fewer than in the object). The count could be less than expected given the segment duration and rate if there are gaps. If not set, every sample in the object is used",
       "type": "integer"
     },
     "get_url": {