### Create Opacity Animation (Go)

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Defines a function to create opacity animation parameters using keyframes. It takes start and end opacity values, along with start and end times, to generate a configuration for opacity keyframe animation. Dependencies include the 'fcp' package and 'fmt' for string formatting.

```go
func createOpacityAnimation(startOpacity, endOpacity float64, startTime, endTime string) fcp.Param {
    return fcp.Param{
        Name: "opacity",
        KeyframeAnimation: &fcp.KeyframeAnimation{
            Keyframes: []fcp.Keyframe{
                {
                    Time:   startTime,
                    Value:  fmt.Sprintf("%f", startOpacity),
                    Interp: "linear",
                    Curve:  "smooth",
                },
                {
                    Time:   endTime,
                    Value:  fmt.Sprintf("%f", endOpacity),
                    Interp: "easeOut",
                    Curve:  "linear",
                },
            },
        },
    }
}
```

--------------------------------

### Cutlass YouTube and VTT to FCPXML Conversion (Bash)

Source: https://github.com/andrewarrow/cutlass/blob/main/README.md

Demonstrates a quick start example for Cutlass, showing how to convert YouTube content and VTT subtitle files into segmented FCPXML clips with transition animations.

```bash
./cutlass youtube dQw4w9WgXcQ
./cutlass vtt-clips dQw4w9WgXcQ.en.vtt 00:30_10,01:45_15,02:30_20
# Generates: segmented_video.fcpxml  
# Result: Perfectly timed clips with transition animations
```

--------------------------------

### Cutlass Installation and Basic Usage (Bash)

Source: https://github.com/andrewarrow/cutlass/blob/main/README.md

Provides instructions for installing the Cutlass tool by cloning the repository, building the executable, and demonstrating its basic usage with a help command.

```bash
# Clone the future of video generation
git clone https://github.com/your-username/cutlass
cd cutlass
go build

# Start creating magic
./cutlass --help
```

--------------------------------

### Installation and Execution (Bash)

Source: https://github.com/andrewarrow/cutlass/blob/main/python/README.md

Provides commands to install project dependencies using pip and run the main script. Assumes a requirements.txt file exists.

```bash
pip install -r requirements.txt
python main.py
```

--------------------------------

### FCPXML Video Element Position Animation Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/ANIMATION.md

Provides a complete FCPXML example for animating the 'position' of a video element within an asset clip. It illustrates the correct timing relative to the media start time and includes X and Y axis animations with specific keyframes.

```xml
<asset-clip ref="r2" offset="0s" duration="3980/600s">
    <video ref="r4" lane="1" offset="0s" start="3600s" duration="20400/3000s">
        <adjust-transform>
            <param name="position">
                <param name="X" key="1">
                    <keyframeAnimation>
                        <keyframe time="3600s" value="-266.667"/>
                        <keyframe time="10803300/3000s" value="0"/>
                    </keyframeAnimation>
                </param>
                <param name="Y" key="2">
                    <keyframeAnimation>
                        <keyframe time="3600s" value="0" curve="linear"/>
                    </keyframeAnimation>
                </param>
            </param>
        </adjust-transform>
    </video>
</asset-clip>
```

--------------------------------

### Python Dataclass Usage for Elements

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Shows how to use Python dataclasses from `fcpxml_lib.models.elements` to create Video and AssetClip elements, highlighting the 'start' attribute requirement for images.

```python
from fcpxml_lib.models.elements import Video, AssetClip, Asset, Format

# ✅ Images use Video elements
video_element = Video(
    ref="r2",
    duration="240240/24000s",
    start="0s"  # Required for images
)

# ✅ Videos use AssetClip elements  
asset_clip = AssetClip(
    ref="r2", 
    duration="373400/3000s"
    # NO start attribute for videos
)
```

--------------------------------

### FCPXML Video Asset Example

Source: https://github.com/andrewarrow/cutlass/blob/main/go/wiki/Architecture-Overview.md

Provides an FCPXML example for a video asset. It includes the asset definition with actual duration, format with frameDuration, and the asset-clip wrapper.

```xml
<!-- Video Asset -->
<asset id="r4" duration="14122857/100000s" hasVideo="1" hasAudio="1" format="r5"/>
<format id="r5" frameDuration="1001/30000s" width="1920" height="1080"/>
<asset-clip ref="r4" duration="373400/3000s"/>
```

--------------------------------

### Python Implementation Pattern for FCPXML Audio

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Provides a Python code example demonstrating the correct implementation pattern for handling audio in FCPXML. It shows how to create assets with audio properties and add both video and audio elements to timeline clips.

```python
# 1. Create assets with audio properties when include_audio=True
asset, format_obj = create_media_asset(
    video_path, asset_id, format_id, include_audio=True
)

# 2. Add both video and audio elements to timeline
clip_elements = [
    {"type": "video", "ref": asset_id, "duration": duration},
    {"type": "audio", "ref": asset_id, "duration": duration, "role": "dialogue"}
]
```

--------------------------------

### Python: File Organization and Splitting Strategy

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Illustrates a recommended directory structure for the `fcpxml_lib` package, showing how to split functionality into subpackages and modules. This example highlights the separation of commands, core operations, and data models.

