MasterLockit API

Version 1.2

Message Header

Message Format

Message Size (referring to all following bytes) Message Type Payload
4 byte unsigned integer 1 byte Variable Size

Message Types

Client -> Server

Server -> Client

Connection Initialization (Handshake)

Handshake Procedure

Message Size 0x1f 0x00 Nounce
4 bytes 1 byte 1 byte 8 bytes
Message Size 0x0f Timestamp (ms since epoch) Device ID Alias Byte Length Alias Protocol Versions Length Protocol Versions API Key Signature
4 bytes 1 byte 8 bytes 8 bytes 4 bytes UTF–8 encoded string 4 bytes 1 byte per supported version 24 bytes 32 bytes
Message Size 0x1f 0x01 Protocol Version
4 bytes 1 byte 1 byte 1 byte
Message Size 0x1f 0x02 Error Code Data
4 bytes 1 byte 1 byte 1 byte variable length

Protocol Versions

The following protocol versions are supported:

Byte Representation Version Number
0x01 1.0

Device IDs

Signature

Handshake Error Codes

Byte Representation Description
0x00 Fatal Error. An error message is provided as an UTF–8 encoded string in the data section.
0x01 Protocol Mismatch: none of the suggested protocol versions if supported by the server.
0x02 API Key is invalid
0x03 Signature is invalid

Message Codes

All data request and notification messages have the following format:

Message Size Message Type Message Code Payload
4 bytes 1 byte 1 byte Variable Size

The following message codes are defined:

Data Request Client -> Server (Message Type 0x01)

Request Name Message Code Payload Format Description
SubscribeDataUpdates 0x01 <Device ID> <Device Type> Subscribe to data updates of a device
UnsubscribeDataUpdates 0x02 <Device ID> <Device Type> Unsubscribe to data updates of a device
SubscribeDeviceUpdates 0x03 <Device Type> Subscribe to device (metadata) updates
UnsubscribeDeviceUpdates 0x04 <Device Type> Unsubscribe to device (metadata) updates
RegisterAsDevice 0x05 <Device Type> Register as a device
UnregisterAsDevice 0x06 <Device Type> Unregister as a device
DataEvent 0x07 <Device Type> <Data> Registered client has new/updated data for the server
FetchClips 0x08 <Range> <ListType> <ViewID> <Clip Demand> Query clips from repository with a certain demand
DeleteClips 0x09 <Clip Demand> Delete clips from repository with a certain filter
Export 0x0A <Export Type> <Export Configuration> Exports clips from repository with a certain filter to a specific device; if zero device id was given, the exported data will be in the ACK response as payload
SubscribeVolatileDataUpdates 0x0B <Device ID> <Device Type> Subscribe to volatile data updates of a device
UnsubscribeVolatileDataUpdates 0x0C <Device ID> <Device Type> Unsubscribe to volatile data updates of a device
FetchLensData 0x0D <Lens Data Demand> Query lens data with a certain demand
StartCJam 0x0E <TC seconds (32bit)> <TC frames (16bit)> Set TC and start C-Jam
RenameDevice 0x0F <Device ID> <New Device Name> Rename device
RemoveDevice 0x10 <Device ID> Remove device

Data Request Server -> Client (Message Type 0x11)

Request Name Message Code Payload Format Description
DataEvent 0x01 <Device ID> <Device Type> <Data> Server has new/updated data for the client
Ping 0x02 For connection liveness checks

Notifications Client -> Server (Message Type 0x02)

Notification Name Message Code Payload Format Description
DeviceMetaEvent 0x01 <Device Type> <Data> Registered client has updated device meta data for the server

Notifications Server -> Client (Message Type 0x12)

Notification Name Message Code Payload Format Description
DeviceAppeared 0x01 <Device ID> <Device Type> A new device appeared
DeviceDisappeared 0x02 <Device ID> <Device Type> A device disappeared
DeviceMetaEvent 0x04 <Device ID> <Device Type> <Data> Device meta data changed
VolatileDataEvent 0x05 <Device ID> <Device Type> <Data> Device emitted volatile data

