VideoApi¶

class VideoApi(api)[source]¶

Bases: RemoveableBulkModuleApi

API for working with videos.

Parameters:

api¶: Api object to use for API connection.

Usage Example:

import supervisely as sly
api = sly.Api.from_env()
video_info = api.video.get_info_by_id(video_id)

Methods

`add_existing`	Add existing video from source Dataset to destination Dataset.
`check_existing_hashes`	Checks existing hashes for Videos.
`convert_info_to_json`	Convert information about an entity to a dictionary.
`copy_batch`	Copies Videos with given IDs to Dataset.
`download_frames`
`download_path`	Downloads Video from Dataset to local path by ID.
`download_path_async`	Downloads Video with given ID to local path.
`download_paths_async`	Download Videos with given IDs and saves them to given local paths asynchronously.
`download_range_by_id`	Downloads Video with given ID between given start and end frames.
`download_range_by_path`	Downloads Video with given path in Supervisely between given start and end frames.
`download_save_range`	Download video with given ID in Supervisely between given start and end frames on the given path.
`exists`	Checks if an entity with the given parent_id and name exists
`get_destination_ids`	Get project ID and dataset ID for given Video ID.
`get_free_name`	Generates a free name for an entity with the given parent_id and name.
`get_free_names`	Returns list of free names for given dataset.
`get_info_by_id`	Get Video information by ID in `VideoInfo` format.
`get_info_by_id_batch`	Get Video information by ID.
`get_info_by_name`	Get information about an entity by its name from the Supervisely server.
`get_json_info_by_id`	Get Video information by ID in json format.
`get_list`	Get list of information about all videos for a given dataset ID.
`get_list_all_pages`	Get list of all or limited quantity entities from the Supervisely server.
`get_list_all_pages_generator`	This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved
`get_list_generator`
`get_list_idx_page_async`	Get the list of items for a given page number.
`get_list_page_generator_async`	Yields list of images in dataset asynchronously page by page.
`info_sequence`	Get list of all `VideoInfo` field names.
`info_tuple_name`	Get string name of `VideoInfo` NamedTuple.
`notify_progress`	Send message to the Annotation Tool and return info if tracking was stopped
`notify_tracking_error`	Send message to the Annotation Tool
`notify_tracking_warning`
`raise_name_intersections_if_exist`	Raises error if videos with given names already exist in dataset.
`remove`	Remove video from supervisely by id.
`remove_batch`	Remove videos from supervisely by IDs.
`rename`	Renames Video with given ID to a new name.
`set_remote`	Updates the source of existing videos by setting new remote links.
`update_custom_data`	Upload custom data info in VideoInfo object.
`upload_dir`	Uploads all videos with supported extensions from given directory to Supervisely.
`upload_dirs`	Uploads all videos with supported extensions from given directories to Supervisely.
`upload_hash`	Upload Video from given hash to Dataset.
`upload_hashes`	Upload Videos from given hashes to Dataset.
`upload_id`	Uploads video from given id to Dataset.
`upload_ids`	Uploads videos from given ids to Dataset.
`upload_link`	Upload Video from given link to Dataset.
`upload_links`	Upload Videos from given links to Dataset.
`upload_path`	Uploads Video with given name from given local path to Dataset.
`upload_paths`	Uploads Videos with given names from given local paths to Dataset.
`upsert_info`	Update Video file metadata
`upsert_infos`	Update Video files metadata
`url`	Get url of the video by dataset ID and video ID

Attributes

`MAX_WAIT_ATTEMPTS`	Maximum number of attempts that will be made to wait for a certain condition to be met.
`WAIT_ATTEMPT_TIMEOUT_SEC`	Number of seconds for intervals between attempts.

InfoType¶: alias of VideoInfo

classmethod convert_info_to_json(info)¶

Convert information about an entity to a dictionary.

Parameters:

info : NamedTuple¶: Information about the entity.

Returns:

Dictionary with information about the entity.

Return type:

dict

static info_sequence()[source]¶

Get list of all VideoInfo field names.

Returns:: List of VideoInfo field names.
Return type:: List[str]

static info_tuple_name()[source]¶

Get string name of VideoInfo NamedTuple.

Returns:: NamedTuple name.
Return type:: str

add_existing(dataset_id, video_info, name)[source]¶

Add existing video from source Dataset to destination Dataset.

Parameters:

dataset_id : int¶: Destination Dataset ID in Supervisely.
video_info¶: Information about the video.
name : str¶: Video name.

Returns:

Information about Video.

Return type:

VideoInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55846
video_id = 19371139

video_info = api.video.get_info_by_id(video_id)

