# Video

## class nominal.core.Video(rid, name, description, properties, labels, created_at, is_archived)

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*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the video file to add to an existing video within Nominal
    - **start** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Starting timestamp of the video file in absolute UTC time.
    - **frame_timestamps** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")*]* *|* *None*)

      Per-frame absolute nanosecond timestamps. Most usecases should instead use the ‘start’
      parameter, unless precise per-frame metadata is available and desired.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video file.

      **Note:** This is currently not displayed to users and may be removed in the future.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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.

Return type:
:   [*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")

### 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** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      File-like object containing video data encoded in H264 or H265.
    - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.
    - **start** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Starting timestamp of the video file in absolute UTC time
    - **frame_timestamps** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")*]* *|* *None*)

      Per-frame absolute nanosecond timestamps. Most usecases should instead use the ‘start’
      parameter, unless precise per-frame metadata is available and desired.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video file.

      **Note:** This is currently not displayed to users and may be removed in the future.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      Metadata about the type of video file, e.g., MP4 vs. MKV.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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.

Return type:
:   [*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")

### add_mcap(path, topic, description=None, overwrite_overlapping=False)

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

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the video file to add to an existing video within Nominal
    - **topic** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Topic pointing to video data within the MCAP file.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video file.

      **Note:** This is currently not displayed to users and may be removed in the future.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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.

Return type:
:   [*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")

### add_mcap_from_io(mcap, name, topic, description=None, file_type=FileTypes.MCAP, overwrite_overlapping=False)

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

Parameters:
:   - **mcap** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      File-like binary object containing MCAP data to upload.
    - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.
    - **topic** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Topic pointing to video data within the MCAP file.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video file.

      **Note:** This is currently not displayed to users and may be removed in the future.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      Metadata about the type of video (e.g. MCAP).
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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.

Return type:
:   [*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")

### add_mcap_to_video(path, topic, description=None, overwrite_overlapping=False)

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

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the video file to add to an existing video within Nominal
    - **topic** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Topic pointing to video data within the MCAP file.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video file.

      **Note:** This is currently not displayed to users and may be removed in the future.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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.

Return type:
:   [*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")

### add_mcap_to_video_from_io(mcap, name, topic, description=None, file_type=FileTypes.MCAP, overwrite_overlapping=False)

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

Parameters:
:   - **mcap** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      File-like binary object containing MCAP data to upload.
    - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.
    - **topic** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Topic pointing to video data within the MCAP file.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video file.

      **Note:** This is currently not displayed to users and may be removed in the future.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      Metadata about the type of video (e.g. MCAP).
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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.

Return type:
:   [*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")

### add_to_video_from_io(video, name, start=None, frame_timestamps=None, description=None, file_type=FileTypes.MP4, overwrite_overlapping=False)

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

Parameters:
:   - **video** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      File-like object containing video data encoded in H264 or H265.
    - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.
    - **start** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Starting timestamp of the video file in absolute UTC time
    - **frame_timestamps** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")*]* *|* *None*)

      Per-frame absolute nanosecond timestamps. Most usecases should instead use the ‘start’
      parameter, unless precise per-frame metadata is available and desired.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video file.

      **Note:** This is currently not displayed to users and may be removed in the future.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      Metadata about the type of video file, e.g., MP4 vs. MKV.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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.

Return type:
:   [*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")

### apply_markings(markings)

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** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

    Markings, or marking RIDs, to apply.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the request fails, including when a marking is archived or the user
    lacks permission to change markings on this resource.

### archive()

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()`](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video.refresh "nominal.core.Video.refresh") to see the change reflected.

### list_files()

List all video files associated with the video.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*VideoFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile "nominal.core.video_file.VideoFile")]

### list_markings()

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`](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video.apply_markings "nominal.core.Video.apply_markings") and
> [`remove_markings`](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video.remove_markings "nominal.core.Video.remove_markings"), which name their targets outright, rather than computing a desired
> set from this list.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking")]

### poll_until_ingestion_completed(interval=timedelta(seconds=1), *, timeout=None)

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

Parameters:
:   - **interval** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)"))

      How long to wait between status checks.
    - **timeout** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)") *|* *None*)

      Give up after this long and raise `NominalIngestTimeout`; None waits indefinitely.

Raises:
:   - [**NominalIngestFailed**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalIngestFailed.md#nominal.exceptions.NominalIngestFailed "nominal.exceptions.NominalIngestFailed") – if the ingest failed
    - [**NominalIngestTimeout**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalIngestTimeout.md#nominal.exceptions.NominalIngestTimeout "nominal.exceptions.NominalIngestTimeout") – if the ingest did not finish within `timeout`
    - [**NominalIngestError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalIngestError.md#nominal.exceptions.NominalIngestError "nominal.exceptions.NominalIngestError") – if the ingest status is not known

### refresh()

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### remove_markings(markings)

Remove markings from this resource.

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

Parameters:
:   **markings** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

    Markings, or marking RIDs, to remove.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the request fails.

### unarchive()

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()`](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video.refresh "nominal.core.Video.refresh") to see the change reflected.

### update(*, name=None, description=None, properties=None, labels=None)

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.:
>
> ```python
> 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)
> ```

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")