How to: Organize Assets

Some integrations may wish to have more control over the folder structure their device creates. In turn, we at Frame.io need to make sure that there is some level of consistency in how files are uploaded to Frame.io from a C2C device, and specifically make guarantees to Frame.io customers about what part of their project a C2C device can interact with. To that end, we allow integrators to customize their asset upload locations within the {YOUR_DEVICE} folder, but do not allow assets to be uploaded outside of that folder.

To upload to a custom folder structure, you will need to work with your Partner Manager. Custom folder structures are a set of tokenized metadata that must be supplied on asset creation. Let's do a simple example:

Let's say we have a 3D camera rig that has reel_name values like "A001", "A002", "A003", etc, and clip_number values like "C001", "C002", etc. We want to create folders for each clip and populate those with the left and right eye files, so the files would look like this in a project:

To do this, we will need to configure two settings:

• Required metadata fields
• Tokenized file path

Required metadata fields are a simple list of keys that must be set on asset creation for your integration:

[reel_name, clip_number]

You can then use any of these keys to create a /-delimitated path, using {field_name} to denote where a field’s value should be injected:

REEL_{reel_name}/{reel_name}_{clip_number}

Both of these settings will have to be given to our team at Frame.io to add as part of your integration’s details. After we set that up, when you create an asset, those values will have to be supplied at the root of the payload in order for the asset creation to be successful:

{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_LEFT.mp4", 
            "filetype": "video/mp4", 
            "filesize": 21136250,
            "offset": 10,
            "metadata": {
              "reel_name": "A001",
              "clip_number": "C001"
            },
        }
__JSON__
} | python -m json.tool

The above will create a file with a full path like: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > REEL_A001 > A001_C001 > A001_C001_LEFT.mp4

The payload will accept any valid JSON value. Non-string values are rendered in the following way:

• integers: Rendered in base-10: 10 -> "10"
• floats: Uses the shortest representation according to algorithm described in "Printing Floating-Point Numbers Quickly and Accurately" in Proceedings of the SIGPLAN '96 Conference on Programming Language Design and Implementation.
• booleans: true and false are rendered as "true" and "false"
• null: Rendered as an empty string. If reel_name where set to null, then the first custom folder would be rendered as REEL_

In general we suggest that you limit your values to strings, and format other values as you see fit (for instance, integers will always be printed without leading zeroes, something you may want to change).

In general, only fields which have a valid value for every clip should be used; if a field does not always have a valid value, you should have a plan for how to represent unset or null values.