AAF adapter: added clip_timecode_offset argument

Added `clip_timecode_offset` as new optional argument.
By default, the behaviour is the same as before.
However, if the parameter is set to `False`, the global
timecode offset will not be added to the clip source range. This allows for easy access to the actual
source range used in the clip.

Author: timlehr

contrib/opentimelineio_contrib/adapters/advanced_authoring_format.py

@@ -57,6 +57,9 @@
 # If enabled, output recursive traversal info of _transcribe() method.
 _TRANSCRIBE_DEBUG = False
 
+# If enabled, the track timecode offset will be included in the clip source_range
+_CLIP_TIMECODE_OFFSET = True
+
 
 def _transcribe_log(s, indent=0, always_print=False):
     if always_print or _TRANSCRIBE_DEBUG:
@@ -300,7 +303,7 @@ def _transcribe(item, parents, edit_rate, indent=0):
         media_start = source_start
         media_length = item.length
 
-        if timecode_info:
+        if _CLIP_TIMECODE_OFFSET and timecode_info:
             media_start, media_length = timecode_info
             source_start += media_start
 
@@ -1153,15 +1156,32 @@ def _contains_something_valuable(thing):
     return True
 
 
-def read_from_file(filepath, simplify=True, transcribe_log=False):
+def read_from_file(filepath, simplify=True,
+                   transcribe_log=False, clip_timecode_offset=True
+                   ):
+    """Reads AAF content from `filepath` and outputs a OTIO timeline object.
+
+    Args:
+        filepath (str): AAF filepath
+        simplify (bool, optional): simplify timeline structure by stripping empty items
+        transcribe_log (bool, optional): log activity as items are getting transcribed
+        clip_timecode_offset (bool, optional): offset clip ranges by track timecode
+
+    Returns:
+        otio.schema.Timeline
 
+    """
     # 'activate' transcribe logging if adapter argument is provided.
     # Note that a global 'switch' is used in order to avoid
     # passing another argument around in the _transcribe() method.
     #
     global _TRANSCRIBE_DEBUG
     _TRANSCRIBE_DEBUG = transcribe_log
 
+    # enable / disable clip timecode offset for clip source_range times
+    global _CLIP_TIMECODE_OFFSET
+    _CLIP_TIMECODE_OFFSET = clip_timecode_offset
+
     with aaf2.open(filepath) as aaf_file:
 
         storage = aaf_file.content

contrib/opentimelineio_contrib/adapters/tests/test_aaf_adapter.py

@@ -589,6 +589,34 @@ def test_timecode(self):
             otio.opentime.RationalTime(86424, 24),
         )
 
+    def test_aaf_clip_with_timecode_offset(self):
+        timeline = otio.adapters.read_from_file(TIMCODE_EXAMPLE_PATH,
+                                                clip_timecode_offset=True)
+        expected_start_times = {
+            'Frame Debugger 0h.mov': 24.0,
+            'Frame Debugger 1h.mov': 86424.0
+        }
+
+        start_times = {}
+        for clip in timeline.each_clip():
+            start_times[clip.name] = clip.source_range.start_time.value
+
+        self.assertEqual(start_times, expected_start_times)
+
+    def test_aaf_clip_without_timecode_offset(self):
+        timeline = otio.adapters.read_from_file(TIMCODE_EXAMPLE_PATH,
+                                                clip_timecode_offset=False)
+        expected_start_times = {
+            'Frame Debugger 0h.mov': 24.0,
+            'Frame Debugger 1h.mov': 24.0
+        }
+
+        start_times = {}
+        for clip in timeline.each_clip():
+            start_times[clip.name] = clip.source_range.start_time.value
+
+        self.assertEqual(start_times, expected_start_times)
+
     def test_aaf_user_comments(self):
         aaf_path = TRIMS_EXAMPLE_PATH
         timeline = otio.adapters.read_from_file(aaf_path)