Added StreamMapper effect

Signed-off-by: Eric Reinecke <ereinecke@netflix.com>

Author: reinecke

src/opentimelineio/CMakeLists.txt

@@ -35,6 +35,7 @@ set(OPENTIMELINEIO_HEADER_FILES
     streamChannelIndexStreamAddress.h
     streamInfo.h
     stringStreamAddress.h
+    streamMapper.h
     streamSelector.h
     audioMixMatrix.h
     timeEffect.h
@@ -77,6 +78,7 @@ add_library(opentimelineio ${OTIO_SHARED_OR_STATIC_LIB}
     streamChannelIndexStreamAddress.cpp
     streamInfo.cpp
     stringStreamAddress.cpp
+    streamMapper.cpp
     streamSelector.cpp
     audioMixMatrix.cpp
     stringUtils.cpp

src/opentimelineio/CORE_VERSION_MAP.cpp

@@ -236,6 +236,7 @@ const label_to_schema_version_map CORE_VERSION_MAP{
           { "Stack", 1 },
           { "StreamAddress", 1 },
           { "StreamInfo", 1 },
+          { "StreamMapper", 1 },
           { "StreamSelector", 1 },
           { "StringStreamAddress", 1 },
           { "Test", 1 },

src/opentimelineio/streamMapper.cpp

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

src/opentimelineio/streamMapper.h

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Contributors to the OpenTimelineIO project
+
+#pragma once
+
+#include "opentimelineio/effect.h"
+#include "opentimelineio/version.h"
+
+#include <map>
+#include <string>
+
+namespace opentimelineio { namespace OPENTIMELINEIO_VERSION_NS {
+
+/// @brief 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:
+///
+/// @code{.json}
+///   {
+///     "monocular": "left_eye"
+///   }
+/// @endcode
+class OTIO_API_TYPE StreamMapper : public Effect
+{
+public:
+    /// @brief This struct provides the StreamMapper schema.
+    struct Schema
+    {
+        static char constexpr name[]  = "StreamMapper";
+        static int constexpr version = 1;
+    };
+
+    using Parent = Effect;
+
+    using StreamMap = std::map<std::string, std::string>;
+
+    /// @brief Create a new StreamMapper.
+    ///
+    /// @param name        The name of the effect object.
+    /// @param effect_name The name of the effect.
+    /// @param stream_map  Mapping of output stream name to input stream name.
+    /// @param metadata    Optional metadata dictionary.
+    OTIO_API StreamMapper(
+        std::string const& name        = std::string(),
+        std::string const& effect_name = std::string(),
+        StreamMap const&   stream_map  = StreamMap(),
+        AnyDictionary const& metadata  = AnyDictionary());
+
+    /// @brief Return the stream name mapping.
+    ///
+    /// Keys are output stream names (as seen downstream); values are input
+    /// stream names (keys in the upstream available_streams map).
+    OTIO_API StreamMap const& stream_map() const noexcept { return _stream_map; }
+
+    /// @brief Set the stream name mapping.
+    OTIO_API void set_stream_map(StreamMap const& stream_map)
+    {
+        _stream_map = stream_map;
+    }
+
+protected:
+    virtual ~StreamMapper();
+
+    bool read_from(Reader&) override;
+    void write_to(Writer&) const override;
+
+private:
+    StreamMap _stream_map;
+};
+
+}} // namespace opentimelineio::OPENTIMELINEIO_VERSION_NS

src/opentimelineio/typeRegistry.cpp

@@ -28,6 +28,7 @@
 #include "opentimelineio/streamChannelIndexStreamAddress.h"
 #include "opentimelineio/streamInfo.h"
 #include "opentimelineio/stringStreamAddress.h"
+#include "opentimelineio/streamMapper.h"
 #include "opentimelineio/streamSelector.h"
 #include "opentimelineio/timeEffect.h"
 #include "opentimelineio/timeline.h"
@@ -94,6 +95,7 @@ TypeRegistry::TypeRegistry()
     register_type<StreamChannelIndexStreamAddress>();
     register_type<StringStreamAddress>();
     register_type<StreamInfo>();
+    register_type<StreamMapper>();
     register_type<StreamSelector>();
     register_type<AudioMixMatrix>();
     register_type<TimeEffect>();

src/py-opentimelineio/opentimelineio-bindings/otio_serializableObjects.cpp

@@ -28,6 +28,7 @@
 #include "opentimelineio/streamChannelIndexStreamAddress.h"
 #include "opentimelineio/streamInfo.h"
 #include "opentimelineio/stringStreamAddress.h"
+#include "opentimelineio/streamMapper.h"
 #include "opentimelineio/streamSelector.h"
 #include "opentimelineio/timeEffect.h"
 #include "opentimelineio/timeline.h"
@@ -816,6 +817,32 @@ static void define_stream_effects(py::module m) {
             &StreamSelector::set_output_streams,
             "List of stream identifier strings to select.");
 
+    py::class_<StreamMapper, Effect,
+               managing_ptr<StreamMapper>>(m, "StreamMapper", py::dynamic_attr(),
+        "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.")
+        .def(py::init([](std::string name,
+                         std::string effect_name,
+                         StreamMapper::StreamMap stream_map,
+                         py::object metadata) {
+                return new StreamMapper(name, effect_name, stream_map,
+                                        py_to_any_dictionary(metadata)); }),
+             py::arg_v("name"_a = std::string()),
+             "effect_name"_a = std::string(),
+             "stream_map"_a = StreamMapper::StreamMap(),
+             py::arg_v("metadata"_a = py::none()))
+        .def_property("stream_map",
+            &StreamMapper::stream_map,
+            &StreamMapper::set_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.");
+
     py::class_<AudioMixMatrix, Effect,
                managing_ptr<AudioMixMatrix>>(m, "AudioMixMatrix", py::dynamic_attr(),
         "An effect that mixes audio streams using a coefficient matrix. "

src/py-opentimelineio/opentimelineio/schema/__init__.py

@@ -25,6 +25,7 @@
     Stack,
     StreamAddress,
     StreamInfo,
+    StreamMapper,
     StreamSelector,
     StringStreamAddress,
     Timeline,
@@ -57,6 +58,7 @@
     serializable_collection,
     stream_address,
     stream_info,
+    stream_mapper,
     stream_selector,
     string_stream_address,
     timeline,
@@ -92,6 +94,7 @@ def timeline_from_clips(clips):
     'StreamAddress',
     'StreamIdentifier',
     'StreamInfo',
+    'StreamMapper',
     'StreamSelector',
     'StringStreamAddress',
     'Timeline',

src/py-opentimelineio/opentimelineio/schema/stream_mapper.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright Contributors to the OpenTimelineIO project
+
+from .. core._core_utils import add_method
+from .. import _otio
+
+
+@add_method(_otio.StreamMapper)
+def __str__(self):
+    return "StreamMapper({})".format(str(self.name))
+
+
+@add_method(_otio.StreamMapper)
+def __repr__(self):
+    return "otio.schema.StreamMapper(name={})".format(repr(self.name))

tests/test_stream_mapping.py

@@ -338,5 +338,94 @@ def test_use_in_available_streams(self):
         self.assertIn(StreamInfo.Identifier.stereo_left, streams)
 
 
+class TestStreamMapper(unittest.TestCase):
+    def test_create_default(self):
+        mapper = otio.schema.StreamMapper()
+        self.assertEqual(mapper.stream_map, {})
+        self.assertEqual(mapper.schema_name(), "StreamMapper")
+        self.assertEqual(mapper.schema_version(), 1)
+
+    def test_create_with_map(self):
+        stream_map = {
+            StreamInfo.Identifier.monocular: StreamInfo.Identifier.left_eye
+        }
+        mapper = otio.schema.StreamMapper(stream_map=stream_map)
+        self.assertEqual(mapper.stream_map, stream_map)
+
+    def test_set_map(self):
+        mapper = otio.schema.StreamMapper()
+        stream_map = {
+            StreamInfo.Identifier.stereo_left: StreamInfo.Identifier.surround_left_front,
+            StreamInfo.Identifier.stereo_right: StreamInfo.Identifier.surround_right_front,
+        }
+        mapper.stream_map = stream_map
+        self.assertEqual(mapper.stream_map, stream_map)
+
+    def test_round_trip_serialization(self):
+        stream_map = {
+            StreamInfo.Identifier.monocular: StreamInfo.Identifier.left_eye
+        }
+        mapper = otio.schema.StreamMapper(
+            name="remap_to_mono",
+            stream_map=stream_map,
+        )
+        json_str = mapper.to_json_string()
+        restored = otio.adapters.read_from_string(json_str, "otio_json")
+        self.assertIsInstance(restored, otio.schema.StreamMapper)
+        self.assertEqual(restored.name, "remap_to_mono")
+        self.assertEqual(restored.stream_map, stream_map)
+
+    def test_left_eye_to_monocular_use_case(self):
+        """StreamMapper can remap left_eye to monocular for downstream consumers."""
+        clip = otio.schema.Clip(
+            name="stereo_shot",
+            media_reference=otio.schema.ExternalReference(
+                target_url="/path/to/stereo.mov"
+            ),
+            effects=[
+                otio.schema.StreamMapper(
+                    stream_map={
+                        StreamInfo.Identifier.monocular: StreamInfo.Identifier.left_eye
+                    }
+                )
+            ]
+        )
+        mapper = clip.effects[0]
+        self.assertIsInstance(mapper, otio.schema.StreamMapper)
+        self.assertEqual(
+            mapper.stream_map[StreamInfo.Identifier.monocular],
+            StreamInfo.Identifier.left_eye
+        )
+
+    def test_use_as_clip_effect(self):
+        """StreamMapper round-trips correctly when embedded in a clip."""
+        clip = otio.schema.Clip(
+            name="remapped_clip",
+            media_reference=otio.schema.ExternalReference(
+                target_url="/path/to/source.mov"
+            ),
+            effects=[
+                otio.schema.StreamMapper(
+                    name="a very bad stereo downmix",
+                    stream_map={
+                        StreamInfo.Identifier.stereo_left: StreamInfo.Identifier.surround_left_front,
+                        StreamInfo.Identifier.stereo_right: StreamInfo.Identifier.surround_right_front,
+                    }
+                )
+            ]
+        )
+        json_str = clip.to_json_string()
+        restored = otio.adapters.read_from_string(json_str, "otio_json")
+        self.assertIsInstance(restored, otio.schema.Clip)
+        self.assertEqual(len(restored.effects), 1)
+        mapper = restored.effects[0]
+        self.assertIsInstance(mapper, otio.schema.StreamMapper)
+        self.assertEqual(mapper.name, "A very bad stereo downmix")
+        self.assertEqual(
+            mapper.stream_map[StreamInfo.Identifier.stereo_left],
+            StreamInfo.Identifier.surround_left_front
+        )
+
+
 if __name__ == "__main__":
     unittest.main()