Version 1.2
Message Size (referring to all following bytes) | Message Type | Payload |
---|---|---|
4 byte unsigned integer | 1 byte | Variable Size |
0x01
Data Request: requires an acknowledge from the server0x02
Notification: one-shot message, does not require an acknowledge from the server0x03
Acknowlege: : may also contain data in response to a request0x04
Negative Acknowlege: : may also contain an error code and futher data in response to a request0x0f
Handshake: handshake initialization0x11
Data Request: requires an acknowledge from the client0x12
Notification: one-shot message, does not require an acknowledge from the client0x13
Acknowlege: may also contain data in response to a request0x14
Negative Acknowlege: : may also contain an error code and futher data in response to a request0x1f
Handshake: handshake responseMessage 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 |
The server responds with either a success or a failure message – mostly depending on the protocol versions the client supports.
The handshake success message has the following form:
Message Size | 0x1f |
0x01 |
Protocol Version |
---|---|---|---|
4 bytes | 1 byte | 1 byte | 1 byte |
After having received the success handshake message, the client proceeds with sending data requests and notifications.
The handshake failure message has the following form:
Message Size | 0x1f |
0x02 |
Error Code | Data |
---|---|---|---|---|
4 bytes | 1 byte | 1 byte | 1 byte | variable length |
The following protocol versions are supported:
Byte Representation | Version Number |
---|---|
0x01 |
1.0 |
signature = HMAC(H = SHA-256, K = API Secret, m = API Key + nonce)
(where +
stands for byte concatenation)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 |
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:
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 |
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 |
0x02
)Notification Name | Message Code | Payload Format | Description |
---|---|---|---|
DeviceMetaEvent |
0x01 |
<Device Type> <Data> | Registered client has updated device meta data for the server |
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 |
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 |
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 |
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. |
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 |
16 byte long id a specified result view, which can be paginated.
8-bytes block:
Start | Length |
---|---|
4 bytes | 4 bytes |
Identifier | Description |
---|---|
0x01 |
Full version of clips |
0x02 |
Only UUIDs with vector clock |
[<VideoClip|SoundClip>]
[{“id”: string, “type”: string, “version”: { “
{
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)
}
Identifier | Description |
---|---|
0x01 |
Clips as CSV |
0x02 |
Clips as JSON |
0x03 |
Shot Log (Excel) |
0x04 |
Sound Report (Excel) |
0x05 |
Slate Log (Excel) |
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>
}
The following data formats do not exist as stand-alone formats, but are inluded in the data formats below.
{
"uuid": string,
"name": string,
"customer": <Customer>,
"numbers" [{
"title": string,
"number": string
}],
"type": string ("movie" or "series")
}
{
"uuid": string,
"name": string,
"address": string,
"isActive": string
}
{
"uuid": string,
"number": int,
"additional": string,
"date": string (yyyy-MM-dd)
}
{
"uuid": string,
"number": int,
"name": string,
"scheduledRunningTime": int (in seconds)
}
{
"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>,
}
{
"uuid": string,
"number": int,
"additional": string,
"comment": string,
"scheduledOnProjectDay": <ProjectDay>,
"createdOnProjectDay": <ProjectDay>,
"shootingStartedOnProjectDay": <ProjectDay>,
"shootingEndedOnProjectDay": <ProjectDay>,
"canceledOnProjectDay": <ProjectDay>,
"repeatedOnProjectDay": <ProjectDay>,
"additionalOnProjectDay": <ProjectDay>,
}
{
"uuid": string,
"number": int,
"comment": string,
"presetComments": [string],
"runningTime": int (in seconds),
"isPickup": boolean,
"printState": int
}
{
"uuid": string,
"elementNumber": int,
"element": string,
"elements": [<ScriptParagraphElement>]
}
{
"uuid": string,
"element": string,
"content": string
"changes": [{
"startIndex": int,
"endIndex": int,
"content": string,
"isComment": boolean
}]
}
The following data formats are used in the data part of the DataEvent
messages:
{
"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
}
{
"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
}
{
"type": "timecode",
"seconds": int,
"frames": int
}
{
"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
}
{
"type": "clap",
"timecode": <TimeCode>,
"slateInfo": <SlateInfo>
}
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 |
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.
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),
}
{}
{}
{
"masterClock": boolean
}
{}
{}
{
"type": [string],
"clips": [string],
"devices": [string],
"rolls": [string],
"projectDays": [string],
"timecodeFrom": <TimeCode>,
"timecodeTo": <TimeCode>,
"creationFrom": long,
"creationTo": long
}
{
"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]
}
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
{ device: { masterClock: true }}
{ vendorTyped: { ... }}