VideoTag¶

class VideoTag(meta, value=None, frame_range=None, key=None, sly_id=None, labeler_login=None, updated_at=None, created_at=None, is_finished=None, non_final_value=None, custom_data=None)[source]¶

Bases: Tag

Tag applied to video or frame range (meta, value, frame_range). Immutable.

Tag applied to video or frame range.

Parameters:

meta¶: Tag metadata (name, value type).
value : str or int or float or None, optional¶: Tag value; type depends on TagValueType of TagMeta.
frame_range : Tuple[int, int] or List[int, int], optional¶: Frame range (start, end) where tag applies.
key : uuid.UUID, optional¶: UUID key. Auto-generated if not provided.
sly_id : int, optional¶: Server-side tag ID.
labeler_login : str, optional¶: Login of user who created the tag.
updated_at : str, optional¶: Last modification timestamp (ISO format).
created_at : str, optional¶: Creation timestamp (ISO format).
is_finished : bool, optional¶: Whether range tag is finalized (for range tags).
non_final_value : bool, optional¶: Whether tag value is temporary.

Usage Example:

import supervisely as sly

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
tag_dog = sly.VideoTag(meta_dog)

meta_cat = sly.TagMeta('cat', sly.TagValueType.ANY_STRING)
tag_cat = sly.VideoTag(meta_cat, value="Fluffy", frame_range=(5, 10))

colors = ["brown", "white", "black"]
meta_coat = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING, possible_values=colors)
tag_coat = sly.VideoTag(meta_coat, value="white", frame_range=(15, 20))

Methods

`clone`	Makes a copy of VideoTag with new fields, if fields are given, otherwise it will use fields of the original VideoTag.
`from_json`	Convert a json dict to VideoTag.
`get_compact_str`	Get string with information about VideoTag: name, value and range of frames.
`get_header_ptable`
`get_row_ptable`
`key`
`to_json`	Convert the VideoTag to a json dict.

Attributes

`custom_data`	Arbitrary user JSON attached to this tag assignment, independent of the tag definition and of the tag value.
`frame_range`	VideoTag frame range.
`is_finished`	VideoTag is finished or not (applicable for range tags).
`meta`	General information about Tag.
`name`	Name property.
`non_final_value`	VideoTag value is final or not.
`value`	Tag value.

classmethod from_json(data, tag_meta_collection, key_id_map=None)[source]¶

Convert a json dict to VideoTag. Read more about Supervisely format.

Parameters:

data : dict¶: VideoTag in json format as a dict.
tag_meta_collection¶: TagMetaCollection object.
key_id_map=None¶: Key ID Map object.

Returns:

VideoTag object

Return type:

VideoTag

Usage Example:

import supervisely as sly

tag_cat_json = {
    "name": "cat",
    "value": "Fluffy",
    "frameRange": [5, 10]
}

from supervisely.video_annotation.video_tag import VideoTag
meta_cat = sly.TagMeta('cat', sly.TagValueType.ANY_STRING)
meta_collection = sly.TagMetaCollection([meta_cat])
tag_cat = VideoTag.from_json(tag_cat_json, meta_collection)

clone(meta=None, value=None, frame_range=None, key=None, sly_id=None, labeler_login=None, updated_at=None, created_at=None, is_finished=None, non_final_value=None, custom_data=None)[source]¶

Makes a copy of VideoTag with new fields, if fields are given, otherwise it will use fields of the original VideoTag.

Parameters:

meta=None¶: General information about VideoTag.
value : str or int or float or None, optional¶: VideoTag value. Depends on TagValueType of TagMeta.
frame_range : Tuple[int, int] or List[int, int], optional¶: VideoTag frame range.
key : uuid.UUID, optional¶: uuid.UUID object.
sly_id : int, optional¶: VideoTag ID in Supervisely.
labeler_login : str, optional¶: Login of user who created VideoTag.
updated_at : str, optional¶: Date and Time when VideoTag was modified last. Date Format: Year:Month:Day:Hour:Minute:Seconds. Example: ‘2021-01-22T19:37:50.158Z’.
created_at : str, optional¶: Date and Time when VideoTag was created. Date Format is the same as in “updated_at” parameter.
is_finished : bool, optional¶: Video Tag is finished or not (applicable for range tags).
non_final_value : bool, optional¶: Video Tag value is final or not (applicable for range tags).

Usage Example:

