# FCPXML Structure Reference
How FCPXML represents different elements and what nodes need modification for each editing operation.
---
## Document Structure
```xml
```
---
## Key Elements
### `` - Media Reference
```xml
```
### `` - Timeline Clip
```xml
```
### `` / `` - A/V Components
```xml
```
### `` - Empty Space
```xml
` - Marker
```xml
Audio levels too low
```
### `` - Keyword Range
```xml
```
### `` - Transition Effect
```xml
```
---
## Edit Operations → XML Changes
### ADD_MARKER
**Target:** Inside ``, ``, ``, or ``
```xml
```
---
### TRIM_CLIP
**Target:** `start` and `duration` attributes of ``
```xml
```
---
### REORDER_CLIPS
**Target:** `offset` attributes of all affected clips
```xml
```
**Important:** Element order in XML doesn't matter, only `offset` values determine timeline position.
---
### ADD_TRANSITION
**Target:** Insert `` element between clips
```xml
```
**Note:** Transition `offset` is typically `clip_end - (transition_duration / 2)`
---
### CHANGE_SPEED
**Target:** Add `` or `` inside clip
```xml
```
**Interpolation values:**
- `linear` - constant speed
- `smooth2` - ease in/out
- `smooth` - smoother ease
---
### SPLIT_CLIP
**Target:** Create two clips from one, adjusting `start`, `duration`, `offset`
```xml
```
---
### DELETE_CLIP
**Ripple delete:** Remove clip, shift subsequent clips
```xml
```
**Non-ripple delete:** Replace with gap
```xml
```
---
## Time Format Conversions
FCPXML uses rational time (fractions of seconds):
| Timecode | FCPXML Time |
|----------|-------------|
| 00:00:01:00 @ 30fps | `1s` or `30/30s` |
| 00:00:00:15 @ 30fps | `15/30s` or `1/2s` |
| 00:01:00:00 | `60s` |
| 00:00:02:10 @ 24fps | `58/24s` |
**Conversion formula:**
```
fcpxml_time = (hours * 3600) + (minutes * 60) + seconds + (frames / fps)
```
**Frame-accurate time:**
```
frames_total = (hours * 3600 * fps) + (minutes * 60 * fps) + (seconds * fps) + frames
fcpxml_time = f"{frames_total}/{fps}s"
```
---
## Resource References
Every clip references resources by `id`:
```xml
```
---
## Compound Clips & Nested Timelines
```xml
```
---
## Audio Specifics
```xml
```
---
## Critical Implementation Notes
1. **Always validate XML** after modification - FCP will reject malformed FCPXML
2. **Maintain resource integrity** - never orphan asset references
3. **Recalculate all offsets** after any operation that changes clip positions
4. **Preserve existing attributes** - don't strip attributes you don't understand
5. **Handle connected clips** - clips on other lanes may connect to spine clips
6. **Time precision matters** - use rational fractions, not floats