Using flow segment timeranges and related spec updates #97
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Define it as a difference between the exclusive end and the last sample timestamp.
Be specific about when the timerange uses an exclusive (samples have duration) or inclusive end (samples don't have a duration).
E.g. for 48kHz audio samples with an exclusive timerange end.
philipnbbc
force-pushed
the
philipn-flow-segment-timeranges
branch
from
4c18ac9 to
8d88b77
Compare
samdbmg
approved these changes
Dec 13, 2024
| @@ -16,11 +16,11 @@ | |||
| "$ref": "timestamp.json" | |||
| }, | |||
| "timerange": { | |||
| "description": "The timerange from the first sample in the segment to the last, with an inclusive start and inclusive or exclusive end, as described by the [TimeRange](../schemas/timerange#top) type. Note that where temporal re-ordering is used, this refers to the presentation timeline.", | |||
| "description": "The timerange for the samples contained in the segment. If samples have a duration then the timerange end is exclusive and covers at least the duration of the last sample. The exclusive timerange end will typically be set to the timestamp of the next sample. If the samples don't have a duration then the timerange end is inclusive. Format is described by the [TimeRange](../schemas/timerange#top) type. Note that where temporal re-ordering is used, the timerange and samples refers to the presentation timeline.", | |||
There was a problem hiding this comment.
Should the timerange start still be inclusive, as stipulated originally?
| @@ -0,0 +1,144 @@ | |||
| # Using Flow Segment Timeranges | |||
|
|
|||
| This application note explains the usage of the Flow Segment `timerange` property, starting with a short primer on Timestamps and Timeranges. | |||
There was a problem hiding this comment.
A cross link to app note 8 might be useful here, inviting the reader to review the details of the representation there, and the usage here
| A sample is a frame of video, a sample of audio or a data item like a subtitle. | ||
|
|
||
| A sample Timestamp is an approximation of the time a sample is "active" on the Timeline. | ||
| The sample Timestamps may simply represent the order of samples on the Timeline and may not be an accurate representation of the time the sample was captured or presented. |
There was a problem hiding this comment.
Nit: Is there a way to make this more practical: because I think in most of our trials we've accepted this inaccuracy as being "close enough"
Suggested change
| The sample Timestamps may simply represent the order of samples on the Timeline and may not be an accurate representation of the time the sample was captured or presented. | |
| The sample Timestamps may simply represent the order of samples on the Timeline and may not be an accurate representation of the time the sample was captured or presented. | |
| However in many cases it is sufficient to assume the sample Timestamp accurately represents when the sample should be presented, and that the inherent inaccuracy was reduced to acceptable levels during the capture process. |
|
|
||
| A Timestamp does not specify the sample duration on the timeline. | ||
|
|
||
| ### What is a Timerange |
There was a problem hiding this comment.
Nit: In the mediatimestamp library and in https://github.com/bbc/tams/blob/main/api/schemas/timerange.json#L2 this is styled as "TimeRange" when capitalised (or "timerange" otherwise). Should the same style be used here?
| Note that a Flow Segment can have gaps within it and creators of Flow Segments need to decide whether a gap at the end of a Flow Segment need to be included or exposed. | ||
|
|
||
| Including the gap in the Flow Segment means extending the `timerange` to the next Flow Segment's first sample Timestamp. | ||
| The `last_duration` is set to the difference between the `timerange` end and the last sample Timestamp. |
There was a problem hiding this comment.
Nit: Consider adding an example of why you'd do this
Suggested change
| The `last_duration` is set to the difference between the `timerange` end and the last sample Timestamp. | |
| The `last_duration` is set to the difference between the `timerange` end and the last sample Timestamp. | |
| This may, for example, indicate that the gap represents a meaningful gap in the content (instead of content that was lost in transmission). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Details
This PR adds an Application Note that describes the use of the Flow Segment
timerangeproperty. The PR also updates the definitions of the Flow Segmenttimerangeandlast_durationproperties.Pivotal Story (if relevant)
Story URL: https://www.pivotaltracker.com/story/show/188581560
Related PRs
Where appropriate. Indicate order to be merged.
Submitter PR Checks
(tick as appropriate)
Reviewer PR Checks
(tick as appropriate)
Info on PRs
The checks above are guidelines. They don't all have to be ticked, but they should all have been considered.