Stream and Channel Mapping Support

docs/index.rst

@@ -42,6 +42,7 @@ Tutorials
    tutorials/feature-matrix
    tutorials/otio-timeline-structure
    tutorials/time-ranges
+   tutorials/channel-mapping
    tutorials/otio-filebundles
    tutorials/write-an-adapter
    tutorials/write-a-media-linker

docs/tutorials/otio-serialized-schema-only-fields.md

@@ -139,6 +139,15 @@ parameters:
 
 ## Module: opentimelineio.schema
 
+### AudioMixMatrix.1
+
+parameters:
+- *effect_name*
+- *enabled*
+- *matrix*
+- *metadata*
+- *name*
+
 ### Clip.2
 
 parameters:
@@ -215,6 +224,11 @@ parameters:
 - *start_frame*
 - *target_url_base*
 
+### IndexStreamAddress.1
+
+parameters:
+- *index*
+
 ### LinearTimeWarp.1
 
 parameters:
@@ -258,6 +272,47 @@ parameters:
 - *name*
 - *source_range*
 
+### StreamAddress.1
+
+parameters:
+
+### StreamChannelIndexStreamAddress.1
+
+parameters:
+- *channel_index*
+- *stream_index*
+
+### StreamInfo.1
+
+parameters:
+- *address*
+- *kind*
+- *metadata*
+- *name*
+
+### StreamMapper.1
+
+parameters:
+- *effect_name*
+- *enabled*
+- *metadata*
+- *name*
+- *stream_map*
+
+### StreamSelector.1
+
+parameters:
+- *effect_name*
+- *enabled*
+- *metadata*
+- *name*
+- *output_streams*
+
+### StringStreamAddress.1
+
+parameters:
+- *address*
+
 ### TimeEffect.1
 
 parameters:

docs/tutorials/otio-serialized-schema.md

@@ -286,6 +286,27 @@ parameters:
 
 ## Module: opentimelineio.schema
 
+### AudioMixMatrix.1
+
+*full module path*: `opentimelineio.schema.AudioMixMatrix`
+
+*documentation*:
+
+```
+An effect that mixes audio streams using a coefficient matrix. The matrix maps output stream names 
+to a dict of input stream names and their mix coefficients. Output keys SHOULD use 
+StreamInfo.Identifier values (e.g. stereo_left, stereo_right) where applicable; they correspond to 
+the keys that will appear in the downstream available_streams map after mixing. Input keys identify 
+source streams and SHOULD match keys in the upstream available_streams map.
+```
+
+parameters:
+- *effect_name*: 
+- *enabled*: If true, the Effect is applied. If false, the Effect is omitted.
+- *matrix*: Output-keyed mixing matrix (output_name -> {input_name -> coefficient}). Output keys SHOULD use StreamInfo.Identifier values where applicable; input keys SHOULD match keys in the upstream available_streams map.
+- *metadata*: 
+- *name*: 
+
 ### Clip.2
 
 *full module path*: `opentimelineio.schema.Clip`
@@ -498,6 +519,19 @@ parameters:
 - *start_frame*: The first frame number used in file names.
 - *target_url_base*: Everything leading up to the file name in the ``target_url``.
 
+### IndexStreamAddress.1
+
+*full module path*: `opentimelineio.schema.IndexStreamAddress`
+
+*documentation*:
+
+```
+Addresses a stream by integer index (e.g. ffmpeg stream index).
+```
+
+parameters:
+- *index*: Integer index identifying the stream within its container.
+
 ### LinearTimeWarp.1
 
 *full module path*: `opentimelineio.schema.LinearTimeWarp`
@@ -601,6 +635,105 @@ parameters:
 - *name*: 
 - *source_range*: 
 