new_info = api.video.add_existing(dataset_id, video_info, "sea lion.mp4")
print(new_info)

# Output:
# VideoInfo(
#     id=19371140,
#     name='sea lion.mp4'
#     hash='30/TQ1BcIOn1AI4RFgRO/6psRtr3lqNPmr4uQ=',
#     link=None,
#     team_id=435,
#     workspace_id=684,
#     project_id=17208,
#     dataset_id=55846,
#     path_original='/h5ung-public/videos/Z/d/HD/lfgipl...NXrg5vz.mp4',
#     frames_to_timecodes=[],
#     frames_count=245,
#     frame_width=1920,
#     frame_height=1080,
#     created_at='2023-02-07T19:35:01.808Z',
#     updated_at='2023-02-07T19:35:01.808Z',
#     tags=[],
#     file_meta={
#         'codecName': 'h264',
#         'codecType': 'video',
#         'duration': 10.218542,
#         'formatName': 'mov,mp4,m4a,3gp,3g2,mj2',
#         'framesCount': 245,
#         'framesToTimecodes': [],
#         'height': 1080,
#         'index': 0,
#         'mime': 'video/mp4',
#         'rotation': 0,
#         'size': '6795452',
#         'startTime': 0,
#         'streams': [],
#         'width': 1920
#     },
#     custom_data={},
#     processing_path='1/194'
# )

check_existing_hashes(hashes)[source]¶

Checks existing hashes for Videos.

Parameters:

hashes : List[str]¶: List of hashes.

Returns:

List of existing hashes

Return type:

List[str]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

# Helpful method when your uploading was interrupted
# You can check what videos has been successfully uploaded by their hashes and what not
# And continue uploading the rest of the videos from that point

# Find project
project = api.project.get_info_by_id(WORKSPACE_ID, PROJECT_ID)

# Get paths of all videos in a directory
videos_paths = sly.fs.list_files('videos_to_upload')

#Calculate hashes for all videos paths
hash_to_video = {}
videos_hashes = []

for idx, item in enumerate(videos_paths):
    item_hash = sly.fs.get_file_hash(item)
    videos_hashes.append(item_hash)
    hash_to_video[item_hash] = item

# Get hashes that are already on server
remote_hashes = api.video.check_existing_hashes(videos_hashes)
already_uploaded_videos = {hh: hash_to_video[hh] for hh in remote_hashes}

copy_batch(dst_dataset_id, ids, change_name_if_conflict=False, with_annotations=False, progress_cb=None)[source]¶

Copies Videos with given IDs to Dataset.

Parameters:

dst_dataset_id : int¶: Destination Dataset ID in Supervisely.
ids : List[int]¶: Videos IDs in Supervisely.
change_name_if_conflict : bool, optional¶: If True adds suffix to the end of Image name when Dataset already contains an Image with identical name, If False and images with the identical names already exist in Dataset raises error.
with_annotations : bool, optional¶: If True Image will be copied to Dataset with annotations, otherwise only Images without annotations.
progress_cb : tqdm or callable, optional¶: Function for tracking the progress of copying.

Raises:

TypeError – if type of ids is not list
ValueError – if videos ids are from the destination Datasetю

Returns:

List with information about Videos.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 1780
video_infos = api.video.get_list(dataset_id)
video_ids = [video_info.id for video_info in video_infos]

destination_dataset_id = 2574
destination_video_infos = api.video.copy_batch(destination_dataset_id, video_ids, with_annotations=True)

download_path(id, path, progress_cb=None)[source]¶

Downloads Video from Dataset to local path by ID.

Parameters:

id : int¶: Video ID in Supervisely.
path : str¶: Local save path for Video.
progress_cb : tqdm or callable, optional¶: Function to check progress.

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_info = api.video.get_info_by_id(770918)
save_path = os.path.join("/home/admin/work/projects/videos/", video_info.name)
api.video.download_path(770918, save_path)

async download_path_async(id, path, semaphore=None, range_start=None, range_end=None, headers=None, chunk_size=1048576, check_hash=True, progress_cb=None, progress_cb_type='number')[source]¶

Downloads Video with given ID to local path.

Parameters:

id : int¶: Video ID in Supervisely.
path : str¶: Local save path for video.
semaphore=None¶: Semaphore for limiting the number of simultaneous downloads.
range_start : int, optional¶: Start byte of range for partial download.
range_end : int, optional¶: End byte of range for partial download.
headers : dict, optional¶: Headers for request.
chunk_size : int, optional¶: Size of chunk for partial download. Default is 1MB.
check_hash : bool, optional¶: If True, checks hash of downloaded file. Check is not supported for partial downloads. When range is set, hash check is disabled.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
progress_cb_type : Literal["number", "size"], optional¶: Type of progress callback. Can be “number” or “size”. Default is “number”.