```python
# 🚨 File getting too long? Split by:
# 1. Related functionality into separate modules
# 2. Different data models into separate files  
# 3. Different command implementations into separate modules

# ✅ Example split:
fcpxml_lib/
├── commands/
│   ├── pile_commands.py      # png-pile, video-pile logic
│   ├── edge_commands.py      # edge, video-at-edge logic  
│   └── timeline_commands.py  # basic timeline operations
├── core/
│   └── fcpxml.py            # Core FCPXML operations
└── models/
    └── elements.py          # Dataclass definitions
```

--------------------------------

### Color Keyframes XML Example

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

An example of how color parameters are defined using XML, illustrating the structure for keyframes with time, value, interpolation, and curve attributes. This format is used for specifying color animations.

```xml
<param name="color">
    <keyframe time="0s" value="1 0 0 1" interp="linear" curve="smooth"/>
    <keyframe time="86399313/24000s" value="0 1 0 1" interp="linear" curve="smooth"/>
</param>
```

--------------------------------

### Create Color Animation (Go)

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Provides a Go function to create color animation parameters. It accepts start and end color strings (RGBA format) and time strings to set up color keyframes. This function is designed to work with the 'fcp' package.

```go
func createColorAnimation(startColor, endColor string, startTime, endTime string) fcp.Param {
    return fcp.Param{
        Name: "color",
        KeyframeAnimation: &fcp.KeyframeAnimation{
            Keyframes: []fcp.Keyframe{
                {
                    Time:   startTime,
                    Value:  startColor, // "1 0 0 1" (RGBA)
                    Interp: "linear",
                    Curve:  "smooth",
                },
                {
                    Time:   endTime,
                    Value:  endColor,   // "0 1 0 1" (RGBA)
                    Interp: "linear",
                    Curve:  "smooth",
                },
            },
        },
    }
}
```

--------------------------------

### Go: Transactional Resource Creation (Effects Example)

Source: https://github.com/andrewarrow/cutlass/blob/main/go/CLAUDE.md

Illustrates the correct way to create resources like effects using transaction methods to ensure proper lifecycle management and validation within Final Cut Pro XML generation.

```go
❌ BAD: Direct manipulation bypasses transaction
effectID := tx.ReserveIDs(1)[0]
effect := Effect{ID: effectID, Name: "Blur", UID: "FFGaussianBlur"}
fcpxml.Resources.Effects = append(fcpxml.Resources.Effects, effect)
// Result: "Effect ID is invalid" - resource never committed!

✅ GOOD: Use transaction creation methods
effectID := tx.ReserveIDs(1)[0]
tx.CreateEffect(effectID, "Gaussian Blur", "FFGaussianBlur")
// Resource properly managed and committed with tx.Commit()
```

--------------------------------

### XML for Opacity and Volume Keyframes in FCPXML

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Shows FCPXML keyframe structures for opacity and volume parameters, which support both 'interp' and 'curve' attributes. Examples include 'linear', 'easeIn', 'easeOut', and 'smooth' interpolations.

```xml
<param name="opacity">
    <keyframe time="0s" value="1" interp="linear" curve="smooth"/>
    <keyframe time="86399313/24000s" value="0.5" interp="easeOut" curve="linear"/>
</param>
<param name="volume">
    <keyframe time="0s" value="0dB" interp="linear" curve="smooth"/>
    <keyframe time="86399313/24000s" value="-6dB" interp="easeIn" curve="linear"/>
</param>
```

--------------------------------

### Create Image Animation (Go)

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Demonstrates how to create simple animations for images, including position and scale transformations. This function utilizes keyframe animations for specified parameters. Avoid complex effects that require temporal processing.

```go
func createImageAnimation(imageVideo *fcp.Video, duration string) {
    // ✅ SAFE: Simple position and scale
    imageVideo.AdjustTransform = &fcp.AdjustTransform{
        Params: []fcp.Param{
            {
                Name: "position",
                KeyframeAnimation: &fcp.KeyframeAnimation{
                    Keyframes: []fcp.Keyframe{
                        {Time: "0s", Value: "0 0"},
                        {Time: duration, Value: "100 50"},
                    },
                },
            },
            {
                Name: "scale",
                KeyframeAnimation: &fcp.KeyframeAnimation{
                    Keyframes: []fcp.Keyframe{
                        {Time: "0s", Value: "1 1", Curve: "linear"},
                        {Time: duration, Value: "1.2 1.2", Curve: "smooth"},
                    },
                },
            },
        },
    }
    
    // ❌ AVOID: Complex effects that require temporal processing
    // imageVideo.FilterVideos = []fcp.FilterVideo{{Ref: "FFMotionBlur"}}
}
```

--------------------------------

### FCPXML Smart Collections XML Examples

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/GRAPHICS.md

Provides the exact XML structure for the five essential smart collections required in FCPXML. These examples are crucial for understanding how to correctly configure these collections to prevent import errors and application crashes.

```xml
<smart-collection name="Projects" type="project" />
<smart-collection name="All Video" type="video" />
<smart-collection name="Audio Only" type="audio" />
<smart-collection name="Stills" type="image" />
<smart-collection name="Favorites" rating="1" />
```

--------------------------------

### Minimal FCPXML Structure (XML)

