2 * \file mlt_properties.c
3 * \brief Properties class definition
4 * \see mlt_properties_s
6 * Copyright (C) 2003-2013 Ushodaya Enterprises Limited
7 * \author Charles Yates <charles.yates@pandora.be>
8 * \author Dan Dennedy <dan@dennedy.org>
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2.1 of the License, or (at your option) any later version.
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library; if not, write to the Free Software
22 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
30 #include "mlt_properties.h"
31 #include "mlt_property.h"
32 #include "mlt_deque.h"
34 #include "mlt_factory.h"
42 #include <sys/types.h>
49 #define PRESETS_DIR "/presets"
51 /** \brief private implementation of the property list */
60 mlt_properties mirror;
62 pthread_mutex_t mutex;
67 /* Memory leak checks */
69 //#define _MLT_PROPERTY_CHECKS_ 2
70 #ifdef _MLT_PROPERTY_CHECKS_
71 static int properties_created = 0;
72 static int properties_destroyed = 0;
75 /** Initialize a properties object that was already allocated.
77 * This does allocate its ::property_list, and it adds a reference count.
78 * \public \memberof mlt_properties_s
79 * \param self the properties structure to initialize
80 * \param child an opaque pointer to a subclass object
81 * \return true if failed
84 int mlt_properties_init( mlt_properties self, void *child )
88 #ifdef _MLT_PROPERTY_CHECKS_
89 // Increment number of properties created
90 properties_created ++;
94 memset( self, 0, sizeof( struct mlt_properties_s ) );
96 // Assign the child of the object
99 // Allocate the local structure
100 self->local = calloc( 1, sizeof( property_list ) );
102 // Increment the ref count
103 ( ( property_list * )self->local )->ref_count = 1;
104 pthread_mutex_init( &( ( property_list * )self->local )->mutex, NULL );;
107 // Check that initialisation was successful
108 return self != NULL && self->local == NULL;
111 /** Create a properties object.
113 * This allocates the properties structure and calls mlt_properties_init() on it.
114 * Free the properties object with mlt_properties_close().
115 * \public \memberof mlt_properties_s
116 * \return a new properties object
119 mlt_properties mlt_properties_new( )
121 // Construct a standalone properties object
122 mlt_properties self = calloc( 1, sizeof( struct mlt_properties_s ) );
125 mlt_properties_init( self, NULL );
127 // Return the pointer
131 /** Set the numeric locale used for string/double conversions.
133 * \public \memberof mlt_properties_s
134 * \param self a properties list
135 * \param locale the locale name
136 * \return true if error
139 int mlt_properties_set_lcnumeric( mlt_properties self, const char *locale )
143 if ( self && locale )
145 property_list *list = self->local;
147 #if defined(__GLIBC__) || defined(__DARWIN__)
149 freelocale( list->locale );
150 list->locale = newlocale( LC_NUMERIC_MASK, locale, NULL );
153 free( list->locale );
154 list->locale = strdup( locale );
163 /** Get the numeric locale for this properties object.
165 * Do not free the result.
166 * \public \memberof mlt_properties_s
167 * \param self a properties list
168 * \return the locale name if this properties has a specific locale it is using, NULL otherwise
171 const char* mlt_properties_get_lcnumeric( mlt_properties self )
173 property_list *list = self->local;
174 const char *result = NULL;
178 #if defined(__DARWIN__)
179 result = querylocale( LC_NUMERIC, list->locale );
180 #elif defined(__GLIBC__)
181 result = list->locale->__names[ LC_NUMERIC ];
183 result = list->locale;
189 static int load_properties( mlt_properties self, const char *filename )
192 FILE *file = fopen( filename, "r" );
194 // Load contents of file
199 char last[ 1024 ] = "";
201 // Read each string from the file
202 while( fgets( temp, 1024, file ) )
204 // Chomp the new line character from the string
205 int x = strlen( temp ) - 1;
206 if ( temp[x] == '\n' || temp[x] == '\r' )
209 // Check if the line starts with a .
210 if ( temp[ 0 ] == '.' )
213 sprintf( temp2, "%s%s", last, temp );
214 strcpy( temp, temp2 );
216 else if ( strchr( temp, '=' ) )
218 strcpy( last, temp );
219 *( strchr( last, '=' ) ) = '\0';
222 // Parse and set the property
223 if ( strcmp( temp, "" ) && temp[ 0 ] != '#' )
224 mlt_properties_parse( self, temp );
230 return file? 0 : errno;
233 /** Create a properties object by reading a .properties text file.
235 * Free the properties object with mlt_properties_close().
236 * \deprecated Please start using mlt_properties_parse_yaml().
237 * \public \memberof mlt_properties_s
238 * \param filename the absolute file name
239 * \return a new properties object
242 mlt_properties mlt_properties_load( const char *filename )
244 // Construct a standalone properties object
245 mlt_properties self = mlt_properties_new( );
248 load_properties( self, filename );
250 // Return the pointer
254 /** Set properties from a preset.
256 * Presets are typically installed to $prefix/share/mlt/presets/{type}/{service}/[{profile}/]{name}.
257 * For example, "/usr/share/mlt/presets/consumer/avformat/dv_ntsc_wide/DVD"
258 * could be an encoding preset for a widescreen NTSC DVD Video.
259 * Do not specify the type and service in the preset name parameter; these are
260 * inferred automatically from the service to which you are applying the preset.
261 * Using the example above and assuming you are calling this function on the
262 * avformat consumer, the name passed to the function should simply be DVD.
263 * Note that the profile portion of the path is optional, but a profile-specific
264 * preset with the same name as a more generic one is given a higher priority.
265 * \todo Look in a user-specific location - somewhere in the home directory.
267 * \public \memberof mlt_properties_s
268 * \param self a properties list
269 * \param name the name of a preset in a well-known location or the explicit path
270 * \return true if error
273 int mlt_properties_preset( mlt_properties self, const char *name )
275 struct stat stat_buff;
278 if ( !( self && name && strlen( name ) ) )
281 // See if name is an explicit file
282 if ( ! stat( name, &stat_buff ) )
284 return load_properties( self, name );
288 // Look for profile-specific preset before a generic one.
289 char *data = getenv( "MLT_PRESETS_PATH" );
290 const char *type = mlt_properties_get( self, "mlt_type" );
291 const char *service = mlt_properties_get( self, "mlt_service" );
292 const char *profile = mlt_environment( "MLT_PROFILE" );
297 data = strdup( data );
301 data = malloc( strlen( mlt_environment( "MLT_DATA" ) ) + strlen( PRESETS_DIR ) + 1 );
302 strcpy( data, mlt_environment( "MLT_DATA" ) );
303 strcat( data, PRESETS_DIR );
305 if ( data && type && service )
307 char *path = malloc( 5 + strlen(name) + strlen(data) + strlen(type) + strlen(service) + ( profile? strlen(profile) : 0 ) );
308 sprintf( path, "%s/%s/%s/%s/%s", data, type, service, profile, name );
309 if ( load_properties( self, path ) )
311 sprintf( path, "%s/%s/%s/%s", data, type, service, name );
312 error = load_properties( self, path );
325 /** Generate a hash key.
327 * \private \memberof mlt_properties_s
328 * \param name a string
332 static inline int generate_hash( const char *name )
334 unsigned int hash = 5381;
336 hash = hash * 33 + (unsigned int) ( *name ++ );
340 /** Copy a serializable property to a properties list that is mirroring this one.
342 * Special case - when a container (such as loader) is protecting another
343 * producer, we need to ensure that properties are passed through to the
345 * \private \memberof mlt_properties_s
346 * \param self a properties list
347 * \param name the name of the property to copy
350 static inline void mlt_properties_do_mirror( mlt_properties self, const char *name )
353 property_list *list = self->local;
354 if ( list->mirror != NULL )
356 char *value = mlt_properties_get( self, name );
358 mlt_properties_set( list->mirror, name, value );
362 /** Increment the reference count.
364 * \public \memberof mlt_properties_s
365 * \param self a properties list
366 * \return the new reference count
369 int mlt_properties_inc_ref( mlt_properties self )
374 property_list *list = self->local;
375 pthread_mutex_lock( &list->mutex );
376 result = ++ list->ref_count;
377 pthread_mutex_unlock( &list->mutex );
382 /** Decrement the reference count.
384 * \public \memberof mlt_properties_s
385 * \param self a properties list
386 * \return the new reference count
389 int mlt_properties_dec_ref( mlt_properties self )
394 property_list *list = self->local;
395 pthread_mutex_lock( &list->mutex );
396 result = -- list->ref_count;
397 pthread_mutex_unlock( &list->mutex );
402 /** Get the reference count.
404 * \public \memberof mlt_properties_s
405 * \param self a properties list
406 * \return the current reference count
409 int mlt_properties_ref_count( mlt_properties self )
413 property_list *list = self->local;
414 return list->ref_count;
419 /** Set a properties list to be a mirror copy of another.
421 * Note that this does not copy all existing properties. Rather, you must
422 * call this before setting the properties that you wish to copy.
423 * \public \memberof mlt_properties_s
424 * \param that the properties which will receive copies of the properties as they are set.
425 * \param self the properties to mirror
428 void mlt_properties_mirror( mlt_properties self, mlt_properties that )
431 property_list *list = self->local;
435 /** Copy all serializable properties to another properties list.
437 * \public \memberof mlt_properties_s
438 * \param self The properties to copy to
439 * \param that The properties to copy from
440 * \return true if error
443 int mlt_properties_inherit( mlt_properties self, mlt_properties that )
445 if ( !self || !that ) return 1;
446 int count = mlt_properties_count( that );
448 for ( i = 0; i < count; i ++ )
450 char *value = mlt_properties_get_value( that, i );
453 char *name = mlt_properties_get_name( that, i );
454 mlt_properties_set( self, name, value );
460 /** Pass all serializable properties that match a prefix to another properties object
462 * \warning The prefix is stripped from the name when it is set on the \p self properties list!
463 * For example a property named "foo.bar" will match prefix "foo.", but the property
464 * will be named simply "bar" on the receiving properties object.
465 * \public \memberof mlt_properties_s
466 * \param self the properties to copy to
467 * \param that The properties to copy from
468 * \param prefix the property names to match (required)
469 * \return true if error
472 int mlt_properties_pass( mlt_properties self, mlt_properties that, const char *prefix )
474 if ( !self || !that ) return 1;
475 int count = mlt_properties_count( that );
476 int length = strlen( prefix );
478 for ( i = 0; i < count; i ++ )
480 char *name = mlt_properties_get_name( that, i );
481 if ( !strncmp( name, prefix, length ) )
483 char *value = mlt_properties_get_value( that, i );
485 mlt_properties_set( self, name + length, value );
491 /** Locate a property by name.
493 * \private \memberof mlt_properties_s
494 * \param self a properties list
495 * \param name the property to lookup by name
496 * \return the property or NULL for failure
499 static inline mlt_property mlt_properties_find( mlt_properties self, const char *name )
501 if ( !self || !name ) return NULL;
502 property_list *list = self->local;
503 mlt_property value = NULL;
504 int key = generate_hash( name );
506 mlt_properties_lock( self );
508 int i = list->hash[ key ] - 1;
511 // Check if we're hashed
512 if ( list->count > 0 &&
513 !strcmp( list->name[ i ], name ) )
514 value = list->value[ i ];
517 for ( i = list->count - 1; value == NULL && i >= 0; i -- )
518 if ( !strcmp( list->name[ i ], name ) )
519 value = list->value[ i ];
521 mlt_properties_unlock( self );
526 /** Add a new property.
528 * \private \memberof mlt_properties_s
529 * \param self a properties list
530 * \param name the name of the new property
531 * \return the new property
534 static mlt_property mlt_properties_add( mlt_properties self, const char *name )
536 property_list *list = self->local;
537 int key = generate_hash( name );
540 mlt_properties_lock( self );
542 // Check that we have space and resize if necessary
543 if ( list->count == list->size )
546 list->name = realloc( list->name, list->size * sizeof( const char * ) );
547 list->value = realloc( list->value, list->size * sizeof( mlt_property ) );
550 // Assign name/value pair
551 list->name[ list->count ] = strdup( name );
552 list->value[ list->count ] = mlt_property_init( );
554 // Assign to hash table
555 if ( list->hash[ key ] == 0 )
556 list->hash[ key ] = list->count + 1;
558 // Return and increment count accordingly
559 result = list->value[ list->count ++ ];
561 mlt_properties_unlock( self );
566 /** Fetch a property by name and add one if not found.
568 * \private \memberof mlt_properties_s
569 * \param self a properties list
570 * \param name the property to lookup or add
571 * \return the property
574 static mlt_property mlt_properties_fetch( mlt_properties self, const char *name )
576 // Try to find an existing property first
577 mlt_property property = mlt_properties_find( self, name );
579 // If it wasn't found, create one
580 if ( property == NULL )
581 property = mlt_properties_add( self, name );
583 // Return the property
587 /** Copy a property to another properties list.
589 * \public \memberof mlt_properties_s
590 * \author Zach <zachary.drew@gmail.com>
591 * \param self the properties to copy to
592 * \param that the properties to copy from
593 * \param name the name of the property to copy
596 void mlt_properties_pass_property( mlt_properties self, mlt_properties that, const char *name )
598 // Make sure the source property isn't null.
599 mlt_property that_prop = mlt_properties_find( that, name );
600 if( that_prop == NULL )
603 mlt_property_pass( mlt_properties_fetch( self, name ), that_prop );
606 /** Copy all properties specified in a comma-separated list to another properties list.
608 * White space is also a delimiter.
609 * \public \memberof mlt_properties_s
610 * \author Zach <zachary.drew@gmail.com>
611 * \param self the properties to copy to
612 * \param that the properties to copy from
613 * \param list a delimited list of property names
614 * \return true if error
618 int mlt_properties_pass_list( mlt_properties self, mlt_properties that, const char *list )
620 if ( !self || !that || !list ) return 1;
621 char *props = strdup( list );
623 const char *delim = " ,\t\n"; // Any combination of spaces, commas, tabs, and newlines
628 count = strcspn( ptr, delim );
630 if( ptr[count] == '\0' )
633 ptr[count] = '\0'; // Make it a real string
635 mlt_properties_pass_property( self, that, ptr );
639 ptr += strspn( ptr, delim );
648 /** Set a property to a string.
650 * The property name "properties" is reserved to load the preset in \p value.
651 * When the value begins with '@' then it is interpreted as a very simple math
652 * expression containing only the +, -, *, and / operators.
653 * The event "property-changed" is fired after the property has been set.
655 * This makes a copy of the string value you supply.
656 * \public \memberof mlt_properties_s
657 * \param self a properties list
658 * \param name the property to set
659 * \param value the property's new value
660 * \return true if error
663 int mlt_properties_set( mlt_properties self, const char *name, const char *value )
667 if ( !self || !name ) return error;
669 // Fetch the property to work with
670 mlt_property property = mlt_properties_fetch( self, name );
672 // Set it if not NULL
673 if ( property == NULL )
675 mlt_log( NULL, MLT_LOG_FATAL, "Whoops - %s not found (should never occur)\n", name );
677 else if ( value == NULL )
679 error = mlt_property_set_string( property, value );
680 mlt_properties_do_mirror( self, name );
682 else if ( *value != '@' )
684 error = mlt_property_set_string( property, value );
685 mlt_properties_do_mirror( self, name );
686 if ( !strcmp( name, "properties" ) )
687 mlt_properties_preset( self, value );
689 else if ( value[ 0 ] == '@' )
698 while ( *value != '\0' )
700 int length = strcspn( value, "+-*/" );
702 // Get the identifier
703 strncpy( id, value, length );
707 // Determine the value
708 if ( isdigit( id[ 0 ] ) )
710 #if defined(__GLIBC__) || defined(__DARWIN__)
711 property_list *list = self->local;
713 current = strtod_l( id, NULL, list->locale );
716 current = strtod( id, NULL );
720 current = mlt_properties_get_double( self, id );
723 // Apply the operation
736 total = total / current;
741 op = *value != '\0' ? *value ++ : ' ';
744 error = mlt_property_set_double( property, total );
745 mlt_properties_do_mirror( self, name );
748 mlt_events_fire( self, "property-changed", name, NULL );
753 /** Set or default a property to a string.
755 * This makes a copy of the string value you supply.
756 * \public \memberof mlt_properties_s
757 * \param self a properties list
758 * \param name the property to set
759 * \param value the string value to set or NULL to use the default
760 * \param def the default string if value is NULL
761 * \return true if error
764 int mlt_properties_set_or_default( mlt_properties self, const char *name, const char *value, const char *def )
766 return mlt_properties_set( self, name, value == NULL ? def : value );
769 /** Get a string value by name.
771 * Do not free the returned string. It's lifetime is controlled by the property
772 * and this properties object.
773 * \public \memberof mlt_properties_s
774 * \param self a properties list
775 * \param name the property to get
776 * \return the property's string value or NULL if it does not exist
779 char *mlt_properties_get( mlt_properties self, const char *name )
782 mlt_property value = mlt_properties_find( self, name );
785 property_list *list = self->local;
786 result = mlt_property_get_string_l( value, list->locale );
791 /** Get a property name by index.
793 * Do not free the returned string.
794 * \public \memberof mlt_properties_s
795 * \param self a properties list
796 * \param index the numeric index of the property
797 * \return the name of the property or NULL if index is out of range
800 char *mlt_properties_get_name( mlt_properties self, int index )
802 if ( !self ) return NULL;
803 property_list *list = self->local;
804 if ( index >= 0 && index < list->count )
805 return list->name[ index ];
809 /** Get a property's string value by index.
811 * Do not free the returned string.
812 * \public \memberof mlt_properties_s
813 * \param self a properties list
814 * \param index the numeric index of the property
815 * \return the property value as a string or NULL if the index is out of range
818 char *mlt_properties_get_value( mlt_properties self, int index )
820 if ( !self ) return NULL;
821 property_list *list = self->local;
822 if ( index >= 0 && index < list->count )
823 return mlt_property_get_string_l( list->value[ index ], list->locale );
827 /** Get a data value by index.
829 * Do not free the returned pointer if you supplied a destructor function when you
831 * \public \memberof mlt_properties_s
832 * \param self a properties list
833 * \param index the numeric index of the property
834 * \param[out] size the size of the binary data in bytes or NULL if the index is out of range
837 void *mlt_properties_get_data_at( mlt_properties self, int index, int *size )
839 if ( !self ) return NULL;
840 property_list *list = self->local;
841 if ( index >= 0 && index < list->count )
842 return mlt_property_get_data( list->value[ index ], size );
846 /** Return the number of items in the list.
848 * \public \memberof mlt_properties_s
849 * \param self a properties list
850 * \return the number of property objects or -1 if error
853 int mlt_properties_count( mlt_properties self )
855 if ( !self ) return -1;
856 property_list *list = self->local;
860 /** Set a value by parsing a name=value string.
862 * \public \memberof mlt_properties_s
863 * \param self a properties list
864 * \param namevalue a string containing name and value delimited by '='
865 * \return true if there was an error
868 int mlt_properties_parse( mlt_properties self, const char *namevalue )
870 if ( !self ) return 1;
871 char *name = strdup( namevalue );
874 char *ptr = strchr( name, '=' );
882 value = strdup( ptr );
887 value = strdup( ptr );
888 if ( value != NULL && value[ strlen( value ) - 1 ] == '\"' )
889 value[ strlen( value ) - 1 ] = '\0';
894 value = strdup( "" );
897 error = mlt_properties_set( self, name, value );
905 /** Get an integer associated to the name.
907 * \public \memberof mlt_properties_s
908 * \param self a properties list
909 * \param name the property to get
910 * \return The integer value, 0 if not found (which may also be a legitimate value)
913 int mlt_properties_get_int( mlt_properties self, const char *name )
916 mlt_property value = mlt_properties_find( self, name );
919 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
920 double fps = mlt_profile_fps( profile );
921 property_list *list = self->local;
922 result = mlt_property_get_int( value, fps, list->locale );
927 /** Set a property to an integer value.
929 * \public \memberof mlt_properties_s
930 * \param self a properties list
931 * \param name the property to set
932 * \param value the integer
933 * \return true if error
936 int mlt_properties_set_int( mlt_properties self, const char *name, int value )
940 if ( !self || !name ) return error;
942 // Fetch the property to work with
943 mlt_property property = mlt_properties_fetch( self, name );
945 // Set it if not NULL
946 if ( property != NULL )
948 error = mlt_property_set_int( property, value );
949 mlt_properties_do_mirror( self, name );
952 mlt_events_fire( self, "property-changed", name, NULL );
957 /** Get a 64-bit integer associated to the name.
959 * \public \memberof mlt_properties_s
960 * \param self a properties list
961 * \param name the property to get
962 * \return the integer value, 0 if not found (which may also be a legitimate value)
965 int64_t mlt_properties_get_int64( mlt_properties self, const char *name )
967 mlt_property value = mlt_properties_find( self, name );
968 return value == NULL ? 0 : mlt_property_get_int64( value );
971 /** Set a property to a 64-bit integer value.
973 * \public \memberof mlt_properties_s
974 * \param self a properties list
975 * \param name the property to set
976 * \param value the integer
977 * \return true if error
980 int mlt_properties_set_int64( mlt_properties self, const char *name, int64_t value )
984 if ( !self || !name ) return error;
986 // Fetch the property to work with
987 mlt_property property = mlt_properties_fetch( self, name );
989 // Set it if not NULL
990 if ( property != NULL )
992 error = mlt_property_set_int64( property, value );
993 mlt_properties_do_mirror( self, name );
996 mlt_events_fire( self, "property-changed", name, NULL );
1001 /** Get a floating point value associated to the name.
1003 * \public \memberof mlt_properties_s
1004 * \param self a properties list
1005 * \param name the property to get
1006 * \return the floating point, 0 if not found (which may also be a legitimate value)
1009 double mlt_properties_get_double( mlt_properties self, const char *name )
1012 mlt_property value = mlt_properties_find( self, name );
1015 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
1016 double fps = mlt_profile_fps( profile );
1017 property_list *list = self->local;
1018 result = mlt_property_get_double( value, fps, list->locale );
1023 /** Set a property to a floating point value.
1025 * \public \memberof mlt_properties_s
1026 * \param self a properties list
1027 * \param name the property to set
1028 * \param value the floating point value
1029 * \return true if error
1032 int mlt_properties_set_double( mlt_properties self, const char *name, double value )
1036 if ( !self || !name ) return error;
1038 // Fetch the property to work with
1039 mlt_property property = mlt_properties_fetch( self, name );
1041 // Set it if not NULL
1042 if ( property != NULL )
1044 error = mlt_property_set_double( property, value );
1045 mlt_properties_do_mirror( self, name );
1048 mlt_events_fire( self, "property-changed", name, NULL );
1053 /** Get a position value associated to the name.
1055 * \public \memberof mlt_properties_s
1056 * \param self a properties list
1057 * \param name the property to get
1058 * \return the position, 0 if not found (which may also be a legitimate value)
1061 mlt_position mlt_properties_get_position( mlt_properties self, const char *name )
1063 mlt_position result = 0;
1064 mlt_property value = mlt_properties_find( self, name );
1067 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
1068 double fps = mlt_profile_fps( profile );
1069 property_list *list = self->local;
1070 result = mlt_property_get_position( value, fps, list->locale );
1075 /** Set a property to a position value.
1077 * \public \memberof mlt_properties_s
1078 * \param self a properties list
1079 * \param name the property to get
1080 * \param value the position
1081 * \return true if error
1084 int mlt_properties_set_position( mlt_properties self, const char *name, mlt_position value )
1088 if ( !self || !name ) return error;
1090 // Fetch the property to work with
1091 mlt_property property = mlt_properties_fetch( self, name );
1093 // Set it if not NULL
1094 if ( property != NULL )
1096 error = mlt_property_set_position( property, value );
1097 mlt_properties_do_mirror( self, name );
1100 mlt_events_fire( self, "property-changed", name, NULL );
1105 /** Get a binary data value associated to the name.
1107 * Do not free the returned pointer if you supplied a destructor function
1108 * when you set this property.
1109 * \public \memberof mlt_properties_s
1110 * \param self a properties list
1111 * \param name the property to get
1112 * \param[out] length The size of the binary data in bytes, if available (often it is not, you should know)
1115 void *mlt_properties_get_data( mlt_properties self, const char *name, int *length )
1117 mlt_property value = mlt_properties_find( self, name );
1118 return value == NULL ? NULL : mlt_property_get_data( value, length );
1121 /** Store binary data as a property.
1123 * \public \memberof mlt_properties_s
1124 * \param self a properties list
1125 * \param name the property to set
1126 * \param value an opaque pointer to binary data
1127 * \param length the size of the binary data in bytes (optional)
1128 * \param destroy a function to deallocate the binary data when the property is closed (optional)
1129 * \param serialise a function that can serialize the binary data as text (optional)
1130 * \return true if error
1133 int mlt_properties_set_data( mlt_properties self, const char *name, void *value, int length, mlt_destructor destroy, mlt_serialiser serialise )
1137 if ( !self || !name ) return error;
1139 // Fetch the property to work with
1140 mlt_property property = mlt_properties_fetch( self, name );
1142 // Set it if not NULL
1143 if ( property != NULL )
1144 error = mlt_property_set_data( property, value, length, destroy, serialise );
1146 mlt_events_fire( self, "property-changed", name, NULL );
1151 /** Rename a property.
1153 * \public \memberof mlt_properties_s
1154 * \param self a properties list
1155 * \param source the property to rename
1156 * \param dest the new name
1157 * \return true if the name is already in use
1160 int mlt_properties_rename( mlt_properties self, const char *source, const char *dest )
1162 mlt_property value = mlt_properties_find( self, dest );
1164 if ( value == NULL )
1166 property_list *list = self->local;
1170 mlt_properties_lock( self );
1171 for ( i = 0; i < list->count; i ++ )
1173 if ( !strcmp( list->name[ i ], source ) )
1175 free( list->name[ i ] );
1176 list->name[ i ] = strdup( dest );
1177 list->hash[ generate_hash( dest ) ] = i + 1;
1181 mlt_properties_unlock( self );
1184 return value != NULL;
1187 /** Dump the properties to a file handle.
1189 * \public \memberof mlt_properties_s
1190 * \param self a properties list
1191 * \param output a file handle
1194 void mlt_properties_dump( mlt_properties self, FILE *output )
1196 if ( !self || !output ) return;
1197 property_list *list = self->local;
1199 for ( i = 0; i < list->count; i ++ )
1200 if ( mlt_properties_get( self, list->name[ i ] ) != NULL )
1201 fprintf( output, "%s=%s\n", list->name[ i ], mlt_properties_get( self, list->name[ i ] ) );
1204 /** Output the properties to a file handle.
1206 * This version includes reference counts and does not put each property on a new line.
1207 * \public \memberof mlt_properties_s
1208 * \param self a properties pointer
1209 * \param title a string to preface the output
1210 * \param output a file handle
1212 void mlt_properties_debug( mlt_properties self, const char *title, FILE *output )
1214 if ( !self || !output ) return;
1215 if ( output == NULL ) output = stderr;
1216 fprintf( output, "%s: ", title );
1219 property_list *list = self->local;
1221 fprintf( output, "[ ref=%d", list->ref_count );
1222 for ( i = 0; i < list->count; i ++ )
1223 if ( mlt_properties_get( self, list->name[ i ] ) != NULL )
1224 fprintf( output, ", %s=%s", list->name[ i ], mlt_properties_get( self, list->name[ i ] ) );
1226 fprintf( output, ", %s=%p", list->name[ i ], mlt_properties_get_data( self, list->name[ i ], NULL ) );
1227 fprintf( output, " ]" );
1229 fprintf( output, "\n" );
1232 /** Save the properties to a file by name.
1234 * This uses the dump format - one line per property.
1235 * \public \memberof mlt_properties_s
1236 * \param self a properties list
1237 * \param filename the name of a file to create or overwrite
1238 * \return true if there was an error
1241 int mlt_properties_save( mlt_properties self, const char *filename )
1244 if ( !self || !filename ) return error;
1245 FILE *f = fopen( filename, "w" );
1248 mlt_properties_dump( self, f );
1255 /* This is a very basic cross platform fnmatch replacement - it will fail in
1256 * many cases, but for the basic *.XXX and YYY*.XXX, it will work ok.
1259 /** Test whether a filename or pathname matches a shell-style pattern.
1261 * \private \memberof mlt_properties_s
1262 * \param wild a string containing a wildcard pattern
1263 * \param file the name of a file to test against
1264 * \return true if the file name matches the wildcard pattern
1267 static int mlt_fnmatch( const char *wild, const char *file )
1272 while( f < strlen( file ) && w < strlen( wild ) )
1274 if ( wild[ w ] == '*' )
1277 if ( w == strlen( wild ) )
1279 while ( f != strlen( file ) && tolower( file[ f ] ) != tolower( wild[ w ] ) )
1282 else if ( wild[ w ] == '?' || tolower( file[ f ] ) == tolower( wild[ w ] ) )
1287 else if ( wild[ 0 ] == '*' )
1297 return strlen( file ) == f && strlen( wild ) == w;
1300 /** Compare the string or serialized value of two properties.
1302 * \private \memberof mlt_properties_s
1303 * \param self a property
1304 * \param that a property
1305 * \return < 0 if \p self less than \p that, 0 if equal, or > 0 if \p self is greater than \p that
1308 static int mlt_compare( const void *self, const void *that )
1310 return strcmp( mlt_property_get_string( *( const mlt_property * )self ), mlt_property_get_string( *( const mlt_property * )that ) );
1313 /** Get the contents of a directory.
1315 * Obtains an optionally sorted list of the files found in a directory with a specific wild card.
1316 * Entries in the list have a numeric name (running from 0 to count - 1). Only values change
1317 * position if sort is enabled. Designed to be posix compatible (linux, os/x, mingw etc).
1318 * \public \memberof mlt_properties_s
1319 * \param self a properties list
1320 * \param dirname the name of the directory
1321 * \param pattern a wildcard pattern to filter the directory listing
1322 * \param sort Do you want to sort the directory listing?
1323 * \return the number of items in the directory listing
1326 int mlt_properties_dir_list( mlt_properties self, const char *dirname, const char *pattern, int sort )
1328 DIR *dir = opendir( dirname );
1333 struct dirent *de = readdir( dir );
1334 char fullname[ 1024 ];
1337 sprintf( key, "%d", mlt_properties_count( self ) );
1338 snprintf( fullname, 1024, "%s/%s", dirname, de->d_name );
1339 if ( pattern == NULL )
1340 mlt_properties_set( self, key, fullname );
1341 else if ( de->d_name[ 0 ] != '.' && mlt_fnmatch( pattern, de->d_name ) )
1342 mlt_properties_set( self, key, fullname );
1343 de = readdir( dir );
1349 if ( sort && mlt_properties_count( self ) )
1351 property_list *list = self->local;
1352 mlt_properties_lock( self );
1353 qsort( list->value, mlt_properties_count( self ), sizeof( mlt_property ), mlt_compare );
1354 mlt_properties_unlock( self );
1357 return mlt_properties_count( self );
1360 /** Close a properties object.
1362 * Deallocates the properties object and everything it contains.
1363 * \public \memberof mlt_properties_s
1364 * \param self a properties object
1367 void mlt_properties_close( mlt_properties self )
1369 if ( self != NULL && mlt_properties_dec_ref( self ) <= 0 )
1371 if ( self->close != NULL )
1373 self->close( self->close_object );
1377 property_list *list = self->local;
1380 #if _MLT_PROPERTY_CHECKS_ == 1
1382 mlt_properties_debug( self, "Closing", stderr );
1385 #ifdef _MLT_PROPERTY_CHECKS_
1386 // Increment destroyed count
1387 properties_destroyed ++;
1389 // Show current stats - these should match when the app is closed
1390 mlt_log( NULL, MLT_LOG_DEBUG, "Created %d, destroyed %d\n", properties_created, properties_destroyed );
1393 // Clean up names and values
1394 for ( index = list->count - 1; index >= 0; index -- )
1396 mlt_property_close( list->value[ index ] );
1397 free( list->name[ index ] );
1400 #if defined(__GLIBC__) || defined(__DARWIN__)
1403 freelocale( list->locale );
1406 free( list->locale );
1409 // Clear up the list
1410 pthread_mutex_destroy( &list->mutex );
1412 free( list->value );
1415 // Free self now if self has no child
1416 if ( self->child == NULL )
1422 /** Determine if the properties list is really just a sequence or ordered list.
1424 * \public \memberof mlt_properties_s
1425 * \param properties a properties list
1426 * \return true if all of the property names are numeric (a sequence)
1429 int mlt_properties_is_sequence( mlt_properties properties )
1432 int n = mlt_properties_count( properties );
1433 for ( i = 0; i < n; i++ )
1434 if ( ! isdigit( mlt_properties_get_name( properties, i )[0] ) )
1439 /** \brief YAML Tiny Parser context structure
1441 * YAML is a nifty text format popular in the Ruby world as a cleaner,
1442 * less verbose alternative to XML. See this Wikipedia topic for an overview:
1443 * http://en.wikipedia.org/wiki/YAML
1444 * The YAML specification is at:
1446 * YAML::Tiny is a Perl module that specifies a subset of YAML that we are
1447 * using here (for the same reasons):
1448 * http://search.cpan.org/~adamk/YAML-Tiny-1.25/lib/YAML/Tiny.pm
1452 struct yaml_parser_context
1457 mlt_deque index_stack;
1460 unsigned int block_indent;
1463 typedef struct yaml_parser_context *yaml_parser;
1465 /** Remove spaces from the left side of a string.
1467 * \param s the string to trim
1468 * \return the number of characters removed
1471 static unsigned int ltrim( char **s )
1475 int n = strlen( c );
1476 for ( i = 0; i < n && *c == ' '; i++, c++ );
1481 /** Remove spaces from the right side of a string.
1483 * \param s the string to trim
1484 * \return the number of characters removed
1487 static unsigned int rtrim( char *s )
1489 int n = strlen( s );
1491 for ( i = n; i > 0 && s[i - 1] == ' '; --i )
1496 /** Parse a line of YAML Tiny.
1498 * Adds a property if needed.
1499 * \private \memberof yaml_parser_context
1500 * \param context a YAML Tiny Parser context
1501 * \param namevalue a line of YAML Tiny
1502 * \return true if there was an error
1505 static int parse_yaml( yaml_parser context, const char *namevalue )
1507 char *name_ = strdup( namevalue );
1511 char *ptr = strchr( name, ':' );
1512 unsigned int indent = ltrim( &name );
1513 mlt_properties properties = mlt_deque_peek_back( context->stack );
1515 // Ascending one more levels in the tree
1516 if ( indent < context->level )
1519 unsigned int n = ( context->level - indent ) / 2;
1520 for ( i = 0; i < n; i++ )
1522 mlt_deque_pop_back( context->stack );
1523 context->index = mlt_deque_pop_back_int( context->index_stack );
1525 properties = mlt_deque_peek_back( context->stack );
1526 context->level = indent;
1529 // Descending a level in the tree
1530 else if ( indent > context->level && context->block == 0 )
1532 context->level = indent;
1535 // If there is a colon that is not part of a block
1536 if ( ptr && ( indent == context->level ) )
1538 // Reset block processing
1539 if ( context->block_name )
1541 free( context->block_name );
1542 context->block_name = NULL;
1546 // Terminate the name and setup the value pointer
1550 char *comment = strchr( ptr, '#' );
1556 // Trim leading and trailing spaces from bare value
1560 // No value means a child
1561 if ( strcmp( ptr, "" ) == 0 )
1563 mlt_properties child = mlt_properties_new();
1564 mlt_properties_set_lcnumeric( child, mlt_properties_get_lcnumeric( properties ) );
1565 mlt_properties_set_data( properties, name, child, 0,
1566 ( mlt_destructor )mlt_properties_close, NULL );
1567 mlt_deque_push_back( context->stack, child );
1568 mlt_deque_push_back_int( context->index_stack, context->index );
1574 // A dash indicates a sequence item
1575 if ( name[0] == '-' )
1577 mlt_properties child = mlt_properties_new();
1580 mlt_properties_set_lcnumeric( child, mlt_properties_get_lcnumeric( properties ) );
1581 snprintf( key, sizeof(key), "%d", context->index++ );
1582 mlt_properties_set_data( properties, key, child, 0,
1583 ( mlt_destructor )mlt_properties_close, NULL );
1584 mlt_deque_push_back( context->stack, child );
1585 mlt_deque_push_back_int( context->index_stack, context->index );
1588 context->level += ltrim( &name ) + 1;
1596 value = strdup( ptr );
1597 if ( value && value[ strlen( value ) - 1 ] == '\"' )
1598 value[ strlen( value ) - 1 ] = 0;
1601 // Value is folded or unfolded block
1602 else if ( *ptr == '|' || *ptr == '>' )
1604 context->block = *ptr;
1605 context->block_name = strdup( name );
1606 context->block_indent = 0;
1607 value = strdup( "" );
1613 value = strdup( ptr );
1617 // A list of scalars
1618 else if ( name[0] == '-' )
1620 // Reset block processing
1621 if ( context->block_name )
1623 free( context->block_name );
1624 context->block_name = NULL;
1630 snprintf( key, sizeof(key), "%d", context->index++ );
1634 char *comment = strchr( ptr, '#' );
1638 // Trim leading and trailing spaces from bare value
1646 value = strdup( ptr );
1647 if ( value && value[ strlen( value ) - 1 ] == '\"' )
1648 value[ strlen( value ) - 1 ] = 0;
1651 // Value is folded or unfolded block
1652 else if ( *ptr == '|' || *ptr == '>' )
1654 context->block = *ptr;
1655 context->block_name = strdup( key );
1656 context->block_indent = 0;
1657 value = strdup( "" );
1663 value = strdup( ptr );
1667 name = name_ = strdup( key );
1671 else if ( context->block == '|' )
1673 if ( context->block_indent == 0 )
1674 context->block_indent = indent;
1675 if ( indent > context->block_indent )
1676 name = &name_[ context->block_indent ];
1678 char *old_value = mlt_properties_get( properties, context->block_name );
1679 value = calloc( 1, strlen( old_value ) + strlen( name ) + 2 );
1680 strcpy( value, old_value );
1681 if ( strcmp( old_value, "" ) )
1682 strcat( value, "\n" );
1683 strcat( value, name );
1684 name = context->block_name;
1688 else if ( context->block == '>' )
1692 char *old_value = mlt_properties_get( properties, context->block_name );
1694 // Blank line (prepended with spaces) is new line
1695 if ( strcmp( name, "" ) == 0 )
1697 value = calloc( 1, strlen( old_value ) + 2 );
1698 strcat( value, old_value );
1699 strcat( value, "\n" );
1701 // Concatenate with space
1704 value = calloc( 1, strlen( old_value ) + strlen( name ) + 2 );
1705 strcat( value, old_value );
1706 if ( strcmp( old_value, "" ) && old_value[ strlen( old_value ) - 1 ] != '\n' )
1707 strcat( value, " " );
1708 strcat( value, name );
1710 name = context->block_name;
1715 value = strdup( "" );
1718 error = mlt_properties_set( properties, name, value );
1720 if ( !strcmp( name, "LC_NUMERIC" ) )
1721 mlt_properties_set_lcnumeric( properties, value );
1729 /** Parse a YAML Tiny file by name.
1731 * \public \memberof mlt_properties_s
1732 * \param filename the name of a text file containing YAML Tiny
1733 * \return a new properties list
1736 mlt_properties mlt_properties_parse_yaml( const char *filename )
1738 // Construct a standalone properties object
1739 mlt_properties self = mlt_properties_new( );
1744 FILE *file = fopen( filename, "r" );
1746 // Load contents of file
1751 char *ptemp = &temp[ 0 ];
1753 // Default to LC_NUMERIC = C
1754 mlt_properties_set_lcnumeric( self, "C" );
1757 yaml_parser context = calloc( 1, sizeof( struct yaml_parser_context ) );
1758 context->stack = mlt_deque_init();
1759 context->index_stack = mlt_deque_init();
1760 mlt_deque_push_back( context->stack, self );
1761 mlt_deque_push_back_int( context->index_stack, 0 );
1763 // Read each string from the file
1764 while( fgets( temp, 1024, file ) )
1766 // Check for end-of-stream
1767 if ( strncmp( ptemp, "...", 3 ) == 0 )
1771 temp[ strlen( temp ) - 1 ] = '\0';
1773 // Skip blank lines, comment lines, and document separator
1774 if ( strcmp( ptemp, "" ) && ptemp[ 0 ] != '#' && strncmp( ptemp, "---", 3 )
1775 && strncmp( ptemp, "%YAML", 5 ) && strncmp( ptemp, "% YAML", 6 ) )
1776 parse_yaml( context, temp );
1781 mlt_deque_close( context->stack );
1782 mlt_deque_close( context->index_stack );
1783 if ( context->block_name )
1784 free( context->block_name );
1789 // Return the pointer
1794 * YAML Tiny Serializer
1797 /** How many bytes to grow at a time */
1798 #define STRBUF_GROWTH (1024)
1800 /** \brief Private to mlt_properties_s, a self-growing buffer for building strings
1810 typedef struct strbuf_s *strbuf;
1812 /** Create a new string buffer
1814 * \private \memberof strbuf_s
1815 * \return a new string buffer
1818 static strbuf strbuf_new( )
1820 strbuf buffer = calloc( 1, sizeof( struct strbuf_s ) );
1821 buffer->size = STRBUF_GROWTH;
1822 buffer->string = calloc( 1, buffer->size );
1826 /** Destroy a string buffer
1828 * \private \memberof strbuf_s
1829 * \param buffer the string buffer to close
1832 static void strbuf_close( strbuf buffer )
1834 // We do not free buffer->string; strbuf user must save that pointer
1840 /** Format a string into a string buffer
1842 * A variable number of arguments follows the format string - one for each
1844 * \private \memberof strbuf_s
1845 * \param buffer the string buffer to write into
1846 * \param format a string that contains text and formatting instructions
1847 * \return the formatted string
1850 static char *strbuf_printf( strbuf buffer, const char *format, ... )
1852 while ( buffer->string )
1855 va_start( ap, format );
1856 size_t len = strlen( buffer->string );
1857 size_t remain = buffer->size - len - 1;
1858 int need = vsnprintf( buffer->string + len, remain, format, ap );
1860 if ( need > -1 && need < remain )
1862 buffer->string[ len ] = 0;
1863 buffer->size += need + STRBUF_GROWTH;
1864 buffer->string = realloc( buffer->string, buffer->size );
1866 return buffer->string;
1869 /** Indent a line of YAML Tiny.
1871 * \private \memberof strbuf_s
1872 * \param output a string buffer
1873 * \param indent the number of spaces to indent
1876 static inline void indent_yaml( strbuf output, int indent )
1879 for ( j = 0; j < indent; j++ )
1880 strbuf_printf( output, " " );
1883 static void strbuf_escape( strbuf output, const char *value, char c )
1885 char *v = strdup( value );
1887 char *found = strchr( s, c );
1892 strbuf_printf( output, "%s\\%c", s, c );
1894 found = strchr( s, c );
1896 strbuf_printf( output, "%s", s );
1900 /** Convert a line string into a YAML block literal.
1902 * \private \memberof strbuf_s
1903 * \param output a string buffer
1904 * \param value the string to format as a block literal
1905 * \param indent the number of spaces to indent
1908 static void output_yaml_block_literal( strbuf output, const char *value, int indent )
1910 char *v = strdup( value );
1912 char *eol = strchr( sol, '\n' );
1916 indent_yaml( output, indent );
1918 strbuf_printf( output, "%s\n", sol );
1920 eol = strchr( sol, '\n' );
1922 indent_yaml( output, indent );
1923 strbuf_printf( output, "%s\n", sol );
1927 /** Recursively serialize a properties list into a string buffer as YAML Tiny.
1929 * \private \memberof mlt_properties_s
1930 * \param self a properties list
1931 * \param output a string buffer to hold the serialized YAML Tiny
1932 * \param indent the number of spaces to indent (for recursion, initialize to 0)
1933 * \param is_parent_sequence Is this properties list really just a sequence (for recursion, initialize to 0)?
1936 static void serialise_yaml( mlt_properties self, strbuf output, int indent, int is_parent_sequence )
1938 property_list *list = self->local;
1941 for ( i = 0; i < list->count; i ++ )
1943 // This implementation assumes that all data elements are property lists.
1944 // Unfortunately, we do not have run time type identification.
1945 mlt_properties child = mlt_property_get_data( list->value[ i ], NULL );
1947 if ( mlt_properties_is_sequence( self ) )
1949 // Ignore hidden/non-serialisable items
1950 if ( list->name[ i ][ 0 ] != '_' )
1952 // Indicate a sequence item
1953 indent_yaml( output, indent );
1954 strbuf_printf( output, "- " );
1956 // If the value can be represented as a string
1957 const char *value = mlt_properties_get( self, list->name[ i ] );
1958 if ( value && strcmp( value, "" ) )
1960 // Determine if this is an unfolded block literal
1961 if ( strchr( value, '\n' ) )
1963 strbuf_printf( output, "|\n" );
1964 output_yaml_block_literal( output, value, indent + strlen( list->name[ i ] ) + strlen( "|" ) );
1966 else if ( strchr( value, ':' ) || strchr( value, '[' ) )
1968 strbuf_printf( output, "\"" );
1969 strbuf_escape( output, value, '"' );
1970 strbuf_printf( output, "\"\n", value );
1974 strbuf_printf( output, "%s\n", value );
1980 serialise_yaml( child, output, indent + 2, 1 );
1984 // Assume this is a normal map-oriented properties list
1985 const char *value = mlt_properties_get( self, list->name[ i ] );
1987 // Ignore hidden/non-serialisable items
1988 // If the value can be represented as a string
1989 if ( list->name[ i ][ 0 ] != '_' && value && strcmp( value, "" ) )
1991 if ( is_parent_sequence == 0 )
1992 indent_yaml( output, indent );
1994 is_parent_sequence = 0;
1996 // Determine if this is an unfolded block literal
1997 if ( strchr( value, '\n' ) )
1999 strbuf_printf( output, "%s: |\n", list->name[ i ] );
2000 output_yaml_block_literal( output, value, indent + strlen( list->name[ i ] ) + strlen( ": " ) );
2002 else if ( strchr( value, ':' ) || strchr( value, '[' ) )
2004 strbuf_printf( output, "%s: \"", list->name[ i ] );
2005 strbuf_escape( output, value, '"' );
2006 strbuf_printf( output, "\"\n" );
2010 strbuf_printf( output, "%s: %s\n", list->name[ i ], value );
2014 // Output a child as a map item
2017 indent_yaml( output, indent );
2018 strbuf_printf( output, "%s:\n", list->name[ i ] );
2021 serialise_yaml( child, output, indent + 2, 0 );
2027 /** Serialize a properties list as a string of YAML Tiny.
2029 * The caller MUST free the returned string!
2030 * This operates on properties containing properties as a hierarchical data
2032 * \public \memberof mlt_properties_s
2033 * \param self a properties list
2034 * \return a string containing YAML Tiny that represents the properties list
2037 char *mlt_properties_serialise_yaml( mlt_properties self )
2039 if ( !self ) return NULL;
2040 const char *lc_numeric = mlt_properties_get_lcnumeric( self );
2041 strbuf b = strbuf_new();
2042 strbuf_printf( b, "---\n" );
2043 mlt_properties_set_lcnumeric( self, "C" );
2044 serialise_yaml( self, b, 0, 0 );
2045 mlt_properties_set_lcnumeric( self, lc_numeric );
2046 strbuf_printf( b, "...\n" );
2047 char *ret = b->string;
2052 /** Protect a properties list against concurrent access.
2054 * \public \memberof mlt_properties_s
2055 * \param self a properties list
2058 void mlt_properties_lock( mlt_properties self )
2061 pthread_mutex_lock( &( ( property_list* )( self->local ) )->mutex );
2064 /** End protecting a properties list against concurrent access.
2066 * \public \memberof mlt_properties_s
2067 * \param self a properties list
2070 void mlt_properties_unlock( mlt_properties self )
2073 pthread_mutex_unlock( &( ( property_list* )( self->local ) )->mutex );
2076 /** Get a time string associated to the name.
2078 * Do not free the returned string. It's lifetime is controlled by the property.
2079 * \public \memberof mlt_properties_s
2080 * \param self a properties list
2081 * \param name the property to get
2082 * \param format the time format that you want
2083 * \return the property's time value or NULL if \p name does not exist or there is no profile
2086 char *mlt_properties_get_time( mlt_properties self, const char* name, mlt_time_format format )
2088 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2091 double fps = mlt_profile_fps( profile );
2092 mlt_property value = mlt_properties_find( self, name );
2093 property_list *list = self->local;
2094 return value == NULL ? NULL : mlt_property_get_time( value, format, fps, list->locale );
2099 /** Convert a frame count to a time string.
2101 * Do not free the returned string. It's lifetime is controlled by the property.
2102 * \public \memberof mlt_properties_s
2103 * \param self a properties list
2104 * \param frames the frame count to convert
2105 * \param format the time format that you want
2106 * \return the time string or NULL if error, e.g. there is no profile
2109 char *mlt_properties_frames_to_time( mlt_properties self, mlt_position frames, mlt_time_format format )
2111 const char *name = "_mlt_properties_time";
2112 mlt_properties_set_position( self, name, frames );
2113 return mlt_properties_get_time( self, name, format );
2116 /** Convert a time string to a frame count.
2118 * \public \memberof mlt_properties_s
2119 * \param self a properties list
2120 * \param time the time string to convert
2121 * \return a frame count or a negative value if error, e.g. there is no profile
2124 mlt_position mlt_properties_time_to_frames( mlt_properties self, const char *time )
2126 const char *name = "_mlt_properties_time";
2127 mlt_properties_set( self, name, time );
2128 return mlt_properties_get_position( self, name );
2131 /** Convert a numeric property to a tuple of color components.
2133 * If the property's string is red, green, blue, white, or black, then it
2134 * is converted to the corresponding opaque color tuple. Otherwise, the property
2135 * is fetched as an integer and then converted.
2136 * \public \memberof mlt_properties_s
2137 * \param self a properties list
2138 * \param name the property to get
2139 * \return a color structure
2142 mlt_color mlt_properties_get_color( mlt_properties self, const char* name )
2144 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2145 double fps = mlt_profile_fps( profile );
2146 property_list *list = self->local;
2147 mlt_property value = mlt_properties_find( self, name );
2148 mlt_color result = { 0xff, 0xff, 0xff, 0xff };
2151 const char *color = mlt_property_get_string_l( value, list->locale );
2152 unsigned int color_int = mlt_property_get_int( value, fps, list->locale );
2154 if ( !strcmp( color, "red" ) )
2160 else if ( !strcmp( color, "green" ) )
2166 else if ( !strcmp( color, "blue" ) )
2172 else if ( !strcmp( color, "black" ) )
2178 else if ( strcmp( color, "white" ) )
2180 result.r = ( color_int >> 24 ) & 0xff;
2181 result.g = ( color_int >> 16 ) & 0xff;
2182 result.b = ( color_int >> 8 ) & 0xff;
2183 result.a = ( color_int ) & 0xff;
2189 /** Set a property to an integer value by color.
2191 * \public \memberof mlt_properties_s
2192 * \param self a properties list
2193 * \param name the property to set
2194 * \param color the color
2195 * \return true if error
2198 int mlt_properties_set_color( mlt_properties self, const char *name, mlt_color color )
2202 if ( !self || !name ) return error;
2204 // Fetch the property to work with
2205 mlt_property property = mlt_properties_fetch( self, name );
2207 // Set it if not NULL
2208 if ( property != NULL )
2210 uint32_t value = ( color.r << 24 ) | ( color.g << 16 ) | ( color.b << 8 ) | color.a;
2211 error = mlt_property_set_int( property, value );
2212 mlt_properties_do_mirror( self, name );
2215 mlt_events_fire( self, "property-changed", name, NULL );
2220 /** Get a string value by name at a frame position.
2222 * Do not free the returned string. It's lifetime is controlled by the property
2223 * and this properties object.
2224 * \public \memberof mlt_properties_s
2225 * \param self a properties list
2226 * \param name the property to get
2227 * \param position the frame number
2228 * \param length the maximum number of frames when interpreting negative keyframe times,
2229 * <=0 if you don't care or need that
2230 * \return the property's string value or NULL if it does not exist
2233 char* mlt_properties_anim_get( mlt_properties self, const char *name, int position, int length )
2235 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2236 double fps = mlt_profile_fps( profile );
2237 mlt_property value = mlt_properties_find( self, name );
2238 property_list *list = self->local;
2239 return value == NULL ? NULL : mlt_property_anim_get_string( value, fps, list->locale, position, length );
2242 /** Set a property to a string at a frame position.
2244 * The event "property-changed" is fired after the property has been set.
2246 * This makes a copy of the string value you supply.
2247 * \public \memberof mlt_properties_s
2248 * \param self a properties list
2249 * \param name the property to set
2250 * \param value the property's new value
2251 * \param position the frame number
2252 * \param length the maximum number of frames when interpreting negative keyframe times,
2253 * <=0 if you don't care or need that
2254 * \return true if error
2257 int mlt_properties_anim_set( mlt_properties self, const char *name, const char *value, int position, int length )
2261 if ( !self || !name ) return error;
2263 // Fetch the property to work with
2264 mlt_property property = mlt_properties_fetch( self, name );
2266 // Set it if not NULL
2269 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2270 double fps = mlt_profile_fps( profile );
2271 property_list *list = self->local;
2272 error = mlt_property_anim_set_string( property, value,
2273 fps, list->locale, position, length );
2274 mlt_properties_do_mirror( self, name );
2277 mlt_events_fire( self, "property-changed", name, NULL );
2282 /** Get an integer associated to the name at a frame position.
2284 * \public \memberof mlt_properties_s
2285 * \param self a properties list
2286 * \param name the property to get
2287 * \param position the frame number
2288 * \param length the maximum number of frames when interpreting negative keyframe times,
2289 * <=0 if you don't care or need that
2290 * \return the integer value, 0 if not found (which may also be a legitimate value)
2293 int mlt_properties_anim_get_int( mlt_properties self, const char *name, int position, int length )
2295 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2296 double fps = mlt_profile_fps( profile );
2297 property_list *list = self->local;
2298 mlt_property value = mlt_properties_find( self, name );
2299 return value == NULL ? 0 : mlt_property_anim_get_int( value, fps, list->locale, position, length );
2302 /** Set a property to an integer value at a frame position.
2304 * \public \memberof mlt_properties_s
2305 * \param self a properties list
2306 * \param name the property to set
2307 * \param value the integer
2308 * \param position the frame number
2309 * \param length the maximum number of frames when interpreting negative keyframe times,
2310 * <=0 if you don't care or need that
2311 * \param keyframe_type the interpolation method for this keyframe
2312 * \return true if error
2315 int mlt_properties_anim_set_int( mlt_properties self, const char *name, int value,
2316 int position, int length, mlt_keyframe_type keyframe_type )
2320 if ( !self || !name ) return error;
2322 // Fetch the property to work with
2323 mlt_property property = mlt_properties_fetch( self, name );
2325 // Set it if not NULL
2326 if ( property != NULL )
2328 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2329 double fps = mlt_profile_fps( profile );
2330 property_list *list = self->local;
2331 error = mlt_property_anim_set_int( property, value, fps, list->locale, position, length, keyframe_type );
2332 mlt_properties_do_mirror( self, name );
2335 mlt_events_fire( self, "property-changed", name, NULL );
2340 /** Get a real number associated to the name at a frame position.
2342 * \public \memberof mlt_properties_s
2343 * \param self a properties list
2344 * \param name the property to get
2345 * \param position the frame number
2346 * \param length the maximum number of frames when interpreting negative keyframe times,
2347 * <=0 if you don't care or need that
2348 * \return the real number, 0 if not found (which may also be a legitimate value)
2351 double mlt_properties_anim_get_double( mlt_properties self, const char *name, int position, int length )
2353 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2354 double fps = mlt_profile_fps( profile );
2355 property_list *list = self->local;
2356 mlt_property value = mlt_properties_find( self, name );
2357 return value == NULL ? 0.0 : mlt_property_anim_get_double( value, fps, list->locale, position, length );
2360 /** Set a property to a real number at a frame position.
2362 * \public \memberof mlt_properties_s
2363 * \param self a properties list
2364 * \param name the property to set
2365 * \param value the real number
2366 * \param position the frame number
2367 * \param length the maximum number of frames when interpreting negative keyframe times,
2368 * <=0 if you don't care or need that
2369 * \param keyframe_type the interpolation method for this keyframe
2370 * \return true if error
2373 int mlt_properties_anim_set_double( mlt_properties self, const char *name, double value,
2374 int position, int length, mlt_keyframe_type keyframe_type )
2378 if ( !self || !name ) return error;
2380 // Fetch the property to work with
2381 mlt_property property = mlt_properties_fetch( self, name );
2383 // Set it if not NULL
2384 if ( property != NULL )
2386 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2387 double fps = mlt_profile_fps( profile );
2388 property_list *list = self->local;
2389 error = mlt_property_anim_set_double( property, value, fps, list->locale, position, length, keyframe_type );
2390 mlt_properties_do_mirror( self, name );
2393 mlt_events_fire( self, "property-changed", name, NULL );
2398 /** Get the animation associated to the name.
2400 * \public \memberof mlt_properties_s
2401 * \param self a properties list
2402 * \param name the property to get
2403 * \return The animation object or NULL if the property has no animation
2406 mlt_animation mlt_properties_get_animation( mlt_properties self, const char *name )
2408 mlt_property value = mlt_properties_find( self, name );
2409 return value == NULL ? NULL : mlt_property_get_animation( value );
2412 /** Set a property to a rectangle value.
2414 * \public \memberof mlt_properties_s
2415 * \param self a properties list
2416 * \param name the property to set
2417 * \param value the rectangle
2418 * \return true if error
2421 extern int mlt_properties_set_rect( mlt_properties self, const char *name, mlt_rect value )
2425 if ( !self || !name ) return error;
2427 // Fetch the property to work with
2428 mlt_property property = mlt_properties_fetch( self, name );
2430 // Set it if not NULL
2431 if ( property != NULL )
2433 error = mlt_property_set_rect( property, value );
2434 mlt_properties_do_mirror( self, name );
2437 mlt_events_fire( self, "property-changed", name, NULL );
2442 /** Get a rectangle associated to the name.
2444 * \public \memberof mlt_properties_s
2445 * \param self a properties list
2446 * \param name the property to get
2447 * \return the rectangle value, the rectangle fields will be DBL_MIN if not found
2450 extern mlt_rect mlt_properties_get_rect( mlt_properties self, const char* name )
2452 property_list *list = self->local;
2453 mlt_property value = mlt_properties_find( self, name );
2454 mlt_rect rect = { DBL_MIN, DBL_MIN, DBL_MIN, DBL_MIN, DBL_MIN };
2455 return value == NULL ? rect : mlt_property_get_rect( value, list->locale );
2458 /** Set a property to a rectangle value at a frame position.
2460 * \public \memberof mlt_properties_s
2461 * \param self a properties list
2462 * \param name the property to set
2463 * \param value the rectangle
2464 * \param position the frame number
2465 * \param length the maximum number of frames when interpreting negative keyframe times,
2466 * <=0 if you don't care or need that
2467 * \param keyframe_type the interpolation method for this keyframe
2468 * \return true if error
2471 extern int mlt_properties_anim_set_rect( mlt_properties self, const char *name, mlt_rect value,
2472 int position, int length , mlt_keyframe_type keyframe_type )
2476 if ( !self || !name ) return error;
2478 // Fetch the property to work with
2479 mlt_property property = mlt_properties_fetch( self, name );
2481 // Set it if not NULL
2482 if ( property != NULL )
2484 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2485 double fps = mlt_profile_fps( profile );
2486 property_list *list = self->local;
2487 error = mlt_property_anim_set_rect( property, value, fps, list->locale, position, length, keyframe_type );
2488 mlt_properties_do_mirror( self, name );
2491 mlt_events_fire( self, "property-changed", name, NULL );
2496 /** Get a rectangle associated to the name at a frame position.
2498 * \public \memberof mlt_properties_s
2499 * \param self a properties list
2500 * \param name the property to get
2501 * \param position the frame number
2502 * \param length the maximum number of frames when interpreting negative keyframe times,
2503 * <=0 if you don't care or need that
2504 * \return the rectangle value, the rectangle fields will be DBL_MIN if not found
2507 extern mlt_rect mlt_properties_anim_get_rect( mlt_properties self, const char *name, int position, int length )
2509 mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL );
2510 double fps = mlt_profile_fps( profile );
2511 property_list *list = self->local;
2512 mlt_property value = mlt_properties_find( self, name );
2513 mlt_rect rect = { DBL_MIN, DBL_MIN, DBL_MIN, DBL_MIN, DBL_MIN };
2514 return value == NULL ? rect : mlt_property_anim_get_rect( value, fps, list->locale, position, length );