Subscribe to release notesStatus pageCommunity
Developer guides

Import video data

How to import video data and sample import formats.

Specifications

Supported file format: MP4

Video encoding: H.264 (also referred to as AVC), H.265

256 MB max file size

Import methods:

  • IAM Delegated Access
  • Signed URLs (https URLs only)
  • Direct upload of local files
    Note: Direct upload currently does not support adding additional metadata and attachments. See the Python example below.

Videos have to pass the frame-count consistency check as well. Read below for details.

🚧

Frame-Count Consistency

Please note that the Labelbox Editor only supports videos which have frame-count consistency. This is achieved when

Frames Per Second (FPS) x Video Duration (Number of secs) == Total Number of Frames

While real-world videos may not always satisfy this requirement due to different encoding schemas, we warn you about this on upload with the message "Unsupported video detected" so you can proceed with caution when labeling.

Why do we check for this? Because while labeling, every frame unaccounted for is a potential error.

Some common examples where frame-count consistency is not achieved:

  • Variable frame rate
  • Negative frame presentation times (PTS)

You can utilize the FFmpeg command line tool to process videos into a compatible format with the following command: ffmpeg -i <input.mp4> -vcodec libx264 -acodec aac <output.mp4>

❗️

Unsupported attributes

Please note that the Labelbox Editor does not support videos with:

  • Non-square sample aspect ratios (may appear stretched or squashed)

Videos that contain these attributes will be flagged or blocked in the Editor, and will soon be flagged at the time of import as well.

When importing video data to Labelbox, your JSON file must include the following information for each video.

ParameterRequiredDescription
row_dataYeshttps path to a cloud-hosted video. For IAM Delegated Access, this URL must be in virtual-hosted-style format. For older regions, your S3 bucket may be in https://<bucket-name>.s3.<region>.amazonaws.com/<key> format. If your object URLs are formatted this way, make sure they are in the virtual-hosted-style format before importing.
global_keyNoUnique user-generated file name or ID for the file. Global keys are enforced to be unique in your org. Data rows will not be imported if its global keys are duplicated to existing data rows.
media_typeNo"VIDEO" (optional media type to provide better validation and error messaging)
metadata_fieldsNoSee Metadata.
attachmentsNoSee Attachments and Asset overlays.

Import format

[
  {
    "row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/video-samples/sample-video-1.mp4",
    "global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/video-samples/sample-video-1.mp4",
    "media_type": "VIDEO",
    "metadata_fields": [{"name": "<metadata_field_name>", "value": "tag_string"}],
    "attachments": [{"type": "VIDEO", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4" }]
  },
  {
    "row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/video-samples/sample-video-2.mp4",
    "global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/video-samples/sample-video-2.mp4",
    "media_type": "VIDEO",
    "metadata_fields": [{"name": "<metadata_field_name>", "value": "tag_string"}],
    "attachments": [{"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"}]
  }
]

[
  {
    "row_data": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-1.mp4",
    "global_key": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-1.mp4",
    "media_type": "VIDEO",
    "metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
    "attachments": [{"type": "VIDEO", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4" }]
  },
  {
    "row_data": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-2.mp4",
    "global_key": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-2.mp4",
    "media_type": "VIDEO",
    "metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
    "attachments": [{"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"}]
  }
]

Python example

from labelbox import Client
from uuid import uuid4 ## to generate unique IDs
import datetime 

client = Client(api_key="<YOUR_API_KEY>")

dataset = client.create_dataset(name="Bulk import example - Video")

assets = [
  {
    "row_data": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-1.mp4",
    "global_key": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-1.mp44",
    "media_type": "VIDEO",
    "metadata_fields": [{"name": "<metadata_field_name>", "value": "tag_string"}],
    "attachments": [{"type": "VIDEO", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4" }]
  },
  {
    "row_data": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-2.mp4",
    "global_key": "https://storage.googleapis.com/labelbox-datasets/video-sample-data/sample-video-2.mp4",
    "media_type": "VIDEO",
    "metadata_fields": [{"name": "<metadata_field_name>", "value": "tag_string"}],
    "attachments": [{"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"}]
  }
]

task = dataset.create_data_rows(assets)
task.wait_till_done()
print(task.errors)

local_file_paths = ['path/to/local/file1', 'path/to/local/file1'] # limit: 15k files


new_dataset = client.create_dataset(name = "Local files upload")

try:
    task = new_dataset.create_data_rows(local_file_paths)
    task.wait_till_done()
except Exception as err:
    print(f'Error while creating labelbox dataset -  Error: {err}')