Source: https://github.com/andrewarrow/cutlass/blob/main/python/README.md

An example of the minimal, valid FCPXML output generated by the library, suitable for import into Final Cut Pro. Includes essential elements like resources, library, event, and project setup.

```xml
<fcpxml version="1.11">
  <resources>
    <format id="r1" name="FFVideoFormat1080p2398" frameDuration="1001/24000s" 
            width="1920" height="1080" colorSpace="1-1-1 (Rec. 709)"/>
  </resources>
  <library>
    <event name="My First Event" uid="...">
      <project name="My First Project" uid="..." modDate="...">
        <sequence format="r1" duration="0s" tcStart="0s" tcFormat="NDF" 
                  audioLayout="stereo" audioRate="48000">
          <spine/>
        </sequence>
      </project>
    </event>
  </library>
</fcpxml>
```

--------------------------------

### Create Basic Transform Animation in Go

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

This Go function creates a basic animation for spatial transformations, including position, scale, and rotation. It utilizes keyframes to define start and end values and allows for specifying animation curves like 'linear' or 'smooth'.

```go
func createBasicTransformAnimation(duration string) *fcp.AdjustTransform {
    startTime := "0s"
    endTime := duration
    
    return &fcp.AdjustTransform{
        Params: []fcp.Param{
            // Position animation (no attributes)
            {
                Name: "position",
                KeyframeAnimation: &fcp.KeyframeAnimation{
                    Keyframes: []fcp.Keyframe{
                        {Time: startTime, Value: "0 0"},
                        {Time: endTime, Value: "200 100"},
                    },
                },
            },
            // Scale animation (curve only)
            {
                Name: "scale",
                KeyframeAnimation: &fcp.KeyframeAnimation{
                    Keyframes: []fcp.Keyframe{
                        {Time: startTime, Value: "1 1", Curve: "linear"},
                        {Time: endTime, Value: "1.5 1.5", Curve: "smooth"},
                    },
                },
            },
            // Rotation animation (curve only)
            {
                Name: "rotation",
                KeyframeAnimation: &fcp.KeyframeAnimation{
                    Keyframes: []fcp.Keyframe{
                        {Time: startTime, Value: "0", Curve: "linear"},
                        {Time: endTime, Value: "45", Curve: "smooth"},
                    },
                },
            },
        },
    }
}
```

--------------------------------

### Go: Transactional Resource Creation Methods

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/BAFFLE_ONE.md

Provides examples of using transaction methods in Go to create FCPXML resources like assets, formats, and effects. Emphasizes that direct appending to slices bypasses validation and can lead to errors.

```go
// For assets
tx.CreateAsset(assetID, filePath, baseName, duration, formatID)

// For formats  
tx.CreateFormat(formatID, name, width, height, colorSpace)
tx.CreateFormatWithFrameDuration(formatID, frameDuration, width, height, colorSpace)

// For effects
tx.CreateEffect(effectID, name, uid)
```

--------------------------------

### Go Transaction Example

Source: https://github.com/andrewarrow/cutlass/blob/main/go/wiki/Architecture-Overview.md

Demonstrates the usage of transactions for complex operations within the Cutlass framework. It shows how to create a transaction, defer rollback, perform operations, and commit.

```go
registry := fcp.NewResourceRegistry(fcpxml)
    tx := fcp.NewTransaction(registry)
    defer tx.Rollback()

    // Perform operations...

    if err := tx.Commit(); err != nil {
        return err
    }
```

--------------------------------

### FCPXML Image Asset Example

Source: https://github.com/andrewarrow/cutlass/blob/main/go/wiki/Architecture-Overview.md

Illustrates the FCPXML structure for an image asset. It shows the asset definition with '0s' duration and a video wrapper, along with its format specifications.

```xml
<!-- Image Asset -->
<asset id="r2" duration="0s" hasVideo="1" format="r3"/>
<format id="r3" width="1280" height="720"/>
<video ref="r2" duration="240240/24000s"/>
```

--------------------------------

### Go: Memory Management - Reusing Slices Pattern

Source: https://github.com/andrewarrow/cutlass/blob/main/go/wiki/FCPXML-Generation-Best-Practices.md

Illustrates a memory management best practice in Go by reusing slices to avoid repeated allocations. The 'GOOD' example pre-allocates the slice capacity, while the 'BAD' example shows repeated appends that can lead to inefficient memory growth.

```go
// ✅ GOOD: Reuse slices
spine.AssetClips = make([]fcp.AssetClip, 0, expectedCount)
for _, clip := range clips {
    spine.AssetClips = append(spine.AssetClips, clip)
}

// ❌ BAD: Repeated allocations
for _, clip := range clips {
    spine.AssetClips = append(spine.AssetClips, clip) // Grows slice repeatedly
}
```

--------------------------------

### Go: Create Video Filter with Effect and Parameters

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Implements a function to create a video filter by specifying an effect UID, a name, and a map of parameters. It structures the filter with its reference and parameters. The function relies on the 'fcp' package.

