Resource aa:keyframes

Overview

A list of key frame positions within the video.

Properties

The aa:keyframes resource has the following properties:

editRate

The edit rate of the asset.

The frame numbers in the segments relate to this edit rate. The value is a rational number. Typical values:

  • 25/1: 25 fps

  • 30000/1001: 29.97 fps

  • 24000/1001: 23.976 fps

  • 60000/1001: 59.94 fps

dropFrame

The drop-frame flag:

true if the asset uses a drop-frame timecode format, false otherwise

assetDuration

New in MC | Cloud UX 2022.12

The length of the asset in frames (or milliseconds if the has has no valid frame rate). The value corresponds to the common.duration property of the aa:asset resource.

An asset can reference only a part of the full video, meaning that the assetDuration is not necessarily the same as the duration of the video.

videoStartTC

Timecode of the first frame of the video.

Please note that starting with MC | AM 2023.7 the handling of SMPTE timecode strings around midnight has changed. See timecodes in MC | AM for details.

categories

(Optional) Definition of the available key frame categories. The value is a JSON object that acts as a name-value map.

The map contains not only entries for all used categories, but it can also have entries for "main" categories. For example, if the categories "marker.green" and "marker.red" are used, then there should also be an entry for "marker", but with isGroup set to true.

Each category entry has the following properties:

  • description: (Optional) Description.

  • isGroup: (Optional) If true, then this category is not used directly, but it is a grouping category like "marker", where sub categories like "marker.green" are actually used. A UI client can work in two ways:

    • It can show a flat list of all categories where isGroup is false (or missing). This allows a user to show and hide all categories separately.

    • It can show a tree of categories. Top-level elements are the categories with isGroup=true, sub-level elements are the ones starting with a group category ID and a dot. For example the tree contains a top-level node "marker" with sub nodes for "marker.green" and "marker.yellow".

  • name: (Optional) The display name for the category, localized for the calling user.

You can query a specific language with the culture query parameter.

Example for the categories property:

{
  "categories": {
    "marker": {
      "description": "MediaCentral Production Management marker",
      "isGroup": true,
      "name": "Marker"
    },
    "marker.green": {
      "description": "MediaCentral Production Management marker green",
      "name": "Green marker"
    },
    "marker.yellow": {
      "description": "MediaCentral Production Management marker yellow",
      "name": "Yellow marker"
    }
  }
}

keyframes

Array with one item for each key frame. The array must be sorted by frame number.

Each key frame item has the following properties:

  • frame: The frame number of the key frame within the video.

  • categories: (Optional) Array of JSON objects that define the categories of the key frame. The JSON object has the following sub properties:

    • id: The ID of the category. The category ID can be used by a UI to filter the key frames or to show an icon for a category. The value corresponds to the key defined in the category description.

    • text: (optional) Text associated with the key frame. Example: the text of a marker in MediaCentral Production Management.

    • user: (optional) Login name of the user who selected the key frame.

    • attributes: (optional) Additional attributes for the key frame. The value must be a JSON object and is interpreted as a name-value map.

Example for a key frame:

{
  "keyframes": [
    {
      "frame": 120,
      "categories": [
        {
          "id": "shot"
        },
        {
          "id": "marker.green",
          "text": "Christiano Ronaldo scores a goal",
          "user": "john.doe",
          "attributes": {
            "someattr": "somevalue"
          }
        }
      ]
    }
  ]
}

Link Relations

aa:asset

A link to the asset that contains the key frames.

Description

A list of key frame positions within the video. The result contains localized names for the key frame categories. You can use the query parameter culture to request a specific culture, e.g. "fr" for French. If you don’t request a specific culture, the service tries to auto-detect the culture. For example, it uses the culture defined in the User Management service when querying an MediaCentral | Asset Management system.

In MediaCentral Production Management the aa:keyframes resource is not supported.

Key frames

Key frames are frames that indicate a specific event within the video. Examples:

  • Frames at a shot border.

  • Frames that indicate a scene change. The MediaCentral Asset Management Video Analysis service marks such frame positions. Scene changes are usually detected with a degree of certainty.

  • Frames manually marked with a marker in MediaCentral Production Management. In this case, a color is assigned to the key frame.

  • Frames manually marked by a user as key frames, for example in MediaCentral | Asset Management Cataloger.

Categories

A key frame is associated with one or more defined categories that define the kind of key frame. A category ID should be a structured name with elements separated by a dot. Currently, there are the following pre-defined categories:

  • shot: Shot border

  • scene.minor: Minor scene change

  • scene.major: Major scene change

  • user: User-defined key frame

  • marker.color: MediaCentral Production Management marker in different colors.

A UI can use the structure names to allow a user to show or hide key frames. The structured names allow UI controls to, for example, show or hide markers of all colors.

Examples

MediaCentral | Asset Management 
 
{
  "editRate": "25/1",
  "dropFrame": false,
  "videoStartTC": "00:00:00:00",
  "_links": {
    "curies": [
      {
        "href": "http://services.avid.com/apis/assets/{rel}",
        "name": "aa",
        "templated": true
      }
    ],
    "self": {
      "href": "https://host/…​"
    },
    "aa:asset": {
      "href": "https://host/…​"
    }
  },
  "categories": {
    "marker": {
      "description": "MediaCentral Production Management marker",
      "isGroup": true,
      "name": "Marker"
    },
    "marker.green": {
      "description": "MediaCentral Production Management marker with color green",
      "name": "Green marker"
    },
    "marker.yellow": {
      "description": "MediaCentral Production Management marker with color yellow",
      "name": "Yellow marker"
    },
    "shot": {
      "description": "Shot border",
      "name": "Shot"
    }
  },
  "keyframes": [
    {
      "frame": 120,
      "categories": [
        {
          "id": "shot"
        },
        {
          "id": "marker.green",
          "text": "Christiano Ronaldo scores a goal",
          "user": "john.doe",
          "attributes": {
            "someattr": "somevalue"
          }
        }
      ]
    },
    {
      "frame": 124,
      "categories": [
        {
          "id": "shot"
        }
      ]
    },
    {
      "frame": 136,
      "categories": [
        {
          "id": "marker.yellow",
          "text": "Cheering crowd",
          "user": "john.doe"
        }
      ]
    }
  ]
}