Skip to main content

Attach files to media

In addition to media files, media objects can reference one or more attachments, generic files that can be used to provide additional information about the media. For example, an attachment may be a text file containing CSV data or a proprietary media format.

In this tutorial, we will upload an attachment to a media object using tator-py. We will then download the file using tator-py, and also show how to download the file using the web interface. To begin this tutorial, you must have installed Tator and tator-py, and uploaded a media to a project.

Upload an attachment to existing media with tator-py​

First, select a media object you would like to attach files to, and obtain its media ID. You can do this by opening the media in the annotation view and locating the ID in the right panel:

Now use the tator-py utility upload_attachment to upload a local file and attach it to the media:

import tator
import os
api = tator.get_api('https://cloud.tator.io', os.getenv('MY_TOKEN'))
path = 'path/to/file/test.log'
for progress, response in tator.util.upload_attachment(api, media_id, path):
    print(f"Attachment upload progress: {progress}%")
print(f"Message: {response.message}")

Upload an attachment to new media with tator-py​

It is also possible to upload an attachment at the same time as the media by first creating a media object and separately calling upload_media and upload_attachment. To do this you will need to obtain the media type ID and project ID from the project settings page in the web interface:

# First create the media object.
media_path = 'path/to/media/test.mp4'
media_spec = {'name': 'test.mp4',
              'type': MEDIA_TYPE_ID,
              'section': 'Media with attachments',
              'md5': tator.util.md5sum(media_path)}
response = api.create_media(PROJECT_ID, media_spec=[media_spec])
media_id = response.id

# Now upload the media.
for progress, response in tator.util.upload_media(api, MEDIA_TYPE_ID, media_path,
                                                  media_id=media_id):
    print(f"Upload media progress: {progress}%")
print(f"Message: {response.message}")

# Now upload the attachment.
for progress, response in tator.util.upload_attachment(api, media_id, path):
    print(f"Attachment upload progress: {progress}%")
print(f"Message: {response.message}")

Download the attachment with tator-py​

The attachment can be downloaded using the tator-py utility download_attachment:

media = api.get_media(media_id)
out_path = 'path/to/outfile/test.log'
for progress in tator.util.download_attachment(api, media, out_path):
    print(f"Attachment download progress: {progress}%")

Download the attachment with the web interface​

If you view the media card for the media in the project detail view, you will now see a paperclip icon in the bottom-right corner:

Clicking on the icon will bring up the attachment dialog, which lists available attachments. Clicking the download button will download the attachment locally.