```go
func createVideoFilter(effectUID, name string, params map[string]string) fcp.FilterVideo {
    filter := fcp.FilterVideo{
        Ref:  effectUID,
        Name: name,
    }
    
    for paramName, value := range params {
        filter.Params = append(filter.Params, fcp.Param{
            Name:  paramName,
            Value: value,
        })
    }
    
    return filter
}

// Example usage:
blurFilter := createVideoFilter("FFGaussianBlur", "Blur", map[string]string{
    "amount": "5.0",
})

colorFilter := createVideoFilter("FFColorCorrection", "Color", map[string]string{
    "saturation": "1.2",
    "exposure":   "0.5",
    "shadows":    "0.1",
    "highlights": "-0.1",
})
```

--------------------------------

### Python: CLI Command File Template

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Provides a template for creating new CLI command files. It includes necessary imports, the command function definition, and comments guiding the implementation for argument handling and business logic delegation.

```python
"""
Command Name Implementation

Brief description of what this command does.
"""

import sys
from pathlib import Path

# Import required fcpxml_lib modules
from fcpxml_lib import create_empty_project, save_fcpxml
from fcpxml_lib.generators.timeline_generators import some_generator

def command_name_cmd(args):
    """CLI implementation for command-name"""
    # Argument validation and processing
    # Business logic delegation
    # Output and error handling
```

--------------------------------

### Go: Create Ease-InOut Animation Curve for Keyframes

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Generates a slice of 'fcp.Keyframe' objects with an ease-in-out timing curve. It calculates intermediate values between a start and end value based on provided time points. This function requires the 'fmt' package for string formatting and the 'fcp' package.

```go
func createEaseInOutCurve(startValue, endValue float64, times []string) []fcp.Keyframe {
    keyframes := make([]fcp.Keyframe, len(times))
    
    for i, time := range times {
        progress := float64(i) / float64(len(times)-1)
        
        // Ease-in-out curve calculation
        easedProgress := progress
        if progress < 0.5 {
            easedProgress = 2 * progress * progress
        } else {
            easedProgress = 1 - 2*(1-progress)*(1-progress)
        }
        
        value := startValue + (endValue-startValue)*easedProgress
        
        keyframes[i] = fcp.Keyframe{
            Time:   time,
            Value:  fmt.Sprintf("%f", value),
            Interp: "smooth",
            Curve:  "smooth",
        }
    }
    
    return keyframes
}
```

--------------------------------

### Create Video Animation and Effects (Go)

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Shows how to apply full animation and effect capabilities to videos. This function demonstrates adding complex animations and various video filters like Gaussian Blur and Color Correction.

```go
func createVideoAnimation(assetClip *fcp.AssetClip, duration string) {
    // ✅ FULL SUPPORT: All animations work
    assetClip.AdjustTransform = createComplexAnimation(duration)
    
    // ✅ FULL SUPPORT: All effects work
    assetClip.FilterVideos = []fcp.FilterVideo{
        createVideoFilter("FFGaussianBlur", "Blur", map[string]string{"amount": "3"}),
        createVideoFilter("FFColorCorrection", "Color", map[string]string{"saturation": "1.2"}),
    }
}
```

--------------------------------

### Validation Success Output Example (Text)

Source: https://github.com/andrewarrow/cutlass/blob/main/python/README.md

Example output demonstrating successful validation of FCPXML rules and well-formedness checks. Shows both schema rule validation and XML linting passing.

```text
🧪 Testing validation failure detection...
✅ Validation correctly caught error: Invalid audio rate: 48000. Must be one of ['32k', '44.1k', '48k', ...]

📄 FCPXML saved to: empty_project.fcpxml
🔍 Running XML well-formedness validation...
✅ XML VALIDATION PASSED
```

--------------------------------

### XML Example: Audio Roles

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Illustrates assigning roles to audio elements for organization within Final Cut Pro.

```xml
<audio role="dialogue">
<audio role="music">
<audio role="effects">
```

--------------------------------

### Go: Create Audio Filter with Effect and Parameters

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Provides a Go function to construct an audio filter, similar to video filters, by defining its effect UID, name, and associated parameters. This is useful for applying audio processing effects. It uses the 'fcp' package for structure.

```go
func createAudioFilter(effectUID, name string, params map[string]string) fcp.FilterAudio {
    filter := fcp.FilterAudio{
        Ref:  effectUID,
        Name: name,
    }
    
    for paramName, value := range params {
        filter.Params = append(filter.Params, fcp.Param{
            Name:  paramName,
            Value: value,
        })
    }
    
    return filter
}

// Example usage:
eqFilter := createAudioFilter("FFAudioEQ", "EQ", map[string]string{
    "low-freq":  "100",
    "low-gain":  "2",
    "mid-freq":  "1000",
    "mid-gain":  "0",
    "high-freq": "10000",
    "high-gain": "-1",
})
```

--------------------------------

### Apply Verified Effects in Go

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

This Go snippet shows how to apply a verified effect, specifically a Gaussian blur, to video assets. It highlights the importance of using an effect's reference ID and specifies parameters for customization, ensuring stability.

```go
// Only use verified effects
video.FilterVideos = []fcp.FilterVideo{{ 
    Ref:  "verified-gaussian-blur-id",
    Name: "Blur",
    Params: []fcp.Param{{Name: "amount", Value: "5"}},
}}
```

--------------------------------

### Go Transaction Example

