Add functions to serialize animation with a time format.

This also includes functions to clear a property (set it to zero and
null values), which is important for reconstructing an animation by API.

mlt_animation_serialize_cut_tf()
mlt_animation_serialize_tf()
mlt_property_clear()
mlt_property_get_string_tf()
mlt_property_get_string_l_tf()
mlt_properties_clear()
mlt_properties_get_value_tf()

Mlt::Properties::get(int, mlt_time_format)
Mlt::Properties::clear()
Mlt::Animation::serialize_cut(mlt_time_format, int, int)

src/framework/mlt.vers

@@ -512,3 +512,14 @@ MLT_6.8.0 {
     mlt_animation_key_set_type;
     mlt_animation_key_set_frame;
 } MLT_6.6.0;
+
+MLT_6.10.0 {
+  global:
+    mlt_animation_serialize_cut_tf;
+    mlt_animation_serialize_tf;
+    mlt_property_clear;
+    mlt_property_get_string_tf;
+    mlt_property_get_string_l_tf;
+    mlt_properties_clear;
+    mlt_properties_get_value_tf;
+} MLT_6.8.0;

src/framework/mlt_animation.c

@@ -23,6 +23,8 @@
 #include "mlt_animation.h"
 #include "mlt_tokeniser.h"
 #include "mlt_profile.h"
+#include "mlt_factory.h"
+#include "mlt_properties.h"
 
 #include <stdio.h>
 #include <stdlib.h>
@@ -585,22 +587,24 @@ int mlt_animation_prev_key( mlt_animation self, mlt_animation_item item, int pos
 	return ( node == NULL );
 }
 
-/** Serialize a cut of the animation.
+/** Serialize a cut of the animation (with time format).
  *
  * The caller is responsible for free-ing the returned string.
  * \public \memberof mlt_animation_s
  * \param self an animation
  * \param in the frame at which to start serializing animation nodes
  * \param out the frame at which to stop serializing nodes
+ * \param time_format the time format to use for the key frames
  * \return a string representing the animation
  */
 
-char *mlt_animation_serialize_cut( mlt_animation self, int in, int out )
+char *mlt_animation_serialize_cut_tf( mlt_animation self, int in, int out, mlt_time_format time_format )
 {
 	struct mlt_animation_item_s item;
 	char *ret = calloc( 1, 1000 );
 	size_t used = 0;
 	size_t size = 1000;
+	mlt_property time_property = mlt_property_init();
 
 	item.property = mlt_property_init();
 	item.frame = item.is_key = 0;
@@ -652,8 +656,7 @@ char *mlt_animation_serialize_cut( mlt_animation self, int in, int out )
 			}
 
 			// Determine length of string to be appended.
-			if ( item.frame - in != 0 )
-				item_len += 20;
+			item_len += 100;
 			if ( item.is_key )
 				item_len += strlen( mlt_property_get_string_l( item.property, self->locale ) );
 
@@ -685,7 +688,13 @@ char *mlt_animation_serialize_cut( mlt_animation self, int in, int out )
 					s = "";
 					break;
 				}
-				sprintf( ret + used, "%d%s=", item.frame - in, s );
+				if ( time_property && self->fps > 0.0 ) {
+					mlt_property_set_int( time_property, item.frame - in );
+					const char *time = mlt_property_get_time( time_property, time_format, self->fps, self->locale );
+					sprintf( ret + used, "%s%s=", time, s );
+				} else {
+					sprintf( ret + used, "%d%s=", item.frame - in, s );
+				}
 
 				// Append item value.
 				if ( item.is_key )
@@ -696,21 +705,45 @@ char *mlt_animation_serialize_cut( mlt_animation self, int in, int out )
 		}
 	}
 	mlt_property_close( item.property );
+	mlt_property_close( time_property );
 
 	return ret;
 }
 
-/** Serialize the animation.
+static mlt_time_format default_time_format()
+{
+	const char *e = getenv("MLT_ANIMATION_TIME_FORMAT");
+	return e? strtol( e, NULL, 10 ) : mlt_time_frames;
+}
+
+/** Serialize a cut of the animation.
  *
+ * This version outputs the key frames' position as a frame number.
  * The caller is responsible for free-ing the returned string.
  * \public \memberof mlt_animation_s
  * \param self an animation
+ * \param in the frame at which to start serializing animation nodes
+ * \param out the frame at which to stop serializing nodes
  * \return a string representing the animation
  */
 