Returns:

None

Return type:

None

Usage Example:

import os
import asyncio
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_info = api.video.get_info_by_id(770918)
save_path = os.path.join("/path/to/save/", video_info.name)

semaphore = asyncio.Semaphore(100)
loop = sly.utils.get_or_create_event_loop()
loop.run_until_complete(
    api.video.download_path_async(video_info.id, save_path, semaphore)
)

async download_paths_async(ids, paths, semaphore=None, headers=None, chunk_size=1048576, check_hash=True, progress_cb=None, progress_cb_type='number')[source]¶

Download Videos with given IDs and saves them to given local paths asynchronously.

Parameters:

ids¶: List of Video IDs in Supervisely.
paths¶: Local save paths for Videos.
semaphore=None¶: Semaphore
headers : dict, optional¶: Headers for request.
chunk_size : int, optional¶: Size of chunk for partial download. Default is 1MB.
check_hash : bool, optional¶: If True, checks hash of downloaded files.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
progress_cb_type : Literal["number", "size"], optional¶: Type of progress callback. Can be “number” or “size”. Default is “number”.

Raises:

ValueError – if len(ids) != len(paths)

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

ids = [770914, 770915]
paths = ["/path/to/save/video1.mp4", "/path/to/save/video2.mp4"]
loop = sly.utils.get_or_create_event_loop()
loop.run_until_complete(api.video.download_paths_async(ids, paths))

download_range_by_id(id, frame_start, frame_end, is_stream=True)[source]¶

Downloads Video with given ID between given start and end frames.

Parameters:

id : int¶: Video ID in Supervisely.
frame_start : int¶: Start frame for video download.
frame_end : int¶: End frame for video download.
is_stream : bool, optional¶: Use stream for video download or not.

Returns:

Response object

Return type:

Response

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198835945
start_fr = 5
end_fr= 35
response = api.video.download_range_by_id(video_id, start_fr, end_fr)

download_range_by_path(path_original, frame_start, frame_end, is_stream=False)[source]¶

Downloads Video with given path in Supervisely between given start and end frames.

Parameters:

path_original : str¶: Path to Video in Supervisely.
frame_start : int¶: Start frame for video download.
frame_end : int¶: End frame for video download.
is_stream : bool, optional¶: Use stream for video download or not.

Returns:

Response object

Return type:

Response

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198835945
start_fr = 5
end_fr= 35
video_info = api.video.get_info_by_id(video_id)
path_sl = video_info.path_original
response = api.video.download_range_by_path(path_sl, start_fr, end_fr)

download_save_range(video_id, frame_start, frame_end, save_path)[source]¶

Download video with given ID in Supervisely between given start and end frames on the given path.

Parameters:

video_id : int¶: Video ID in Supervisely.
frame_start : int¶: Start frame for video download.
frame_end : int¶: End frame for video download.
save_path : str¶: Path to save video.

Returns:

Full path to saved video

Return type:

str

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198835945
start_fr = 5
end_fr= 35
video_info = api.video.get_info_by_id(video_id)
name = video_info.name
save_path = os.path.join('/home/admin/work/projects/videos', name)
result = api.video.download_save_range(video_id, start_fr, end_fr, save_path)
print(result)
# Output: /home/admin/work/projects/videos/MOT16-03.mp4

exists(parent_id, name)¶

Checks if an entity with the given parent_id and name exists

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity.

Returns:

Returns True if entity exists, and False if not

Return type:

bool

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
exists = api.image.exists(dataset_id, name)
print(exists) # True

get_destination_ids(id)[source]¶

Get project ID and dataset ID for given Video ID.

Parameters:

id : int¶: Video ID in Supervisely.

Returns:

Project ID and dataset ID

Return type:

Tuple[int, int]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198702499
project_id, dataset_id = api.video.get_destination_ids(video_id)

print(project_id, dataset_id)
# Output: 17208 55846

get_free_name(parent_id, name)¶

Generates a free name for an entity with the given parent_id and name. Adds an increasing suffix to original name until a unique name is found.

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity.

Returns:

Returns free name.

Return type:

str

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
free_name = api.image.get_free_name(dataset_id, name)
print(free_name) # IMG_0315_001.jpeg

get_free_names(dataset_id, names)[source]¶

Returns list of free names for given dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: List of names to check.

Returns:

List of free names.

Return type:

List[str]

get_info_by_id(id, raise_error=False, force_metadata_for_links=True)[source]¶