Source: https://github.com/andrewarrow/cutlass/wiki/Architecture-Overview.md

Demonstrates the usage of a transaction in the Cutlass framework for performing atomic operations. It shows how to create a transaction, defer rollback, perform operations, and commit the changes, ensuring data integrity.

```Go
registry := fcp.NewResourceRegistry(fcpxml)
tx := fcp.NewTransaction(registry)
def tx.Rollback()

// Perform operations...

if err := tx.Commit(); err != nil {
    return err
}
```

--------------------------------

### Go: Create Complex Animation with Multi-Parameter Keyframes

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Defines a function to create a complex animation with multiple parameters like position, scale, and opacity. It utilizes keyframe animations with specified timings and easing curves. Dependencies include the 'fcp' package for duration and keyframe handling.

```go
func createComplexAnimation(duration string) []fcp.Param {
    midTime := fcp.ConvertSecondsToFCPDuration(
        fcp.ParseFCPDuration(duration) / 2.0,
    )
    
    return []fcp.Param{
        // Three-point position animation
        {
            Name: "position",
            KeyframeAnimation: &fcp.KeyframeAnimation{
                Keyframes: []fcp.Keyframe{
                    {Time: "0s", Value: "-100 -50"},
                    {Time: midTime, Value: "0 0"},
                    {Time: duration, Value: "100 50"},
                },
            },
        },
        // Scale with easing
        {
            Name: "scale",
            KeyframeAnimation: &fcp.KeyframeAnimation{
                Keyframes: []fcp.Keyframe{
                    {Time: "0s", Value: "0.5 0.5", Curve: "smooth"},
                    {Time: midTime, Value: "1.2 1.2", Curve: "smooth"},
                    {Time: duration, Value: "1 1", Curve: "linear"},
                },
            },
        },
        // Opacity fade
        {
            Name: "opacity",
            KeyframeAnimation: &fcp.KeyframeAnimation{
                Keyframes: []fcp.Keyframe{
                    {Time: "0s", Value: "0", Interp: "easeIn", Curve: "smooth"},
                    {Time: midTime, Value: "1", Interp: "linear", Curve: "smooth"},
                    {Time: duration, Value: "0.8", Interp: "easeOut", Curve: "linear"},
                },
            },
        },
    }
}
```

--------------------------------

### Construction-Time Validation Example (Python)

Source: https://github.com/andrewarrow/cutlass/blob/main/python/README.md

Illustrates how the library catches errors during object construction, specifically an invalid audio rate for a Sequence. This provides immediate feedback with a clear error message.

```python
# This will fail immediately with clear error message:
bad_sequence = Sequence(audio_rate="48000")  # Should be "48k"
# ValidationError: Invalid audio rate: 48000. Must be one of ['32k', '44.1k', '48k', ...]
```

--------------------------------

### Safe Practices: Using Built-in Elements in Go

Source: https://github.com/andrewarrow/cutlass/blob/main/go/wiki/Animation-and-Effects.md

Provides examples of safely implementing spatial transformations, cropping, and verified effects using built-in elements in Go. These methods are presented as crash-free alternatives to custom UIDs.

```go
// Spatial transformations - always safe
video.AdjustTransform = &fcp.AdjustTransform{
    Position: "100 50",
    Scale:    "1.5 1.5",
    Params: []fcp.Param{
        {Name: "rotation", Value: "45"},
        {Name: "anchor", Value: "0.5 0.5"},
    },
}

// Cropping - always safe
assetClip.AdjustCrop = &fcp.AdjustCrop{
    Mode: "trim",
    TrimRect: &fcp.TrimRect{
        Left:   "0.1",
        Right:  "0.9", 
        Top:    "0.1",
        Bottom: "0.9",
    },
}

// Only use verified effects
video.FilterVideos = []fcp.FilterVideo{{ 
    Ref:  "verified-gaussian-blur-id",
    Name: "Blur",
    Params: []fcp.Param{{Name: "amount", Value: "5"}},
}}
```

--------------------------------

### Timeline Element Rules for Images vs. Videos

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Details the distinct timeline element requirements for images and videos within FCPXML. Images use `Video` elements with a `start` attribute, while videos use `AssetClip` elements without it.

```python
from fcpxml_lib.models.elements import Video, AssetClip

# ✅ Images: Use Video elements with start attribute
if file_path.lower().endswith(('.jpg', '.png')):
    element = Video(
        ref=asset_id,
        duration=duration,
        start="0s"  # Required for images
    )

# ✅ Videos: Use AssetClip elements without start attribute  
elif file_path.lower().endswith(('.mp4', '.mov')):
    element = AssetClip(
        ref=asset_id,
        duration=duration
        # NO start attribute for videos
    )
```

--------------------------------

### FCPXML Asset Resource Definition Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Shows the definition of a media asset resource in FCPXML, including its ID, name, source file path, duration, and video/audio properties. This example references a video file with audio.

```xml
<asset id="r2" name="video.mov" 
       src="file:///path/to/video.mov" 
       start="0s" duration="3600s" 
       hasVideo="1" hasAudio="1" 
       audioSources="1" audioChannels="2" 
       audioRate="48000"/>
```

--------------------------------

### FCPXML Resource Structure Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPCAFE.md