Acknowledge

An acknowledge message in response to a data request has the following format:

Message Size 0x03 / 0x13 SHA–1 of requeSt message Data
4 bytes 1 byte 20 bytes variable length

Negative Acknowledge

A negative acknowledge message in response to a data request has the following format:

Message Size 0x04 / 0x14 SHA–1 of request message Error code Data
4 bytes 1 byte 20 bytes 4 byte variable length

Error Codes

Value Description
0 Fatal Error. An error message is provided as an UTF–8 encoded string in the data section.
1 The message code is not supported.
2 The message as an invalid format.

Device Types

Identifier Description Sends data of type
0x01 Camera Video Clip
0x02 Sound Recorder Sound Clip
0x03 Time Code Generator Time Code
0x04 Slate Info Device Upcoming Slate Info
0x05 Slate Clap Event
0x06 Storage n/a
0x07 Lens Lens Data

View ID

16 byte long id a specified result view, which can be paginated.

Range

8-bytes block:

Start Length
4 bytes 4 bytes

List Type

Identifier Description
0x01 Full version of clips
0x02 Only UUIDs with vector clock

Full clips data format

[<VideoClip|SoundClip>]

Only UUIDs with vector clock format

[{“id”: string, “type”: string, “version”: { “”: string, … }}, …]

Clip Demand

{
    clips: [uuid1, uuid2, ...], // optional. filter clips by UUID
    devices: [deviceId1, deviceId2, ...], // optional. filter clips by device ID
    timecodeFrom: "00:00:00:00" // optional. filter clips by TC range
    timecodeTo: "12:00:00:00" // optional. filter clips by TC range
    creationFrom: 1325376000000 // optional. filter clips by creation timestamp (ms since epoch)
    creationTo: 1325462400000 // optional. filter clips by creation timestamp (ms since epoch)
}

Export Type

Identifier Description
0x01 Clips as CSV
0x02 Clips as JSON
0x03 Shot Log (Excel)
0x04 Sound Report (Excel)
0x05 Slate Log (Excel)

Export Configuration

Is a JSON encoded configuration, following the this schema:

{
   "targetDeviceId": string, // optional. device id of target storage device; if not present report data will be in the ACK response's payload
   "filename": string, // optional. MUST be set when targetDeviceId was given as well.
   "headerData": <mixed>, // depending on the export type (e.g. sound report does support that field)
   "demand": <ClipDemand>
}

Common Formats

The following data formats do not exist as stand-alone formats, but are inluded in the data formats below.

Project

{
   "uuid": string,
   "name": string,
   "customer": <Customer>,
   "numbers" [{
       "title": string,
       "number": string
   }],
   "type": string ("movie" or "series")
}

Customer

{
   "uuid": string,
   "name": string,
   "address": string,
   "isActive": string
}

ProjectDay

{
    "uuid": string,
    "number": int,
    "additional": string,
    "date": string (yyyy-MM-dd)
}

Episode

{
    "uuid": string,
    "number": int,
    "name": string,
    "scheduledRunningTime": int (in seconds)
}

Scene

{
    "uuid": string,
    "number": int,
    "additional": string,
    "editorsRunningTime": int (in seconds),
    "pages": int (in eights),
    "comment": string,
    "content": string,
    "insideOutside": string,
    "dayNight": string,
    "location": string,
    "sets": [string],
    "storyDay": {
        "number": int
        "date": string (yyyy-MM-dd)
    },
    splitTimes: [{
        "actualRunningTime": int (in seconds),
        "estimatedRunningTime": int (in seconds),
        "pages": int (in eights)
        projectDay: <ProjectDay>
    }],
    "scenesIncluded": [<Scene>],
    "scheduledOnProjectDay": <ProjectDay>,
    "createdOnProjectDay": <ProjectDay>,

    "shootingStartedOnProjectDay": <ProjectDay>,
    "shootingEndedOnProjectDay": <ProjectDay>,
    "canceledOnProjectDay": <ProjectDay>,
    "repeatedOnProjectDay": <ProjectDay>,
    "additionalOnProjectDay": <ProjectDay>,
}

