Skip to content

Commit 893daf0

Browse files
j616j616
committed
Add ADR0045 on Flow init segment support
1 parent e27248f commit 893daf0

2 files changed

Lines changed: 136 additions & 0 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,5 +80,6 @@ For more information on how we use ADRs, see [here](./adr/README.md).
8080
| [0041](./adr/0041-require-explicit-framerate.md) | Requiring explicit frame rates |
8181
| [0042](./adr/0042-uncontrolled-object-instance-labels.md) | Make `label` Mandatory for Uncontrolled Object Instances |
8282
| [0043](./adr/0043-signalling-retention-time.md) | Signalling retention time |
83+
| [0045](./adr/0045-flow-init-segments.md) | Support for init Segments in Flows |
8384

8485
\* Note: ADR 0004a was the unintended result of a number clash in the early development of TAMS which wasn't caught before publication

‎docs/adr/0045-flow-init-segments.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
status: "proposed"
3+
---
4+
# Support for init Segments in Flows
5+
6+
## Context and Problem Statement
7+
8+
Various media formats employ initialisation segments (aka init segments) for communicating parameters required to configure decoders.
9+
Notably, CMAF-compatible formats such as MPEG DASH and Fragmented MP4 (fMP4).
10+
Init segments are normally communicated via a manifest, alongside media segments.
11+
The decoder will fetch and process the init segment, before identifying the required media segments (which may be mid-stream) and fetching and processing those.
12+
13+
From a TAMS perspective, init segments are not normally associated with any particular point of time.
14+
A client must be able to write/read, or construct, an init segment independently of the timeline.
15+
16+
## Decision Drivers
17+
18+
We would like to:
19+
20+
* support TAMS features (e.g. edit-by-reference) as fully as possible
21+
* be compatible with as many decoders/players as possible
22+
* place as little burden on implementations as possible with TAMS-specific functionality
23+
* have no/minimal impact on existing (non-init segment based) implementations
24+
* re-use existing patterns/functionality where possible/practical
25+
* allow the use of existing init segment extensions (e.g. C2PA)
26+
* avoid specifying Flow parameters that are format-specific
27+
28+
## Considered Options
29+
30+
* {title of option 1}
31+
* {title of option 2}
32+
* {title of option 3}
33+
* … <!-- numbers of options can vary -->
34+
35+
## Decision Outcome
36+
37+
Chosen option: "{title of option 1}", because
38+
{Justification, e.g., only option which resolves requirements, or comes out best (see below)}.
39+
40+
<!-- This is an optional element. Feel free to remove. -->
41+
### Implementation
42+
43+
{Once the proposal has been implemented, add a link to the relevant PRs here}
44+
45+
<!-- This is an optional element. Feel free to remove. -->
46+
## Pros and Cons of the Options
47+
48+
### Option 1: Generate init segments from essence parameters
49+
50+
This option would see reading clients (or the store) generate their own init segments based on the existing technical metadata in the Flow metadata.
51+
This is likely not possible with TAMS currently.
52+
The TAMS API likely does not capture all metadata media formats may need to include in init segments.
53+
54+
* Good, because it requires no changes to the API specification
55+
* Bad, because initial research indicates this will not be possible due to missing metadata
56+
* Bad, because it requires a potentially complex implementation that requires in-depth knowledge of the structure of init segments and significant domain expertise
57+
58+
### Option 2: Significantly expand essence parameters to fully capture everything
59+
60+
This option would see Option 1 extended to include the addition of required parameters to Flow metadata.
61+
62+
* Bad, because it will likely require significant additions to Flow technical metadata
63+
* Bad, because it will likely require the addition of format specific parameters to Flow technical metadata
64+
* Bad, because it requires a potentially complex implementation that requires in-depth knowledge of the structure of init segments and significant domain expertise
65+
66+
### Option 3: Create a Flow Segment with a never timerange for the init segment
67+
68+
The TAMS TimeRange format has a special "never" value - `()`.
69+
This currently has no meaning for Flow Segments, as media segments always have a duration.
70+
Init segments can be considered to have no duration.
71+
This option would see the never TimeRange used to represent init segments.
72+
73+
* Good, because it requires little/no spec changes
74+
* Good, because it doesn't require format-specific Flow parameters
75+
* Neutral, because it doesn't allow for different init segments for different parts of the Flow
76+
* Note: It is not clear we have a real use case for this as a new init segment likely means a change to the technical parameters, which requires a new Flow in TAMS
77+
* Initial testing indicates common fMP4/DASH players do not support multiple init segments
78+
* Bad, because the approach is somewhat unintuitive
79+
* Bad, because it may result in unexpected behaviour with existing TAMS implementations
80+
81+
### Option 4: Make the init segment a Flow-level property for which a URL can be generated
82+
83+
This option would see the init segment managed via the existing Object CRUD mechanisms.
84+
But rather than being registered against a Flow Segment, it would be registered against a new Flow property.
85+
Existing Object patterns would be used for upload, URL generation, re-use, delete, etc.
86+
Like Flow Segments, different Flows could re-use the same init Object.
87+
Implementations might use the init segment's Object ID to determine the compatibility of Flow Segments in edit-by-reference workflows.
88+
89+
* Good, because it doesn't require format-specific Flow parameters
90+
* Good, because it re-uses existing patterns/mechanisms
91+
* Neutral, because it doesn't allow for different init segments for different parts of the Flow
92+
* Note: It is not clear we have a real use case for this as a new init segment likely means a change to the technical parameters, which requires a new Flow in TAMS
93+
* Initial testing indicates common fMP4/DASH players do not support multiple init segments
94+
* Netural, because it requires a backwards-compatible addition to the spec
95+
96+
### Option 5: Make the init segment an object-level property, which can be uploaded and have a URL generated
97+
98+
As with Option 4, this option would see the init segment managed via the existing Object CRUD mechanisms.
99+
Rather than associating the init Object with the Flow, this option would see it associated with each Media Object.
100+
A change in the init segment's Object ID may be used to determine a need to re-provision the init segment in the consuming client.
101+
102+
* Good, because it doesn't require format-specific Flow parameters
103+
* Good, because it re-uses existing patterns/mechanisms
104+
* Neutral, because it allows for different init segments for different parts of the Flow
105+
* Note: It is not clear we have a real use case for this as a new init segment likely means a change to the technical parameters, which requires a new Flow in TAMS
106+
* Initial testing indicates common fMP4/DASH players do not support multiple init segments
107+
* Netural, because it requires a backwards-compatible addition to the spec
108+
* Bad, because it will result in a significant increase in Object metadata which makes up a large proportion of data stored in TAMS
109+
110+
### Option 6: Have a Flow that is the init segment Flow
111+
112+
This option would see a new init segment Flow type.
113+
An init Flow would be associated with the media Flow.
114+
Init segments would be assigned the TimeRange over which they are valid in the associated media Flow.
115+
This would allow for multiple init segments to be applied to different parts of the media Flow's timeline.
116+
117+
* Good, because it doesn't require format-specific Flow parameters
118+
* Good, because it re-uses existing patterns/mechanisms
119+
* Neutral, because it allows for different init segments for different parts of the Flow
120+
* Note: It is not clear we have a real use case for this as a new init segment likely means a change to the technical parameters, which requires a new Flow in TAMS
121+
* Initial testing indicates common fMP4/DASH players do not support multiple init segments
122+
* Netural, because it requires a backwards-compatible addition to the spec
123+
* Neutral, because it may be unintuitive
124+
* Neutral, because it would require open-ended Flow Segments to support live Flows
125+
126+
### Option 7: Put the init segment somewhere on the TAMS API instead of as an object (e.g. as a base64 blob)
127+
128+
As with Options 4, 5, or 6.
129+
But the init segment would be stored as a base 64 encoded blob (or similar) that may be held in the backend database, instead of as file stored in an object store.
130+
131+
In addition to the base options:
132+
133+
* Bad, because it would represent a new pattern where one isn't strictly required
134+
* Bad, because it would require a different GET path to media segments
135+
* Bad, because it would likely require additional work on the part of clients to construct a virtual file for the init segment to pass to decoders/players

0 commit comments

Comments
 (0)