AcademySoftwareFoundation / AcademySoftwareFoundation/OpenTimelineIO

What does `null` available_range mean?

Open
#1,665 10 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
C++
Stars
2k
Forks
351
Avg merge
1d 12h
Merged PRs (30d)
1

Description

In the OTIO documentation, [here](https://opentimelineio.readthedocs.io/en/stable/tutorials/time-ranges.html), it says that a Clip or MediaReference available_range may be `null` when the available range of media is not known. However, it doesn't explain how that actually works in practice. Specifically how does such a clip align if it has (or doesn't have) embedded timecode in the media file? Related to this, what happens when embedded timecode differs from the available_range value in a MediaReference.

We have a real world case of this in the DPEL [ALab Trailer OTIO](https://dpel.aswf.io/alab-trailer/) asset.

Here are specifics from @darbyjohnston (thanks!)

The ALab .otio file has audio references that do not specify an "available_range":
```
"media_references": {
"DEFAULT_MEDIA": {
"OTIO_SCHEMA": "ExternalReference.1",
"metadata": {},
"name": "",
"available_range": null,
"available_image_bounds": null,
"target_url": "ALab_WAVs/mk020_sfx.wav"
}
}
```

and clips with source_range starting at 0:
```
{
"OTIO_SCHEMA": "Clip.2",
...
"name": "mk020_sfx",
"source_range": {
"OTIO_SCHEMA": "TimeRange.1",
"duration": {
"OTIO_SCHEMA": "RationalTime.1",
"rate": 24.0,
"value": 2483.0
},
"start_time": {
"OTIO_SCHEMA": "RationalTime.1",
"rate": 24.0,
"value": 0.0
}
},
...
}
```

However the referenced .wav files have start times specified in samples, for example here is the output from ffprobe:
```
Input #0, wav, from 'ALab_WAVs/mk020_sfx.wav':
Metadata:
comment : vFRAMERATE=24.000
: vSPEED=24.000
: vNOTE=mk020_sfx.wav
encoded_by : Media Composer 21.12.1.55644
originator_reference: 000000000000002a66f0b88799059884
date : 2022-10-31
creation_time : 23:03:19
time_reference : 172800000
```
172800000 / 48000 = 3600 seconds for a start time of 01:00:00:00.

So the specific issue here is that we need to clearly document how this case is handled, and possibly update the ALab example asset to conform to that.

Contributor guide

Open the contributing guide

Research direction

Start with the OTIO time-ranges documentation and inspect the referenced ALab Trailer .otio asset alongside the example .wav metadata and ffprobe output. Trace how null available_range, source_range, and embedded time references are interpreted, then document the behavior for each case and state whether the ALab asset needs updating.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.