diff --git a/README.md b/README.md index e6c534006..bf124b28b 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,17 @@ -# Welcome to xSTUDIO - v1.1.0 +# Welcome to xSTUDIO 1.1.0 xSTUDIO is a media playback and review application designed for professionals working in the film and TV post production industries, particularly the Visual Effects and Feature Animation sectors. xSTUDIO is focused on providing an intuitive, easy to use interface with a high performance playback engine at its core and C++ and Python APIs for pipeline integration and customisation for total flexibility. -This codebase will build version 1.0.0 (alpha) of xstudio. There are some known issues that are currently being worked on: +This repository builds xSTUDIO `v1.1.0`. The top-level documentation has been refreshed to match the current source tree and is split between the user guide in `docs/user_docs` and the developer reference in `docs/reference`. + +There are still some known issues that are currently being worked on: * Moderate audio distortion on playback (Windows only) -* Ueser Documentation and API Documentation is badly out-of-date. * Saved sessions might not restore media correctly (Windows only) ## Building xSTUDIO -This release of xSTUDIO can be built on various Linux flavours, Microsoft Windows and MacOS. We provide comprehensive build steps here. +This release of xSTUDIO can be built on various Linux distributions, Microsoft Windows, and macOS. We provide comprehensive build steps here. ### Building xSTUDIO for Linux @@ -23,10 +24,10 @@ This release of xSTUDIO can be built on various Linux flavours, Microsoft Window * [Windows](docs/reference/build_guides/windows.md) -### Building xSTUDIO for MacOS +### Building xSTUDIO for macOS -* [MacOS](docs/reference/build_guides/macos.md) +* [macOS](docs/reference/build_guides/macos.md) -### Documentation Note +### Documentation -Note that the xSTUDIO user guide is built with Sphinx using the Read-The-Docs theme. The package dependencies for building the docs can be challenging to install so we instead include the fully built docs as part of xSTUDIO's repo, as well as the source for building the docs. Our build set-up by default disables the building of the docs to make life easy! +xSTUDIO's documentation is built with Sphinx and Doxygen. The source lives under `docs/`, with end-user workflows in `docs/user_docs` and build/API reference material in `docs/reference`. The standard build keeps documentation disabled by default; enable it with `-DBUILD_DOCS=ON` if you want to generate the HTML site locally. diff --git a/docs/index.rst b/docs/index.rst index 21365530c..912038b19 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +3,18 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to xSTUDIO's documentation! -=================================== +Welcome to xSTUDIO 1.1.0 +======================== + +xSTUDIO is a playback, review, and pipeline-integration application for VFX, +animation, and post-production workflows. + +This documentation set is split into two parts: + +* :ref:`user_docs` for day-to-day playback, review, timeline, and note-taking + workflows. +* :ref:`reference_docs` for build instructions plus the C++ and Python API + surfaces exposed by the current source tree. | | @@ -30,4 +40,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/reference/api/index.rst b/docs/reference/api/index.rst index 8194495a3..7e512327a 100644 --- a/docs/reference/api/index.rst +++ b/docs/reference/api/index.rst @@ -1,17 +1,19 @@ .. _api_: -.. note:: - August 2025: The C++ API documentation is WIP. For developers interested in developing C++ we encourage you to look over the source code of xSTUDIO's native plugins. These are to be found inside the **src/plugin** folder from the root of the xSTUDIO source repo. +C++ API +======== - Many of xSTUDIO's important features have been implemented as plugins. Primarily this approach was taken to ensure that xSTUDIO can be expanded and modified in the future without needing to re-work core components of the source code. In addition this both ensures that the C++ plugin API is well-developed and flexible and also provides a rich set of reference implementations for new developers to begin working from for their own projects. +The C++ side of xSTUDIO is structured around public headers and plugin +extension points. The generated API pages below focus on the headers that +define the current plugin surface and shared utility types. - Nevertheless, we will strive to improve the API Class documentation here over the coming months. +For concrete implementations, inspect the matching source under `src/plugin` +alongside the header docs. -API -=== .. toctree:: :maxdepth: 2 + overview plugin utility enums diff --git a/docs/reference/api/overview.rst b/docs/reference/api/overview.rst new file mode 100644 index 000000000..8b34a9c4b --- /dev/null +++ b/docs/reference/api/overview.rst @@ -0,0 +1,51 @@ +.. _api_overview: + +C++ API Overview +================ + +xSTUDIO's C++ API is plugin-first. The public headers in `include/xstudio` +define the core extension points, while concrete examples live in `src/plugin`. + +What This Reference Covers +-------------------------- + +The pages in this section expose the public headers that are most useful when +extending xSTUDIO: + +* `plugin_manager/plugin_base.hpp` for `StandardPlugin` and viewport-related + hooks. +* `ui/viewport/video_output_plugin.hpp` for off-screen render and video-output + integrations. +* `colour_pipeline/colour_pipeline.hpp` for display and colour-management + plugins. +* `ui/viewport/viewport_layout_plugin.hpp` and + `plugin_manager/hud_plugin.hpp` for compare layouts and HUD or overlay + plugins. +* `data_source/data_source.hpp`, `media_reader/media_reader.hpp`, + `media_metadata/media_metadata.hpp`, and `media_hook/media_hook.hpp` for + ingest and metadata customization. +* `utility/*.hpp` for the shared value types, JSON helpers, frame and timecode + types, UUID helpers, and other support classes used throughout the API. + +Reference Implementations +------------------------- + +The fastest way to understand the API is usually to read the shipped plugins +alongside the header docs: + +* `src/plugin/colour_pipeline/ocio` shows the built-in OCIO integration. +* `src/plugin/viewport_layout/*` contains the default, grid, composite, and + wipe layout implementations. +* `src/plugin/hud/*` contains concrete HUD overlays such as pixel probe and EXR + data window. +* `src/plugin/media_reader/*` and `src/plugin/media_metadata/*` contain file + format readers and metadata readers. +* `src/plugin/data_source/*` contains data-source integrations, including the + DNEG-specific examples. + +Reading Strategy +---------------- + +If you are new to the codebase, start with `StandardPlugin`, then move to the +specific plugin type you need. After that, inspect the matching implementation +under `src/plugin` and the relevant utility headers used by that plugin. diff --git a/docs/reference/api/plugin.rst b/docs/reference/api/plugin.rst index ba0da0c1e..bd338e9bc 100644 --- a/docs/reference/api/plugin.rst +++ b/docs/reference/api/plugin.rst @@ -5,6 +5,16 @@ StandardPlugin .. doxygenfile:: plugin_manager/plugin_base.hpp :project: xStudio +HUDPluginBase +============= +.. doxygenfile:: plugin_manager/hud_plugin.hpp + :project: xStudio + +ViewportLayoutPlugin +==================== +.. doxygenfile:: ui/viewport/viewport_layout_plugin.hpp + :project: xStudio + VideoOutputPlugin ================= .. doxygenfile:: ui/viewport/video_output_plugin.hpp @@ -14,3 +24,23 @@ ColourPipelinePlugin ==================== .. doxygenfile:: colour_pipeline/colour_pipeline.hpp :project: xStudio + +DataSourcePlugin +================ +.. doxygenfile:: data_source/data_source.hpp + :project: xStudio + +MediaReaderPlugin +================= +.. doxygenfile:: media_reader/media_reader.hpp + :project: xStudio + +MediaMetadataPlugin +=================== +.. doxygenfile:: media_metadata/media_metadata.hpp + :project: xStudio + +MediaHookPlugin +=============== +.. doxygenfile:: media_hook/media_hook.hpp + :project: xStudio diff --git a/docs/reference/build_guides/index.rst b/docs/reference/build_guides/index.rst index 0d28b364c..854423012 100644 --- a/docs/reference/build_guides/index.rst +++ b/docs/reference/build_guides/index.rst @@ -4,12 +4,19 @@ xSTUDIO Build Guides #################### -At the time of writing these notes (August 2025) xSTUDIO is publically available as *source code* only and as such, to obtain the application, it must be built from the source. +xSTUDIO is currently distributed from source in this repository, so building +from source is the standard way to obtain the application. Post Production Studios and Other Organisations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Many VFX and Animation studios, especially larger ones, typically have technical teams who have expertise in building software from source code. For such teams with expertise in building and deploying software packages we expect that building xstudio should be straightforward. The build guides below should provide valuable reference. Note that version 1.X of xSTUDIO has been developed against the VFX Reference Platform 2024 standard plus a small set of open source packages/libraries that are easily obtained or built on any platform. A :ref:`list of these build dependencies ` is provided for your convenience. +Many VFX and animation studios, especially larger ones, typically have +technical teams with experience building software from source. For those teams, +the guides below should provide a practical reference. xSTUDIO 1.1.x is +developed against the VFX Reference Platform 2024 plus a small set of open +source packages and libraries that are easily obtained or built on any +platform. A :ref:`list of these build dependencies ` is provided +for convenience. Individual Users ^^^^^^^^^^^^^^^^ @@ -27,4 +34,4 @@ If you have any **questions** reach out on the ASWF Slack in the `#ori-xstudio-d rocky_linux_9_1 ubuntu_22_04 centos_7 - dependencies \ No newline at end of file + dependencies diff --git a/docs/reference/index.rst b/docs/reference/index.rst index c31c8fa64..0bd9714b5 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,8 +1,18 @@ -.. _python_api_: +.. _reference_docs: xSTUDIO Reference ================= +xSTUDIO's reference material is aimed at developers, technical directors, and +pipeline engineers. + +This section is split into three parts: + +* :ref:`build_guides` for platform-specific build and dependency notes. +* :ref:`api_` for the public C++ headers and plugin extension points. +* :ref:`python_api_` for the Python connection layer, session wrappers, and + plugin helpers shipped in `python/src/xstudio`. + .. toctree:: :maxdepth: 2 :glob: diff --git a/docs/reference/python_api/api.rst b/docs/reference/python_api/api.rst index b2103a703..e7baf5a42 100644 --- a/docs/reference/python_api/api.rst +++ b/docs/reference/python_api/api.rst @@ -3,176 +3,176 @@ xstudio.api *********** +High-Level Entry Points +======================= + API -=== +--- .. autoclass:: xstudio.api.API :members: - -app -=== - App --- .. autoclass:: xstudio.api.app.App :members: +Studio +------ +.. autoclass:: xstudio.api.studio.Studio + :members: -contact_sheet +Module System ============= -ContactSheet ------------- -.. autoclass:: xstudio.api.session.playlist.ContactSheet +ModuleAttribute +--------------- +.. autoclass:: xstudio.api.module.ModuleAttribute :members: +Module +------ +.. autoclass:: xstudio.api.module.ModuleBase + :members: -container -========= +Global Services +=============== -PlaylistItem ------------- -.. autoclass:: xstudio.api.session.container.PlaylistItem +GlobalStore +----------- +.. autoclass:: xstudio.api.intrinsic.GlobalStore :members: -PlaylistTree ------------- -.. autoclass:: xstudio.api.session.container.PlaylistTree +History +------- +.. autoclass:: xstudio.api.intrinsic.History :members: -Container ---------- -.. autoclass:: xstudio.api.session.Container +MediaCache +---------- +.. autoclass:: xstudio.api.intrinsic.MediaCache :members: +Thumbnail +--------- +.. autoclass:: xstudio.api.intrinsic.Thumbnail + :members: -global_store -============ +PluginManager +------------- +.. autoclass:: xstudio.api.intrinsic.PluginManager + :members: -GlobalStore ------------ -.. autoclass:: xstudio.api.intrinsic.GlobalStore +Scanner +------- +.. autoclass:: xstudio.api.intrinsic.Scanner :members: -helpers -======= +Viewport +-------- +.. autoclass:: xstudio.api.intrinsic.Viewport + :members: -.. automodule:: xstudio.api.auxiliary.helpers +ColourPipeline +-------------- +.. autoclass:: xstudio.api.intrinsic.ColourPipeline :members: +Session Graph +============= -json_store -========== +Session +------- +.. autoclass:: xstudio.api.session.Session + :members: -JsonStore +Container --------- -.. autoclass:: xstudio.api.auxiliary.json_store.JsonStore +.. autoclass:: xstudio.api.session.Container :members: - -media -===== - -Media ------ -.. autoclass:: xstudio.api.session.media.Media +PlaylistItem +------------ +.. autoclass:: xstudio.api.session.container.PlaylistItem :members: -media_source -============ - -MediaSource ------------ -.. autoclass:: xstudio.api.session.media.MediaSource +PlaylistTree +------------ +.. autoclass:: xstudio.api.session.container.PlaylistTree :members: -media_stream -============ - -MediaStream ------------ -.. autoclass:: xstudio.api.session.media.MediaStream +Playlist +-------- +.. autoclass:: xstudio.api.session.playlist.Playlist :members: -media_cache -============ - -MediaCache ------------ -.. autoclass:: xstudio.api.intrinsic.MediaCache +ContactSheet +------------ +.. autoclass:: xstudio.api.session.playlist.ContactSheet :members: -timeline -======== +Subset +------ +.. autoclass:: xstudio.api.session.playlist.Subset + :members: Timeline -------- .. autoclass:: xstudio.api.session.playlist.Timeline :members: -playhead -======== +Playback And Media +================== Playhead -------- .. autoclass:: xstudio.api.session.playhead.Playhead :members: -playhead_selection -================== - PlayheadSelection ----------------- -.. autoclass:: xstudio.api.session.playhead.playhead_selection.PlayheadSelection +.. autoclass:: xstudio.api.session.playhead.PlayheadSelection :members: -playlist -======== - -Playlist --------- -.. autoclass:: xstudio.api.session.playlist.Playlist +Media +----- +.. autoclass:: xstudio.api.session.media.Media :members: -session -======= - -Session -------- -.. autoclass:: xstudio.api.session.Session +MediaSource +----------- +.. autoclass:: xstudio.api.session.media.MediaSource :members: -studio -====== - -Studio ------- -.. autoclass:: xstudio.api.studio.Studio +MediaStream +----------- +.. autoclass:: xstudio.api.session.media.MediaStream :members: -subset -====== +Bookmarks And Notes +=================== -Subset ------- -.. autoclass:: xstudio.api.session.playlist.Subset +Bookmarks +--------- +.. autoclass:: xstudio.api.session.bookmark.Bookmarks :members: -module -====== +Bookmark +-------- +.. autoclass:: xstudio.api.session.bookmark.Bookmark + :members: -ModuleAttribute ---------------- -.. autoclass:: xstudio.api.module.ModuleAttribute +Note +---- +.. autoclass:: xstudio.api.session.bookmark.Note :members: -Module ------- -.. autoclass:: xstudio.api.module.ModuleBase +Annotation +---------- +.. autoclass:: xstudio.api.session.bookmark.Annotation :members: -plugin -====== +Plugin Authoring Helpers +======================== Plugin ------ @@ -189,5 +189,8 @@ ViewportLayoutPlugin .. autoclass:: xstudio.plugin.ViewportLayoutPlugin :members: +Helpers +======== - +.. automodule:: xstudio.api.auxiliary.helpers + :members: diff --git a/docs/reference/python_api/index.rst b/docs/reference/python_api/index.rst index 9043e846e..a6acd953d 100644 --- a/docs/reference/python_api/index.rst +++ b/docs/reference/python_api/index.rst @@ -3,11 +3,17 @@ Python API ========== -.. note:: - August 2025: The Python API documentation is currently WIP. There are plenty of method docstrings filled out but some methods and classes are lacking full desciptions. Please bear with the xSTUDIO developers as we improve these pages. +The Python package shipped with xSTUDIO supports remote control, embedded +scripting, session manipulation, playback control, and plugin development. + +Use the pages below as the entry point into the current Python surface shipped +under `python/src/xstudio`. .. toctree:: :maxdepth: 2 - :glob: - - * + overview + root + connection + api + core + demo diff --git a/docs/reference/python_api/overview.rst b/docs/reference/python_api/overview.rst new file mode 100644 index 000000000..a03bdf733 --- /dev/null +++ b/docs/reference/python_api/overview.rst @@ -0,0 +1,53 @@ +.. _python_api_overview: + +Python API Overview +=================== + +The Python package in this repository exposes three complementary layers: + +* `xstudio.connection` for connecting to a running xSTUDIO process. +* `xstudio.api` for high-level wrappers around sessions, playlists, timelines, + media, viewports, and other application actors. +* `xstudio.plugin` for authoring Python plugins and UI extensions. + +Connection Model +---------------- + +The usual entry point is `xstudio.connection.Connection`. Once connected, use +the `api` property to access the higher-level wrapper classes: + +.. code-block:: python + + from xstudio.connection import Connection + + connection = Connection(auto_connect=True) + api = connection.api + + print(api.host, api.port) + print(api.session.playlists) + +This same structure works for remote control, embedded scripting, and plugin +code. The main difference is where the `Connection` comes from and whether +xSTUDIO is already running. + +Main Object Graph +----------------- + +At a high level, the object model looks like this: + +* `Connection` owns the transport and message loop. +* `API` exposes application-level services such as the current session, + caches, plugin manager, and scanner. +* `Studio` and `App` wrap the running application. +* `Session` exposes playlists, subsets, contact sheets, sequences, media, + bookmarks, and playheads. +* `Viewport`, `Playhead`, and `ColourPipeline` provide viewer-specific control. + +Where To Look In The Source Tree +-------------------------------- + +* `python/src/xstudio/api` contains the main high-level wrappers. +* `python/src/xstudio/plugin` contains Python plugin base classes. +* `python/src/xstudio/demo` contains small example scripts. +* `src/plugin/python_plugins` contains shipped plugin examples that integrate + with the UI. diff --git a/docs/user_docs/appendix/python_plugins.rst b/docs/user_docs/appendix/python_plugins.rst index c08404882..a9c67a516 100644 --- a/docs/user_docs/appendix/python_plugins.rst +++ b/docs/user_docs/appendix/python_plugins.rst @@ -129,6 +129,8 @@ At the same location in the filesystem I also need an **__init__.py** file to ex More Complex plugin Examples ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**August 2025** - We are still working on some comprehensive Python Plugin API examples that showcase all the features and what is possible in terms of UI interface development, integration and interaction with xSTUDIO. - -However there are some existing plugins that ship with the xSTUDIO source code that provide some fully developed plugins that do HUD overlay graphics or add a custom Viewport layout (picture-in-picture). These plugins are intended to be useful reference implementations of these features and can be found in the **src/plugin/python_plugins/** folder in the xSTUDIO source code repository. +The Python plugin examples in this guide are intentionally small, but xSTUDIO +also ships more complete reference implementations. In particular, +**src/plugin/python_plugins/** contains developed examples for HUD overlays and +custom viewport layouts that are useful starting points for UI integration, +interaction, and playback-driven tooling. diff --git a/docs/user_docs/getting_started/getting_started.rst b/docs/user_docs/getting_started/getting_started.rst index 020aa57b8..9d38e3c15 100644 --- a/docs/user_docs/getting_started/getting_started.rst +++ b/docs/user_docs/getting_started/getting_started.rst @@ -7,107 +7,147 @@ Getting Started Building xSTUDIO ---------------- -Follow our comprehensive :ref:`build guide documentation `: for instructions on building xSTUDIO. +Follow the :ref:`build guide documentation ` for platform-specific +instructions on building xSTUDIO. Launching xSTUDIO ----------------- -This depends somewhat on how you have installed xSTUDIO, but generally the method for launching xSTUDIO will be: +How you launch xSTUDIO depends on how it was installed, but the common cases +are: * Linux - On most Linux desktops To launch an empty xSTUDIO "Session" type ``xstudio`` on the Linux command line and press enter. - Note that *if xstudio is already running* the 'xstudio' command on its own will not launch a new xstudio interface but rather communicate with the exsiting instance. This is how xSTUDIO's fast media *push* loading works. To ensure you get a new xSTUDIO GUI session, you can add the '-n' command line option: ``xstudio -n``. + On most Linux desktops, launch an empty xSTUDIO session by typing + ``xstudio`` in a terminal. + + If xSTUDIO is already running, the `xstudio` command normally talks to the + existing instance instead of opening a second UI. This is how xSTUDIO's + media *push* workflow works. To force a new GUI session, use + ``xstudio -n``. * Windows - xSTUDIO installation on Windows should add a shortcut to the Windows start menu. -* MacOS - xSTUDIO is deployed as an application bundle on MacOS, just double click on the application icon as with any other App. + The Windows installer should add a shortcut to the Start menu. +* macOS + xSTUDIO is typically installed as an application bundle. Launch it by + opening the app in Finder, or from a shell using the app bundle's + executable path. .. image:: ../images/default-interface.png Loading Media (filesystem browser) ---------------------------------- -An easy way to load media is to drag-and-drop files or folders into the main window from the file system. If you drop a folder, the directory will be recursively searched for media files and they will all be added. +The fastest way to start reviewing media is to drag files or folders into the +main window. If you drop a folder, xSTUDIO recursively searches it for media +that it can load. + +There are three common drag-and-drop targets: -There are 3 destinations into which you can drag-and-drop from the filesystem browser: + - The empty space of the Playlists panel. This creates a new playlist and + adds the dropped media. + - An existing playlist entry in the Playlists panel. This adds the dropped + media to that playlist. + - The Media List panel. This appends the dropped media to the container that + is currently being inspected there. - - The empty space of the Playlists panel : this will create a new playlist and add the media. - - Subfolders of the top-level folder that was dropped into xSTUDIO will create a *subset* - - An existing playlist entry in the Playlists panel : this will add the media to the playlist that you dropped the file into. - - The Media List panel : this will add the media to the end of the playlist being inspected in the media List. +If the top-level folder you drop contains subfolders, xSTUDIO can represent +those as *subsets* beneath the new playlist. .. raw:: html - +
| - + .. _command_line_loading: Loading Media (command line) ---------------------------- -Media can be loaded using the xSTUDIO command line from a terminal window which will be convenient and powerful for users familiar with shell syntax. By default, if xSTUDIO is already running, files will be added to the existing session instead of starting a new session. If you want to launch a new session, use the -n flag. +Media can also be loaded from a terminal. By default, if xSTUDIO is already +running, command-line paths are added to the existing session instead of +starting a new UI. Use `-n` if you explicitly want a new session. -xSTUDIO supports various modes for loading sequences. You can mix different modes as required +xSTUDIO supports a mix of individual files, wildcard patterns, directories, and +frame-sequence patterns in the same command: .. code-block:: bash xstudio /path/to/test.mov /path/to/\*.jpg /path/to/frames.####.exr=1-10 /path/to/other_frames.####.exr -On Windows your command might look like this, but by using simple command aliasing in Powershell can simplify this +On Windows your command might look like this: .. code-block:: bash - C:\Program Files\xSTUDIO\bin\xstudio.exe C:\Users\JaneSmith\\Media\test_movie.mp4 C:\Users\JaneSmith\Media\exrs\exr_sequence.####.exr + C:\Program Files\xSTUDIO\bin\xstudio.exe C:\Users\JaneSmith\Media\test_movie.mp4 C:\Users\JaneSmith\Media\exrs\exr_sequence.####.exr -Or, on MacOS you will need the path to the xSTUDIO app bundle, which *may* look like this +On macOS you will usually call the executable inside the app bundle, for +example: .. code-block:: bash /Applications/xSTUDIO.app/Contents/MacOS/xstudio.bin /Users/joe/Downloads/imported_media -Note that a specific subset of frames can be loaded, or by ommitting a range all frames matching the pattern will be loaded. +A specific subset of frames can be loaded, or you can omit the range to load +all frames that match the pattern. .. note:: - Passing a filesystem directory rather than a filepath means the directory will be recursively searched for media that can be loaded into xSTUDIO. + Passing a filesystem directory rather than a file path means the directory + will be recursively searched for media that can be loaded into xSTUDIO. .. note:: - Movie files will be played back at their 'natural' frame rate, in other words xSTUDIO respects the encoded frame rate of the given file. + Movie files are played back at their encoded frame rate. .. note:: - Image sequences (e.g. a series of JPEG or EXR files) default to 24fps (you can adjust this in preferences). + Image sequences default to 24 fps unless you change the preference. -For more details on command line loading please see Appendix Pt.1. +For more details on command-line loading and scripting, see the appendix +sections on media items and Python scripting. Viewing Media ------------- -When you drag/drop into the xSTUDIO media list panel, the first item dropped will be put on screen immediately. To look at other media within the current playlist use the up/down arrow keys to cycle through the items that are in the playlist. See the section 'The Media List Panel' for more ways to select the media that you're viewing. If you drag/drop into the playlists panel, media won't be immediately loaded into the viewport. **You need to double click on the newly created playlist to put its content into the viewport** +If you drag media directly into the Media List, the first item dropped is shown +immediately. Use the up and down arrow keys to cycle through the viewed media. + +If you drag media into the Playlists panel instead, the media is added to the +session but not automatically shown in the viewport. To start viewing it, +double-click the playlist you just created. .. note:: - The MediaList panel shows the content of the *selected* playlist. Be aware that the *selected playlist* maybe different to the *viewed playlist* that is showing images in the viewer. + The Media List panel shows the contents of the *selected* container. The + *selected* container can be different from the *viewed* container that is + currently driving the viewport. -To select a playlist single click on it in the Playlist panel. To select a playlist and also start viewing its content, double click the playlist in the Playlist panel. +Single-click a playlist to select it. Double-click a playlist to select it and +switch the viewport to that container. -If your selected playlist is the same as the viewed playlist, simply single click on a media item in the MediaList panel to view it in the viewer and start playing/looping on it. The up/down arrow hotkeys are also an easy way to cycle through the viewed media in the playlist. +If your selected playlist is already the viewed playlist, single-clicking a +media item in the Media List shows it in the viewport. The arrow-key shortcuts +remain the fastest way to step through nearby items. -If your selected playlist is not the viewed playlist then double clicking on an item in the MediaList will switch your viewed playlist to the selected and the media you clicked on will start playing. +If your selected playlist is not the viewed playlist, double-clicking a media +item switches the viewed playlist and starts playing that item. .. _creating_a_sequence: Creating a Sequence (Timeline) ------------------------------ -To start creating a multi track edit you must first have a Playlist because Sequences can only exist as a child of a Playlist (see :ref:`Media List ` for more details). One can right-mouse-button click with a Playlist selected, or hit the 'More' button (three dots to top right of Playlist panel) and choose *New Sequence*. +To create a multi-track edit, start with a playlist. Sequences are children of +playlists. With a playlist selected, right-click it or use the *More* button in +the Playlists panel and choose *New Sequence*. -Once a Sequence has been created, it can be populated with media by drag-dropping from the parent Playlist or even drag-dropping new media directly into the Media List with the Sequence selected in the Playlists panel. +Once a sequence exists, populate it by dragging media from the parent playlist +into the timeline. You can also drag new media directly into the Media List +while the sequence is selected. .. note:: - Media can be loaded into a Sequence but not be within the edit. In this way the Sequence serves as its own *media bin* as well as containing the actual edit. Media loaded into the sequence will show in the Media List panel, and can be drag and dropped from there into the timeline interface to add to or create new video/audio tracks. + Media can be loaded into a sequence without already being placed in the + edit. In that sense, a sequence acts as both a timeline and its own local + media bin. Media loaded into the sequence appears in the Media List and can + then be dragged into timeline tracks. -This short video demonstrates Sequence creation. +This short video demonstrates sequence creation. .. raw:: html - -
+
diff --git a/docs/user_docs/index.rst b/docs/user_docs/index.rst index e208a93d2..bafc10865 100644 --- a/docs/user_docs/index.rst +++ b/docs/user_docs/index.rst @@ -7,7 +7,15 @@ xSTUDIO User Guide .. image:: images/interface-01.png .. note:: - The screenshots included in this user guide include some visual content from the 'Meridian' title, part of the `Netflix Open Content `_ media data set. + The screenshots included in this user guide include some visual content + from the 'Meridian' title, part of the `Netflix Open Content `_ + media data set. + +This guide describes the current xSTUDIO 1.1.x workflow model: sessions, +playlists, media inspection, compare modes, sequences, notes, grading, and +pipeline scripting. Some screenshots were captured on earlier builds, but the +terminology and workflow descriptions below have been refreshed against the +current repository. .. toctree:: :maxdepth: 2 @@ -17,4 +25,4 @@ xSTUDIO User Guide ./interface/interface ./workflow/workflow ./appendix/index - ./release_notes/index \ No newline at end of file + ./release_notes/index diff --git a/docs/user_docs/overview.rst b/docs/user_docs/overview.rst index 2a93978d6..ebecf8ebf 100644 --- a/docs/user_docs/overview.rst +++ b/docs/user_docs/overview.rst @@ -10,63 +10,80 @@ Introduction xSTUDIO Dual Window Interface -What is xSTUDIO? +What is xSTUDIO? **************** -xSTUDIO is a media playback and review application designed for professionals working in the film and TV post production industries, particularly the Visual Effects and Feature Animation sectors. xSTUDIO is focused on providing an intuitive, easy to use interface with a high performance playback engine at its core and C++ and Python APIs for pipeline integration and customisation for total flexibility. The application is compatible with MacOS (Apple), Microsoft Windows and many popular Linux desktop distributions. +xSTUDIO is a media playback and review application for film, episodic, VFX, +animation, and other post-production workflows. It combines a high-performance +playback engine with review tools, timeline editing, colour-managed viewing, +and both C++ and Python extension points for studio integration. -xSTUDIO is optimised to import and handle very large collections of media sources rapidly, loads specialised image formats and displays images with accurate colour management. Users can quickly import, organise and group media into playlists and 'subsets', playing through and looping on media items and adding review notes and sketched annotations, allowing one to view the media in a highly interactive and collaborative way. A non-linear editing (NLE) timeline interface allows users to create, import and export multi-track video and audio edits quickly and easily. This enables workflows that are essential for teams in VFX, animation and other post-production activities who need to see, on demand, the artwork that they and their colleagues are creating both as discreet media items and in the context of a sequence edit. For example one can jump between the viewed media source instantaneously, inspect pixels close-up, do frame-by-frame comparisons across multiple media sources, annotate the media with drawings and captions or add feedback notes to share. +xSTUDIO is built to handle large collections of media quickly, including image +sequences, movie files, playlists, subsets, contact sheets, and timelines. It +supports drag-and-drop review, rapid compare workflows, notes and annotations, +timeline-focused playback, and colour-accurate display through OCIO-based +colour management. +Core Concepts +************* -xSTUDIO v1.X - Overview -*********************** +The application is organized around a small number of core concepts: -xSTUDIO is a robust and high performance playback and review solution. It has been deployed at DNEG since September 2022 and is in daily use by thousands of VFX and Animation artists, supervisors and producers across our global teams to conduct daylies and image review. The application has been developed and extended thanks to the input and feedback from DNEG's large and diverse crew and as such xSTUDIO is very much a product made for and made by VFX and animation professionals. +* A **Session** is the overall review workspace. +* **Playlists** group media for review and can contain **subsets**, + **contact sheets**, and **sequences**. +* The **Media List** shows the contents of the currently inspected container. +* The **Viewport** is where media is displayed, compared, graded, and + annotated. +* A **Sequence** is xSTUDIO's timeline container for editorial-style review + and export. -Here are some highlights of xSTUDIO's capaility and performance. +xSTUDIO Overview +**************** + +Here are the major capabilities that the current codebase and documentation +cover. **The Interface** - The application interface is highly flexible and configurable. - - Set-up its appearance and components to suit you own visual preferences and workflows. - - *Layouts* allow multiple interface configurations to be created and seamlessly switched as you work. - - Many components of the UI can be toggled on or off: - - Create a 'clean' and minimial look to the application ... - - ... or an interface bursting with features and information ... - - ... or anything in between. + - Multiple layouts let you switch between different panel arrangements as you + work. + - Panels can be shown, hidden, or rearranged to support focused viewing, + timeline editing, or broader review sessions. **Loading Media** - - Display virtually any image format in common use today (EXR, TIF, JPG, MOV, MP4 etc). - - Drag and drop media from the desktop file system browser directly into the xSTUDIO interface. - - Use the command line interface to 'push' media into a running xSTUDIO instance from a terminal window. - - Use the Python API to build playlists with your own custom scripts. + - Load common image and movie formats, including image sequences and + high-resolution review media. + - Drag and drop media from the desktop directly into playlists or the media + list. + - Use the command line to push media into a running xSTUDIO session. + - Use the Python API to build playlists and sessions programmatically. **Playlists** - - Create any number of playlists, colour code and arrange them under category headers. - - Drag and drop to reorder and organise media and playlists. - - Colour code individual media and playlists with the 'flags' feature. - - Nest mini-playlist *subsets* under parent playlists to further structure your viewables. - - Create *contact sheets* under parent playlists, to lay-out multiple media items in a grid arrangement for comparison. + - Create any number of playlists and arrange them under category headers. + - Reorder playlists and media with drag and drop. + - Flag media and playlists for quick visual organization. + - Use subsets and contact sheets to structure and compare large groups of + shots. **Sequences** - - Create multi-track video timelines by drag/dropping media from playlists into the timeline interface. - - Edit your timelines with the simple, easy to use editing tools. - - Import and export timelines using the OpenTimelineIO interchange facility. - - Use review friendly timeline tools like the 'focus' mode and item looping to make sequence based reviews fast and easy. + - Create multi-track timelines by dragging media from playlists into the + timeline. + - Edit video and audio arrangements with xSTUDIO's sequence tools. + - Import and export timelines through OpenTimelineIO. + - Use review-focused tools such as focus mode, looping, and timeline-aware + playhead control. **Notes** - - Add notes and annotations to media on individual frames or range of frames. - - On screen annotations can be created with easy to use, highly responsive sketching tools. Annotations features currently include: - 1. Adjustable colour, opacity and size of brush strokes. - 2. Shapes tool for boxes, circles, lines and arrows etc. - 3. Eraser pen for even more sketching flexibility . - 4. Editable text captions with adjustable position, scale, colour and opacity. - 5. 'Snapshot' button allows you to save an annotation to disk as a jpeg /tiff etc image. - - Navigate your media collection through the notes interface by jumping directly to bookmarked frames. + - Add notes and annotations on individual frames or over frame ranges. + - Use drawing, shapes, arrows, text, and snapshots to capture review + feedback. + - Navigate review material by jumping directly to bookmarked frames. .. figure:: images/interface-02.png :alt: xSTUDIO's Contact Sheet viewer mode @@ -77,50 +94,46 @@ Here are some highlights of xSTUDIO's capaility and performance. **The Viewer** - - Colour accurate display (OCIO v2 colour management). - - Hotkey driven interaction. - - Adjust exposure and playback rate. - - Zoom/pan image tools, RGBA channel display. - - Multiple 'Compare Modes' allowing comparison of image stacks: - - Grid Mode for tiled layout of multiple sources - - A/B & Wipe Compare - - Compositing modes (Over, Screen, Add etc.) - - String Out mode: dynamically string together many sources in a flat edit list - - Adjustable masking overlay and guide-lines. - - 'Pop-out' 2nd viewer for dual display set-ups. - - Audio playback for sources containing embedded audio streams. + - Colour-accurate display with OCIO v2 colour management. + - Hotkey-driven playback and navigation. + - Exposure, gamma, and channel-view controls. + - Zoom, pan, masking, guides, and detailed pixel inspection. + - Compare modes including grid, A/B, wipe, composite, and string-out. + - Audio playback for sources with embedded audio streams. + - Optional pop-out or quick-view style viewing for focused inspection. **Other Capabilities** - - Apply creative grades to shots & renders with the grading tool. + - Apply creative grades to shots and renders with the grading tool. - Grades can be masked with editable polygon shapes - Grade masks can be softened - - Export a grade to Nuke with a simple copy/paste operation - - QuickView for instant inspection of individual media items - - While xSTUDIO is running, a command line call can pop-out an independent light player window for viewing a single piece of media in isolation. + - Export a grade to Nuke with a simple copy and paste operation + - QuickView for instant inspection of individual media items. + - While xSTUDIO is running, a command-line call can pop out an independent + light player window for viewing a single piece of media in isolation. + +Pipeline Integration +******************** -**API features for pipeline developers** +xSTUDIO is designed to be extended as well as used interactively. *C++ API* - - Write plugins with full access to the application's internal components down to the lowest level if desired. - - C++ base classes are provided for implementation of common plugin typs: - - Video Output Plugin - for delivering video external to the application, like SDI video cards, rendering to disk or streaming video content - - Viewport Overlay Plugin - for drawing custom graphics, text and data directly into the viewport - - Colour Pipeline Plugin - for implementing colour management. - - Media Reader Plugin - implement readers for specific file formats - - Data Source Plugin - build plugins to interact with production databases and source media to import into xSTUDIO - - Metadata Hook Plugin - add pipeline metadata to media on creation - - Code for DNEG's powerful Shotgrid browser interface, exploiting the Shotgrid REST API, is also included for reference. It is written for DNEG's proprietary Shotgrid table schemas and won't work 'out of the box' but developers could adapt the code to work at other studios if desired. + - Write plugins with direct access to the application's internal actors, + media pipeline, and viewport systems. + - The public headers include base classes for video output, viewport overlays, + viewport layouts, colour pipelines, media readers, media metadata readers, + data sources, and media hooks. + - Concrete examples ship in `src/plugin`, including OCIO colour management, + built-in viewport layouts, HUD overlays, media readers, and DNEG-specific + data source integrations. *Python API* - - Create python Plugins that can: - - deliver menus and any other GUI elements you wish - - interact with the xSTUDIO session by adding and re-organising media - - add on-screen overlay graphics - - receive event notification during playback - - Connect to an xSTUDIO instance transparently from a separate process via the Python API - thus xSTUDIO can be run in a separate software environment to an application, controlling it through the API. - - An embedded python interpreter is also available to execute scripts within xSTUDIO. This runs in a separate thread to the UI so python execution will not affect GUI interactivity or playback. - - Create and build media playlists through straightforward API methods. - - Access the 'playhead' to control playback (start, stop, step frame, jump position etc). - - Various demo python plugins and scripts are provided as well as API docs to get developers started quickly. + - Create Python plugins that add UI, interact with the session model, draw + viewport overlays, and react to playback events. + - Control a running xSTUDIO instance from an external Python process through + the same high-level API wrappers used internally. + - Use the Python API to create playlists, manage timelines, inspect media, + control playheads, and automate review workflows. + - Demo scripts and plugin examples ship in `python/src/xstudio/demo` and + `src/plugin/python_plugins`. diff --git a/docs/user_docs/release_notes/index.rst b/docs/user_docs/release_notes/index.rst index f127c935d..e876df206 100644 --- a/docs/user_docs/release_notes/index.rst +++ b/docs/user_docs/release_notes/index.rst @@ -11,13 +11,17 @@ v1.1.0 **Overview** -xSTUDIO is a high performance playback and review tool designed by and for Visual Effects, Animation and Post Production professionals. The application can load and play large collections of media files. The efficient playback engine allows you to quickly load and play high resolution image formats with a wide range of file formats and encoding. Intuitive tools allow you to create and organise playlists and media sub-sets within playlists to build interactive review sessions, image and video reference libraries. A multi-track timeline editing interface provides the facility for loading or creating edits from simple to complex. xSTUDIO's python and C++ APIs provide +xSTUDIO 1.1.0 is a high-performance playback and review tool for VFX, +animation, and post-production workflows. It can load large collections of +media, organize them into playlists and subsets, compare shots in the viewport, +build multi-track sequences, and integrate with pipeline tooling through both +Python and C++ APIs. **New in this version (v1.1.x)** - Render playlists, timelines and contact sheets to output video quickly, easily and with any ffmpeg encoding parameters that you like. - Set media FPS via the toolbar, right-click Viewport menu or hotkey shortcut. -- Numerous API extensions inspired by feedbaqck from the community. +- Numerous API extensions inspired by feedback from the community. - Viewport time slider auto zoom in Timeline 'focus' mode. **xSTUDIO Highlights**