Quickstart¶
This is for users who wish to get started using the “OTIOView” application to inspect the contents of editorial timelines.
Note This guide assumes that you are working inside a virtualenv.
Install Prerequisites¶
OTIOView has an additional prerequisite to OTIO:
Try
python -m pip install PySide2
orpython -m pip install PySide6
If difficulties are encountered, please file an issue on OpenTimelineIO’s github for assistance.
Install OTIO¶
python -m pip install opentimelineio
Setup Any Additional Adapters You May Want¶
A default OTIO installation includes only the “Core” adapters, which include the native OTIO JSON format (.otio
), OpenTimelineIO directory bundles (.otiod
), and OpenTimelineIO ZIP bundles (.otiod
).
A curated list of adapters for popular file formats like EDL, AAF, ALE, and FCP XML can be installed using the OpenTimelineIO Plugins package in PyPI. These plugins can also be individually installed from their PyPI packages.
For mor information, see the Adapters section.
Run OTIOView¶
Once you have pip installed OpenTimelineIO, you should be able to run:
otioview path/to/your/file.edl
Developer Quickstart¶
Get the source and submodules:
git clone git@github.com:AcademySoftwareFoundation/OpenTimelineIO.git
Before reading further, it is good to note that there is two parts to the C++ code: the OTIO C++ library that you can use in your C++ projects, and the C++ Python bindings that makes the C++ library available in Python.
To build OTIO for C++ development:¶
Linux/Mac¶
mkdir build
cd build
cmake .. { options }
make install
Windows - in an “x64 Native Tools Command Prompt” for Visual Studio¶
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX={path/to/install/location} { options }
cmake --build . --target install --config Release
The CMAKE_INSTALL_PREFIX
variable must be set to a path with no spaces in it,
because CMake’s default install location is in C:\Program Files
, which won’t work
with OpenTimelineIO due to spaces in the path.
To build OTIO for Python development:¶
python -m pip install -e .
To build OTIO for both C++ and Python development:¶
The Python package is a mix of pure python and C++ code. Therefore, it is
recommended to use the python tooling (python -m pip
) to develop both
the C++ binding and the pure python code. We use setuptools
as our
python build backend, which means pip
will call the setup.py
in the root
of the directory to build both the pure python and the C++ bindings.
setuptools
will take care of all the complexity of building a C++ Python
extension for you.
The first time setup.py
is run, cmake scripts will be created, and the headers
and libraries will be installed where you specify. If the C++ or Python sources
are subsequently modified, running this command again will build and update everything
appropriately.
Note Any CMake arguments can be passed through pip
by using the CMAKE_ARGS
environment variable when building from source. *nix Example:
env CMAKE_ARGS="-DCMAKE_VAR=VALUE1 -DCMAKE_VAR_2=VALUE2" python -m pip install .
python -m pip install .
adds some overhead that might be annoying or unwanted when
developing the python bindings. For that reason (and only that reason), if you want a faster
iteration process, you can use setuptools
commands. For example you can use
python setup.py build_ext
to only run the compilation step. Be aware that calling setup.py
directly is highly discouraged and should only be used when no of the other options
are viable. See https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html.
To compile your own C++ file referencing the OTIO headers from your C++ build using gcc or clang, add the following -I flags:
c++ -c source.cpp -I/home/someone/cxx-otio-root/include -I/home/someone/cxx-otio-root/include/opentimelineio/deps
To link your own program against your OTIO build using gcc or clang, add the following -L/-l flags:
c++ ... -L/home/someone/cxx-otio-root/lib -lopentimelineio
To use opentime without opentimelineio, link with -lopentime instead, and compile with:
c++ -c source.cpp -I/home/someone/cxx-otio-root/include
Debugging Quickstart¶
Linux / GDB / LLDB¶
To compile in debug mode, set the OTIO_CXX_DEBUG_BUILD
environment variable to any value
and then python -m pip install
.
You can then attach GDB to python and run your program:
gdb --args python script_you_want_to_debug.py
Or LLDB:
lldb -- python script_you_want_to_debug.py
One handy tip is that you can trigger a breakpoint in gdb by inserting a SIGINT:
#include <csignal>
// ...
std::raise(SIGINT);
GDB will automatically break when it hits the SIGINT line.
How to Generate the C++ Documentation:¶
Mac / Linux¶
The doxygen docs can be generated with the following commands:
cd doxygen ; doxygen config/dox_config ; cd ..
Another option is to trigger the make target:
make doc-cpp