Add implementation of to_nearest_timecode (#1717)

Add implementation of to_nearest_timecode which makes approximate conversion of timecode from a rate using the closest valid time code rate.

Signed-off-by: Anton Marini <vade@vade.info>

Author: vade

src/opentime/rationalTime.cpp

@@ -570,6 +570,26 @@ RationalTime::to_timecode(
         frames);
 }
 
+std::string
+RationalTime::to_nearest_timecode(
+    double          rate,
+    IsDropFrameRate drop_frame,
+    ErrorStatus*    error_status) const
+{
+    std::string result = to_timecode(rate, drop_frame, error_status);
+
+    if (error_status)
+    {
+        *error_status = ErrorStatus();
+
+        double nearest_rate = nearest_valid_timecode_rate(rate);
+
+        return to_timecode(nearest_rate, drop_frame, error_status);
+    }
+
+    return result;
+}
+
 std::string
 RationalTime::to_time_string() const
 {

src/opentime/rationalTime.h

@@ -190,6 +190,17 @@ class RationalTime
         return to_timecode(_rate, IsDropFrameRate::InferFromRate, error_status);
     }
 
+    std::string to_nearest_timecode(
+        double          rate,
+        IsDropFrameRate drop_frame,
+        ErrorStatus*    error_status = nullptr) const;
+
+    std::string to_nearest_timecode(ErrorStatus* error_status = nullptr) const
+    {
+        return to_nearest_timecode(_rate, IsDropFrameRate::InferFromRate, error_status);
+    }
+
+
     // produce a string in the form
     // hours:minutes:seconds
     // which may have a leading negative sign. seconds may have up to

src/py-opentimelineio/opentime-bindings/opentime_rationalTime.cpp

@@ -131,6 +131,26 @@ For example, the duration of a clip from frame 10 to frame 15 is 6 frames. Resul
                         IsDropFrameRate::InferFromRate,
                         ErrorStatusConverter());
                 })
+        .def("to_nearest_timecode", [](RationalTime rt, double rate, std::optional<bool> drop_frame) {
+                return rt.to_nearest_timecode(
+                        rate,
+                        df_enum_converter(drop_frame),
+                        ErrorStatusConverter()
+                );
+        }, "rate"_a, "drop_frame"_a, "Convert to nearest timecode (``HH:MM:SS;FRAME``)")
+        .def("to_nearest_timecode", [](RationalTime rt, double rate) {
+                return rt.to_nearest_timecode(
+                        rate,
+                        IsDropFrameRate::InferFromRate,
+                        ErrorStatusConverter()
+                );
+        }, "rate"_a)
+        .def("to_nearest_timecode", [](RationalTime rt) {
+                return rt.to_nearest_timecode(
+                        rt.rate(),
+                        IsDropFrameRate::InferFromRate,
+                        ErrorStatusConverter());
+                })
         .def("to_time_string", &RationalTime::to_time_string)
         .def_static("from_timecode", [](std::string s, double rate) {
                 return RationalTime::from_timecode(s, rate, ErrorStatusConverter());

src/py-opentimelineio/opentimelineio/opentime.py

@@ -16,6 +16,7 @@
     'from_time_string',
     'from_seconds',
     'to_timecode',
+    'to_nearest_timecode',
     'to_frames',
     'to_seconds',
     'to_time_string',
@@ -47,6 +48,15 @@ def to_timecode(rt, rate=None, drop_frame=None):
     )
 
 
+def to_nearest_timecode(rt, rate=None, drop_frame=None):
+    """Convert a :class:`~RationalTime` into a timecode string."""
+    return (
+        rt.to_nearest_timecode()
+        if rate is None and drop_frame is None
+        else rt.to_nearest_timecode(rate, drop_frame)
+    )
+
+
 def to_frames(rt, rate=None):
     """Turn a :class:`~RationalTime` into a frame number."""
     return rt.to_frames() if rate is None else rt.to_frames(rate)