+### StreamAddress.1
+
+*full module path*: `opentimelineio.schema.StreamAddress`
+
+*documentation*:
+
+```
+Base class for addressing a specific stream within a media reference.
+```
+
+parameters:
+
+### StreamChannelIndexStreamAddress.1
+
+*full module path*: `opentimelineio.schema.StreamChannelIndexStreamAddress`
+
+*documentation*:
+
+```
+Addresses a stream by track index and channel index within that track. Use this for container 
+formats that organise media into discrete tracks each of which may contain one or more channels, 
+such as MP4/MOV and MXF.
+```
+
+parameters:
+- *channel_index*: Integer index of the channel within the stream.
+- *stream_index*: Integer index of the media track within its container.
+
+### StreamInfo.1
+
+*full module path*: `opentimelineio.schema.StreamInfo`
+
+*documentation*:
+
+```
+Describes a single media stream provided within a source media. A media stream is the smallest unit 
+of temporal media, such as a single eye's video, an isolated audio channel, or a camera view within 
+a 3D scene. StreamAddress provides a mechanism for addressing a specific stream within a media 
+container.
+```
+
+parameters:
+- *address*: The address used to identify the stream within its media.
+- *kind*: A string identifying the kind of stream (e.g. "Video", "Audio").
+- *metadata*: 
+- *name*: 
+
+### StreamMapper.1
+
+*full module path*: `opentimelineio.schema.StreamMapper`
+
+*documentation*:
+
+```
+An effect that remaps stream identifiers to new names. Each entry in stream_map maps an output 
+stream name (the key as it will appear downstream) to an input stream name (the key as it appears in
+ the upstream MediaReference available_streams). A typical use is to normalize a source-specific 
+identifier into a well-known StreamInfo.Identifier value -- for example, to expose the left eye of a
+ stereo source as the conventional monocular stream.
+```
+
+parameters:
+- *effect_name*: 
+- *enabled*: If true, the Effect is applied. If false, the Effect is omitted.
+- *metadata*: 
+- *name*: 
+- *stream_map*: Mapping of output stream name to input stream name. Keys SHOULD use StreamInfo.Identifier values where applicable; values SHOULD match keys in the upstream available_streams map.
+
+### StreamSelector.1
+
+*full module path*: `opentimelineio.schema.StreamSelector`
+
+*documentation*:
+
+```
+An effect that selects specific named output streams from an item. Use this to select a stereo view,
+ specific audio channels, etc. The item will expose these streams downstream with the same naming.
+```
+
+parameters:
+- *effect_name*: 
+- *enabled*: If true, the Effect is applied. If false, the Effect is omitted.
+- *metadata*: 
+- *name*: 
+- *output_streams*: List of stream identifier strings to select.
+
+### StringStreamAddress.1
+
+*full module path*: `opentimelineio.schema.StringStreamAddress`
+
+*documentation*:
+
+```
+Addresses a stream by string identifier (e.g. channel label).
+```
+
+parameters:
+- *address*: String identifier for the stream.
+
 ### TimeEffect.1
 
 *full module path*: `opentimelineio.schema.TimeEffect`

src/opentimelineio/CMakeLists.txt

@@ -30,6 +30,14 @@ set(OPENTIMELINEIO_HEADER_FILES
     serialization.h
     stack.h
     stackAlgorithm.h
+    indexStreamAddress.h
+    streamAddress.h
+    streamChannelIndexStreamAddress.h
+    streamInfo.h
+    stringStreamAddress.h
+    streamMapper.h
+    streamSelector.h
+    audioMixMatrix.h
     timeEffect.h
     timeline.h
     track.h
@@ -66,6 +74,14 @@ add_library(opentimelineio ${OTIO_SHARED_OR_STATIC_LIB}
     serialization.cpp
     stack.cpp
     stackAlgorithm.cpp
+    indexStreamAddress.cpp
+    streamAddress.cpp
+    streamChannelIndexStreamAddress.cpp
+    streamInfo.cpp
+    stringStreamAddress.cpp
+    streamMapper.cpp
+    streamSelector.cpp
+    audioMixMatrix.cpp
     stringUtils.cpp
     stringUtils.h # stringUtils.h is a private header
     timeEffect.cpp

src/opentimelineio/CORE_VERSION_MAP.cpp

@@ -209,6 +209,7 @@ const label_to_schema_version_map CORE_VERSION_MAP{
     { "0.19.0.dev1",
       {
           { "Adapter", 1 },
+          { "AudioMixMatrix", 1 },
           { "Clip", 2 },
           { "Composable", 1 },
           { "Composition", 1 },
@@ -219,6 +220,7 @@ const label_to_schema_version_map CORE_VERSION_MAP{
           { "GeneratorReference", 1 },
           { "HookScript", 1 },
           { "ImageSequenceReference", 1 },
+          { "IndexStreamAddress", 1 },
           { "Item", 1 },
           { "LinearTimeWarp", 1 },
           { "Marker", 2 },
@@ -231,6 +233,12 @@ const label_to_schema_version_map CORE_VERSION_MAP{
           { "SerializableObject", 1 },
           { "SerializableObjectWithMetadata", 1 },
           { "Stack", 1 },
+          { "StreamAddress", 1 },
+          { "StreamChannelIndexStreamAddress", 1 },
+          { "StreamInfo", 1 },
+          { "StreamMapper", 1 },
+          { "StreamSelector", 1 },
+          { "StringStreamAddress", 1 },
           { "Test", 1 },
           { "TimeEffect", 1 },
           { "Timeline", 1 },

src/opentimelineio/audioMixMatrix.cpp

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Contributors to the OpenTimelineIO project
+
+#include "opentimelineio/audioMixMatrix.h"
+
+namespace opentimelineio { namespace OPENTIMELINEIO_VERSION_NS {
+
+AudioMixMatrix::AudioMixMatrix(
+    std::string const&   name,
+    std::string const&   effect_name,
+    MixMatrix const&     matrix,
+    AnyDictionary const& metadata)
+    : Parent(name, effect_name, metadata)
+    , _matrix(matrix)
+{}
+
+AudioMixMatrix::~AudioMixMatrix()
+{}
+
+bool
+AudioMixMatrix::read_from(Reader& reader)
+{
+    return reader.read_if_present("matrix", &_matrix) && Parent::read_from(reader);
+}
+
+void
+AudioMixMatrix::write_to(Writer& writer) const
+{
+    Parent::write_to(writer);
+    writer.write("matrix", _matrix);
+}
+
+}} // namespace opentimelineio::OPENTIMELINEIO_VERSION_NS