Metadata Management

Frame provides comprehensive metadata management capabilities, allowing you to preserve original metadata, strip it completely, or replace it with custom values. This guide covers all three metadata modes and supported fields.

Metadata Modes

Frame supports three metadata handling modes through the MetadataConfig type:

interface MetadataConfig {
  mode: 'preserve' | 'clean' | 'replace';
  title?: string;
  artist?: string;
  album?: string;
  genre?: string;
  date?: string;
  comment?: string;
}

Preserve Mode
Clean Mode
Replace Mode

Preserve Metadata

Mode: mode: "preserve"Preserves all metadata from the source file and optionally adds or overwrites specific fields.

How It Works

All existing metadata tags are copied to the output file
Any fields specified in the config will overwrite existing values
Empty fields are ignored (existing values preserved)
Default mode for most Frame presets

Use Cases

Maintaining original file information
Preserving creation date, camera info, location data
Keeping audio tags (artist, album, etc.)
Adding supplementary metadata while keeping original tags

Configuration

Preserve all metadata (no changes):

{
  "metadata": {
    "mode": "preserve"
  }
}

Preserve metadata but update title:

{
  "metadata": {
    "mode": "preserve",
    "title": "Updated Title"
  }
}

FFmpeg Implementation

# Preserves all metadata by default (no flags needed)
# Adds/overwrites specific fields if provided:
-metadata title="Updated Title"

Preserve mode is ideal for personal media libraries where you want to maintain all original information like dates, camera settings, and location data.

Clean Metadata

Mode: mode: "clean"Removes all metadata from the output file, creating a “clean” file with no tags.

How It Works

All metadata is stripped from the output
Results in slightly smaller file size
Removes potentially sensitive information
Specified fields in the config are ignored (all metadata removed)

Use Cases

Privacy protection - remove camera info, GPS location, dates
Public sharing - social media, web uploads
Minimizing file size - every byte counts
Avoiding metadata conflicts - starting fresh
Removing identifying information

Configuration

{
  "metadata": {
    "mode": "clean"
  }
}

FFmpeg Implementation

-map_metadata -1

What Gets Removed

Title, artist, album, genre
Creation date and time
Camera make and model
GPS coordinates
Software/encoder information
Copyright information
Custom metadata fields

Clean mode removes all metadata including creation dates. This is irreversible. Consider using “preserve” mode if you might need this information later.

Example Use: Privacy Protection

When sharing videos online, metadata can reveal:

Your exact location (GPS coordinates)
When the video was recorded
What device/camera you used
Your name (if stored in metadata)

Solution: Use clean mode for all public sharing.

Frame’s social media presets (TikTok, YouTube, Discord, X) use clean mode by default to protect your privacy.

Replace Metadata

Mode: mode: "replace"Removes all existing metadata and replaces it with only the fields you specify.

How It Works

All existing metadata is stripped first
Only specified fields are added to the output
Empty fields are ignored (not added)
Gives you complete control over output metadata

Use Cases

Creating custom metadata from scratch
Music/audio production workflows
Standardizing metadata across a collection
Removing unwanted tags while adding specific information
Creating clean, professional deliverables

Configuration

{
  "metadata": {
    "mode": "replace",
    "title": "My Video Title",
    "artist": "Creator Name",
    "date": "2024",
    "comment": "Created with Frame"
  }
}

Result: Output file contains only these four metadata fields.

FFmpeg Implementation

-map_metadata -1 \
-metadata title="My Video Title" \
-metadata artist="Creator Name" \
-metadata date="2024" \
-metadata comment="Created with Frame"

Example: Music Production

Preparing an audio track for distribution:

{
  "metadata": {
    "mode": "replace",
    "title": "Track Name",
    "artist": "Artist Name",
    "album": "Album Title",
    "genre": "Electronic",
    "date": "2024"
  }
}

Replace mode is perfect for professional deliverables where you want exact control over what metadata is present.

Supported Metadata Fields

Frame supports the following standard metadata fields, compatible with most containers:

Title

Field: titleType: String

Description

The title or name of the video/audio content.

Use Cases

Video title for media libraries
Song/track name for audio files
Episode name for TV shows
Descriptive name for recordings

Examples

"title": "Vacation 2024 - Day 1"
"title": "Interview with John Doe"
"title": "Awesome Track Name"

Container Support

All major containers: MP4, MKV, MOV, WebM, MP3, FLAC, etc.

Artist

Field: artistType: String

Description

The creator, performer, or artist of the content.

