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

# fiftyone.core.media_reference

The `media_reference` field’s stored value: which source a sample’s media
comes from, and where in that source it is.

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

**Classes:**

| [`MediaReference`](#fiftyone.core.media_reference.MediaReference)(\*args, \*\*kwargs)   | Base class for what a sample stores about its media.   |
|-----------------------------------------------------------------------------------------|--------------------------------------------------------|

### *class* fiftyone.core.media_reference.MediaReference(\*args, \*\*kwargs)

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

Base class for what a sample stores about its media.

A reference names a media source recorded on the owning dataset and the
part of it this sample is, as one key: the source’s id, then coordinates
of the kind’s own choosing. Everything the source’s episodes share –
where the source is, how its files are laid out – is stored once on the
dataset; everything here is this sample’s alone.

* **Parameters:**
  **key** – `<media source id>/<coordinates within the source>`

**Attributes:**

| [`key`](#fiftyone.core.media_reference.MediaReference.key)                   | A unicode string field.                                 |
|------------------------------------------------------------------------------|---------------------------------------------------------|
| [`source_id`](#fiftyone.core.media_reference.MediaReference.source_id)       | The id of the media source on the owning dataset.       |
| [`media_type`](#fiftyone.core.media_reference.MediaReference.media_type)     | The media type of every reference-backed sample.        |
| [`display_name`](#fiftyone.core.media_reference.MediaReference.display_name) | A human-readable name for the referenced media.         |
| [`STRICT`](#fiftyone.core.media_reference.MediaReference.STRICT)             |                                                         |
| [`field_names`](#fiftyone.core.media_reference.MediaReference.field_names)   | An ordered tuple of the public fields of this document. |

**Methods:**

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

**Classes:**

| [`my_metaclass`](#fiftyone.core.media_reference.MediaReference.my_metaclass)   |    |
|--------------------------------------------------------------------------------|----|

#### key

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

#### *static* source_of(key)

The media source a reference key names.

* **Parameters:**
  **key** – a media reference key
* **Returns:**
  the source id

#### *property* source_id

The id of the media source on the owning dataset.

#### *property* media_type

The media type of every reference-backed sample. A sample of one
modality names its media by filepath; a reference is what multimodal
media is named by.

#### *property* display_name

A human-readable name for the referenced media.

#### 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.