VideoDatasetFile

class nominal.core.VideoDatasetFile(id: str, dataset_rid: str, name: str, bounds: Bounds | None, uploaded_at: IntegralNanosecondsUTC, ingested_at: IntegralNanosecondsUTC | None, deleted_at: IntegralNanosecondsUTC | None, ingest_status: IngestStatus, timestamp_channel: str | None, timestamp_type: TypedTimestampType | None, file_tags: Mapping[str, str] | None, tag_columns: Mapping[str, str] | None, *, 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)

Bases: DatasetFile

A video file stored as a dataset channel.

A specialization of 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() → None

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: Path | str, *, part_size: int = DEFAULT_CHUNK_SIZE, num_retries: int = 3) → Path

Download the dataset file to a destination on local disk.

Parameters:

• output_directory – Download file to the given directory

• part_size – Size (in bytes) of chunks to use when downloading file.

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

Returns:

Path that the file was downloaded to

Raises:

• FileNotFoundError – Output directory doesn’t exist

• FileExistsError – File already exists at destination

• RuntimeError – Error downloading file

download_original_files(output_directory: Path | str, *, part_size: int = DEFAULT_CHUNK_SIZE, num_retries: int = 3) → Sequence[Path]

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

Parameters:

• output_directory – Download file(s) to the given directory

• part_size – Size (in bytes) of chunks to use when downloading files.

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

Returns:

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

Raises:

• NotADirectoryError – Output directory exists, but is not a directory

• FileNotFoundError – Output directory doesn’t exist

• FileExistsError – File already exists at destination

• RuntimeError – Failed to determine metadata about files to download

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() → int | None

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.

get_ingest_error() → NominalIngestError | None

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

Refreshes the file from the API before checking.

poll_until_ingestion_completed(interval: timedelta = datetime.timedelta(seconds=1)) → Self

Block until dataset file ingestion has completed

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

refresh() → Self

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

• starting_timestamp – 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 – Absolute timestamp the file’s last frame should land on; rescales the file’s frame timestamps around its start.

• true_frame_rate – 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 – 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 – no field was provided, or more than one of {ending_timestamp, true_frame_rate, scale_factor} was provided.

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 there is no description parameter.