# VideoDatasetFile

## class nominal.core.VideoDatasetFile(id, dataset_rid, name, bounds, uploaded_at, ingested_at, deleted_at, ingest_status, timestamp_channel, timestamp_type, file_tags, tag_columns, *, num_frames=None, num_segments=None, media_duration_seconds=None, media_frame_rate=None, scale_factor=None)

Bases: [`DatasetFile`](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

A video file stored as a dataset channel.

A specialization of [`DatasetFile`](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.DatasetFile") for video files. Supports all inherited dataset-file
behavior (refresh/download/delete/poll/etc.) and exposes read-only aggregate metadata
produced by segmentation.

### id

### dataset_rid

### name

### bounds

### uploaded_at

### ingested_at

### deleted_at

### ingest_status

### timestamp_channel

### timestamp_type

### file_tags

### tag_columns

### num_frames: int | None = None

### num_segments: int | None = None

### media_duration_seconds: float | None = None

### media_frame_rate: float | None = None

### scale_factor: float | None = None

### delete()

Deletes the dataset file, removing its data permanently from Nominal.

> **Note**
>
> This cannot be undone outside of fully re-ingesting the file into Nominal.

### download(output_directory, *, part_size=DEFAULT_CHUNK_SIZE, num_retries=3)

Download the dataset file to a destination on local disk.

Parameters:
:   - **output_directory** ([*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)"))

      Download file to the given directory
    - **part_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Size (in bytes) of chunks to use when downloading file.
    - **num_retries** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Number of retries to perform per part download if any exception occurs

Returns:
:   Path that the file was downloaded to

Raises:
:   - [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – Output directory doesn’t exist
    - [**FileExistsError**](https://docs.python.org/3/builtins/exceptions.html#FileExistsError "(in Python v3.15)") – File already exists at destination
    - [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – Error downloading file

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

### download_original_files(output_directory, *, part_size=DEFAULT_CHUNK_SIZE, num_retries=3)

Download the input file(s) for a containerized extractor to a destination on local disk.

Parameters:
:   - **output_directory** ([*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)"))

      Download file(s) to the given directory
    - **part_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Size (in bytes) of chunks to use when downloading files.
    - **num_retries** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Number of retries to perform per part download if any exception occurs

Returns:
:   Path(s) that the file(s) were downloaded to

Raises:
:   - [**NotADirectoryError**](https://docs.python.org/3/builtins/exceptions.html#NotADirectoryError "(in Python v3.15)") – Output directory exists, but is not a directory
    - [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – Output directory doesn’t exist
    - [**FileExistsError**](https://docs.python.org/3/builtins/exceptions.html#FileExistsError "(in Python v3.15)") – File already exists at destination
    - [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – Failed to determine metadata about files to download

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

> **Note**
>
> Any file that fails to download will result in an error log and will not be returned
> as an output path

### get_file_size()

Retrieves the size of the file in bytes, or None if it could not be determined

> **Note**
>
> This has only been extensively tested on AWS-based environments, and may fail in some
> self-hosted environments– a RuntimeError will be thrown in this case.

Return type:
:   [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") | *None*

### get_ingest_error()

Returns the ingest exception if the file FAILED, or None if there is no error.

Refreshes the file from the API before checking.

Return type:
:   [*NominalIngestError*](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalIngestError.md#nominal.exceptions.NominalIngestError "nominal.exceptions.NominalIngestError") | *None*

### poll_until_ingestion_completed(interval=datetime.timedelta(seconds=1))

Block until dataset file ingestion has completed

This method polls Nominal for ingest status after uploading a file to a dataset on an interval.

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

### refresh()

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

### update(*, name: str | None = None, starting_timestamp: datetime | int | None = None) → Self

### update(*, name: str | None = None, starting_timestamp: datetime | int | None = None, ending_timestamp: datetime | int) → Self

### update(*, name: str | None = None, starting_timestamp: datetime | int | None = None, true_frame_rate: float) → Self

### update(*, name: str | None = None, starting_timestamp: datetime | int | None = None, scale_factor: float) → Self

Update this video file’s name and/or timing. Updates the current instance, and returns it.

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

      New name (title) for the file.
    - **starting_timestamp** ([*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*)

      New absolute start timestamp. The file’s earliest segment is shifted to
      this timestamp and every other segment in the file is shifted by the same offset.
    - **ending_timestamp** ([*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*)

      Absolute timestamp the file’s last frame should land on; rescales the
      file’s frame timestamps around its start.
    - **true_frame_rate** ([*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)") *|* *None*)

      Frame rate the video was recorded at, irregardless of the frame rate the
      media plays at; rescales the file’s frame timestamps around its start.
    - **scale_factor** ([*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)") *|* *None*)

      Ratio of absolute time to media time. For example, a value of 2 indicates
      that for every second of media, two seconds have elapsed in absolute time.

Returns:
:   This file, refreshed with its new bounds and recomputed segment metadata.

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – no field was provided, or more than one of {ending_timestamp, true_frame_rate,
    scale_factor} was provided.

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

> **Note**
>
> Only one of {ending_timestamp, true_frame_rate, scale_factor} may be present at one time.
>
> video channels do not carry per-file descriptions, so unlike the legacy
> [`VideoFile.update`](https://dev.nominal.io/python/ref/generated/nominal.core.VideoFile.md#nominal.core.VideoFile.update "nominal.core.VideoFile.update") there is no `description` parameter.