-char *mlt_animation_serialize( mlt_animation self )
+char *mlt_animation_serialize_cut( mlt_animation self, int in, int out )
+{
+	return mlt_animation_serialize_cut_tf( self, in, out, default_time_format() );
+}
+
+/** Serialize the animation (with time format).
+ *
+ * The caller is responsible for free-ing the returned string.
+ * \public \memberof mlt_animation_s
+ * \param self an animation
+ * \param time_format the time format to use for the key frames
+ * \return a string representing the animation
+ */
+
+char *mlt_animation_serialize_tf( mlt_animation self, mlt_time_format time_format )
 {
-	char *ret = mlt_animation_serialize_cut( self, -1, -1 );
+	char *ret = mlt_animation_serialize_cut_tf( self, -1, -1, time_format );
 	if ( self && ret )
 	{
 		free( self->data );
@@ -720,6 +753,20 @@ char *mlt_animation_serialize( mlt_animation self )
 	return ret;
 }
 
+/** Serialize the animation.
+ *
+ * This version outputs the key frames' position as a frame number.
+ * The caller is responsible for free-ing the returned string.
+ * \public \memberof mlt_animation_s
+ * \param self an animation
+ * \return a string representing the animation
+ */
+
+char *mlt_animation_serialize( mlt_animation self )
+{
+	return mlt_animation_serialize_tf( self, default_time_format() );
+}
+
 /** Get the number of keyframes.
  *
  * \public \memberof mlt_animation_s

src/framework/mlt_animation.h

@@ -26,6 +26,17 @@
 #include "mlt_types.h"
 #include "mlt_property.h"
 
+/** \brief Animation class
+ *
+ * Once an animation has been constructed using mlt_properties_s, this interface
+ * provides a to query and manipulate the animation except for values. One must
+ * use mlt_properties_s still to get, set, and change values.
+ *
+ * \envvar \em MLT_ANIMATION_TIME_FORMAT the time value string format to use,
+ * defaults to mlt_time_frames. Use the numeric value of mlt_time_format as
+ * the value of this variable.
+ */
+
 /** \brief An animation item that represents a keyframe-property combination. */
 
 struct mlt_animation_item_s
@@ -49,7 +60,9 @@ extern int mlt_animation_remove( mlt_animation self, int position );
 extern void mlt_animation_interpolate( mlt_animation self );
 extern int mlt_animation_next_key( mlt_animation self, mlt_animation_item item, int position );
 extern int mlt_animation_prev_key( mlt_animation self, mlt_animation_item item, int position );
+extern char *mlt_animation_serialize_cut_tf( mlt_animation self, int in, int out, mlt_time_format );
 extern char *mlt_animation_serialize_cut( mlt_animation self, int in, int out );
+extern char *mlt_animation_serialize_tf( mlt_animation self, mlt_time_format );
 extern char *mlt_animation_serialize( mlt_animation self );
 extern int mlt_animation_key_count( mlt_animation self );
 extern int mlt_animation_key_get( mlt_animation self, mlt_animation_item item, int index );

src/framework/mlt_properties.c

@@ -812,24 +812,39 @@ char *mlt_properties_get_name( mlt_properties self, int index )
 	return NULL;
 }
 
-/** Get a property's string value by index.
+/** Get a property's string value by index (with time format).
  *
  * Do not free the returned string.
  * \public \memberof mlt_properties_s
  * \param self a properties list
  * \param index the numeric index of the property
+ * \param time_format the time format to use for animation
  * \return the property value as a string or NULL if the index is out of range
  */
 
-char *mlt_properties_get_value( mlt_properties self, int index )
+char *mlt_properties_get_value_tf( mlt_properties self, int index, mlt_time_format time_format )
 {
 	if ( !self ) return NULL;
 	property_list *list = self->local;
 	if ( index >= 0 && index < list->count )
-		return mlt_property_get_string_l( list->value[ index ], list->locale );
+		return mlt_property_get_string_l_tf( list->value[ index ], list->locale, time_format );
 	return NULL;
 }
 
+/** Get a property's string value by index.
+ *
+ * Do not free the returned string.
+ * \public \memberof mlt_properties_s
+ * \param self a properties list
+ * \param index the numeric index of the property
+ * \return the property value as a string or NULL if the index is out of range
+ */
+
+char *mlt_properties_get_value( mlt_properties self, int index )
+{
+	return mlt_properties_get_value_tf( self, index, mlt_time_frames );
+}
+
 /** Get a data value by index.
  *
  * Do not free the returned pointer if you supplied a destructor function when you
@@ -2125,6 +2140,29 @@ void mlt_properties_unlock( mlt_properties self )
 		pthread_mutex_unlock( &( ( property_list* )( self->local ) )->mutex );
 }
 
+/** Remove the value for a property.
+ *
+ * This initializes the value to zero and removes any string, data, or animation.
+ * This is especially useful when you want to reset an animation.
+ * \public \memberof mlt_properties_s
+ * \param self a properties list
+ * \param name the name of the property to clear
+ */
+
+void mlt_properties_clear( mlt_properties self, const char *name )
+{
+	if ( !self || !name ) return;
+
+	// Fetch the property to work with
+	mlt_property property = mlt_properties_fetch( self, name );
+
+	// Set it if not NULL
+	if ( property )
+		mlt_property_clear( property );
+
+	mlt_events_fire( self, "property-changed", name, NULL );
+}
+
 /** Get a time string associated to the name.
  *
  * Do not free the returned string. It's lifetime is controlled by the property.

src/framework/mlt_properties.h

@@ -62,6 +62,7 @@ extern int mlt_properties_set_or_default( mlt_properties self, const char *name,
 extern int mlt_properties_parse( mlt_properties self, const char *namevalue );
 extern char *mlt_properties_get( mlt_properties self, const char *name );
 extern char *mlt_properties_get_name( mlt_properties self, int index );
+extern char *mlt_properties_get_value_tf( mlt_properties self, int index, mlt_time_format );
 extern char *mlt_properties_get_value( mlt_properties self, int index );
 extern void *mlt_properties_get_data_at( mlt_properties self, int index, int *size );
 extern int mlt_properties_get_int( mlt_properties self, const char *name );
@@ -86,6 +87,7 @@ extern mlt_properties mlt_properties_parse_yaml( const char *file );
 extern char *mlt_properties_serialise_yaml( mlt_properties self );
 extern void mlt_properties_lock( mlt_properties self );
 extern void mlt_properties_unlock( mlt_properties self );
+extern void mlt_properties_clear( mlt_properties self, const char *name );
 
 extern char *mlt_properties_get_time( mlt_properties, const char* name, mlt_time_format );
 extern char *mlt_properties_frames_to_time( mlt_properties, mlt_position, mlt_time_format );