Slate

{
    "uuid": string,
    "number": int,
    "additional": string,
    "comment": string,
    "scheduledOnProjectDay": <ProjectDay>,
    "createdOnProjectDay": <ProjectDay>,
    "shootingStartedOnProjectDay": <ProjectDay>,
    "shootingEndedOnProjectDay": <ProjectDay>,
    "canceledOnProjectDay": <ProjectDay>,
    "repeatedOnProjectDay": <ProjectDay>,
    "additionalOnProjectDay": <ProjectDay>,
}

Take

{
    "uuid": string,
    "number": int,
    "comment": string,
    "presetComments": [string],
    "runningTime": int (in seconds),
    "isPickup": boolean,
    "printState": int
}

Script Paragraph

{
    "uuid": string,
    "elementNumber": int,
    "element": string,
    "elements": [<ScriptParagraphElement>]
}

Script Paragraph Element

{
    "uuid": string,
    "element": string,
    "content": string
    "changes": [{
        "startIndex": int,
        "endIndex": int,
        "content": string,
        "isComment": boolean
    }]
}

Data Formats

The following data formats are used in the data part of the DataEvent messages:

Video Clip

{
    "id": string,
    "type": "video",
    "version": {
      "<DeviceID>": int,
      ...
    },
    "camera": {
        "number": int,
        "model": string,
        "name": string
    },
    "project": <Project>,
    "clipName": string,
    "camRoll": string,
    "episode": <Episode>,
    "scene": <Scene>,
    "slate" <Slate>,
    "take": <Take>,
    "projectDay": <ProjectDay>,
    "clipLabel": {
        "name": string,
        "comment": string,
        "episode": <Episode>,
        "scene": <Scene>,
        "slate": <Slate>,
    },
    "angle": float,
    "aperture": string,
    "lens": string,
    "magazine": string,
    "height": string,
    "distance": string,
    "filter": [string],
    "whiteBalance": string,
    "exposureIndexASA": string,
    "exposureTime": string,
    "shutterAngle": string,
    "isClapperOnly": boolean,
    "isProductionSound": boolean,
    "isMOS": boolean,
    "fileName": string,
    "sensorFPS": string,
    "tcStartSeconds": int,
    "tcStartFrames": int,
    "tcStopSeconds": int,
    "tcStopFrames": int,
    "isWaste": boolean,
    "isRecFinal": boolean,
    "isManual": boolean,
    "clipLogs": [{
        "tcSeconds": int,
        "tcFrames": int,
        "comment": string,
        "presetComments": [string]
    }],
    "cast": [{
        "firstname": string,
        "lastname": string
    }],
    "scriptParagraphs": [<ScriptParagraph>],
    "scriptLine": {
        "startElementUUID": string,
        "endElementUUID": string,
        "startIndex": int,
        "endIndex": int,
        "markedLines": [{
            "startElementUUID": string,
            "endElementUUID": string,
            "startIndex": int,
            "endIndex": int
        }]
    }
    "created": long,
    "updated": long
}

Sound Clip

