Configuring the consumer or output
Profiles were introduced in v0.2.4.
Profiles define the output video properties, which affects the image processing. This replaces legacy usage of MLT_NORMALISATION, but there is backwards compatibility and overriding. Profile documents are text files that can are loaded by the factory or on-demand. A bunch of profile documents come with MLT, and these can be loaded by their name without knowing their location. Applications can call functions to load a file by its absolute path and name. Also, an application can pass a string containing a profile definition.
- num = numerator
- den = denominator
- description is optional, but recommended
- A num/den lets you specify a fraction without rounding errors introduced by floating point.
- A "name" can be specified. Normally, name is the basename of the filename, typically equivalent to MLT_PROFILE. However, if an application is setting profiles through a properties object or string, then it should include a "name" property.
- When you specify a document to load from the system directory of profiles, you use the document's file name without its path (basename).
- The system profiles directory is $prefix/share/mlt/profiles
Environment Variables (Global Profile)
Environment variables control how the framework selects and loads a profile. Here are the rules governing the usage of environment variables to load the global profile:
- MLT_NORMALISATION is deprecated
- MLT_PROFILE is new and takes a higher priority than MLT_NORMALISATION
- MLT_PROFILE refers to a profile document
- without a path, it refers to a file in the system profiles directory
- it can also point to a specific file
- If MLT_PROFILE is not set:
- If MLT_NORMALISATION=NTSC, then MLT loads dv_ntsc
- If MLT_NORMALISATION=PAL, then MLT loads dv_pal
- As of v0.2.5, setting MLT_PROFILES_PATH overrides the system profiles directory. Currently, it only accepts one directory rather than a colon-delimited list of directories.
- If both MLT_NORMALISATION and MLT_PROFILE are not set, then it uses hardcoded defaults equivalent to dv_pal
- Environment variables are not required!
Consumer Profile Property
You can also specify the profile to use by setting the "mlt_profile" property on the consumer. This overrides any environment variable setting. In addition, any of the following properties that occur after the "mlt_profile" override the respective profile setting:
- aspect_ratio (normally computed from profile's sample_aspect_num / sample_aspect_den)
- display_ratio (normally computed from profile's display_aspect_num / display_aspect_den)
"aspect_ratio" is used heavily throughout the system. "display_ratio" is used quite a bit as well. If you override the aspect_num or aspect_den, be sure to set the ratio in floating point as well!
The producer base class initializes the following properties from the profile:
- aspect_ratio (sample_aspect_num / sample_aspect_den). However, this is usually updated by the producer based upon its file resource or intrinsic properties (e.g. 1.0 for square pixels from a still image producer).
The producer does not, however, inherit any individual profile parameter that you override on the consumer properties.
A producer constructs frame objects. The frame initializes the following properties from the profile:
- aspect_ratio (sample_aspect_num / sample_aspect_den) However, this is usually updated by the producer based upon its file resource or intrinsic properties (e.g. 1.0 for square pixels from a still image producer).
The frame does not, however, inherit any individual profile parameter that you override on the consumer properties.
- melt -profile dv_ntsc some.dv ...
- MLT_PROFILE=dv_ntsc melt some.dv
- melt some.dv -consumer sdl mlt_profile=dv_ntsc
- melt some.dv -consumer sdl mlt_profile=dv_ntsc progressive=1
- MLT_PROFILE=./my_profile.txt melt some.dv
Luma and Data Feed Files
The Luma wipes and data feed/show files still use the MLT_NORMALISATION environment variable. There is currently no plan to address how to integrate these with the new profiles system. However, upon loading a profile, MLT attempts to set MLT_NORMALISATION in the MLT environment for legacy support. It recognizes the following framerate strings within MLT_PROFILE or the profile "name" property: ntsc, 60, 30, pal, 50, 25.