Use Cases

Music artist/band name
Video creator/channel name
Performer name
Content producer

Examples

"artist": "The Beatles"
"artist": "Creator Channel Name"
"artist": "John Doe"

Music Players

Used by music players to group tracks by artist and display in “now playing” info.

Container Support

All major audio and video containers

Album

Field: albumType: String

Description

The album, collection, or series name.

Use Cases

Music album title
Video series name
Collection or compilation name
TV show title

Examples

"album": "Abbey Road"
"album": "Vacation 2024"
"album": "Podcast Series Name"

Music Libraries

Music players use this to group tracks into albums and display album artwork.

Container Support

All major containers, especially important for audio formats

Genre

Field: genreType: String

Description

The genre or category of the content.

Use Cases

Music genre classification
Video category
Content type designation
Library organization

Common Music Genres

"genre": "Rock"
"genre": "Electronic"
"genre": "Jazz"
"genre": "Classical"
"genre": "Hip Hop"
"genre": "Podcast"

Video Genres

"genre": "Documentary"
"genre": "Tutorial"
"genre": "Vlog"
"genre": "Music Video"

Container Support

All major containers

Date

Field: dateType: String

Description

The creation, recording, or release date.

Format Options

Year only: "2024"
Full date: "2024-03-15"
Full timestamp: "2024-03-15T14:30:00"

Use Cases

Recording date
Release date
Publishing date
Copyright year

Examples

"date": "2024"
"date": "2024-03-15"
"date": "2024-03-15T14:30:00"

Notes

Different from file system dates (creation/modified)
Preserved across file copies and conversions
Used by media libraries for sorting/filtering

Container Support

All major containers

Comment

Field: commentType: String

Description

Free-form text for additional information, notes, or descriptions.

Use Cases

Video description
Production notes
Credits
Additional information
Custom metadata

Examples

"comment": "Encoded with Frame on 2024-03-15"
"comment": "Original camera: Sony A7III, Shot in 4K 60fps"
"comment": "Copyright 2024 - All Rights Reserved"
"comment": "Mastered by John Doe Studios"

Length Limits

Most containers support very long comment fields (1000+ characters), but keep it reasonable for compatibility.

Container Support

All major containers

Metadata Mode Comparison

Mode	Preserves Original	Removes Original	Adds Custom	Use Case
Preserve	✓	✗	✓ (overwrites)	Personal libraries, keeping info
Clean	✗	✓	✗	Privacy, public sharing
Replace	✗	✓	✓ (only specified)	Professional delivery, custom tags

Practical Examples

Personal Archive
Social Media Upload
Music Distribution
Video Production

Archiving Personal Videos

Preserve all original metadata from camera:

{
  "metadata": {
    "mode": "preserve"
  }
}

Preserves:

Recording date/time
Camera make/model
GPS location (if present)
All original tags

Perfect for:

Family videos
Travel footage
Personal memories
Maintaining history

Remove all metadata for privacy:

{
  "metadata": {
    "mode": "clean"
  }
}

Removes:

GPS location
Recording device info
Personal information
Dates and times

Perfect for:

YouTube uploads
TikTok/Instagram
Twitter/X posts
Public sharing

Frame’s social media presets (TikTok, X, Discord) automatically use clean mode.

Professional Music Release

Replace metadata with professional tags:

{
  "metadata": {
    "mode": "replace",
    "title": "Song Title",
    "artist": "Artist Name",
    "album": "Album Title",
    "genre": "Electronic",
    "date": "2024",
    "comment": "© 2024 Record Label. All Rights Reserved."
  }
}

Result:

Clean, professional metadata
No extraneous information
Proper artist/album attribution
Copyright notice

Perfect for:

Music releases
Professional audio
Distribution platforms
Client deliverables

Client Deliverable

Custom metadata for professional delivery:

{
  "metadata": {
    "mode": "replace",
    "title": "Project Name - Final Cut",
    "artist": "Production Company Name",
    "date": "2024-03-15",
    "comment": "Delivered to Client Name. HD ProRes export."
  }
}

Perfect for:

Client deliverables
Professional projects
Production archives
Clear documentation

Privacy Considerations

Video and audio files can contain sensitive metadata that you may not want to share publicly.

Common Privacy Risks

GPS Location Data

GPS Coordinates in Metadata

Risk: Your exact filming location is embedded in the file.How it happens:

Smartphones and cameras with GPS
Automatically tagged during recording
Precise latitude/longitude coordinates
Can pinpoint your home, workplace, or other locations