Get Video information by ID in VideoInfo format.

Parameters:

id : int¶: Video ID in Supervisely.
raise_error : bool¶: Return an error if the video info was not received.
force_metadata_for_links : bool¶: Specify whether to force retrieving video metadata from the server.

Returns:

Information about Video.

Return type:

VideoInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198702499
video_info = api.video.get_info_by_id(video_id)
print(video_info)
# Output:
# VideoInfo(
#     id=198702499,
#     name='Videos_dataset_animals_sea_lion.mp4'
#     hash='30/TQ1BcIOn1AI4RFgRO/6psRtr3lqNPmr4uQ=',
#     link=None,
#     team_id=435,
#     workspace_id=684,
#     project_id=17208,
#     dataset_id=55846,
#     path_original='/h5s-public/videos/Z/d/HD/lfgNXrg5vz.mp4',
#     frames_to_timecodes=[],
#     frames_count=245,
#     frame_width=1920,
#     frame_height=1080,
#     created_at='2023-02-07T19:35:01.808Z',
#     updated_at='2023-02-07T19:35:01.808Z',
#     tags=[],
#     file_meta={
#         'codecName': 'h264',
#         'codecType': 'video',
#         'duration': 10.218542,
#         'formatName': 'mov,mp4,m4a,3gp,3g2,mj2',
#         'framesCount': 245,
#         'framesToTimecodes': [],
#         'height': 1080,
#         'index': 0,
#         'mime': 'video/mp4',
#         'rotation': 0,
#         'size': '6795452',
#         'startTime': 0,
#         'streams': [],
#         'width': 1920
#     },
#     custom_data={},
#     processing_path='1/194'
# )

get_info_by_id_batch(ids, progress_cb=None, force_metadata_for_links=False)[source]¶

Get Video information by ID.

Parameters:

ids : List[int]¶: List of Video IDs in Supervisely, they must belong to the same dataset.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
force_metadata_for_links : bool¶: Specify whether to force retrieving video metadata from the server.

Returns:

List of information about Videos.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_ids = [376728, 376729, 376730, 376731, 376732, 376733]
video_infos = api.video.get_info_by_id_batch(video_ids)

get_info_by_name(parent_id, name, fields=[])¶

Get information about an entity by its name from the Supervisely server.

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity for which the information is being retrieved.
fields : List[str]¶: The list of api fields which will be returned with the response.

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55832
name = "IMG_0315.jpeg"
info = api.image.get_info_by_name(dataset_id, name)
print(info)
# Output: ImageInfo(id=19369643, name='IMG_0315.jpeg', ...)

get_json_info_by_id(id, raise_error=False, force_metadata_for_links=True)[source]¶

Get Video information by ID in json format.

Parameters:

id : int¶: Video ID in Supervisely.
raise_error : bool¶: Return an error if the video info was not received.
force_metadata_for_links : bool¶: Specify whether to force retrieving video metadata from the server.

Returns:

Information about Video.

Return type:

dict

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 19371139
video_info = api.video.get_info_by_id(video_id)
print(video_info)
# Output:
# {
#     'createdAt': '2023-02-07T19:35:01.808Z',
#     'customData': {},
#     'datasetId': 55846,
#     'description': '',
#     'fileMeta': {
#         'codecName': 'h264',
#         'codecType': 'video',
#         'duration': 10.218542,
#         'formatName': 'mov,mp4,m4a,3gp,3g2,mj2',
#         'framesCount': 245,
#         'framesToTimecodes': [],
#         'height': 1080,
#         'index': 0,
#         'mime': 'video/mp4',
#         'rotation': 0,
#         'size': '6795452',
#         'startTime': 0,
#         'streams': [],
#         'width': 1920
#     },
#     'fullStorageUrl': 'https://app.supervisely.com/h..i35vz.mp4',
#     'hash': '30/TQ1BcIOn1ykA2psRtr3lq3HF6NPmr4uQ=',
#     'id': 19371139,
#     'link': None,
#     'meta': {'videoStreamIndex': 0},
#     'name': 'Videos_dataset_animals_sea_lion.mp4',
#     'pathOriginal': '/h5u1vqgms4-public/videos/Z/d/HD/lfgiplg5vz.mp4',
#     'processingPath': '1/194',
#     'projectId': 17208,
#     'tags': [
#         {
#             'createdAt': '2023-02-07T19:35:01.808Z',
#             'entityId': 19371139,
#             'frameRange': [244, 244],
#             'id': 12241539,
#             'labelerLogin': 'admin',
#             'tagId': 377141,
#             'updatedAt': '2023-02-07T19:35:01.808Z'
#         }
#     ],
#     'teamId': 435,
#     'updatedAt': '2023-02-07T19:35:01.808Z',
#     'workspaceId': 684
# }

