VideoApi¶

class VideoApi[source]¶

Bases: supervisely.api.module_api.RemoveableBulkModuleApi

API for working with Video. VideoApi object is immutable.

Parameters

api : Api: API connection to the server.

Usage example

import supervisely as sly

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()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

video_id = 19371139
video_info = api.video.get_info_by_id(video_id) # api usage example

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_info_to_json
`copy_batch`	Copies Videos with given IDs to Dataset.
`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<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`	rtype `Iterator`[`List`[`VideoInfo`]]
`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.
`set_remote`	This method helps to change local source to remote for videos without re-uploading them as new.
`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 supervisely.api.module_api.VideoInfo

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 : VideoInfo: Information about the video.
name : str: Video name.

Returns

Information about Video. See info_sequence

Return type

VideoInfo

import supervisely as sly
from supervisely.video.video import get_info

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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

Checkout detailed example here (you must be logged into your Supervisely account)

import supervisely as sly

# 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

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

# 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}

classmethod convert_info_to_json(info)¶

_convert_info_to_json

Return type: Dict

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

Raises

ValueError if videos ids are from the destination Dataset

Returns

List with information about Videos. See info_sequence

Return type

List[VideoInfo]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 : asyncio.Semaphore, optional: 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

NoneType

Usage example

import supervisely as sly
import asyncio

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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[int]: List of Video IDs in Supervisely.
paths : List[str]: Local save paths for Videos.
semaphore : asyncio.Semaphore, optional: 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

NoneType

Usage example

import supervisely as sly
import asyncio

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly


os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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<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. See info_sequence

Return type

VideoInfo

Usage example

import supervisely as sly


os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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. See info_sequence.

Return type

List[VideoInfo]

Usage example

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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. See info_sequence

Return type

dict

Usage example

import supervisely as sly


os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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.supervise.ly/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 supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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

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 : asyncio.Semaphore, optional: Semaphore for limiting the number of simultaneous requests.
kwargs: Additional arguments.

Returns

List of images in dataset.

Return type

AsyncGenerator[List[ImageInfo]]

Usage example

import supervisely as sly
import asyncio

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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))

static info_sequence()[source]¶

Get list of all VideoInfo field names.

Returns: List of VideoInfo field names.`
Return type: list

static info_tuple_name()[source]¶

Get string name of VideoInfo NamedTuple.

Returns: NamedTuple name.
Return type: str

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

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

Parameters

track_id : int: int
video_id : int: int
frame_start : int: int
frame_end : int: int
current : int: int
total : int: int

Returns

str

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

Send message to the Annotation Tool

Parameters

track_id : int: int
error : str: str
message : str: 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

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

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

set_remote(videos, links)[source]¶

This method helps to change local source to remote for videos without re-uploading them as new.

Parameters

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

Returns

json-encoded content of a response.

Usage example

import supervisely as sly

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 supervisely as sly
from supervisely.video.video import get_info

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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)[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.

Returns

Information about Video. See info_sequence

Return type

VideoInfo

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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. See info_sequence

Return type

List[VideoInfo]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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. See info_sequence

Return type

VideoInfo

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 : Optional[List[VideoInfo]]: Videos information.

Returns

List with information about Videos. See info_sequence

Return type

List[VideoInfo]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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. See info_sequence

Return type

List[VideoInfo]

import supervisely as sly
from supervisely.video.video import get_info

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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. See info_sequence

Return type

List[VideoInfo]

Usage example

import supervisely as sly
from supervisely.video.video import get_info

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 : Optional[Progress]

Returns

List with information about Videos. See info_sequence

Return type

VideoInfo

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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
item_progress

Returns

List with information about Videos. See info_sequence

Return type

List[VideoInfo]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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