Example metadata:

GPSLatitude: 37°46'30.0"N
GPSLongitude: 122°25'00.0"W

Protection: Use clean or replace mode for any public sharing.

Recording Date/Time

Timestamps

Risk: Reveals when content was created, potentially exposing patterns.Information exposed:

Exact date and time of recording
Can reveal when you’re away from home
May conflict with public statements
Can be used to establish timelines

Protection: Use clean mode to remove all timestamps.

Device Information

Camera/Phone Details

Risk: Reveals what equipment you own.Information exposed:

Camera make and model
Phone type
Software versions
Serial numbers (rare but possible)

Example:

Make: Apple
Model: iPhone 14 Pro
Software: iOS 17.2

Protection: Use clean mode to strip device info.

Personal Information

Author/Creator Fields

Risk: Your name or username may be embedded.How it happens:

Computer username stored in metadata
Software registration name
Camera owner name settings
Editor/creator fields

Protection:

Use clean mode for anonymous sharing
Use replace mode to set custom creator name

Privacy Best Practices

For Public Sharing (Social Media, Web):

{
  "metadata": {
    "mode": "clean"
  }
}

For Personal Archives:

{
  "metadata": {
    "mode": "preserve"
  }
}

For Professional Delivery:

{
  "metadata": {
    "mode": "replace",
    "title": "Project Name",
    "artist": "Company Name"
  }
}

Container Compatibility

Not all containers support all metadata fields equally:

Container	Full Metadata Support	Notes
MP4	✓	Excellent support for all fields
MKV	✓	Extensive metadata support
MOV	✓	Apple-specific tags also supported
MP3	✓	ID3 tags (music metadata standard)
FLAC	✓	Vorbis comments (music metadata)
M4A	✓	iTunes-compatible metadata
WebM	Partial	Limited metadata support
WAV	Limited	Basic metadata only
GIF	✗	No metadata support

Get Started

Features

Guides

Development

​Metadata Management

​Metadata Modes

​Preserve Metadata

​How It Works

​Use Cases

​Configuration

​FFmpeg Implementation

​Clean Metadata

​How It Works

​Use Cases

​Configuration

​FFmpeg Implementation

​What Gets Removed

​Example Use: Privacy Protection

​Replace Metadata

​How It Works

​Use Cases

​Configuration

​FFmpeg Implementation

​Example: Music Production

​Supported Metadata Fields

​Title

​Description

​Use Cases

​Examples

​Container Support

​Artist

​Description

​Use Cases

​Examples

​Music Players

​Container Support

​Album

​Description

​Use Cases

​Examples

​Music Libraries

​Container Support

​Genre

​Description

​Use Cases

​Common Music Genres

​Video Genres

​Container Support

​Date

​Description

​Format Options

​Use Cases

​Examples

​Notes

​Container Support

​Comment

​Description

​Use Cases

​Examples

​Length Limits

​Container Support

​Metadata Mode Comparison

​Practical Examples

​Archiving Personal Videos

​Preparing for Public Sharing

​Professional Music Release

​Client Deliverable

​Privacy Considerations

​Common Privacy Risks

​GPS Coordinates in Metadata

​Timestamps

​Camera/Phone Details

​Author/Creator Fields

​Privacy Best Practices

​Container Compatibility

​See Also

Build docs developers (and LLMs) love

Metadata Management

Metadata Modes

Preserve Metadata

How It Works

Use Cases

Configuration

FFmpeg Implementation

Clean Metadata

How It Works

Use Cases

Configuration

FFmpeg Implementation

What Gets Removed

Example Use: Privacy Protection

Replace Metadata

How It Works

Use Cases

Configuration

FFmpeg Implementation

Example: Music Production

Supported Metadata Fields

Title

Description

Use Cases

Examples

Container Support

Artist

Description

Use Cases

Examples

Music Players

Container Support

Album

Description

Use Cases

Examples

Music Libraries

Container Support

Genre

Description

Use Cases

Common Music Genres

Video Genres

Container Support

Date

Description

Format Options

Use Cases

Examples

Notes

Container Support

Comment

Description

Use Cases

Examples

Length Limits

Container Support

Metadata Mode Comparison

Practical Examples

Archiving Personal Videos

Preparing for Public Sharing

Professional Music Release

Client Deliverable

Privacy Considerations

Common Privacy Risks

GPS Coordinates in Metadata

Timestamps

Camera/Phone Details

Author/Creator Fields

Privacy Best Practices

Container Compatibility

See Also