Skip to main content

Masking with Luma Mattes

Luma mattes are used to create masks by leveraging the brightness (luminance) values of an image or video. The white areas of the matte will retain full visibility, while the black areas will be fully transparent. Grey values represent partial transparency, allowing for smooth transitions and blending.

Static Luma Mattes​

Static luma mattes use a black-and-white image to define the transparent and visible areas of another clip. The white areas of the image remain fully visible, while the black areas will mask out the corresponding parts of the video or image.

The following image is a static circular luma matte:

Circle Mask

To apply this matte, reference the image as a luma asset in the same track as the video or image it will mask:

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "luma",
                            "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/luma-mattes/static/circle-sd.jpg"
                        },
                        "start": 0,
                        "length": 10
                    },
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/cat.hd.mp4"
                        },
                        "start": 0,
                        "length": 10
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 1280,
            "height": 720
        }
    }
}

In this configuration, the luma asset applies a circular matte to the video clip. The white areas of the luma image will reveal the underlying video, while the black areas will display the cat video clip in the same track, effectively creating a masked effect.

Animated Luma Mattes​

Instead of using a static black-and-white image, you can use a video with black-and-white animations as a luma matte. This allows for dynamic transitions and unique effects between clips and tracks.

To apply an animated luma matte, reference the animated video as a luma asset in the same track as the video or image it will mask:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "luma",
              "src": "https://templates.shotstack.io/basic/asset/video/luma/double-arrow/double-arrow-down.mp4"
            },
            "start": 3,
            "length": 2
          },
          {
            "start": 0,
            "length": 4,
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/table-mountain.mp4"
            }
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/road.mp4"
            },
            "start": 3,
            "length": 4
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "size": {
        "width": 1280,
        "height": 720
    }
  }
}

In this setup, the luma asset applies an animated matte to the video clip. The varying shades of black, white, and grey in the luma video control the transparency levels, revealing portions of the underlying video. This creates a smooth, dynamic transition between two clips by masking one clip and gradually revealing the other.