Video

class nominal.core.Video(rid: str, name: str, description: str | None, properties: Mapping[str, str], labels: Sequence[str], created_at: IntegralNanosecondsUTC, is_archived: bool)

Bases: HasRid, MarkableMixin, RefreshableConjureMixin[Video]

rid: str

name: str

description: str | None

properties: Mapping[str, str]

labels: Sequence[str]

created_at: IntegralNanosecondsUTC

is_archived: bool

add_file(path: PathLike, *, start: datetime | IntegralNanosecondsUTC, description: str | None = None, overwrite_overlapping: bool = False) → VideoFile

add_file(path: PathLike, *, frame_timestamps: Sequence[IntegralNanosecondsUTC], description: str | None = None, overwrite_overlapping: bool = False) → VideoFile

Append to a video from a file-path to H264-encoded video data. Only one of start or frame_timestamps is allowed.

Parameters:

• path – Path to the video file to add to an existing video within Nominal

• start – Starting timestamp of the video file in absolute UTC time.

• frame_timestamps – Per-frame absolute nanosecond timestamps. Most usecases should instead use the ‘start’ parameter, unless precise per-frame metadata is available and desired.

• description – Description of the video file.

  Note: This is currently not displayed to users and may be removed in the future.

• overwrite_overlapping – If True, any segments from other video files within this video that overlap with the newly added file will be deleted before inserting the new segments.

Returns:

Reference to the created video file.

add_from_io(video: BinaryIO, name: str, *, start: datetime | IntegralNanosecondsUTC, description: str | None = None, file_type: tuple[str, str] | FileType = FileTypes.MP4, overwrite_overlapping: bool = False) → VideoFile

add_from_io(video: BinaryIO, name: str, *, frame_timestamps: Sequence[IntegralNanosecondsUTC], description: str | None = None, file_type: tuple[str, str] | FileType = FileTypes.MP4, overwrite_overlapping: bool = False) → VideoFile

Append to a video from a file-like object containing video data encoded in H264 or H265.

Parameters:

• video – File-like object containing video data encoded in H264 or H265.

• name – Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.

• start – Starting timestamp of the video file in absolute UTC time

• frame_timestamps – Per-frame absolute nanosecond timestamps. Most usecases should instead use the ‘start’ parameter, unless precise per-frame metadata is available and desired.

• description – Description of the video file.

  Note: This is currently not displayed to users and may be removed in the future.

• file_type – Metadata about the type of video file, e.g., MP4 vs. MKV.

• overwrite_overlapping – If True, any segments from other video files within this video that overlap with the newly added file will be deleted before inserting the new segments.

Returns:

Reference to the created video file.

add_mcap(path: Path | str, topic: str, description: str | None = None, overwrite_overlapping: bool = False) → VideoFile

Append to a video from a file-path to an MCAP file containing video data.

Parameters:

• path – Path to the video file to add to an existing video within Nominal

• topic – Topic pointing to video data within the MCAP file.

• description – Description of the video file.

  Note: This is currently not displayed to users and may be removed in the future.

• overwrite_overlapping – If True, any segments from other video files within this video that overlap with the newly added file will be deleted before inserting the new segments.

Returns:

Reference to the created video file.

add_mcap_from_io(mcap: BinaryIO, name: str, topic: str, description: str | None = None, file_type: tuple[str, str] | FileType = FileTypes.MCAP, overwrite_overlapping: bool = False) → VideoFile

Append to a video from a file-like binary stream with MCAP data containing video data.

Parameters:

• mcap – File-like binary object containing MCAP data to upload.

• name – Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.

• topic – Topic pointing to video data within the MCAP file.

• description – Description of the video file.

  Note: This is currently not displayed to users and may be removed in the future.

• file_type – Metadata about the type of video (e.g. MCAP).

• overwrite_overlapping – If True, any segments from other video files within this video that overlap with the newly added file will be deleted before inserting the new segments.

Returns:

Reference to the created video file.

add_mcap_to_video(path: Path | str, topic: str, description: str | None = None, overwrite_overlapping: bool = False) → VideoFile

Append to a video from a file-path to an MCAP file containing video data.

Parameters:

• path – Path to the video file to add to an existing video within Nominal

• topic – Topic pointing to video data within the MCAP file.

• description – Description of the video file.

  Note: This is currently not displayed to users and may be removed in the future.

