Video Project

To import video annotations to a Video or Audio Project, you need to import a JSON file of the annotations.

The Video annotation JSON contains three main fields: metadata, instances, tags, and comments.

{
    "metadata": {},
    "instances": [],
    "tags": [],
    "comments": []
}

🚧

The fields that are marked in bold in the descriptions are mandatory.

Metadata

{
    "metadata": {
        "name": "video_file_example_1",
        "width": 1920,
        "height": 1080,
        "status": "Completed",
        "url": "https://sa-public-files.s3.us-west-2.amazonaws.com/Video+project/video_file_example_1.mp4",
        "duration": 30526667,
        "projectId": 101067,
        "error": null,
        "annotatorEmail": "[email protected]",
        "qaEmail": "[email protected]",
        "lastAction": {
            "timestamp": 1628861289127,
            "email": "[email protected]"
        }
}

Description (mandatory fields are marked in bold):

  • "name": string - Item name as stated in the CSV file or generated by SDK.
  • "width": integer - The video’s width. The field is null if the video was not opened in the editor.
  • "height": integer - The video’s height. The field is null if the video was not opened in the editor.
  • "status": string - The item’s status. It can be: NotStarted, InProgress, QualityCheck, Returned, Skipped, or Completed.
  • “url”: string - The URL from the attached CSV file.
  • “duration”: integer - The item duration in microseconds.
  • “projectId”: integer - The project ID.
  • "error": boolean - If it is true, the item is disapproved in the tool. If it is false, then the item is approved in the tool. The field is null if the item is neither approved nor disapproved.
  • "annotatorEmail": string - The annotator’s email address.
  • "qaEmail": string - The QA’s email address.
  • "lastAction": Information about the user who last edited the item. Edits include changing the class of an instance, adding or deleting attribute, pointlabels, or tags, and adding, deleting, moving, or scaling instances.
    • "email": string - The email address of the last user who added or edited an instance. Format example: "email": “[email protected]
    • "timestamp": integer - The date and time when the instance was last edited.

📘

About mandatory fields

  • If the object lastAction exists, then the email and timestamp are mandatory.

Instances

Bounding Box

[{
            "meta": {
                "id": "MTc5NTAuMjE2MTEyNTIzOTY=",
                "type": "bbox",
                "classId": 5005974,
                "className": "Class 1",
                "pointLabels": {
                    "0": "Pointlabel_1"
                },
                "createdBy": {
                    "email": "[email protected]",
                    "role": "Annotator"
                },
                "createdAt": "2021-08-13T13:26:32.409Z",
                "updatedBy": {
                    "email": "[email protected]",
                    "role": "Admin"
                },
                "updatedAt": "2021-08-13T13:27:13.667Z",
                "start": 0,
                "end": 23332991,
                },
            "parameters": [
                {
                    "start": 0,
                    "end": 23332991,
                    "timestamps": [
                        {
                            "points": {
                                "x1": 515.51,
                                "y1": 216.7,
                                "x2": 866.79,
                                "y2": 678.58
                            },
                            "timestamp": 0,
                            "attributes": []
                        },
                        {
                            "points": {
                                "x1": 515.51,
                                "y1": 216.7,
                                "x2": 866.79,
                                "y2": 678.58
                            },
                            "timestamp": 10617971,
                            "attributes": [
                                {
                                    "id": 1065772,
                                    "groupId": 291577,
                                    "name": "Attribute1",
                                    "groupName": "Group 1"
                                }
                            ]
                        },
                        {
                            "points": {
                                "x1": 1208.82,
                                "y1": 112.01,
                                "x2": 1560.1,
                                "y2": 573.89
                            },
                            "timestamp": 23332991,
                            "attributes": [
                                {
                                    "id": 1065772,
                                    "groupId": 291577,
                                    "name": "Attribute1",
                                    "groupName": "Group 1"
                                }]
                        }]
                }]
        }
]

Description (mandatory fields are marked in bold):

  • “meta”: objects
    • “id”: string - Unique instance ID.
    • “type”: string - The dictionary is a Bounding Box.
    • “classId”: integer - Class ID (A class ID from the “classes.json” belonging to the instance’s corresponding class, or -1 if the instance is not classified).
    • "className": string - Class name (one of the class names in “classes.json”, or an empty value if the instance is not classified).
    • “pointLabels”: The keys are from “0” to “7” for the 8 vertices of the bounding box.
    • "createdBy": Information about the user who created the bounding box.
      • "email": string - The email address of the user who created the bounding box.
      • "role": string - The role of the user who created the bounding box.
    • "createdAt": string - The date and time when the instance was created.
    • "updatedBy": Information about the user who updated the bounding box.
      • "email": string - The email address of the user who updated the bounding box.
      • "role": string - The role of the user who updated the bounding box.
    • "updatedAt": string - The date and time when the bounding box was updated.
    • “start”: integer - The time that marks the beginning of a bounding box. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a bounding box. The timestamp is in microseconds.
  • “parameters”: array
    • “start”: integer - The time that marks the beginning of a bounding box. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a bounding box. The timestamp is in microseconds.
    • “timestamps”: array - Shows information about a bounding box at specific timestamps (start, end, edit).
      • “timestamp”: integer - Timestamp that marks the change of the bounding box. The timestamp in microseconds.
      • “points”: objects - Points of the bounding box in this location on the timeline. The list of floats is: "x1, y1" for the left upper corner, and "x2, y2" for the right lower corner.
      • “attributes”: array - List of attributes for the bounding box, in this location on a timeline.
        • “id”: integer - Attribute ID (must be in “classes.json”)
        • “groupId”: integer - Attribute group ID (must be in “classes.json”)
        • "name": string - Attribute name
        • "groupName": string - Attributes group name

📘

About mandatory fields

  • If the objects createdBy and updatedBy exist, then email and role are mandatory.
  • If the array attributes exists, it can be either empty or it can contain objects with the following fields: name and groupName.

Polygon

[{
"meta": {
  "id": "MTc5NTAuMjE2MTEyNTIzOTY=",
  "type": "polygon",
  "classId": 5005974,
  "className": "Class 1",
  "createdBy": {
    "email": "[email protected]",
    "role": "Admin"
  },
  "createdAt": "2022-07-04T05:41:49.406Z",
  "updatedBy": {
    "email": "[email protected]",
    "role": "Annotator"
  },
  "updatedAt": "2022-07-04T06:56:34.117Z",
  "start": 0,
  "end": 8466792,
},
"parameters": [
  {
    "start": 0,
    "end": 8466792,
    "timestamps": [
      {
        "points": [
          2569.35,
          589.34,
          2239.38,
          722.35,
          2693.83,
          851.81
        ],
        "timestamp": 0,
        "attributes": []
      },
      {
        "points": [
          2908.24,
          644.52,
          2578.27,
          777.53,
          3032.72,
          906.99
        ],
        "timestamp": 331064,
        "attributes": [
             {
                    "id": 1065772,
                     "groupId": 291577,
                     "name": "Attribute1",
                      "groupName": "Group 1"
              }
                      ]
      },
      {
        "points": [
          2406.54,
          516.11,
          2076.57,
          649.12,
          2531.02,
          778.58
        ],
        "timestamp": 2385171,
        "attributes": [
             {
                     "id": 1065772,
                      "groupId": 291577,
                      "name": "Attribute1",
                       "groupName": "Group 1"
                }
              ]
      },
      {
        "points": [
          2406.54,
          516.11,
          2076.57,
          649.12,
          2531.02,
          778.58
        ],
        "timestamp": 8466792,
        "attributes": [
             {
                   "id": 1065772,
                    "groupId": 291577,
                     "name": "Attribute1",
                     "groupName": "Group 1"
              }]
      }]
  }],
}

Description (mandatory fields are marked in bold):

  • “meta”: objects
    • “id”: string - Unique instance ID.
    • “type”: string - The dictionary is a polygon.
    • “classId”: integer - Class ID (A class ID from the “classes.json” belonging to the instance’s corresponding class, or -1 if the instance is not classified).
    • "className": string - Class name (one of the class names in “classes.json”, or an empty value if the instance is not classified).
    • "createdBy": Information about the user who created the polygon.
      • "email": string - The email address of the user who created the polygon.
      • "role": string - The role of the user who created the polygon.
    • "createdAt": string - The date and time when the instance was created.
    • "updatedBy": Information about the user who updated the polygon.
      • "email": string - The email address of the user who updated the polygon.
      • "role": string - The role of the user who updated the polygon.
    • "updatedAt": string - The date and time when the polygon was updated.
    • “start”: integer - The time that marks the beginning of a polygon. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a polygon. The timestamp is in microseconds.
  • “parameters”: array
    • “start”: integer - The time that marks the beginning of a polygon. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a polygon. The timestamp is in microseconds.
    • “timestamps”: array - Shows information about a polygon at specific timestamps (start, end, edit).
      • “timestamp”: integer - Timestamp that marks the change of the polygon. The timestamp in microseconds.
      • “points”: objects - Points of the polygon in this location on the timeline.
      • “attributes”: array - List of attributes for the polygon, in this location on a timeline.
        • “id”: integer - Attribute ID (must be in “classes.json”)
        • “groupId”: integer - Attribute group ID (must be in “classes.json”)
        • "name": string - Attribute name
        • "groupName": string - Attributes group name

📘

  • If the objects createdBy and updatedBy exist, then email and role are mandatory.
  • If the array attributes exists, it can be either empty or it can contain objects with the following fields: name and groupName.

Polyline

{
  "meta": {
    "id": "MTc5NTAuMjE2MTEyNTIzOTY=",
    "type": "polyline",
    "classId": 5005974,
    "className": "Traffic sign",
    "createdBy": {
      "email": "[email protected]",
      "role": "Admin"
    },
    "createdAt": "2022-07-04T06:25:38.013Z",
    "updatedBy": {
      "email": "[email protected]",
      "role": "Admin"
    },
    "updatedAt": "2022-07-04T06:56:37.852Z",
    "start": 1569598,
    "end": 3110554,
  },
  "parameters": [
    {
      "start": 1569598,
      "end": 3110554,
      "timestamps": [
        {
          "points": [
            1209.22,
            550.59,
            1525.34,
            511.07,
            1527.81,
            423.2,
            1846.4,
            295.81,
            1848.73,
            295.81,
            1311.89,
            891.07,
            1315.63,
            880.51,
            1315.63,
            882.82
          ],
          "timestamp": 1569598,
          "attributes": [
            {
                   "id": 1065772,
                    "groupId": 291577,
                     "name": "Attribute 1",
                     "groupName": "Group 1"
              }
          ]
        },
        {
          "points": [
            444.76,
            925.27,
            760.88,
            885.75,
            763.35,
            797.88,
            1081.94,
            670.49,
            1084.27,
            670.49,
            547.43,
            1265.75,
            551.17,
            1255.19,
            551.17,
            1257.5
          ],
          "timestamp": 1858477,
          "attributes": [
            {
                   "id": 1065772,
                    "groupId": 291577,
                     "name": "Attribute 1",
                     "groupName": "Group 1"
              }
          ]
        },
        {
          "points": [
            444.76,
            925.27,
            763.35,
            797.88,
            1081.94,
            670.49,
            1084.27,
            670.49,
            547.43,
            1265.75,
            551.17,
            1255.19,
            551.17,
            1257.5
          ],
          "timestamp": 2039058,
          "attributes": [
            {
                   "id": 1065772,
                    "groupId": 291577,
                     "name": "Attribute 1",
                     "groupName": "Group 1"
              }
          ]
        },
        {
          "points": [
            444.76,
            925.27,
            852.42,
            1266.78,
            1081.94,
            670.49,
            1084.27,
            670.49,
            547.43,
            1265.75,
            551.17,
            1255.19,
            551.17,
            1257.5
          ],
          "timestamp": 2385171,
          "attributes": [
            {
                   "id": 1065772,
                    "groupId": 291577,
                     "name": "Attribute 1",
                     "groupName": "Group 1"
              }
          ]
        },
        {
          "points": [
            444.76,
            925.27,
            852.42,
            1266.78,
            1081.94,
            670.49,
            1084.27,
            670.49,
            547.43,
            1265.75,
            551.17,
            1255.19,
            551.17,
            1257.5
          ],
          "timestamp": 3110554,
          "attributes": [
            {
                   "id": 1065772,
                   "groupId": 291577,
                   "name": "Attribute 1",
                   "groupName": "Group 1"
              }
          ]
        }
      ]
    }
  ]
}

Description (mandatory fields are marked in bold):

  • “meta”: objects
    • “id”: string - Unique instance ID.
    • “type”: string - The dictionary is a polyline.
    • “classId”: integer - Class ID (A class ID from the “classes.json” belonging to the instance’s corresponding class, or -1 if the instance is not classified).
    • "className": string - Class name (one of the class names in “classes.json”, or an empty value if the instance is not classified).
    • "createdBy": Information about the user who created the polyline.
      • "email": string - The email address of the user who created the polyline.
      • "role": string - The role of the user who created the polyline.
    • "createdAt": string - The date and time when the instance was created.
    • "updatedBy": Information about the user who updated the polyline.
      • "email": string - The email address of the user who updated the polyline.
      • "role": string - The role of the user who updated the polyline.
    • "updatedAt": string - The date and time when the polyline was updated.
    • “start”: integer - The time that marks the beginning of a polyline. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a polyline. The timestamp is in microseconds.
  • “parameters”: array
    • “start”: integer - The time that marks the beginning of a polyline. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a polyline. The timestamp is in microseconds.
    • “timestamps”: array - Shows information about a polyline at specific timestamps (start, end, edit).
      • “timestamp”: integer - Timestamp that marks the change of the polyline. The timestamp in microseconds.
      • “points”: objects - Points of the polyline in this location on the timeline.
      • “attributes”: array - List of attributes for the polyline, in this location on a timeline.
        • “id”: integer - Attribute ID (must be in “classes.json”)
        • “groupId”: integer - Attribute group ID (must be in “classes.json”)
        • "name": string - Attribute name
        • "groupName": string - Attributes group name

📘

  • If the objects createdBy and updatedBy exist, then email and role are mandatory.
  • If the array attributes exists, it can be either empty or it can contain objects with the following fields: name and groupName.

Point

{
  "meta": {
    "id": "MTc5NTAuMjE2MTEyNTIzOTY=",
    "type": "point",
    "className": "Animal",
    "start": 0,
    "end": 4250000,
  },
  "parameters": [
    {
      "start": 0,
      "end": 4250000,
      "timestamps": [
        {
          "x": 6575.34,
          "y": 324.97,
          "timestamp": 3750000,
          "attributes": [
            {
              "name": "Running",
              "groupName": "Motion"
            }
          ]
        },
        {
          "x": 298.46,
          "y": 23.76,
          "timestamp": 4250000,
          "attributes": [
            {
              "name": "Jumping",
              "groupName": "Motion"
            }
          ]
        }
      ]
    }
  ]
}

Description (mandatory fields are marked in bold):

  • “meta”: objects
    • “id”: string - Unique instance ID.
    • “type”: string - The dictionary is a point.
    • "className": string - Class name (one of the class names in “classes.json”, or an empty value if the instance is not classified).
    • "createdBy": Information about the user who created the point.
      • "email": string - The email address of the user who created the point.
      • "role": string - The role of the user who created the point.
    • "createdAt": string - The date and time when the instance was created.
    • "updatedBy": Information about the user who updated the point.
      • "email": string - The email address of the user who updated the point.
      • "role": string - The role of the user who updated the point.
    • "updatedAt": string - The date and time when the point was updated.
    • “start”: integer - The time that marks the beginning of a point. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a point. The timestamp is in microseconds.
  • “parameters”: array
    • “start”: integer - The time that marks the beginning of a point. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a point. The timestamp is in microseconds.
    • “timestamps”: array - Shows information about a point at specific timestamps (start, end, edit).
      • “timestamp”: integer - Timestamp that marks the change of the point. The timestamp in microseconds.
      • “x”: integer - The x-coordinate of the instance.
      • “y”: integer - The y-coordinate of the instance.
      • “attributes”: array - List of attributes for the point, in this location on a timeline.
        • “id”: integer - Attribute ID (must be in “classes.json”)
        • “groupId”: integer - Attribute group ID (must be in “classes.json”)
        • "name": string - Attribute name
        • "groupName": string - Attributes group name

📘

  • If the objects createdBy and updatedBy exist, then email and role are mandatory.
  • If the array attributes exists, it can be either empty or it can contain objects with the following fields: name and groupName.

Event (timeline only)

[
         {
            "meta": {
                "id": "MTc5NTAuMjE2MTEyNTIzOTY=",
                "type": "event",
                "classId": 5005974,
                "className": "Car",
                "createdBy": {
                    "email": "[email protected]",
                    "role": "Annotator"
                },
                "createdAt": "2021-10-06T14:51:19.503Z",
                "updatedBy": {
                    "email": "[email protected]",
                    "role": "Admin"
                },
                "updatedAt": "2021-10-06T14:51:37.151Z",
                "start": 0,
                "end": 11546512},
            "parameters": [
                {
                    "start": 0,
                    "end": 11546512,
                    "timestamps": [
                        {
                            "timestamp": 0,
                            "attributes": [
                                {
                                    "id": 1176348,
                                    "groupId": 338632,
                                    "name": "Yellow",
                                    "groupName": "Color"
                                }
                            ]
                        },
                        {
                            "timestamp": 11546512,
                            "attributes": [
                                {
                                    "id": 1176348,
                                    "groupId": 338632,
                                    "name": "Yellow",
                                    "groupName": "Color"
                                }
                            ]
                        }]
                  }]
         }
]

Description (mandatory fields are marked in bold):

  • “meta”: objects
    • “id”: string - Unique instance ID.
    • “type”: The dictionary is an event.
    • “classId”: integer - Class ID (A class ID from the “classes.json” belonging to the instance’s corresponding class, or -1 if the instance is not classified).
    • "className": string - Class name (one of the class names in “classes.json”, or an empty value if the instance is not classified).
    • "createdBy": Information about the user who created the event.
      • "email": string - The email address of the user who created the event.
      • "role": string - The role of the user who created the event.
    • "createdAt": string - The date and time when the event was created.
    • "updatedBy": objects
      • "email": string - The email address of the user who updated the event.
      • "role": string - The role of the user who updated the event.
    • "updatedAt": string - The date and time when the event was updated.
    • “start”: integer - The time that marks the beginning of the event. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of the event. The timestamp is in microseconds.
  • “parameters”: array
    • “start”: integer - The time that marks the beginning of the event. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of the event. The timestamp is in microseconds.
    • “timestamps”: array - Shows information about the event at specific timestamps (start, end, edit).
      • “timestamp”: integer - Timestamp that marks the change of the event. The timestamp in microseconds.
      • “attributes”: array of objects - List of attributes for the event in this location on a timeline.
        • “id”: integer - Attribute ID (must be in “classes.json”)
        • “groupId”: integer - Attribute group ID (must be in “classes.json”)
        • "name": string - Attribute name (must be in “classes.json”)
        • "groupName": string - Attributes group name (must be in “classes.json”)

📘

About mandatory fields

  • If the objects createdBy and updatedBy exist, then email and role are mandatory.
  • If the array attributes exists, it can be either empty or it can contain objects with the following fields: name and groupName.

Tag

{
   "meta": {
     "type": "tag",
     "classId": 5005974,
     "className": "Weather",
     "createdBy": {
       "email": "[email protected]",
       "role": "Annotator"
     },
     "createdAt": "2022-07-18T09:27:45.813Z",
     "updatedBy": {
       "email": "[email protected]",
       "role": "QA"
     },
     "updatedAt": "2022-07-18T09:40:44.867Z",
     "attributes": [
       {
         "id": 847267,
         "groupId": 215515,
         "name": "Yes",
         "groupName": "Rainy"
       }
     ]
   }
 }
}

Description (mandatory fields are marked in bold):

  • “meta”: objects
    • “type”: string - The dictionary is a tag.
    • “classId”: integer - Class ID (A class ID from the “classes.json” belonging to the instance’s corresponding class).
    • "className": string - Class name (one of the class names in “classes.json”).
    • "createdBy": Information about the user who created the tag.
      • "email": string - The email address of the user who created the tag.
      • "role": string - The role of the user who created the tag.
    • "createdAt": string - The date and time when the instance was created.
    • "updatedBy": Information about the user who updated the tag.
      • "email": string - The email address of the user who updated the tag.
      • "role": string - The role of the user who updated the tag.
    • "updatedAt": string - The date and time when the tag was updated.
    • “attributes”: array - List of attributes for the tag.
      • “id”: integer - Attribute ID (must be in “classes.json”)
      • “groupId”: integer - Attribute group ID (must be in “classes.json”)
      • "name": string - Attribute name
      • "groupName": string - Attribute group name

📘

  • If the objects createdBy and updatedBy exist, then email and role are mandatory.
  • If the array attributes exists, it can be either empty or it can contain objects with the following fields: name and groupName.

Tags

Free text tag

[
        "Tag3",
        "Tag2",
        "Tag1"
]

Description:

  • "Tag": string - List of tag names added to the item.

Comments

{
   "meta": {
     "type": "comment",
     "resolved": false,
     "start": 0,
     "end": 10000,
     "createdBy": {
       "email": "[email protected]",
       "role": "Admin"
     },
     "createdAt": "2022-07-18T09:27:45.813Z",
     "updatedBy": {
       "email": "[email protected]",
       "role": "Admin"
     },
     "updatedAt": "2022-07-18T09:40:44.867Z",
     "correspondence": [
       {
         "text": "Fix this",
         "email": "[email protected]",
         "role": "Admin",
         "createdAt": "2021-01-14T07:34:00.695Z"
       },
       {
         "text": "Fixed",
         "email": "[email protected]",
         "role": "Admin",
         "createdAt": "2021-01-15T07:34:00.695Z"
       }
     ]
   },
   "parameters": [
     {
       "start": 0,
       "end": 10000,
       "timestamps": [
         {
           "timestamp": 0,
           "points": {
             "x1": 10,
             "x2": 10,
             "y1": 10,
             "y2": 20
           }
         },
         {
           "timestamp": 7000,
           "points": {
             "x1": 10,
             "x2": 10,
             "y1": 20,
             "y2": 20
           }
         },
         {
           "timestamp": 10000,
           "points": {
             "x1": 10,
             "x2": 10,
             "y1": 15,
             "y2": 15
           }
         }
        ]
     }
   ]
 }

Description:

  • “meta”: objects
    • “type”: string - The dictionary is a comment.
    • “resolved”: boolean - If it’s True, then the comment is resolved. If it’s False, then the comment isn't resolved. When you upload a comment, the default value is false.
    • “start”: integer - The time that marks the beginning of the comment. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of the comment. The timestamp is in microseconds.
    • “createdBy”: objects - Information about the user who created the comment.
      • “email”: string - The email of the user who created the comment.
      • “role”: string - The role of the user who created the comment.
    • “createdAt”: string - The date and time when the comment was created.
    • “updatedBy”: objects - Information about the user who last updated the comment.
      • “email”: string - The email address of the user who last updated the comment.
      • “role”: string - The role of the user who last updated the comment.
    • “updatedAt”: string - The time the comment was updated.
    • "correspondence": array of objects - List of messages in the comment.
      • "text": string - The comment.
      • "email": string - The email address of the user who wrote the comment.
      • “role”: string - The role of the user who last creates the comment.
      • “createdAt”: string - The date and time when the comment was created.
  • “parameters”: array
    • “start”: integer - The time that marks the beginning of a comment. The timestamp is in microseconds.
    • “end”: integer - The time that marks the end of a comment. The timestamp is in microseconds.
    • “timestamps”: array - Shows information about a comment at specific timestamps (start, end, edit).
      • “timestamp”: integer - Timestamp that marks the change of the comment. The timestamp is in microseconds.
      • “points”: objects - Points of the comment in this location on the timeline. The list of floats is: "x1, y1" for the left upper corner and "x2, y2" for the right lower corner.