AcademySoftwareFoundation / AcademySoftwareFoundation/OpenTimelineIO
Common Edit Command Library
- Dominant language
- C++
- Stars
- 2k
- Forks
- 351
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 1
Description
### Overview
The industry is full of timeline management software but nearly all of them include a fundamental set of tools for manipulation. The most well known being:
- Overwrite
- Trim
- Cut
- Slip
- Slide
- Ripple
- Roll
- Fill (3/4 Point Edit)
OpenTimelineIO, while not seeking to become a fully realized NLE, could benefit from having a simple toolkit to help automate building/modifying timelines based on time rather than index alone.
### Proposal
For editing commands, we should strive to do all validation and assert that everything works before committing anything on the timeline. I'm proposing the `EditEvent` which might something like:
```cpp
class EditEvent {
public:
EditEventKind kind; // e.g. Insert, Append, Remove, Modify
Retainer parent;
Retainer composable;
// ... Additional fields to execute the above as required
bool run(ErrorStatus* error_status);
bool revert();
};
```
An event is atomic in nature and does "one thing" to a `Composable`. Each edit maneuver (e.g. `otio.edit.place(...)`) would generate a vector of these events that can be played forward and, possibly, backward. The result of them collectively is the commands result.
```cpp
for (EditEvent &event: events) {
event.run(error_status);
if (*error_status) {
for (auto it = completed_events.rbegin(); /*...*/)
(*it).revert();
break;
}
completed_events.push_back(event);
}
```
Alternatively, we could build a more robust transaction system since all items can be cloned but there are memory considerations for that and beyond the scope of this initial proposal.
### API
The API might look like:
```
otio.edit.place(item, into=track, at=rat_time, placement_kind=otio.edit.PlacementKind)
otio.edit.trim(item, edge=otio.edit.ItemEdge)
etc.
```
Additional commands can be added as the editing foundation is built.
### Pros:
- Atomic events make reuse simple and should scale well with the complexity of edit commands
- Hooks up nicely to an undo/redo framework on third party software
### Cons:
- Additional code to handle event care
### Questions/Considerations:
- Could we handle `preview` flags for edit commands? This would let third party tools inspect the outcome of events before committing them.
- Should `EditEvent` be a class system (e.g. `InsertEvent`, `ModifyEvent`) or something else entirely?
Contributor guide
Research direction
The issue names no implementation files or tests. Start by turning the proposed EditEvent and otio.edit.place/trim API into a scoped design, resolving event types, rollback, and preview behavior. Done requires an agreed, bounded command set and a maintainer-approved implementation plan.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100