Cutlass

Cutlass

This comprehensive reference covers every Go struct used in FCPXML generation and their corresponding XML elements. Understanding these structs is essential for programmatic FCPXML manipulation.

Core Document Structure

FCPXML

The root document container that wraps all FCPXML content.

type FCPXML struct {
    XMLName   xml.Name  `xml:"fcpxml"`
    Version   string    `xml:"version,attr"`      // "1.13" - FCPXML format version
    Resources Resources `xml:"resources"`         // All assets, formats, effects, media
    Library   Library   `xml:"library"`          // Events, projects, sequences
}

XML Output:

<fcpxml version="1.13">
    <resources>...</resources>
    <library>...</library>
</fcpxml>

Resource Management System

Resources

Container for all reusable assets, formats, effects, and media definitions. Every referenced element in the timeline must have a corresponding resource.

type Resources struct {
    Assets     []Asset     `xml:"asset,omitempty"`      // Video/audio/image files
    Formats    []Format    `xml:"format"`               // Resolution, frame rate specs
    Effects    []Effect    `xml:"effect,omitempty"`     // Motion templates, titles
    Media      []Media     `xml:"media,omitempty"`      // Compound clips, sequences
}

Asset

Represents a media file (video, audio, image) with all its technical properties.

type Asset struct {
    ID            string    `xml:"id,attr"`              // "r1", "r2" - unique identifier
    Name          string    `xml:"name,attr"`            // "video.mp4" - display name
    UID           string    `xml:"uid,attr"`             // Unique media identifier
    Start         string    `xml:"start,attr"`           // "0s" - media start timecode
    HasVideo      string    `xml:"hasVideo,attr,omitempty"`    // "1" if contains video
    Format        string    `xml:"format,attr,omitempty"`      // Reference to Format ID
    VideoSources  string    `xml:"videoSources,attr,omitempty"` // "1" - number of video tracks
    HasAudio      string    `xml:"hasAudio,attr,omitempty"`     // "1" if contains audio
    AudioSources  string    `xml:"audioSources,attr,omitempty"` // "1" - number of audio tracks
    AudioChannels string    `xml:"audioChannels,attr,omitempty"` // "2" - stereo, "1" - mono
    AudioRate     string    `xml:"audioRate,attr,omitempty"`     // "48000" - sample rate in Hz
    Duration      string    `xml:"duration,attr"`        // "240240/24000s" - FCP duration format
    MediaRep      MediaRep  `xml:"media-rep"`           // File path and signature
    Metadata      *Metadata `xml:"metadata,omitempty"`   // Optional metadata
}

Critical Usage: Images use duration="0s" (timeless), videos have calculated duration.

Format

Defines video/audio format specifications like resolution, frame rate, and color space.

type Format struct {
    ID            string `xml:"id,attr"`                    // "r1" - unique identifier
    Name          string `xml:"name,attr,omitempty"`        // "FFVideoFormat1080p30"
    FrameDuration string `xml:"frameDuration,attr,omitempty"` // "1001/30000s" for 29.97fps
    Width         string `xml:"width,attr,omitempty"`       // "1920" - pixels
    Height        string `xml:"height,attr,omitempty"`      // "1080" - pixels
    ColorSpace    string `xml:"colorSpace,attr,omitempty"`  // "1-1-1 (Rec. 709)"
}

Critical Usage: Images omit FrameDuration, videos require it for proper playback.

Effect

References Motion templates, built-in effects, or title templates.

type Effect struct {
    ID   string `xml:"id,attr"`        // "r1" - unique identifier
    Name string `xml:"name,attr"`      // "Text", "Blur" - display name
    UID  string `xml:"uid,attr,omitempty"` // ".../Text.moti" - template path
}

MediaRep

File system reference with security bookmarks for media assets.

type MediaRep struct {
    Kind     string `xml:"kind,attr"`      // "original-media"
    Sig      string `xml:"sig,attr"`       // File signature hash
    Src      string `xml:"src,attr"`       // "file:///path/to/video.mp4" - MUST be absolute
    Bookmark string `xml:"bookmark,omitempty"` // macOS security bookmark
}

Metadata

Extensible metadata system for storing custom information.

type Metadata struct {
    MDs []MetadataItem `xml:"md"`     // Array of key-value pairs
}

type MetadataItem struct {
    Key   string      `xml:"key,attr"`         // "author", "description"
    Value string      `xml:"value,attr,omitempty"` // Simple values
    Array *StringArray `xml:"array,omitempty"`      // Array values
}

type StringArray struct {
    Strings []string `xml:"string"`   // ["item1", "item2"]
}

Project Structure

Library

Top-level container for all projects and events.