{
    "id": string,
    "type": "sound",
    "version": {
      "<DeviceID>": int,
      ...
    },
    "soundRecorder": {
        "number": int,
        "model": string,
        "name": string
    },
    "project": <Project>,
    "clipName": string,
    "episode": <Episode>,
    "scene": <Scene>,
    "slate" <Slate>,
    "take": <Take>,
    "projectDay": <ProjectDay>,
    "clipLabel": {
        "name": string,
        "comment": string,
        "episode": <Episode>,
        "scene": <Scene>,
        "slate": <Slate>,
    },
    "height": string,
    "distance": string,
    "isClapperOnly": boolean,
    "fileName": string,
    "fps": string,
    "tcStartSeconds": int,
    "tcStartFrames": int,
    "tcStopSeconds": int,
    "tcStopFrames": int,
    "isWaste": boolean,
    "isRecFinal": boolean,
    "isManual": boolean,
    "clipLogs": [{
        "tcSeconds": int,
        "tcFrames": int,
        "comment": string,
        "presetComments": [string]
    }],
    "cast": [{
        "firstname": string,
        "lastname": string
    }],
    "scriptParagraphs": [<ScriptParagraph>],
    "scriptLine": {
        "startElementUUID": string,
        "endElementUUID": string,
        "startIndex": int,
        "endIndex": int,
        "markedLines": [{
            "startElementUUID": string,
            "endElementUUID": string,
            "startIndex": int,
            "endIndex": int
        }]
    }
    "bitdepth": String,
    "filetype": String,
    "samplingrate": String,
    "soundroll": String,

    "tracks": [
        {
            "name": string,
            "number": int,
            "isActive": boolean
        }
    ],
    "sound_types": [ string ],
    "created": int,
    "updated": int,
    "circle": boolean,
    "comment": string
}

Time Code

{
  "type": "timecode",
  "seconds": int,
  "frames": int
}

Upcoming Slate Info

{
  "type": "slate",
  "mos": boolean,
  "day": boolean,
  "night": boolean,
  "inside": boolean,
  "outside": boolean,
  "fps": int,
  "cam": string,
  "date": string (yyyy-MM-dd),
  "roll": string,
  "scene": string,
  "slate": string,
  "take": string,
  "producer": string,
  "director": string,
  "dop": string,
  "soundmixer": string
}

Clap Event

{
  "type": "clap",
  "timecode": <TimeCode>,
  "slateInfo": <SlateInfo>
}

Volatile Data Formats

Lens Data

Lens data is transfered as binary packed in the following format:

TC seconds TC frames Vendor-specific data
4 bytes (uint) 2 byte (ushort) variable

Timecode

The “local” TC generator device (i.e. properties.masterClock == true) will send a TC JSON message for every generated frame. Remote TC generator devices will ignore volatile data requests.

Device Meta Data Formats

There is a general data format for device metadata which contains a device-specific metadata format as well as a vendor-specific metadata format as in in-line objects:

{
  "common": {
    "alias": string,
    "connected": boolean
    "energyLevel": int (-1 for unknown, 0-100 as energy level in percent),
"parentDeviceId": string?
  },
  "device": <Device-Specific Object>,
  "vendor": <Vendor-Specific Object with string values>,
  "vendorTyped": <Vendor-Specific Object> (recommended),
}

Video Clip Device

{}

Sound Clip Device

{}

Time Code Device

{
  "masterClock": boolean
}

Upcoming Slate Info Device

{}

Clap Event Device

{}

Clip Demand

{
    "type": [string],
    "clips": [string],
    "devices": [string],
    "rolls": [string],
    "projectDays": [string],
    "timecodeFrom": <TimeCode>,
    "timecodeTo": <TimeCode>,
    "creationFrom": long,
    "creationTo": long
}

Vendor-specific Meta Data Formats (typed)

Lockit

{
  "lockitBatteryType": [string],
  "acnChannel": [number]>,
  "isInHubMode": [bool],
  "projectFramerate": [Project FPS Enum],
  "userbits": [hex string],
  "externalPower": [bool],
  "unitId": [string],
  "generatorSource": [string],
  "tunePWM": [string],
  "lockitType": [string],
  "cjamEnabled": [boolean],
  "usDiff": [number]
}

Project FPS Enum

FPS_23_98
FPS_24
FPS_25
FPS_29_97
FPS_29_97_DROP
FPS_30
FPS_30_DROP
FPS_47_95
FPS_48
FPS_50
FPS_59_94
FPS_59_94_DROP
FPS_60
FPS_60_DROP

Hints

Fetch internal Lockit properties