Asset Metadata

Grail supports three types of metadata on assets, giving you flexible ways to organize and find your media.

Type	Source	Editable	Example
Path metadata	Extracted from file paths	No	Year, department, project
File metadata	Extracted from file contents (FFprobe)	No	Resolution, duration, codec
User metadata	Custom fields you define	Yes	Status, editor, notes

All three types appear in the Metadata and File Information panels on the asset detail page and can be used to filter assets in the asset browser.

---

Path Metadata

Path metadata is automatically extracted from file paths using patterns you define on each storage source. This is useful when your folder structure encodes meaningful information like year, department, or project name.

Setting Up a Path Pattern

1. Open storage sources

   Navigate to Storage Sources and click on the storage source you want to configure.

2. Open the metadata pattern editor

   Click Edit Metadata Pattern on the storage source card.

3. Define your pattern

   Enter a pattern that matches your folder structure using {fieldName} placeholders.

   For example, if your files are stored like:

   /2024/Marketing/CampaignVideo.mp4

   Use the pattern:

   /{year}/{department}/**

   This extracts year: "2024" and department: "Marketing" from the file path.

4. Test the pattern

   Use the test path input to verify your pattern matches correctly before saving.

5. Apply to existing assets

   After saving, choose whether to apply the pattern retroactively to all existing assets or only to newly discovered files.

Tip

Use ** as a wildcard to match any remaining path segments. For example, /{year}/{department}/** matches files at any depth below the department folder.

Advanced Patterns

For complex folder structures, switch to Advanced mode to write a custom regex pattern with named capture groups. The editor shows the equivalent regex for your simple pattern as a starting point.

How Path Metadata Appears

Path metadata values are read-only and shown with a lock icon on the asset detail page. They are set automatically based on where the file is stored — to change them, move the file and rescan.

---

File Metadata

File metadata is technical information extracted automatically from file contents using FFprobe during indexing. This includes:

• Resolution — Video width and height (e.g., 1920x1080)
• Duration — Length of the media file
• Codec — Video and audio codec information
• Frame rate — Video frame rate
• Bit rate — Overall and per-stream bit rates
• Audio channels — Number of audio channels and sample rate

File metadata appears in the File Information panel on the asset detail page. These values are read-only and update automatically when a file is re-indexed.

---

User Metadata

User metadata fields are custom fields that you define for your organization. Unlike path and file metadata, user metadata is fully editable — you can set values per asset or update many assets at once with bulk editing.

Defining Metadata Fields

1. Open metadata field settings

   Navigate to Settings > Metadata Fields.

2. Add a field

   Click Add Field and configure:

   • Label — The display name (e.g., “Project Code”)

   • Description (optional) — Help text shown below the field name

   • Field Type — Choose from:

     Type	Description
     Text	Free-form text input
     Number	Numeric values
     Date	Date values
     Single List	Choose one value from a dropdown
     Multi List	Choose multiple values from a dropdown

3. Save the field

   The field is immediately available on all assets in your organization.

Note

List field types (Single List and Multi List) build their dropdown options automatically from values that have been used across your assets. As you add values, they become available as suggestions for other assets.

Editing Metadata on an Asset

On the asset detail page, expand the Metadata panel to see all defined fields. Click a field value to edit it, or click the + icon to add a value to an empty field.

• Text fields — Click to open a text editor. Press Cmd/Ctrl+Enter to save.
• List fields — Use the dropdown to select or search for values. For Multi List fields, select multiple values.

Bulk Editing

To update metadata across multiple assets at once:

1. Select assets

   In the asset browser, select the assets you want to update using the checkboxes. Bulk actions support up to 1,000 selected assets at a time.

2. Open bulk edit

   Click Edit Metadata in the batch action bar.

3. Choose fields and values

   Check the fields you want to update, then enter new values. For Multi List fields, choose between:

   • Replace — Set the exact values (overwrites existing)
   • Add — Append new values to existing ones

4. Apply changes

   Review the summary and click Apply to update all selected assets.

---

Filtering by Metadata

All three metadata types can be used to filter assets in the asset browser. Click the Metadata filter to see available fields grouped by type:

• Path metadata fields show a folder icon
• User metadata fields show a person icon
• File metadata fields show a document icon

Select values to filter, or use text search for text-type fields. Active metadata filters appear as pills in the filter bar alongside other filters like tags, date range, and media type.