Demonstrates the structure of the resources section in an FCPXML file. This includes defining formats with frame durations, effects with UIDs, and assets with source file paths. Proper resource definition is crucial for FCPXML validity.

```xml
<resources>
    <format id="r1" name="FFVideoFormat1080p2997" frameDuration="1001/30000s" />
    <effect id="r2" name="Shapes" uid=".../Shapes.motn" />
    <asset id="r3" src="file:///path/to/video.mov" />
</resources>
```

--------------------------------

### FCPXML Audio Clip Element Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Illustrates the audio element in FCPXML, linked to a media asset with specified timing. It demonstrates referencing the asset and setting audio parameters like volume and role.

```xml
<audio ref="r2" offset="0s" duration="10s" start="0s" role="dialogue">
    <param name="volume" value="0dB"/>
</audio>
```

--------------------------------

### FCPXML Asset-Clip Layer Position Animation Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/ANIMATION.md

Illustrates an FCPXML example for animating the 'position' of an entire asset-clip layer. Keyframes for asset-clip animations are relative to the clip's offset, starting at time='0s'.

```xml
<asset-clip ref="r2" offset="0s" duration="3980/600s">
    <adjust-transform>
        <param name="position">
            <param name="X" key="1">
                <keyframeAnimation>
                    <keyframe time="0s" value="0"/>
                    <keyframe time="2200/3000s" value="133.333"/>
                </keyframeAnimation>
            </param>
            <param name="Y" key="2">
                <keyframeAnimation>
                    <keyframe time="0s" value="0" curve="linear"/>
                </keyframeAnimation>
            </param>
        </param>
    </adjust-transform>
    <video ref="r4" lane="1" offset="0s" start="3600s" duration="20400/3000s">
        <!-- video element animations use different timing -->
    </video>
</asset-clip>
```

--------------------------------

### Media Asset Creation: Transaction Methods vs. Manual

Source: https://github.com/andrewarrow/cutlass/blob/main/go/CLAUDE.md

Demonstrates the correct way to create media assets using transaction methods which automatically detect and set media properties like audio and video, contrasting it with the incorrect manual approach that can lose these properties.

```go
❌ BAD: Manual asset creation loses audio properties
asset := Asset{
    HasVideo: "1",
    HasAudio: "1",  // Will be lost if not handled properly
    // ... other properties
}
fcpxml.Resources.Assets = append(fcpxml.Resources.Assets, asset)

✅ GOOD: Transaction methods detect media types automatically
tx.CreateAsset(assetID, videoPath, baseName, duration, formatID)
// Automatically sets HasAudio="1" for videos, omits for images
```

--------------------------------

### Go Command for Building and Running Cutalyst

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPCAFE.md

This command builds the Cutalyst project and then executes it with specific input and output files for testing.

```bash
go build && ./cutalyst -i "Andre_Agassi" -w tennis.fcpxml
```

--------------------------------

### XML for Scale, Rotation, and Anchor Keyframes in FCPXML

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

Illustrates the FCPXML structure for keyframes supporting only the 'curve' attribute, specifically for scale, rotation, and anchor parameters. Includes examples of 'linear' and 'smooth' curve interpolations.

```xml
<param name="scale">
    <keyframe time="86399313/24000s" value="1 1" curve="linear"/>  <!-- Only curve -->
    <keyframe time="172798626/24000s" value="1.5 1.5" curve="smooth"/>  <!-- Only curve -->
</param>
<param name="rotation">
    <keyframe time="0s" value="0" curve="linear"/>
    <keyframe time="86399313/24000s" value="45" curve="smooth"/>
</param>
<param name="anchor">
    <keyframe time="0s" value="0.5 0.5" curve="linear"/>
    <keyframe time="86399313/24000s" value="0.3 0.7" curve="smooth"/>
</param>
```

--------------------------------

### Go Function for Creating Position Animations in FCPXML

Source: https://github.com/andrewarrow/cutlass/wiki/Animation-and-Effects.md

A Go function to generate FCPXML 'position' parameter structures for animations. It creates keyframes with specified start and end values and times, adhering to FCPXML's handling of position keyframes.

```go
func createPositionAnimation(startPos, endPos string, startTime, endTime string) fcp.Param {
    return fcp.Param{
        Name: "position",
        KeyframeAnimation: &fcp.KeyframeAnimation{
            Keyframes: []fcp.Keyframe{
                {Time: startTime, Value: startPos},     // No attributes
                {Time: endTime, Value: endPos},         // No attributes
            },
        },
    }
}
```

--------------------------------

### Go: Using ResourceRegistry for ID Generation Patterns

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/BAFFLE_TWO.md

Demonstrates correct patterns for using the `ResourceRegistry` to generate and reserve unique IDs. It shows how to initialize the registry, reserve multiple IDs for different resource types, and calculate the next available ID based on existing resources.

