Profiles

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.

Profile Document

Example:

description=DV PAL
frame_rate_num=25
frame_rate_den=1
width=720
height=576
progressive=0
sample_aspect_num=59
sample_aspect_den=54
display_aspect_num=4
display_aspect_den=3

• 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 "profile" property on the consumer. This overrides any environment variable setting. In addition, any of the following properties that occur after the "profile" override the respective profile setting:

• fps
• frame_rate_num
• frame_rate_den
• width
• height
• progressive
• aspect_ratio (normally computed from profile's sample_aspect_num / sample_aspect_den)
• sample_aspect_num
• sample_aspect_den
• display_ratio (normally computed from profile's display_aspect_num / display_aspect_den)
• 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!

Producer Properties

The producer base class initializes the following properties from the profile:

• fps
• frame_rate_num
• frame_rate_den
• 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).

IMPORTANT: The producer does not, however, inherit any individual profile parameter that you override on the consumer properties.

Frame Properties

A producer constructs frame objects. The frame initializes the following properties from the profile:

• width
• height
• 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).

IMPORTANT: The frame does not, however, inherit any individual profile parameter that you override on the consumer properties.

Inigo Usage

Examples:

1. MLT_PROFILE=dv_ntsc inigo some.dv
2. inigo some.dv -consumer sdl profile=dv_ntsc
3. inigo some.dv -consumer sdl profile=dv_ntsc progressive=1
4. MLT_PROFILE=./my_profile.txt inigo 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.