• overwrite_overlapping – If True, any segments from other video files within this video that overlap with the newly added file will be deleted before inserting the new segments.

Returns:

Reference to the created video file.

add_mcap_to_video_from_io(mcap: BinaryIO, name: str, topic: str, description: str | None = None, file_type: tuple[str, str] | FileType = FileTypes.MCAP, overwrite_overlapping: bool = False) → VideoFile

Append to a video from a file-like binary stream with MCAP data containing video data.

Parameters:

• mcap – File-like binary object containing MCAP data to upload.

• name – Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.

• topic – Topic pointing to video data within the MCAP file.

• description – Description of the video file.

  Note: This is currently not displayed to users and may be removed in the future.

• file_type – Metadata about the type of video (e.g. MCAP).

• overwrite_overlapping – If True, any segments from other video files within this video that overlap with the newly added file will be deleted before inserting the new segments.

Returns:

Reference to the created video file.

add_to_video_from_io(video: BinaryIO, name: str, start: datetime | int | None = None, frame_timestamps: Sequence[int] | None = None, description: str | None = None, file_type: tuple[str, str] | FileType = FileTypes.MP4, overwrite_overlapping: bool = False) → VideoFile

Append to a video from a file-like object containing video data encoded in H264 or H265.

Parameters:

• video – File-like object containing video data encoded in H264 or H265.

• name – Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.

• start – Starting timestamp of the video file in absolute UTC time

• frame_timestamps – Per-frame absolute nanosecond timestamps. Most usecases should instead use the ‘start’ parameter, unless precise per-frame metadata is available and desired.

• description – Description of the video file.

  Note: This is currently not displayed to users and may be removed in the future.

• file_type – Metadata about the type of video file, e.g., MP4 vs. MKV.

• overwrite_overlapping – If True, any segments from other video files within this video that overlap with the newly added file will be deleted before inserting the new segments.

Returns:

Reference to the created video file.

apply_markings(markings: Iterable[Marking | str]) → None

Apply markings to this resource, leaving any already-applied markings in place.

Applying a marking that is already applied is a no-op rather than an error.

Parameters:

markings – Markings, or marking RIDs, to apply.

Raises:

NominalError – If the request fails, including when a marking is archived or the user lacks permission to change markings on this resource.

archive() → None

Archive this video. Archived videos are not deleted, but are hidden from the UI.

Note

This does not update the instance in place; call refresh() to see the change reflected.

list_files() → Sequence[VideoFile]

List all video files associated with the video.

list_markings() → Sequence[Marking]

The markings currently applied to this resource.

Markings the user does not have permission to read are omitted.

Note

The service filters unreadable markings out of the response, so this may be a strict subset of what is actually applied. Treat it as “what I can see”, not “what is there”: a resource can carry markings that never appear here. Use apply_markings and remove_markings, which name their targets outright, rather than computing a desired set from this list.

Raises:

NominalError – If the request fails.

poll_until_ingestion_completed(interval: timedelta = timedelta(seconds=1), *, timeout: timedelta | None = None) → None

Block until video ingestion has completed. This method polls Nominal for ingest status after uploading a video on an interval.

Parameters:

• interval – How long to wait between status checks.

• timeout – Give up after this long and raise NominalIngestTimeout; None waits indefinitely.

Raises:

• NominalIngestFailed – if the ingest failed

• NominalIngestTimeout – if the ingest did not finish within timeout

• NominalIngestError – if the ingest status is not known

refresh() → Self

remove_markings(markings: Iterable[Marking | str]) → None

Remove markings from this resource.

Removing a marking that is not applied is a no-op rather than an error.

Parameters:

markings – Markings, or marking RIDs, to remove.

Raises:

NominalError – If the request fails.

unarchive() → None

Unarchives this video, allowing it to show up in the ‘All Videos’ pane in the UI.

Note

This does not update the instance in place; call refresh() to see the change reflected.

update(*, name: str | None = None, description: str | None = None, properties: Mapping[str, str] | None = None, labels: Sequence[str] | None = None) → Self

Replace video metadata. Updates the current instance, and returns it.

Only the metadata passed in will be replaced, the rest will remain untouched.

Note

This replaces the metadata rather than appending it. To append to labels or properties, merge them before calling this method. E.g.:

new_labels = ["new-label-a", "new-label-b"]
for old_label in video.labels:
    new_labels.append(old_label)
video = video.update(labels=new_labels)