```go
// Use the ResourceRegistry pattern
registry := fcp.NewResourceRegistry(fcpxml)
tx := fcp.NewTransaction(registry)
defers tx.Rollback()

// Reserve IDs safely
ids := tx.ReserveIDs(3)
assetID := ids[0]    // "r2"
formatID := ids[1]   // "r3"
effectID := ids[2]   // "r4"

// Alternative: Count existing resources for next ID
resourceCount := len(fcpxml.Resources.Assets) + len(fcpxml.Resources.Formats) + len(fcpxml.Resources.Effects)
nextID := fmt.Sprintf("r%d", resourceCount+1)

// For batch operations, reserve IDs upfront
batchIDs := tx.ReserveIDs(10)
for i, mediaFile := range mediaFiles {
    asset := createAsset(mediaFile, batchIDs[i])
    fcpxml.Resources.Assets = append(fcpxml.Resources.Assets, asset)
}

```

--------------------------------

### FCPXML Video Clip Element Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Shows the structure of a video element within an FCPXML sequence, referencing an asset and defining its duration and start time. It also includes parameters for visual adjustments like cropping and scaling.

```xml
<video ref="r2" offset="0s" duration="10s" start="0s">
    <param name="crop" value="0 0 1920 1080"/>
    <param name="scale" value="1 1"/>
</video>
```

--------------------------------

### FCPXML Timebase Formatting (Go)

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/DAWFileKit.md

Demonstrates two approaches to formatting time durations for FCPXML in Go. The first shows a simple duration formatting, while the second introduces a Rational struct for enhanced precision.

```go
// Current: Simple duration formatting
func FormatDurationForFCPXML(d time.Duration) string {
    return fmt.Sprintf("%d/30000s", int64(d.Seconds()*30000))
}
```

```go
// Enhanced: Rational number precision
type Rational struct {
    Numerator   int64
    Denominator int64
}

func (r Rational) ToFCPXML() string {
    return fmt.Sprintf("%d/%ds", r.Numerator, r.Denominator)
}
```

--------------------------------

### Correct Multi-Lane Video and Audio Implementation XML

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Shows the correct XML implementation for complex clips with multi-lane video and audio. It includes essential asset-level audio properties and corresponding timeline audio elements for proper FCP import.

```xml
<!-- 1. Assets MUST have audio properties -->
<asset id="r2" name="video" hasVideo="1" hasAudio="1" audioSources="1" audioChannels="2" audioRate="48000">
    <media-rep kind="original-media" src="file:///path/to/video.mov"/>
</asset>

<!-- 2. Timeline MUST have both video AND audio elements -->
<clip offset="0s" name="Video Clip" duration="240240/24000s" format="r3" tcFormat="NDF">
    <conform-rate scaleEnabled="0" srcFrameRate="24"/>
    <adjust-transform><!-- keyframe animations --></adjust-transform>
    <video ref="r2" offset="0s" duration="240240/24000s"/>
    <audio ref="r2" offset="0s" duration="240240/24000s" role="dialogue"/>
</clip>
```

--------------------------------

### Go: Video Property Detection for Asset Creation

Source: https://github.com/andrewarrow/cutlass/blob/main/go/CLAUDE.md

Highlights the importance of detecting video properties automatically using `CreateVideoAssetWithDetection()` instead of hardcoding them, ensuring compatibility with various media formats and frame rates.

```go
❌ BAD: Hardcoded properties cause import failures
asset.HasAudio = "1"  // Video might not have audio!
format.Width = "1920" // Video might be 1080×1920 portrait!
format.FrameDuration = "1001/30000s" // Video might be different fps!

✅ GOOD: Use CreateVideoAssetWithDetection() for proper detection
tx.CreateVideoAssetWithDetection(assetID, videoPath, baseName, duration, formatID)
// Automatically detects: width, height, frame rate, audio presence
// Matches samples: portrait videos get correct 1080×1920 dimensions
// Audio-only if file actually has audio tracks
// Frame rate validation: Rejects bogus rates >120fps, maps to standard FCP rates
```

--------------------------------

### FCPXML Video Filter Element Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Provides an example of a video filter element in FCPXML, referencing an effect resource and specifying its parameters. This example shows a Gaussian Blur filter with an amount parameter.

```xml
<filter-video ref="r5" name="Gaussian Blur">
    <param name="amount" value="10"/>
</filter-video>
```

--------------------------------

### Generate FCPXML with Media

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Demonstrates the core architecture pattern for creating an FCPXML file, adding media to a timeline, and saving the output. It emphasizes using validated functions from the fcpxml_lib for robustness.

```python
from fcpxml_lib.core.fcpxml import create_empty_project, add_media_to_timeline, save_fcpxml

def generate_my_feature(input_files: list, output_file: str) -> bool:
    # 1. Create base FCPXML structure
    fcpxml = create_empty_project()
    
    # 2. Add media using validated functions
    success = add_media_to_timeline(
        fcpxml, 
        input_files, 
        clip_duration_seconds=3.0
    )
    if not success:
        raise RuntimeError("Failed to add media to timeline")
    
    # 3. Apply modifications to timeline elements
    # Access via: fcpxml.library.events[0].projects[0].sequences[0].spine
    
    # 4. Save with validation
    return save_fcpxml(fcpxml, output_file)
```

--------------------------------

### Create and Save FCPXML Project (Python)

Source: https://github.com/andrewarrow/cutlass/blob/main/python/README.md

Demonstrates the basic usage of the library to create an empty FCPXML project and save it to a file. Requires the 'main' module for core functionality.