type Library struct {
    Location          string            `xml:"location,attr,omitempty"` // Library file path
    Events            []Event           `xml:"event"`                   // Project containers
    SmartCollections  []SmartCollection `xml:"smart-collection,omitempty"` // Dynamic collections
}

Event

Container for related projects, similar to folders.

type Event struct {
    Name     string    `xml:"name,attr"`           // "My Event" - display name
    UID      string    `xml:"uid,attr,omitempty"`  // Unique identifier
    Projects []Project `xml:"project"`             // Contained projects
}

Project

Individual project containing sequences (timelines).

type Project struct {
    Name      string     `xml:"name,attr"`              // "My Project"
    UID       string     `xml:"uid,attr,omitempty"`     // Unique identifier
    ModDate   string     `xml:"modDate,attr,omitempty"` // "2023-12-01 10:30:00"
    Sequences []Sequence `xml:"sequence"`               // Timelines
}

Sequence

The main timeline containing all video/audio elements.

type Sequence struct {
    Format      string `xml:"format,attr"`       // Reference to Format ID
    Duration    string `xml:"duration,attr"`     // "600600/24000s" - total length
    TCStart     string `xml:"tcStart,attr"`      // "0s" - timecode start
    TCFormat    string `xml:"tcFormat,attr"`     // "NDF" - Non-Drop Frame
    AudioLayout string `xml:"audioLayout,attr"`  // "stereo" - audio configuration
    AudioRate   string `xml:"audioRate,attr"`    // "48000" - sample rate
    Spine       Spine  `xml:"spine"`            // Main timeline container
}

Timeline Elements

Spine

The main timeline container that holds all video/audio elements in chronological order.

type Spine struct {
    XMLName    xml.Name    `xml:"spine"`
    AssetClips []AssetClip `xml:"asset-clip,omitempty"` // Video/audio files
    Gaps       []Gap       `xml:"gap,omitempty"`        // Empty timeline spaces
    Titles     []Title     `xml:"title,omitempty"`      // Text elements
    Videos     []Video     `xml:"video,omitempty"`      // Generators, shapes, images
}

Critical Feature: Custom MarshalXML automatically sorts elements by timeline offset.

AssetClip

References video/audio assets in the timeline. Used for MOV, MP4, WAV files.

type AssetClip struct {
    XMLName         xml.Name         `xml:"asset-clip"`
    Ref             string           `xml:"ref,attr"`          // Asset ID reference
    Lane            string           `xml:"lane,attr,omitempty"` // "1", "2" - layer number
    Offset          string           `xml:"offset,attr"`       // "0s" - timeline position
    Name            string           `xml:"name,attr"`         // Display name
    Start           string           `xml:"start,attr,omitempty"` // "30030/24000s" - in-point
    Duration        string           `xml:"duration,attr"`     // "240240/24000s" - clip length
    Format          string           `xml:"format,attr,omitempty"` // Override format
    TCFormat        string           `xml:"tcFormat,attr,omitempty"` // Timecode format
    AudioRole       string           `xml:"audioRole,attr,omitempty"` // Audio role assignment
    ConformRate     *ConformRate     `xml:"conform-rate,omitempty"`   // Frame rate conversion
    AdjustCrop      *AdjustCrop      `xml:"adjust-crop,omitempty"`    // Cropping parameters
    AdjustTransform *AdjustTransform `xml:"adjust-transform,omitempty"` // Position/scale/rotation
    NestedAssetClips []AssetClip     `xml:"asset-clip,omitempty"`     // Connected clips
    Titles          []Title          `xml:"title,omitempty"`          // Overlaid titles
    Videos          []Video          `xml:"video,omitempty"`          // Overlaid generators
    FilterVideos    []FilterVideo    `xml:"filter-video,omitempty"`   // Applied effects
}

Video

Used for generators, shapes, images, and synthetic content. Images use Video (not AssetClip).

type Video struct {
    XMLName xml.Name `xml:"video"`
    Ref           string         `xml:"ref,attr"`              // Asset/Effect ID reference
    Lane          string         `xml:"lane,attr,omitempty"`   // Layer number
    Offset        string         `xml:"offset,attr"`           // Timeline position
    Name          string         `xml:"name,attr"`             // Display name
    Duration      string         `xml:"duration,attr"`         // Element duration
    Start         string         `xml:"start,attr,omitempty"`  // Media in-point
    Params        []Param        `xml:"param,omitempty"`       // Effect parameters
    AdjustTransform *AdjustTransform `xml:"adjust-transform,omitempty"` // Spatial transforms
    FilterVideos     []FilterVideo   `xml:"filter-video,omitempty"`     // Applied effects
    NestedVideos     []Video     `xml:"video,omitempty"`      // Connected videos
    NestedAssetClips []AssetClip `xml:"asset-clip,omitempty"` // Connected clips
    NestedTitles     []Title     `xml:"title,omitempty"`      // Connected