diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..2a6df3209d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,21 @@ +Welcome to OpenTimelineIO's documentation! +================================================== + +Overview +-------- + +OpenTimelineIO (OTIO) is an API and interchange format for editorial cut information. You can think +of it as a modern Edit Decision List (EDL) that also includes an API for reading, writing, and +manipulating editorial data. It also includes a plugin system for translating to/from existing +editorial formats as well as a plugin system for linking to proprietary media storage schemas. + +OTIO supports clips, timing, tracks, transitions, markers, metadata, etc. but not embedded video or +audio. Video and audio media are referenced externally. We encourage 3rd party vendors, animation +studios and visual effects studios to work together as a community to provide adaptors for each +video editing tool and pipeline. + +Links +--------- +[OpenTimelineIO Home Page](http://opentimeline.io/) + +[OpenTimelineIO Discussion Group](https://lists.aswf.io/g/otio-discussion) diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index efaaf3a98d..0000000000 --- a/docs/index.rst +++ /dev/null @@ -1,100 +0,0 @@ -Welcome to OpenTimelineIO's documentation! -================================================== - -Overview --------- - -OpenTimelineIO (OTIO) is an API and interchange format for editorial cut information. You can think -of it as a modern Edit Decision List (EDL) that also includes an API for reading, writing, and -manipulating editorial data. It also includes a plugin system for translating to/from existing -editorial formats as well as a plugin system for linking to proprietary media storage schemas. - -OTIO supports clips, timing, tracks, transitions, markers, metadata, etc. but not embedded video or -audio. Video and audio media are referenced externally. We encourage 3rd party vendors, animation -studios and visual effects studios to work together as a community to provide adaptors for each -video editing tool and pipeline. - -Links ---------- -`OpenTimelineIO Home Page `_ - -`OpenTimelineIO Discussion Group `_ - -Quick Start ------------- -.. toctree:: - :maxdepth: 2 - - tutorials/quickstart - tutorials/otio-env-variables - -Tutorials ------------- -.. toctree:: - :maxdepth: 2 - - tutorials/adapters - tutorials/architecture - tutorials/contributing - tutorials/feature-matrix - tutorials/otio-timeline-structure - tutorials/time-ranges - tutorials/otio-filebundles - tutorials/write-an-adapter - tutorials/write-a-media-linker - tutorials/write-a-hookscript - tutorials/write-a-schemadef - tutorials/versioning-schemas - -Use Cases ------------- -.. toctree:: - :maxdepth: 2 - - use-cases/animation-shot-frame-ranges - use-cases/conform-new-renders-into-cut - use-cases/shots-added-removed-from-cut - -API Reference -------------- - -.. toctree:: - :maxdepth: 2 - - api/modules/opentimelineio - -C++ Implementation Reference ----------------------------- - -.. toctree:: - :maxdepth: 2 - - cxx/bridges.md - cxx/cxx.md - cxx/older.md - -Schema Reference ----------------- - -.. toctree:: - :maxdepth: 2 - - tutorials/otio-file-format-specification - tutorials/otio-serialized-schema - tutorials/otio-serialized-schema-only-fields - -Autogenerated Plugin Reference ------------------------------- - -.. toctree:: - :maxdepth: 2 - - tutorials/otio-plugins.md - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/tutorials/architecture.md b/docs/tutorials/architecture.md index 4970648230..d4f228d6eb 100644 --- a/docs/tutorials/architecture.md +++ b/docs/tutorials/architecture.md @@ -5,8 +5,26 @@ Overview OpenTimelineIO is an open source library for the interchange of editorial information. This document describes the structure of the python library. -To import the library into python: -`import opentimelineio as otio` +You can import the library using the following: + +=== " :fontawesome-brands-python: python" + + ``` python + import opentimelineio as otio + ``` + +=== " C++" + + ``` c++ + #include + + // This allows using otio:: instead of the long fully qualified namespace + namespace otio = opentimelineio::OPENTIMELINEIO_VERSION; + ``` + + !!! warning + The `opentimelineio.h` header doesn't actually exist, you'll use + the specific headers you need in your code. Canonical Structure -------------------- @@ -39,30 +57,58 @@ The `otio.schema.Clip` objects can reference media through a `otio.schema.Extern Schema composition objects (`otio.schema.Stack` and `otio.schema.Track`) implement the python mutable sequence API. A simple script that prints out each shot might look like: +=== "python" -```python -import opentimelineio as otio + ```python + import opentimelineio as otio -# read the timeline into memory -tl = otio.adapters.read_from_file("my_file.otio") + # read the timeline into memory + tl = otio.adapters.read_from_file("my_file.otio") -for each_seq in tl.tracks: - for each_item in each_seq: - if isinstance(each_item, otio.schema.Clip): - print each_item.media_reference -``` + for each_seq in tl.tracks: + for each_item in each_seq: + if isinstance(each_item, otio.schema.Clip): + print each_item.media_reference + ``` -Or, in the case of a nested composition, like this: +=== "C++" -```python -import opentimelineio as otio + ``` c++ + #include + #include + #include -# read the timeline into memory -tl = otio.adapters.read_from_file("my_file.otio") + #include -for clip in tl.each_clip(): - print clip.media_reference -``` + namespace otio = opentimelineio::OPENTIMELINEIO_VERSION; + + otio::ErrorStatus error_status; + otio::SerializableObject::Retainer timeline( + dynamic_cast(otio::Timeline::from_json_file("my_file.otio", &error_status))); + if (!timeline || otio::is_error(error_status)) + { + + std::cout << "error reading timeline"; + exit(1); + } + otio::ErrorStatus error_status; + const auto clips = timeline->clip_if(&error_status); + if (otio::is_error(error_status)) + { + std::cout << "error iterating clips"; + exit(1); + } + + for (const otio::SerializableObject::Retainer& clip : clips) + { + // This doesn't work, just an example + cout << clip->media_reference(); + } + + ``` + +!!! note + Custom schema can also be implemented, for more information look [here](about:blank). ## Time on otio.schema.Clip diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..b8700059b5 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,32 @@ +site_name: OpenTimelineIO +site_url: http://opentimeline.io +repo_url: http://github.com/PixarAnimationStudios/OpenTimelineIO +edit_uri: edit/main/docs +repo_name: Edit on GitHub + +markdown_extensions: + - toc: + permalink: true + - attr_list + - admonition + - codehilite + - pymdownx.details + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + +theme: + name: material + features: + - navigation.instant + - navigation.sections + - navigation.tracking + - navigation.tabs + - content.tabs.link