get_list(dataset_id, filters=None, raw_video_meta=False, fields=None, force_metadata_for_links=False)[source]¶

Get list of information about all videos for a given dataset ID.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
filters : List[Dict[str, str]], optional¶: List of parameters to sort output Videos. See: https://api.docs.supervisely.com/#tag/Videos/paths/~1videos.list/get
raw_video_meta : bool¶: Get normalized metadata from server if False.
fields : List[str], optional¶: List of fields to return.
force_metadata_for_links : Optional[bool]¶: Specify whether to force retrieving video metadata from the server.

Returns:

List of information about videos in given dataset.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55846
video_infos = api.video.get_list(dataset_id)
print(video_infos)
# Output: [VideoInfo(...), VideoInfo(...)]

filtered_video_infos = api.video.get_list(dataset_id, filters=[{'field': 'id', 'operator': '=', 'value': '19371139'}])
print(filtered_video_infos)
# Output: [VideoInfo(id=19371139, ...)]

get_list_all_pages(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

Get list of all or limited quantity entities from the Supervisely server.

Parameters:

method : str¶: Request method name
data : dict¶: Dictionary with request body info
progress_cb : Progress, optional¶: Function for tracking download progress.
convert_json_info_cb : Callable, optional¶: Function for convert json info
limit : int, optional¶: Number of entity to retrieve
return_first_response : bool, optional¶: Specify if return first response

Returns:

List of entities.

Return type:

List[dict]

get_list_all_pages_generator(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

Parameters:

method : str¶: Request method name
data : dict¶: Dictionary with request body info
progress_cb : Progress, optional¶: Function for tracking download progress.
convert_json_info_cb : Callable, optional¶: Function for convert json info
limit : int, optional¶: Number of entity to retrieve
return_first_response : bool, optional¶: Specify if return first response

async get_list_idx_page_async(method, data)¶

Get the list of items for a given page number. Page number is specified in the data dictionary.

Parameters:

method : str¶: Method to call for listing items.
data : dict¶: Data to pass to the API method.

Returns:

List of items.

Return type:

Tuple[int, List[NamedTuple]]

async get_list_page_generator_async(method, data, pages_count=None, semaphore=None)¶

Yields list of images in dataset asynchronously page by page.

Parameters:

method : str¶: Method to call for listing items.
data : dict¶: Data to pass to the API method.
pages_count : int, optional¶: Preferred number of pages to retrieve if used with a per_page limit. Will be automatically adjusted if the pagesCount differs from the requested number.
semaphore=None¶: Semaphore for limiting the number of simultaneous requests.

Returns:

List of images in dataset.

Return type:

AsyncGenerator[List[ImageInfo]]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

method = 'images.list'
data = {'datasetId': 123456}

loop = sly.utils.get_or_create_event_loop()
images = loop.run_until_complete(api.image.get_list_generator_async(method, data))

notify_progress(track_id, video_id, frame_start, frame_end, current, total, extra_data=None)[source]¶

Send message to the Annotation Tool and return info if tracking was stopped

Parameters:

track_id¶: int
video_id¶: int
frame_start¶: int
frame_end¶: int
current¶: int
total¶: int
extra_data : Optional[Dict]¶: Additional payload fields to merge into the notification data.

Returns:

str

notify_tracking_error(track_id, error, message)[source]¶

Send message to the Annotation Tool

Parameters:

track_id¶: int
error¶: str
message¶: str

Returns:

None

raise_name_intersections_if_exist(dataset_id, names, message=None)[source]¶

Raises error if videos with given names already exist in dataset. Default error message: “Videos with the following names already exist in dataset [ID={dataset_id}]: {name_intersections}. Please, rename videos and try again or set change_name_if_conflict=True to rename automatically on upload.”

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: List of names to check.
message : str, optional¶: Error message.

Returns:

None

Return type:

None

remove(video_id)[source]¶

Remove video from supervisely by id.

Parameters:

video_id : int¶: Videos ID in Supervisely.

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 2389126
api.video.remove(video_id)

remove_batch(ids, progress_cb=None, batch_size=50)[source]¶

Remove videos from supervisely by IDs. All video IDs must belong to the same dataset. Therefore, it is necessary to sort IDs before calling this method.

Parameters:

ids : List[int]¶: List of Videos IDs in Supervisely.
progress_cb : tqdm or callable, optional¶: Function for tracking progress of removing.

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_ids = [2389126, 2389127]
api.video.remove_batch(video_ids)

rename(id, name)[source]¶

Renames Video with given ID to a new name.

Parameters:

id : int¶: Video ID in Supervisely.
name : str¶: New Video name.

Returns:

Information about updated video.

Return type:

VideoInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 123456
new_video_name = "VID_3333_new.mp4"
api.video.rename(id=video_id, name=new_video_name)

set_remote(videos, links)[source]¶

Updates the source of existing videos by setting new remote links. This method is used when a video was initially uploaded as a file or added via a link, but later it was decided to change its location (e.g., moved to another storage or re-uploaded elsewhere). By updating the link, the video source can be redirected to the new location.

Parameters:

videos : List[int]¶: List of video ids.
links : List[str]¶: List of new remote links.

Returns:

json-encoded content of a response.

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

videos = [123, 124, 125]
links = [
    "s3://bucket/f1champ/ds1/lap_1.mp4",
    "s3://bucket/f1champ/ds1/lap_2.mp4",
    "s3://bucket/f1champ/ds1/lap_3.mp4",
]
result = api.video.set_remote(videos, links)

update_custom_data(id, data)[source]¶

Upload custom data info in VideoInfo object.

Parameters:

video_id : int: Videos ID in Supervisely.
metas : dict: Metadata dict with custom values. Note: Do not recommend changing metas as it affects displaying data in label tools. In case changing the metadata is necessary, make sure to include an “streams” field with its value in the request body.

Returns:

Return updating result

Return type:

dict

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 19402023
api.video.update_custom_data(video_id, {"field": "value"})
video_info = api.video.get_info_by_id(video_id)
print(video_info.custom_data)
# Output: {'field': 'value'}

upload_dir(dataset_id, dir_path, recursive=True, change_name_if_conflict=True, progress_cb=None)[source]¶

Uploads all videos with supported extensions from given directory to Supervisely. Optionally, uploads videos from subdirectories of given directory.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
dir_path : str¶: Path to directory with videos.
recursive : bool, optional¶: If True, will upload videos from subdirectories of given directory recursively. Otherwise, will upload videos only from given directory.
change_name_if_conflict : bool, optional¶: If True adds suffix to the end of Video name when Dataset already contains an Video with identical name, If False and videos with the identical names already exist in Dataset raises error.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking upload progress.

Returns:

List of uploaded videos infos

Return type:

List[VideoInfo]

upload_dirs(dataset_id, dir_paths, recursive=True, change_name_if_conflict=True, progress_cb=None)[source]¶

Uploads all videos with supported extensions from given directories to Supervisely. Optionally, uploads videos from subdirectories of given directories.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
dir_paths : List[str]¶: List of paths to directories with videos.
recursive : bool, optional¶: If True, will upload videos from subdirectories of given directories recursively. Otherwise, will upload videos only from given directories.
change_name_if_conflict : bool, optional¶: If True adds suffix to the end of Video name when Dataset already contains an Video with identical name, If False and videos with the identical names already exist in Dataset raises error.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking upload progress.

Returns:

List of uploaded videos infos

Return type:

List[VideoInfo]

upload_hash(dataset_id, name, hash, stream_index=None, metadata=None)[source]¶

Upload Video from given hash to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
name : str¶: Video name with extension.
hash : str¶: Video hash.
stream_index : int, optional¶: Index of video stream.
metadata : dict, optional¶: Video metadata.

Returns:

Information about Video.

Return type:

VideoInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dst_dataset_id = 55846
src_video_id = 186580617
video_info = api.video.get_info_by_id(src_video_id)
hash = video_info.hash
# It is necessary to upload video with the same extention as in src dataset
name = video_info.name
new_video_info = api.video.upload_hash(dst_dataset_id, name, hash)
print(new_video_info)
# Output:
# VideoInfo(
#     id=19371139,
#     name='Videos_dataset_animals_sea_lion.mp4'
#     hash='30/TQ1BcIOn1AI4RFgRO/6psRtr3lqNPmr4uQ=',
#     link=None,
#     team_id=435,
#     workspace_id=684,
#     project_id=17208,
#     dataset_id=55846,
#     path_original='/h5s-public/videos/Z/d/HD/lfgNXrg5vz.mp4',
#     frames_to_timecodes=[],
#     frames_count=245,
#     frame_width=1920,
#     frame_height=1080,
#     created_at='2023-02-07T19:35:01.808Z',
#     updated_at='2023-02-07T19:35:01.808Z',
#     tags=[],
#     file_meta={
#         'codecName': 'h264',
#         'codecType': 'video',
#         'duration': 10.218542,
#         'formatName': 'mov,mp4,m4a,3gp,3g2,mj2',
#         'framesCount': 245,
#         'framesToTimecodes': [],
#         'height': 1080,
#         'index': 0,
#         'mime': 'video/mp4',
#         'rotation': 0,
#         'size': '6795452',
#         'startTime': 0,
#         'streams': [],
#         'width': 1920
#     },
#     custom_data={},
#     processing_path='1/194'
# )

upload_hashes(dataset_id, names, hashes, metas=None, progress_cb=None)[source]¶

Upload Videos from given hashes to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: Videos names with extension.
hashes : List[str]¶: Videos hashes.
metas : List[dict], optional¶: Videos metadata.
progress_cb : tqdm or callable, optional¶: Function for tracking download progress.

Returns:

List with information about Videos.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

src_dataset_id = 466639
dst_dataset_id = 468620

hashes = []
names = []
metas = []
video_infos = api.video.get_list(src_dataset_id)
# Create lists of hashes, videos names and meta information for each video
for video_info in video_infos:
    hashes.append(video_info.hash)
    # It is necessary to upload videos with the same names(extentions) as in src dataset
    names.append(video_info.name)
    metas.append({video_info.name: video_info.frame_height})

progress = sly.Progress("Videos upload: ", len(hashes))
new_videos_info = api.video.upload_hashes(dst_dataset_id, names, hashes, metas, progress.iters_done_report)

# Output:
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Videos upload: ", "current": 0, "total": 2, "timestamp": "2021-03-24T10:18:57.111Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Videos upload: ", "current": 2, "total": 2, "timestamp": "2021-03-24T10:18:57.304Z", "level": "info"}

upload_id(dataset_id, name, id, meta=None)[source]¶

Uploads video from given id to Dataset.

Parameters:

dataset_id : int¶: Destination dataset ID.
name : str¶: Video name with extension.
id : int¶: Source video ID in Supervisely.
meta : Optional[Dict]¶: Video metadata.

Returns:

Information about Video.

Return type:

VideoInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

src_video_id = 186580617
dst_dataset_id = 468620

new_video_info = api.video.upload_id(dst_dataset_id, 'new_video_name.mp4', src_video_id)

upload_ids(dataset_id, names, ids, metas=None, progress_cb=None, infos=None)[source]¶

Uploads videos from given ids to Dataset.

Parameters:

dataset_id : int¶: Destination dataset ID.
names : List[str]¶: Videos names with extension.
ids : List[int]¶: Source videos IDs in Supervisely.
metas : Optional[List[Dict]]¶: Videos metadata.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
infos=None¶: Videos information.

Returns:

List with information about Videos.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

src_dataset_id = 466639
dst_dataset_id = 468620

ids = []
names = []
metas = []

video_infos = api.video.get_list(src_dataset_id)
# Create lists of ids, videos names and meta information for each video
for video_info in video_infos:
    ids.append(video_info.id)
    # It is necessary to upload videos with the same names(extentions) as in src dataset
    names.append(video_info.name)
    metas.append({video_info.name: video_info.frame_height})

progress = sly.Progress("Videos upload: ", len(ids))
new_videos_info = api.video.upload_ids(dst_dataset_id, names, ids, metas, progress.iters_done_report)

upload_link(dataset_id, link, name=None, info=None, hash=None, meta=None, skip_download=False, force_metadata_for_links=True)[source]¶

Upload Video from given link to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
link : str¶: Video link.
name : str, optional¶: Video name with extension.
info : dict, optional¶: Video info.
hash : str, optional¶: Video hash.
meta : List[Dict], optional¶: Video metadata.
skip_download : Optional[bool]¶: Skip download video to local storage.
force_metadata_for_links : Optional[bool]¶: Specify whether to force retrieving video metadata from the server after upload

Returns:

List with information about Video.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55847
link = "https://video...040243048_main.mp4"
name = "cars.mp4"

info = api.video.upload_link(dataset_id, link, name)
print(info)
# Output: [
#     VideoInfo(
#         id=19371139,
#         name='cars.mp4'
#         hash='30/TQ1BcIOn1AI4RFgRO/6psRtr3lqNPmr4uQ=',
#         link=None,
#         team_id=435,
#         workspace_id=684,
#         project_id=17208,
#         dataset_id=55847,
#         path_original='/h5ung-public/videos/Z/d/HD/lfgipl...NXrg5vz.mp4',
#         frames_to_timecodes=[],
#         frames_count=245,
#         frame_width=1920,
#         frame_height=1080,
#         created_at='2023-02-07T19:35:01.808Z',
#         updated_at='2023-02-07T19:35:01.808Z',
#         tags=[],
#         file_meta={
#             'codecName': 'h264',
#             'codecType': 'video',
#             'duration': 10.218542,
#             'formatName': 'mov,mp4,m4a,3gp,3g2,mj2',
#             'framesCount': 245,
#             'framesToTimecodes': [],
#             'height': 1080,
#             'index': 0,
#             'mime': 'video/mp4',
#             'rotation': 0,
#             'size': '6795452',
#             'startTime': 0,
#             'streams': [],
#             'width': 1920
#         },
#         custom_data={},
#         processing_path='1/194'
#     )
# ]

upload_links(dataset_id, links, names, infos=None, hashes=None, metas=None, skip_download=False, progress_cb=None, force_metadata_for_links=True)[source]¶

Upload Videos from given links to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
links : List[str]¶: Videos links.
names : List[str]¶: Videos names with extension.
infos : List[dict]¶: Videos infos.
hashes : List[str]¶: Videos hashes.
metas : List[dict], optional¶: Videos metadatas.
skip_download : Optional[bool]¶: Skip download videos to local storage.
progress_cb : tqdm or callable, optional¶: Function for tracking the progress of copying.
force_metadata_for_links : Optional[bool]¶: Specify whether to force retrieving videos metadata from the server after upload

Returns:

List with information about Videos.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55847
links = [
    "https://videos...7477606_main.mp4",
    "https://videos...040243048_main.mp4",
    "https://videos...065451525_main.mp4"
]
names = ["cars.mp4", "animals.mp4", "traffic.mp4"]
video_infos = api.video.upload_links(dataset_id, links, names)
print(video_infos)

# Output: [
#     VideoInfo(id=19593405, ...),
#     VideoInfo(id=19593406, ...),
#     VideoInfo(id=19593407, ...)
# ]

upload_path(dataset_id, name, path, meta=None, item_progress=None)[source]¶

Uploads Video with given name from given local path to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
name : str¶: Video name with extension.
path : str¶: Local video path.
meta : dict, optional¶: Video metadata.
item_progress=None¶

Returns:

List with information about Videos.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id=55846
video_name = "7777.mp4"
video_path = "/home/admin/Downloads/video/770918.mp4"

video_infos = api.video.upload_path(
    dataset_id=dataset_id,
    name=video_name,
    path=video_path,
)

upload_paths(dataset_id, names, paths, progress_cb=None, metas=None, infos=None, item_progress=None)[source]¶

Uploads Videos with given names from given local paths to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: List of Videos names with extension.
paths : List[str]¶: List of local Videos paths.
progress_cb : tqdm or callable, optional¶: Function for tracking download progress.
metas : List[dict], optional¶: Videos metadata.
infos=None¶
item_progress=None¶

Returns:

List with information about Videos.

Return type:

List[VideoInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id=55846
video_names = ["7777.mp4", "8888.mp4", "9999.mp4"]
video_paths = ["/home/admin/Downloads/video/770918.mp4", "/home/admin/Downloads/video/770919.mp4", "/home/admin/Downloads/video/770920.mp4"]

video_infos = api.video.upload_paths(
    dataset_id=dataset_id,
    names=video_names,
    paths=video_paths,
)

upsert_info(hash, info)[source]¶

Update Video file metadata

Parameters:

hash : str¶: Video hash.
info : dict¶: Uploading info.

Returns:

Return updating result

Return type:

dict

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 19388386
video_info = api.video.get_info_by_id(video_id)
video_hash = video_info.hash

res = api.video.upsert_info(video_hash, {"field": "value"})
print(res)

# Output: {'success': True}

upsert_infos(hashes, infos, links=None)[source]¶

Update Video files metadata

Parameters:

hashes : str¶: Video hash.
infos : dict¶: Uploading info.

Returns:

Return updating result

Return type:

dict

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 56443
video_ids = [19388386, 19388387, 19388388]
video_infos = api.video.get_list(
    dataset_id=dataset_id,
    filters=[{'field': 'id', 'operator': 'in', 'value': video_ids}]
)
video_hashes = [video_info.hash for video_info in video_infos]
new_infos = [{"field1": "value1"}, {"field2": "value2"}, {"field3": "value3"}]

res = api.video.upsert_infos(video_hashes, new_infos)
print(res)

# Output: {'success': True}

url(dataset_id, video_id, video_frame=0)[source]¶

Get url of the video by dataset ID and video ID

Parameters:

dataset_id : int¶: Dataset ID in which the Video is located.
video_id : int¶: Video ID in Supervisely.
video_frame : int, optional¶: Video frame index.

Returns:

Url of the video by dataset_id and video_id.

Return type:

str