RFC: MLT Properties 1.0

This is where I want to take mlt_properties (including mlt_property) before a 1.0 release.

• easier and faster to use as an array
• time value string
• color property
• rectangle property
• property animation

Array Usage

There are several places in the code that uses mlt_properties as a dynamic array by converting a number to string for a key. We should refactor that making it easier to use in that manner. Possibly we can make the need for a string key unnecessary. However, if we remove the need for a string key, we still need a way to serialize index to a numeric string in some contexts (not YAML).

Time Value String

Today when you request a number from a property created from a string, we have support for special string values like @expression and #color. Also, we have a SMIL clock-value parser in the xml producer. Now, consider SMTPE timecode or SMIL clock-value string. Today, when you ask for an int, it only converts numeric characters up to the first colon. We can easily detect colons and treat it as hours, minutes, seconds, and frames. We simply need a framerate. Nearly every properties object corresponds to a service, and all services have a special _profile property. So, we can easily get framerate for most occasions!

• hours and minutes are optional
• clock value is [[hh:]mm:]ss.{fraction of seconds}
• timecode is [[[hh:]mm:]ss:]ff where 'ff' is frames
• a semicolon as delimiter means drop-frame
• digits may be omitted, e.g. 3:: means 3 minutes; however, semi-colons are used to delimit keyframes in property animation. So, the combination of timecode, drop-frame, no frame digits, and property animation is not supported.
• mlt_properties_get_int() -> frames
• mlt_properties_get_double() -> seconds
• mlt_properties_get_int64() -> microseconds
• mlt_properites_get_position() -> frames
• mlt_properties_get_timestring(mlt_time_clock|mlt_time_smpte) -> converts int/position as frames or double as seconds to a time value string
• mlt_properties_get_time() reserved for a future mlt_time type?

If the string does not contain a colon or semi-colon, then one must use mlt_properties_get_position() to force interpret a string with decimal as seconds and return number of frames.

If the properties object does not contain a _profile, then like other parts of the code, it will assume dv_pal profile values. Code that makes temporary properties or uses it for some other purpose can either set _profile or deal with the consequences.

Color Property

This adds a new typedef struct mlt_color in mlt_types.h with fields for each color component: r, g, b, a. Then, add a new mlt_properties_get_color() that returns mlt_color. It looks like structures work ok in most swig bindings, but it should be tested. No "mlt class" should be needed - copy and pass the struct by value.

Rectangle Property

This combined with property animation obsoletes mlt_geometry. This adds a new typedef struct mlt_rect in mlt_types.h with fields for x, y, width, height, and opacity. Is distort really needed? It seems like that can be handled as a separate property - usually one wants distort to be all or nothing. Like time parsing needs framerate, mlt_geometry needs normalized width and height, but these are the same as the profile width and height, which, again, can be obtained through the _profile property.

Property Animation

See also PropertyAnimation for some earlier thinking on this. I am no longer thinking about mlt_keyframe and property groups but merely moving the geometry syntax and functions into mlt_properties. Instead of mlt_geometry_fetch, I am thinking about a mlt_properties_get_int_at, mlt_properties_get_double_at, and so on where 'at' implies a time (mlt_position).

We also eventually want to support Bezier splines for pacing interpolation. One thought is to put the delimited control points within square brackes after the time: 00:00:00:00[x1 y1 x2 y2]=0.0; 00:00:03:00[x1 y1 x2 y2]=10. Any non-numeric and non-decimal-point (period or comma) delimiter can be used.

Strings will always be discrete and non-interpolated, but maybe a ! after the time value can be used to indicate discrete for numeric types. I suppose this means we should support a unique interpolation type for each keyframe. Again, later. Initial version will be as today with linear only for numeric plus discrete for strings. Time value strings are strings and discrete only, but that means we could convey a start timecode on a clip with a timecode discontinuity, which is handy. Of course, storing time as integer or double can be interpolated.

There is no support for animating individual components of a color. Only the color as integer can be animated.

-- DanDennedy - 2011-09-28