import supervisely as sly
from supervisely.video_annotation.video_tag import VideoTag

meta_car = sly.TagMeta('car_tag', sly.TagValueType.ANY_STRING)
car_tag = VideoTag(meta_car, value='acura', frame_range=(7, 9))

meta_bus = sly.TagMeta('bus', sly.TagValueType.ANY_STRING)
new_tag = car_tag.clone(meta=meta_bus, frame_range=(15, 129), key=car_tag.key())
new_tag_json = new_tag.to_json()
print(new_tag_json)
# Output: {
#     "name": "bus",
#     "value": "acura",
#     "frameRange": [
#         15,
#         129
#     ],
#     "key": "360438485fd34264921ca19bd43b0b71"
# }

get_compact_str()[source]¶

Get string with information about VideoTag: name, value and range of frames.

Returns:

Information about VideoTag object

Return type:

str

Usage Example:

import supervisely as sly
from supervisely.video_annotation.video_tag import VideoTag
meta_cat = sly.TagMeta('cat', sly.TagValueType.ANY_STRING)
tag_cat = VideoTag(meta_cat, value="Fluffy", frame_range=(5, 10))
compact_tag_cat = tag_cat.get_compact_str()
print(compact_tag_cat) # cat:Fluffy[5 - 10]

to_json(key_id_map=None)[source]¶

Convert the VideoTag to a json dict. Read more about Supervisely format.

Parameters:

key_id_map=None¶: Key ID Map object.

Returns:

Json format as a dict

Return type:

dict

Usage Example:

import supervisely as sly
from supervisely.video_annotation.video_tag import VideoTag
meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
tag_dog = VideoTag(meta_dog)
tag_dog_json = tag_dog.to_json()
print(tag_dog_json)
# Output: {
#     "name": "dog",
#     "key": "058ad7993a534082b4d94cc52542a97d"
# }

property custom_data : dict¶

Arbitrary user JSON attached to this tag assignment, independent of the tag definition and of the tag value. Empty dict when the assignment carries none.

Returns:

Custom data of the Tag

Return type:

dict

Usage Example:

import supervisely as sly

meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, value="Husky", custom_data={"confidence": 0.92})

print(tag_dog.custom_data)
# Output: {'confidence': 0.92}

property frame_range : tuple[int, int]¶

VideoTag frame range.

Returns:

Range of frames for current VideoTag

Return type:

Tuple[int, int]

Usage Example:

cat_range = tag_cat.frame_range # [5, 10]

property is_finished : bool¶

VideoTag is finished or not (applicable for range tags).

Returns:

True if VideoTag is finished, otherwise False

Return type:

bool

Usage Example:

is_finished = tag_cat.is_finished

property meta : supervisely.annotation.tag_meta.TagMeta¶

General information about Tag. When creating a new Tag, it’s value is automatically cross-checked against TagValueType to make sure that value is valid.

Returns:

TagMeta object

Return type:

TagMeta

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
tag_dog = sly.Tag(meta_dog)

# Our TagMeta has value type 'NONE', if we try to add value to our Tag, "ValueError" error will be raised
tag_dog = sly.Tag(meta_dog, value="Husky")
# Output: ValueError: Tag dog can not have value Husky

property name : str¶

Name property.

Returns:

Name

Return type:

str

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, value="Husky")

print(tag_dog.name)
# Output: "dog"

property non_final_value : bool¶

VideoTag value is final or not.

Returns:

True if VideoTag value is final, otherwise False

Return type:

bool

Usage Example:

non_final_value = tag_cat.non_final_value

property value : str¶

Tag value. Return type depends on TagValueType. Date tag values are returned as ISO datetime strings.

Returns:

Tag value

Return type:

str, int or float or None

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, value="Husky")

meta_age = sly.TagMeta('age', sly.TagValueType.ANY_NUMBER)
tag_age = sly.Tag(meta_age, value=9)

colors = ["Black", "White", "Golden", "Brown"]
meta_color = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING, possible_values=colors)
tag_color = sly.Tag(meta_color, value="White")

meta_date = sly.TagMeta('reviewed_at', sly.TagValueType.DATE)
tag_date = sly.Tag(meta_date, value="2026-04-23T15:15:48")

type(tag_dog.value)   # 'str'
type(tag_age.value)   # 'int'
type(tag_color.value) # 'str'
type(tag_date.value)  # 'str'