```python
from main import create_empty_project, save_fcpxml

# Create an empty project
fcpxml = create_empty_project("My Project", "My Event")

# Save to file
save_fcpxml(fcpxml, "output.fcpxml")
```

--------------------------------

### Python Implementation Pattern for Titles

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Provides a Python code snippet demonstrating the implementation pattern for titles, including creating background assets, title effects, and video elements referencing assets.

```python
# 1. Create background asset from real media file
background_asset, background_format = create_media_asset(
    str(media_file), asset_id, format_id
)

# 2. Create title effect in resources
title_effect = {
    "id": effect_id,
    "name": "Text", 
    "uid": ".../Titles.localized/Basic Text.localized/Text.localized/Text.moti"
}

# 3. Create video element referencing the ASSET
video_element = {
    "type": "video",
    "ref": asset_id,  # ✅ References asset, not format
    "nested_elements": [title_elements]  # ✅ Titles nested inside
}
```

--------------------------------

### FCPXML Keyword Element Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Illustrates how to add keyword annotations to FCPXML content, defining a time range and the keyword value. This example tags a 30-second segment as 'interview'.

```xml
<keyword start="0s" duration="30s" value="interview"/>
```

--------------------------------

### Cutalyst Application Structure

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/DAWFileKit.md

Illustrates the modular design of the Cutalyst application, showing separate packages for different functionalities like FCPXML generation, Wikipedia parsing, VTT processing, and YouTube integration.

```text
Cutalyst Application:
├── Core CLI Logic
├── FCPXML Generation (fcp/)
├── Wikipedia Parsing (wikipedia/)
├── VTT Processing (vtt/)
└── YouTube Integration (youtube/)
```

--------------------------------

### FCPXML Transition Element Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Shows the basic structure for a transition element in FCPXML, specifying its name, timeline offset, and duration. This example uses a 'Cross Dissolve' transition.

```xml
<transition name="Cross Dissolve" offset="9s" duration="2s"/>
```

--------------------------------

### FCPXML Marker Element Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Demonstrates the inclusion of a marker element within an FCPXML timeline, indicating a specific point with a value and duration. This example marks 'Scene 2' and is not completed.

```xml
<marker start="30s" duration="1s" value="Scene 2" completed="0"/>
```

--------------------------------

### Media Asset Creation

Source: https://github.com/andrewarrow/cutlass/blob/main/python/CLAUDE.md

Explains the correct method for creating media assets, which includes automatic media type detection and proper asset construction. It advises against manual asset creation to bypass validation checks.

```python
from fcpxml_lib.core.fcpxml import create_media_asset

# ✅ Automatic media type detection and proper asset creation
asset, format_obj = create_media_asset(
    file_path="video.mp4",
    asset_id="r2", 
    format_id="r3"
)
# Handles: absolute paths, media type detection, audio properties

# ❌ Manual asset creation bypasses validation
asset = Asset(id="r2", src="./video.mp4")  # Relative path fails!
```

--------------------------------

### Generate Basic FCPXML with Video Asset

Source: https://github.com/andrewarrow/cutlass/wiki/API-Reference.md

Creates a basic FCPXML file, reserves IDs, sets up a video asset with specified path and duration, adds it to a timeline, commits changes, validates compliance, and writes the FCPXML to an output path. This function is essential for initializing FCPXML documents with video content.

```go
func GenerateBasicFCPXML(videoPath, outputPath string) error {
    // 1. Create base FCPXML
    fcpxml, err := fcp.GenerateEmpty("")
    if err != nil {
        return err
    }
    
    // 2. Set up resource management
    registry := fcp.NewResourceRegistry(fcpxml)
    tx := fcp.NewTransaction(registry)
    defer tx.Rollback()
    
    // 3. Reserve IDs
    ids := tx.ReserveIDs(2)
    assetID := ids[0]
    formatID := ids[1]
    
    // 4. Create video asset
    duration := fcp.ConvertSecondsToFCPDuration(10.0)
    err = tx.CreateVideoAssetWithDetection(assetID, videoPath, filepath.Base(videoPath), duration, formatID)
    if err != nil {
        return err
    }
    
    // 5. Add to timeline
    sequence := &fcpxml.Library.Events[0].Projects[0].Sequences[0]
    sequence.Spine.AssetClips = append(sequence.Spine.AssetClips, fcp.AssetClip{
        Ref:      assetID,
        Offset:   "0s",
        Duration: duration,
        Name:     filepath.Base(videoPath),
    })
    
    // 6. Commit and validate
    if err := tx.Commit(); err != nil {
        return err
    }
    
    if err := fcp.ValidateClaudeCompliance(fcpxml); err != nil {
        return err
    }
    
    // 7. Write output
    return fcp.WriteToFile(fcpxml, outputPath)
}
```

--------------------------------

### FCPXML Format Resource Definition Example

Source: https://github.com/andrewarrow/cutlass/blob/main/reference/FCPXML.md

Defines a video format resource within FCPXML, specifying its ID, name, frame duration, resolution, and color space. This example details a 1080p 30fps format.

```xml
<format id="r1" name="FFVideoFormat1080p30" 
        frameDuration="1001/30000s" 
        width="1920" height="1080" 
        colorSpace="1-1-1 (Rec. 709)"/>
```