AcademySoftwareFoundation / AcademySoftwareFoundation/OpenTimelineIO

Confusing Example in file format metadata docs

Open
#1,684 0 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 [metadata section](https://opentimelineio.readthedocs.io/en/stable/tutorials/otio-file-format-specification.html?highlight=file%20format%20specification#metadata) of the readthedocs file format specification, the example timeline is a bit odd because it starts with a transition that has an `in_offset` of `10/24` but there is no item before that transition to transition from. Similarly, the last item is a transition with an `out_offset` of `10/24` but there is no item after to transition to.

These are probably semantically invalid and should either:

- Have a gap or black generator clip before/after to fill at least the in/out offset durations
- Set the in/out offset durations to 0

## Additional Questions

If you do have a transition with a zero in offset at the head of a timeline - what is the source media for the A side of the transition? Is it presumed to be transparent for video and silence for audio?

Contributor guide

Open the contributing guide

Research direction

Open the metadata section of the linked Read the Docs file format specification and inspect the example timeline. Update the example so its transition offsets are semantically valid, and clarify the zero-in-offset behavior; done means the example and boundary-transition semantics are unambiguous.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.