Metadata includes technical and contextual information about each video uploaded to the platform. By default, all the videos have the following metadata associated with them:

• duration: The duration of the video, expressed in seconds
• filename: The filename
• fps: The number of frames per second
• height: The height of the video
• size: The size of the video file, expressed in KB
• video_title: The title of the video (defaults to the file name)
• width: The width of the video

Custom metadata allows you to add more data to your videos, providing more detailed, specialized, or context-specific information.

The values you provide must be of the following types: string, integer, float or boolean. If you want to store other types of data such as objects or arrays, you must convert your data into string values.

Provide custom metadata

Once the platform has finished indexing your videos, you can provide custom metadata by invoking the update method of the indexes.videos object with the following parameters:

• index_id: A string representing the unique identifier of the index containing the video for which you want to provide custom metadata.
• video_id: A string representing the unique identifier of the video
• user_metadata: A dictionary containing your custom metadata. In this example, the metadata dictionary has four keys: views, downloads, language and country. The views and downloads keys are integers, and thecreation_date and country keys are strings.

1
from twelvelabs import TwelveLabs
2
3
client.indexes.videos.update(
4
    index_id="<YOUR_INDEX_ID>",
5
    video_id="<YOUR_VIDEO_ID>",
6
    user_metadata={
7
        "views": 12000,
8
        "downloads": 40000,
9
        "language": "en-us",
10
        "country": "USA"
11
    }
12
)

Filter on custom metadata

Once you’ve added custom metadata to your videos, you can use it to filter your search results.

The example code below filters on a custom field named views of type integer. The platform will return only the results found in the videos for which the value of the views field equals 120000.

1
from twelvelabs import TwelveLabs
2
3
search_results = client.search.query(
4
  index_id="<YOUR_INDEX_ID>",
5
  query_text= "<YOUR_QUERY>",
6
  search_options=["visual"],
7
  filter = '{ "views": 120000}'
8
)

For more details on filtering search results, see the Filtering page.