Matching Clip Metadata

This guide describes how to query the LockitNetwork API for clip metadata (e.g. episode/scene/shot/take information) using the clipMatch API endpoint.

Authentication

First of all, we have to ensure we have a valid LockitNetwork API token. Please see the OAuth 2.0 guide for more information.

Preparing the Request

The LockitNetwork API allows to request all clip metadata of a day of shooting (projectday) while also providing clip matching capabilities via file names.

In order to build the request URL (​/projects​/{projectId}​/projectdays​/{dayId}​/matchClips) we have to first obtain the IDs of our project and day of shooting. The list of all our projects can be requested via the GET /projects endpoint:

curl -H 'Authorization: Bearer MY-TOKEN' 'https://api.lockitnetwork.com/projects'

[
  {
    "uuid" : "d591f63022ea4fc9a684c6888f58c59a",
    "name" : "Test",
    "isSeries" : false,
    "isPremium" : true,
    [...]
  },
  [...]
]

NOTE

The project-specific LockitNetwork API endpoints are only enabled for premium projects (i.e. when the paid LockitNetwork Production Service is active for the project).

We will use our test project with UUID d591f63022ea4fc9a684c6888f58c59a. The days of shooting of our test project can then be requested using the {GET ​/projects​/{projectId}​/projectdays​} endpoint:

curl -H 'Authorization: Bearer MY-TOKEN' 'https://api.lockitnetwork.com/projects/d591f63022ea4fc9a684c6888f58c59a/projectdays'

[
  {
    "uuid" : "64abe0b3b49641f0a31cbd29ca692219",
    "project" : "d591f63022ea4fc9a684c6888f58c59a",
    "day" : 1,
    "prefix" : "",
    "suffix" : "",
    "date" : {
      "year" : 2020,
      "month" : 1,
      "day" : 21
    },
    "unit" : null,
    "episodeBlock" : null
  },
  [...]
]

With our required IDs at hand we can construct the URL for matching the clips of the day of shooting. In this example we will send two file names for matching in the request body: A001_C001_EXAMPLE.R3D and A002_C002_rendered.mov.

curl -H 'Authorization: Bearer MY-TOKEN' \
-d '["A001_C001_EXAMPLE.R3D", "A002_C002_rendered.mov"]' \
'https://api.lockitnetwork.com/projects/d591f63022ea4fc9a684c6888f58c59a/projectdays/64abe0b3b49641f0a31cbd29ca692219/matchClips'

{
  "matches" : {
    "A001_C001_EXAMPLE.R3D" : {
      "uuid" : "5db79a4bef174d8395e24187b36120c2",
      "episode" : {
        "number" : 1,
        [...]
      },
      "scene" : {
        "number" : 58,
        "content" : "E-Shot Martin's car",
        "insideOutside" : "Ext",
        "dayNight" : "Day",
        "sets" : [
          {
            "name" : "Martin's garage",
            [...]
          }
        ],
        "splitTimes" : [
          {
            "actualRunningTime" : 20,
            "estimatedRunningTime" : 20,
            [...]
          }
        ],
        [...]
      },
      "slate" : {
        "number" : 1,
        [...]
      },
      "take" : {
        "number" : 2,
        [...]
      },
    },
    "A002_C002_rendered.mov" : {
      [...]
    }
  },
  "unmatched" : [
    {
      "camRoll" : "A001",
      "clipName" : "C003",
      "fileName" : "A001_C003_0121FJ",
      "episode" : { [...] },
      "scene" : { [...] },
      "slate" : { [...] },
      "take" : { [...] },
      [...]
    },
    [...]
  ]
}

The response contains a matches object with the sent file names as keys and the corresponding clip metadata (or null for unmatched clips) as values. By default, the unmatched object contains an array of clip metadata for all unmatched clips on the day of shooting. In order to suppress the listing of unmatched clip metadata the onlyMatches query parameter can be used:

curl -H 'Authorization: Bearer MY-TOKEN' \
-d '["A001_C001_EXAMPLE.R3D", "A002_C002_rendered.mov"]' \
'https://api.lockitnetwork.com/projects/d591f63022ea4fc9a684c6888f58c59a/projectdays/64abe0b3b49641f0a31cbd29ca692219/matchClips?onlyMatches=true'

{
  "matches" : { [...] },
  "unmatched": []
}