<!-- # hard line break macro for HTML -->

# fiftyone.core.metadata

Metadata stored in dataset samples.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Classes:**

| [`Metadata`](#fiftyone.core.metadata.Metadata)(\*args, \*\*kwargs)           | Base class for storing metadata about generic samples.   |
|------------------------------------------------------------------------------|----------------------------------------------------------|
| [`ImageMetadata`](#fiftyone.core.metadata.ImageMetadata)(\*args, \*\*kwargs) | Class for storing metadata about image samples.          |
| [`VideoMetadata`](#fiftyone.core.metadata.VideoMetadata)(\*args, \*\*kwargs) | Class for storing metadata about video samples.          |
| [`SceneMetadata`](#fiftyone.core.metadata.SceneMetadata)(\*args, \*\*kwargs) | Class for storing metadata about 3D scene samples.       |

**Functions:**

| [`compute_sample_metadata`](#fiftyone.core.metadata.compute_sample_metadata)(sample[, overwrite, ...])   | Populates the `metadata` field of the sample.                                                                              |
|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| [`get_metadata_cls`](#fiftyone.core.metadata.get_metadata_cls)(media_type)                               | Get the `metadata` class for a media_type                                                                                  |
| [`compute_metadata`](#fiftyone.core.metadata.compute_metadata)(sample_collection[, ...])                 | Populates the `metadata` field of all samples in the collection.                                                           |
| [`get_image_info`](#fiftyone.core.metadata.get_image_info)(f)                                            | Retrieves the dimensions and number of channels of the given image from a file-like object that is streaming its contents. |

### *class* fiftyone.core.metadata.Metadata(\*args, \*\*kwargs)

Bases: [`DynamicEmbeddedDocument`](fiftyone.core.odm.embedded_document.md#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument)

Base class for storing metadata about generic samples.

* **Parameters:**
  * **size_bytes** (*None*) – the size of the media, in bytes
  * **mime_type** (*None*) – the MIME type of the media

**Attributes:**

| [`size_bytes`](#fiftyone.core.metadata.Metadata.size_bytes)   | A 32 bit integer field.                                 |
|---------------------------------------------------------------|---------------------------------------------------------|
| [`mime_type`](#fiftyone.core.metadata.Metadata.mime_type)     | A unicode string field.                                 |
| [`STRICT`](#fiftyone.core.metadata.Metadata.STRICT)           |                                                         |
| [`field_names`](#fiftyone.core.metadata.Metadata.field_names) | An ordered tuple of the public fields of this document. |

**Methods:**

| [`build_for`](#fiftyone.core.metadata.Metadata.build_for)(path_or_url[, mime_type])           | Builds a [`Metadata`](#fiftyone.core.metadata.Metadata) object for the given file.                       |
|-----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| [`clean`](#fiftyone.core.metadata.Metadata.clean)()                                           | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. |
| [`clear_field`](#fiftyone.core.metadata.Metadata.clear_field)(field_name)                     | Clears the field from the document.                                                                      |
| [`copy`](#fiftyone.core.metadata.Metadata.copy)()                                             | Returns a deep copy of the document.                                                                     |
| [`fancy_repr`](#fiftyone.core.metadata.Metadata.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document.                                          |
| [`field_to_mongo`](#fiftyone.core.metadata.Metadata.field_to_mongo)(field_name)               |                                                                                                          |
| [`field_to_python`](#fiftyone.core.metadata.Metadata.field_to_python)(field_name, value)      |                                                                                                          |
| [`from_dict`](#fiftyone.core.metadata.Metadata.from_dict)(d[, extended])                      | Loads the document from a BSON/JSON dictionary.                                                          |
| [`from_json`](#fiftyone.core.metadata.Metadata.from_json)(s)                                  | Loads the document from a JSON string.                                                                   |
| [`get_field`](#fiftyone.core.metadata.Metadata.get_field)(field_name)                         | Gets the field of the document.                                                                          |
| [`get_text_score`](#fiftyone.core.metadata.Metadata.get_text_score)()                         | Get text score from text query                                                                           |
| [`has_field`](#fiftyone.core.metadata.Metadata.has_field)(field_name)                         | Determines whether the document has a field of the given name.                                           |
| [`iter_fields`](#fiftyone.core.metadata.Metadata.iter_fields)()                               | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                 |
| [`merge`](#fiftyone.core.metadata.Metadata.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document.                                            |
| [`set_field`](#fiftyone.core.metadata.Metadata.set_field)(field_name, value[, create])        | Sets the value of a field of the document.                                                               |
| [`to_dict`](#fiftyone.core.metadata.Metadata.to_dict)([extended])                             | Serializes this document to a BSON/JSON dictionary.                                                      |
| [`to_json`](#fiftyone.core.metadata.Metadata.to_json)([pretty_print])                         | Serializes the document to a JSON string.                                                                |
| [`to_mongo`](#fiftyone.core.metadata.Metadata.to_mongo)(\*args, \*\*kwargs)                   | Return as SON data ready for use with MongoDB.                                                           |
| [`validate`](#fiftyone.core.metadata.Metadata.validate)([clean])                              | Ensure that all fields' values are valid and that required fields are present.                           |

**Classes:**

| [`my_metaclass`](#fiftyone.core.metadata.Metadata.my_metaclass)   |    |
|-------------------------------------------------------------------|----|

#### size_bytes

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### mime_type

A unicode string field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### *classmethod* build_for(path_or_url, mime_type=None)

Builds a [`Metadata`](#fiftyone.core.metadata.Metadata) object for the given file.

* **Parameters:**
  * **path_or_url** – the path to the data on disk or a URL
  * **mime_type** (*None*) – the MIME type of the file. If not provided, it
    will be guessed
* **Returns:**
  a [`Metadata`](#fiftyone.core.metadata.Metadata)

#### STRICT *= False*

#### clean()

Hook for doing document level data cleaning (usually validation or assignment)
before validation is run.

Any ValidationError raised by this method will not be associated with
a particular field; it will have a special-case association with the
field defined by NON_FIELD_ERRORS.

#### clear_field(field_name)

Clears the field from the document.

* **Parameters:**
  **field_name** – the field name
* **Raises:**
  **ValueError** – if the field does not exist

#### copy()

Returns a deep copy of the document.

* **Returns:**
  a `SerializableDocument`

#### fancy_repr(class_name=None, select_fields=None, exclude_fields=None, \*\*kwargs)

Generates a customizable string representation of the document.

* **Parameters:**
  * **class_name** (*None*) – optional class name to use
  * **select_fields** (*None*) – iterable of field names to restrict to
  * **exclude_fields** (*None*) – iterable of field names to exclude
  * **\*\*kwargs** – additional key-value pairs to include in the string
    representation
* **Returns:**
  a string representation of the document

#### *property* field_names

An ordered tuple of the public fields of this document.

#### field_to_mongo(field_name)

#### field_to_python(field_name, value)

#### *classmethod* from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

* **Parameters:**
  * **d** – a dictionary
  * **extended** (*False*) – whether the input dictionary may contain
    serialized extended JSON constructs
* **Returns:**
  a `SerializableDocument`

#### *classmethod* from_json(s)

Loads the document from a JSON string.

* **Returns:**
  a `SerializableDocument`

#### get_field(field_name)

Gets the field of the document.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  the field value
* **Raises:**
  **AttributeError** – if the field does not exist

#### get_text_score()

Get text score from text query

#### has_field(field_name)

Determines whether the document has a field of the given name.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  True/False

#### iter_fields()

Returns an iterator over the `(name, value)` pairs of the
public fields of the document.

* **Returns:**
  an iterator that emits `(name, value)` tuples

#### merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

* **Parameters:**
  * **doc** – a `SerializableDocument` of same type as this document
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields rather than treating the list as a single value
  * **merge_dicts** (*True*) – whether to recursively merge the contents of
    top-level dict fields rather than treating the dict as a single
    value
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields

#### my_metaclass

alias of `DocumentMetaclass`

#### set_field(field_name, value, create=True)

Sets the value of a field of the document.

* **Parameters:**
  * **field_name** – the field name
  * **value** – the field value
  * **create** (*True*) – whether to create the field if it does not exist
* **Raises:**
  **ValueError** – if `field_name` is not an allowed field name or does
      not exist and `create == False`

#### to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

* **Parameters:**
  **extended** (*False*) – whether to serialize extended JSON constructs
  such as ObjectIDs, Binary, etc. into JSON format
* **Returns:**
  a dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

* **Parameters:**
  **pretty_print** (*False*) – whether to render the JSON in human readable
  format with newlines and indentations
* **Returns:**
  a JSON string

#### to_mongo(\*args, \*\*kwargs)

Return as SON data ready for use with MongoDB.

#### validate(clean=True)

Ensure that all fields’ values are valid and that required fields
are present.

Raises `ValidationError` if any of the fields’ values are found
to be invalid.

### *class* fiftyone.core.metadata.ImageMetadata(\*args, \*\*kwargs)

Bases: [`Metadata`](#fiftyone.core.metadata.Metadata)

Class for storing metadata about image samples.

* **Parameters:**
  * **size_bytes** (*None*) – the size of the image on disk, in bytes
  * **mime_type** (*None*) – the MIME type of the image
  * **width** (*None*) – the width of the image, in pixels
  * **height** (*None*) – the height of the image, in pixels
  * **num_channels** (*None*) – the number of channels in the image

**Attributes:**

| [`width`](#fiftyone.core.metadata.ImageMetadata.width)               | A 32 bit integer field.                                 |
|----------------------------------------------------------------------|---------------------------------------------------------|
| [`height`](#fiftyone.core.metadata.ImageMetadata.height)             | A 32 bit integer field.                                 |
| [`num_channels`](#fiftyone.core.metadata.ImageMetadata.num_channels) | A 32 bit integer field.                                 |
| [`STRICT`](#fiftyone.core.metadata.ImageMetadata.STRICT)             |                                                         |
| [`field_names`](#fiftyone.core.metadata.ImageMetadata.field_names)   | An ordered tuple of the public fields of this document. |
| [`mime_type`](#fiftyone.core.metadata.ImageMetadata.mime_type)       | A unicode string field.                                 |
| [`size_bytes`](#fiftyone.core.metadata.ImageMetadata.size_bytes)     | A 32 bit integer field.                                 |

**Methods:**

| [`build_for`](#fiftyone.core.metadata.ImageMetadata.build_for)(img_or_path_or_url[, mime_type])    | Builds an [`ImageMetadata`](#fiftyone.core.metadata.ImageMetadata) object for the given image.           |
|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| [`clean`](#fiftyone.core.metadata.ImageMetadata.clean)()                                           | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. |
| [`clear_field`](#fiftyone.core.metadata.ImageMetadata.clear_field)(field_name)                     | Clears the field from the document.                                                                      |
| [`copy`](#fiftyone.core.metadata.ImageMetadata.copy)()                                             | Returns a deep copy of the document.                                                                     |
| [`fancy_repr`](#fiftyone.core.metadata.ImageMetadata.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document.                                          |
| [`field_to_mongo`](#fiftyone.core.metadata.ImageMetadata.field_to_mongo)(field_name)               |                                                                                                          |
| [`field_to_python`](#fiftyone.core.metadata.ImageMetadata.field_to_python)(field_name, value)      |                                                                                                          |
| [`from_dict`](#fiftyone.core.metadata.ImageMetadata.from_dict)(d[, extended])                      | Loads the document from a BSON/JSON dictionary.                                                          |
| [`from_json`](#fiftyone.core.metadata.ImageMetadata.from_json)(s)                                  | Loads the document from a JSON string.                                                                   |
| [`get_field`](#fiftyone.core.metadata.ImageMetadata.get_field)(field_name)                         | Gets the field of the document.                                                                          |
| [`get_text_score`](#fiftyone.core.metadata.ImageMetadata.get_text_score)()                         | Get text score from text query                                                                           |
| [`has_field`](#fiftyone.core.metadata.ImageMetadata.has_field)(field_name)                         | Determines whether the document has a field of the given name.                                           |
| [`iter_fields`](#fiftyone.core.metadata.ImageMetadata.iter_fields)()                               | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                 |
| [`merge`](#fiftyone.core.metadata.ImageMetadata.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document.                                            |
| [`set_field`](#fiftyone.core.metadata.ImageMetadata.set_field)(field_name, value[, create])        | Sets the value of a field of the document.                                                               |
| [`to_dict`](#fiftyone.core.metadata.ImageMetadata.to_dict)([extended])                             | Serializes this document to a BSON/JSON dictionary.                                                      |
| [`to_json`](#fiftyone.core.metadata.ImageMetadata.to_json)([pretty_print])                         | Serializes the document to a JSON string.                                                                |
| [`to_mongo`](#fiftyone.core.metadata.ImageMetadata.to_mongo)(\*args, \*\*kwargs)                   | Return as SON data ready for use with MongoDB.                                                           |
| [`validate`](#fiftyone.core.metadata.ImageMetadata.validate)([clean])                              | Ensure that all fields' values are valid and that required fields are present.                           |

**Classes:**

| [`my_metaclass`](#fiftyone.core.metadata.ImageMetadata.my_metaclass)   |    |
|------------------------------------------------------------------------|----|

#### width

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### height

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### num_channels

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### *classmethod* build_for(img_or_path_or_url, mime_type=None)

Builds an [`ImageMetadata`](#fiftyone.core.metadata.ImageMetadata) object for the given image.

* **Parameters:**
  * **img_or_path_or_url** – an image, an image path on disk, or a URL
  * **mime_type** (*None*) – the MIME type of the image. If not provided, it
    will be guessed
* **Returns:**
  an [`ImageMetadata`](#fiftyone.core.metadata.ImageMetadata)

#### STRICT *= False*

#### clean()

Hook for doing document level data cleaning (usually validation or assignment)
before validation is run.

Any ValidationError raised by this method will not be associated with
a particular field; it will have a special-case association with the
field defined by NON_FIELD_ERRORS.

#### clear_field(field_name)

Clears the field from the document.

* **Parameters:**
  **field_name** – the field name
* **Raises:**
  **ValueError** – if the field does not exist

#### copy()

Returns a deep copy of the document.

* **Returns:**
  a `SerializableDocument`

#### fancy_repr(class_name=None, select_fields=None, exclude_fields=None, \*\*kwargs)

Generates a customizable string representation of the document.

* **Parameters:**
  * **class_name** (*None*) – optional class name to use
  * **select_fields** (*None*) – iterable of field names to restrict to
  * **exclude_fields** (*None*) – iterable of field names to exclude
  * **\*\*kwargs** – additional key-value pairs to include in the string
    representation
* **Returns:**
  a string representation of the document

#### *property* field_names

An ordered tuple of the public fields of this document.

#### field_to_mongo(field_name)

#### field_to_python(field_name, value)

#### *classmethod* from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

* **Parameters:**
  * **d** – a dictionary
  * **extended** (*False*) – whether the input dictionary may contain
    serialized extended JSON constructs
* **Returns:**
  a `SerializableDocument`

#### *classmethod* from_json(s)

Loads the document from a JSON string.

* **Returns:**
  a `SerializableDocument`

#### get_field(field_name)

Gets the field of the document.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  the field value
* **Raises:**
  **AttributeError** – if the field does not exist

#### get_text_score()

Get text score from text query

#### has_field(field_name)

Determines whether the document has a field of the given name.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  True/False

#### iter_fields()

Returns an iterator over the `(name, value)` pairs of the
public fields of the document.

* **Returns:**
  an iterator that emits `(name, value)` tuples

#### merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

* **Parameters:**
  * **doc** – a `SerializableDocument` of same type as this document
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields rather than treating the list as a single value
  * **merge_dicts** (*True*) – whether to recursively merge the contents of
    top-level dict fields rather than treating the dict as a single
    value
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields

#### mime_type

A unicode string field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### my_metaclass

alias of `DocumentMetaclass`

#### set_field(field_name, value, create=True)

Sets the value of a field of the document.

* **Parameters:**
  * **field_name** – the field name
  * **value** – the field value
  * **create** (*True*) – whether to create the field if it does not exist
* **Raises:**
  **ValueError** – if `field_name` is not an allowed field name or does
      not exist and `create == False`

#### size_bytes

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

* **Parameters:**
  **extended** (*False*) – whether to serialize extended JSON constructs
  such as ObjectIDs, Binary, etc. into JSON format
* **Returns:**
  a dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

* **Parameters:**
  **pretty_print** (*False*) – whether to render the JSON in human readable
  format with newlines and indentations
* **Returns:**
  a JSON string

#### to_mongo(\*args, \*\*kwargs)

Return as SON data ready for use with MongoDB.

#### validate(clean=True)

Ensure that all fields’ values are valid and that required fields
are present.

Raises `ValidationError` if any of the fields’ values are found
to be invalid.

### *class* fiftyone.core.metadata.VideoMetadata(\*args, \*\*kwargs)

Bases: [`Metadata`](#fiftyone.core.metadata.Metadata)

Class for storing metadata about video samples.

* **Parameters:**
  * **size_bytes** (*None*) – the size of the video on disk, in bytes
  * **mime_type** (*None*) – the MIME type of the video
  * **frame_width** (*None*) – the width of the video frames, in pixels
  * **frame_height** (*None*) – the height of the video frames, in pixels
  * **frame_rate** (*None*) – the frame rate of the video
  * **total_frame_count** (*None*) – the total number of frames in the video
  * **duration** (*None*) – the duration of the video, in seconds
  * **encoding_str** (*None*) – the encoding string for the video

**Attributes:**

| [`frame_width`](#fiftyone.core.metadata.VideoMetadata.frame_width)             | A 32 bit integer field.                                 |
|--------------------------------------------------------------------------------|---------------------------------------------------------|
| [`frame_height`](#fiftyone.core.metadata.VideoMetadata.frame_height)           | A 32 bit integer field.                                 |
| [`frame_rate`](#fiftyone.core.metadata.VideoMetadata.frame_rate)               | A floating point number field.                          |
| [`total_frame_count`](#fiftyone.core.metadata.VideoMetadata.total_frame_count) | A 32 bit integer field.                                 |
| [`duration`](#fiftyone.core.metadata.VideoMetadata.duration)                   | A floating point number field.                          |
| [`encoding_str`](#fiftyone.core.metadata.VideoMetadata.encoding_str)           | A unicode string field.                                 |
| [`STRICT`](#fiftyone.core.metadata.VideoMetadata.STRICT)                       |                                                         |
| [`field_names`](#fiftyone.core.metadata.VideoMetadata.field_names)             | An ordered tuple of the public fields of this document. |
| [`mime_type`](#fiftyone.core.metadata.VideoMetadata.mime_type)                 | A unicode string field.                                 |
| [`size_bytes`](#fiftyone.core.metadata.VideoMetadata.size_bytes)               | A 32 bit integer field.                                 |

**Methods:**

| [`build_for`](#fiftyone.core.metadata.VideoMetadata.build_for)(video_path_or_url[, mime_type])     | Builds an [`VideoMetadata`](#fiftyone.core.metadata.VideoMetadata) object for the given video.           |
|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| [`clean`](#fiftyone.core.metadata.VideoMetadata.clean)()                                           | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. |
| [`clear_field`](#fiftyone.core.metadata.VideoMetadata.clear_field)(field_name)                     | Clears the field from the document.                                                                      |
| [`copy`](#fiftyone.core.metadata.VideoMetadata.copy)()                                             | Returns a deep copy of the document.                                                                     |
| [`fancy_repr`](#fiftyone.core.metadata.VideoMetadata.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document.                                          |
| [`field_to_mongo`](#fiftyone.core.metadata.VideoMetadata.field_to_mongo)(field_name)               |                                                                                                          |
| [`field_to_python`](#fiftyone.core.metadata.VideoMetadata.field_to_python)(field_name, value)      |                                                                                                          |
| [`from_dict`](#fiftyone.core.metadata.VideoMetadata.from_dict)(d[, extended])                      | Loads the document from a BSON/JSON dictionary.                                                          |
| [`from_json`](#fiftyone.core.metadata.VideoMetadata.from_json)(s)                                  | Loads the document from a JSON string.                                                                   |
| [`get_field`](#fiftyone.core.metadata.VideoMetadata.get_field)(field_name)                         | Gets the field of the document.                                                                          |
| [`get_text_score`](#fiftyone.core.metadata.VideoMetadata.get_text_score)()                         | Get text score from text query                                                                           |
| [`has_field`](#fiftyone.core.metadata.VideoMetadata.has_field)(field_name)                         | Determines whether the document has a field of the given name.                                           |
| [`iter_fields`](#fiftyone.core.metadata.VideoMetadata.iter_fields)()                               | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                 |
| [`merge`](#fiftyone.core.metadata.VideoMetadata.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document.                                            |
| [`set_field`](#fiftyone.core.metadata.VideoMetadata.set_field)(field_name, value[, create])        | Sets the value of a field of the document.                                                               |
| [`to_dict`](#fiftyone.core.metadata.VideoMetadata.to_dict)([extended])                             | Serializes this document to a BSON/JSON dictionary.                                                      |
| [`to_json`](#fiftyone.core.metadata.VideoMetadata.to_json)([pretty_print])                         | Serializes the document to a JSON string.                                                                |
| [`to_mongo`](#fiftyone.core.metadata.VideoMetadata.to_mongo)(\*args, \*\*kwargs)                   | Return as SON data ready for use with MongoDB.                                                           |
| [`validate`](#fiftyone.core.metadata.VideoMetadata.validate)([clean])                              | Ensure that all fields' values are valid and that required fields are present.                           |

**Classes:**

| [`my_metaclass`](#fiftyone.core.metadata.VideoMetadata.my_metaclass)   |    |
|------------------------------------------------------------------------|----|

#### frame_width

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### frame_height

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### frame_rate

A floating point number field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### total_frame_count

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### duration

A floating point number field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### encoding_str

A unicode string field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### *classmethod* build_for(video_path_or_url, mime_type=None)

Builds an [`VideoMetadata`](#fiftyone.core.metadata.VideoMetadata) object for the given video.

* **Parameters:**
  * **video_path_or_url** – the path to a video on disk or a URL
  * **mime_type** (*None*) – the MIME type of the image. If not provided, it
    will be guessed
* **Returns:**
  a [`VideoMetadata`](#fiftyone.core.metadata.VideoMetadata)

#### STRICT *= False*

#### clean()

Hook for doing document level data cleaning (usually validation or assignment)
before validation is run.

Any ValidationError raised by this method will not be associated with
a particular field; it will have a special-case association with the
field defined by NON_FIELD_ERRORS.

#### clear_field(field_name)

Clears the field from the document.

* **Parameters:**
  **field_name** – the field name
* **Raises:**
  **ValueError** – if the field does not exist

#### copy()

Returns a deep copy of the document.

* **Returns:**
  a `SerializableDocument`

#### fancy_repr(class_name=None, select_fields=None, exclude_fields=None, \*\*kwargs)

Generates a customizable string representation of the document.

* **Parameters:**
  * **class_name** (*None*) – optional class name to use
  * **select_fields** (*None*) – iterable of field names to restrict to
  * **exclude_fields** (*None*) – iterable of field names to exclude
  * **\*\*kwargs** – additional key-value pairs to include in the string
    representation
* **Returns:**
  a string representation of the document

#### *property* field_names

An ordered tuple of the public fields of this document.

#### field_to_mongo(field_name)

#### field_to_python(field_name, value)

#### *classmethod* from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

* **Parameters:**
  * **d** – a dictionary
  * **extended** (*False*) – whether the input dictionary may contain
    serialized extended JSON constructs
* **Returns:**
  a `SerializableDocument`

#### *classmethod* from_json(s)

Loads the document from a JSON string.

* **Returns:**
  a `SerializableDocument`

#### get_field(field_name)

Gets the field of the document.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  the field value
* **Raises:**
  **AttributeError** – if the field does not exist

#### get_text_score()

Get text score from text query

#### has_field(field_name)

Determines whether the document has a field of the given name.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  True/False

#### iter_fields()

Returns an iterator over the `(name, value)` pairs of the
public fields of the document.

* **Returns:**
  an iterator that emits `(name, value)` tuples

#### merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

* **Parameters:**
  * **doc** – a `SerializableDocument` of same type as this document
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields rather than treating the list as a single value
  * **merge_dicts** (*True*) – whether to recursively merge the contents of
    top-level dict fields rather than treating the dict as a single
    value
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields

#### mime_type

A unicode string field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### my_metaclass

alias of `DocumentMetaclass`

#### set_field(field_name, value, create=True)

Sets the value of a field of the document.

* **Parameters:**
  * **field_name** – the field name
  * **value** – the field value
  * **create** (*True*) – whether to create the field if it does not exist
* **Raises:**
  **ValueError** – if `field_name` is not an allowed field name or does
      not exist and `create == False`

#### size_bytes

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

* **Parameters:**
  **extended** (*False*) – whether to serialize extended JSON constructs
  such as ObjectIDs, Binary, etc. into JSON format
* **Returns:**
  a dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

* **Parameters:**
  **pretty_print** (*False*) – whether to render the JSON in human readable
  format with newlines and indentations
* **Returns:**
  a JSON string

#### to_mongo(\*args, \*\*kwargs)

Return as SON data ready for use with MongoDB.

#### validate(clean=True)

Ensure that all fields’ values are valid and that required fields
are present.

Raises `ValidationError` if any of the fields’ values are found
to be invalid.

### *class* fiftyone.core.metadata.SceneMetadata(\*args, \*\*kwargs)

Bases: [`Metadata`](#fiftyone.core.metadata.Metadata)

Class for storing metadata about 3D scene samples.

* **Parameters:**
  * **size_bytes** (*None*) – the size of scene definition and all children
    assets on disk, in bytes
  * **mime_type** (*None*) – the MIME type of the scene
  * **asset_counts** (*None*) – dict of child asset file type to count

**Attributes:**

| [`asset_counts`](#fiftyone.core.metadata.SceneMetadata.asset_counts)   | A dictionary field that wraps a standard Python dictionary.   |
|------------------------------------------------------------------------|---------------------------------------------------------------|
| [`STRICT`](#fiftyone.core.metadata.SceneMetadata.STRICT)               |                                                               |
| [`field_names`](#fiftyone.core.metadata.SceneMetadata.field_names)     | An ordered tuple of the public fields of this document.       |
| [`mime_type`](#fiftyone.core.metadata.SceneMetadata.mime_type)         | A unicode string field.                                       |
| [`size_bytes`](#fiftyone.core.metadata.SceneMetadata.size_bytes)       | A 32 bit integer field.                                       |

**Methods:**

| [`build_for`](#fiftyone.core.metadata.SceneMetadata.build_for)(scene_path[, mime_type, \_cache, ...])   | Builds a [`SceneMetadata`](#fiftyone.core.metadata.SceneMetadata) object for the given 3D scene.         |
|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| [`clean`](#fiftyone.core.metadata.SceneMetadata.clean)()                                                | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. |
| [`clear_field`](#fiftyone.core.metadata.SceneMetadata.clear_field)(field_name)                          | Clears the field from the document.                                                                      |
| [`copy`](#fiftyone.core.metadata.SceneMetadata.copy)()                                                  | Returns a deep copy of the document.                                                                     |
| [`fancy_repr`](#fiftyone.core.metadata.SceneMetadata.fancy_repr)([class_name, select_fields, ...])      | Generates a customizable string representation of the document.                                          |
| [`field_to_mongo`](#fiftyone.core.metadata.SceneMetadata.field_to_mongo)(field_name)                    |                                                                                                          |
| [`field_to_python`](#fiftyone.core.metadata.SceneMetadata.field_to_python)(field_name, value)           |                                                                                                          |
| [`from_dict`](#fiftyone.core.metadata.SceneMetadata.from_dict)(d[, extended])                           | Loads the document from a BSON/JSON dictionary.                                                          |
| [`from_json`](#fiftyone.core.metadata.SceneMetadata.from_json)(s)                                       | Loads the document from a JSON string.                                                                   |
| [`get_field`](#fiftyone.core.metadata.SceneMetadata.get_field)(field_name)                              | Gets the field of the document.                                                                          |
| [`get_text_score`](#fiftyone.core.metadata.SceneMetadata.get_text_score)()                              | Get text score from text query                                                                           |
| [`has_field`](#fiftyone.core.metadata.SceneMetadata.has_field)(field_name)                              | Determines whether the document has a field of the given name.                                           |
| [`iter_fields`](#fiftyone.core.metadata.SceneMetadata.iter_fields)()                                    | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                 |
| [`merge`](#fiftyone.core.metadata.SceneMetadata.merge)(doc[, merge_lists, merge_dicts, overwrite])      | Merges the contents of the given document into this document.                                            |
| [`set_field`](#fiftyone.core.metadata.SceneMetadata.set_field)(field_name, value[, create])             | Sets the value of a field of the document.                                                               |
| [`to_dict`](#fiftyone.core.metadata.SceneMetadata.to_dict)([extended])                                  | Serializes this document to a BSON/JSON dictionary.                                                      |
| [`to_json`](#fiftyone.core.metadata.SceneMetadata.to_json)([pretty_print])                              | Serializes the document to a JSON string.                                                                |
| [`to_mongo`](#fiftyone.core.metadata.SceneMetadata.to_mongo)(\*args, \*\*kwargs)                        | Return as SON data ready for use with MongoDB.                                                           |
| [`validate`](#fiftyone.core.metadata.SceneMetadata.validate)([clean])                                   | Ensure that all fields' values are valid and that required fields are present.                           |

**Classes:**

| [`my_metaclass`](#fiftyone.core.metadata.SceneMetadata.my_metaclass)   |    |
|------------------------------------------------------------------------|----|

#### asset_counts

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is `{}`.

* **Parameters:**
  * **field** (*None*) – an optional `Field` instance describing the type
    of the values in the dict
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### *classmethod* build_for(scene_path, mime_type=None, \_cache=None, skip_failures=True, warn_failures=True)

Builds a [`SceneMetadata`](#fiftyone.core.metadata.SceneMetadata) object for the given 3D scene.

* **Parameters:**
  * **scene_path** – a scene path
  * **mime_type** (*None*) – the MIME type of the scene. If not provided,
    defaults to `application/octet-stream`
  * **skip_failures** (*True*) – whether to gracefully continue without raising an
    error if metadata cannot be computed for a sample
  * **warn_failures** (*True*) – whether to log a warning if metadata cannot
    be computed for a sample
* **Returns:**
  a [`SceneMetadata`](#fiftyone.core.metadata.SceneMetadata)

#### STRICT *= False*

#### clean()

Hook for doing document level data cleaning (usually validation or assignment)
before validation is run.

Any ValidationError raised by this method will not be associated with
a particular field; it will have a special-case association with the
field defined by NON_FIELD_ERRORS.

#### clear_field(field_name)

Clears the field from the document.

* **Parameters:**
  **field_name** – the field name
* **Raises:**
  **ValueError** – if the field does not exist

#### copy()

Returns a deep copy of the document.

* **Returns:**
  a `SerializableDocument`

#### fancy_repr(class_name=None, select_fields=None, exclude_fields=None, \*\*kwargs)

Generates a customizable string representation of the document.

* **Parameters:**
  * **class_name** (*None*) – optional class name to use
  * **select_fields** (*None*) – iterable of field names to restrict to
  * **exclude_fields** (*None*) – iterable of field names to exclude
  * **\*\*kwargs** – additional key-value pairs to include in the string
    representation
* **Returns:**
  a string representation of the document

#### *property* field_names

An ordered tuple of the public fields of this document.

#### field_to_mongo(field_name)

#### field_to_python(field_name, value)

#### *classmethod* from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

* **Parameters:**
  * **d** – a dictionary
  * **extended** (*False*) – whether the input dictionary may contain
    serialized extended JSON constructs
* **Returns:**
  a `SerializableDocument`

#### *classmethod* from_json(s)

Loads the document from a JSON string.

* **Returns:**
  a `SerializableDocument`

#### get_field(field_name)

Gets the field of the document.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  the field value
* **Raises:**
  **AttributeError** – if the field does not exist

#### get_text_score()

Get text score from text query

#### has_field(field_name)

Determines whether the document has a field of the given name.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  True/False

#### iter_fields()

Returns an iterator over the `(name, value)` pairs of the
public fields of the document.

* **Returns:**
  an iterator that emits `(name, value)` tuples

#### merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

* **Parameters:**
  * **doc** – a `SerializableDocument` of same type as this document
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields rather than treating the list as a single value
  * **merge_dicts** (*True*) – whether to recursively merge the contents of
    top-level dict fields rather than treating the dict as a single
    value
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields

#### mime_type

A unicode string field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### my_metaclass

alias of `DocumentMetaclass`

#### set_field(field_name, value, create=True)

Sets the value of a field of the document.

* **Parameters:**
  * **field_name** – the field name
  * **value** – the field value
  * **create** (*True*) – whether to create the field if it does not exist
* **Raises:**
  **ValueError** – if `field_name` is not an allowed field name or does
      not exist and `create == False`

#### size_bytes

A 32 bit integer field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

* **Parameters:**
  **extended** (*False*) – whether to serialize extended JSON constructs
  such as ObjectIDs, Binary, etc. into JSON format
* **Returns:**
  a dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

* **Parameters:**
  **pretty_print** (*False*) – whether to render the JSON in human readable
  format with newlines and indentations
* **Returns:**
  a JSON string

#### to_mongo(\*args, \*\*kwargs)

Return as SON data ready for use with MongoDB.

#### validate(clean=True)

Ensure that all fields’ values are valid and that required fields
are present.

Raises `ValidationError` if any of the fields’ values are found
to be invalid.

### fiftyone.core.metadata.compute_sample_metadata(sample, overwrite=False, skip_failures=True)

Populates the `metadata` field of the sample.

* **Parameters:**
  * **sample** – a [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample)
  * **overwrite** (*False*) – whether to overwrite existing metadata
  * **skip_failures** (*True*) – whether to gracefully continue without raising
    an error if metadata cannot be computed

### fiftyone.core.metadata.get_metadata_cls(media_type)

Get the `metadata` class for a media_type

* **Parameters:**
  **media_type** (*str*) – a media type value
* **Returns:**
  a [`Metadata`](#fiftyone.core.metadata.Metadata) class

### fiftyone.core.metadata.compute_metadata(sample_collection, overwrite=False, num_workers=None, skip_failures=True, warn_failures=True, progress=None)

Populates the `metadata` field of all samples in the collection.

Any samples with existing metadata are skipped, unless
`overwrite == True`.

* **Parameters:**
  * **sample_collection** – a
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
  * **overwrite** (*False*) – whether to overwrite existing metadata
  * **num_workers** (*None*) – a suggested number of threads to use
  * **skip_failures** (*True*) – whether to gracefully continue without raising an
    error if metadata cannot be computed for a sample
  * **warn_failures** (*True*) – whether to log a warning if metadata cannot
    be computed for a sample
  * **progress** (*None*) – whether to render a progress bar (True/False), use the
    default value `fiftyone.config.show_progress_bars` (None), or a
    progress callback function to invoke instead

### fiftyone.core.metadata.get_image_info(f)

Retrieves the dimensions and number of channels of the given image from
a file-like object that is streaming its contents.

* **Parameters:**
  **f** – a file-like object that supports `read()`, `seek()`, `tell()`
* **Returns:**
  `(width, height, num_channels)`