Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 11 additions & 28 deletions docs/_includes/developer-tools-and-frameworks/openfcpxmlkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,36 +2,19 @@

![](/static/openfcpxmlkit-social-card.png)

**OpenFCPXMLKit** is modern Swift 6 framework for working with Final Cut Pro's FCPXML with full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration.

OpenFCPXMLKit provides a comprehensive API for parsing, creating, and manipulating FCPXML files with advanced timecode operations, async/await patterns, and robust error handling. Built with Swift 6.3 and targeting **macOS 26+** and **iOS 26+**, it offers type-safe operations, comprehensive test coverage (877 tests), and seamless integration with SwiftTimecode and XLKit for professional video editing workflows. A cross-platform XML abstraction layer (Foundation on macOS, AEXML on iOS) keeps the library usable on both platforms.

OpenFCPXMLKit is currently in an experimental stage. It covers most core FCPXML attributes and parameters and provides a solid foundation for parsing, creation, and manipulation, with room for future expansion and additional feature coverage.

This codebase is developed using AI agents.

> [!IMPORTANT]
> OpenFCPXMLKit is highly experimental and has not yet been extensively tested in production environments, real-world workflows, or application integration. Report generation, in particular, remains at a very early and experimental stage. This library serves as a modernised foundation for AI-assisted development and experimentation with FCPXML processing capabilities.

> [!CAUTION]
> The codebase's API is still evolving and may change without notice between versions. Please consult the documentation for API usage. Use with caution in any workflow you rely on.

> [!NOTE]
> This project is shared as is and is not under active or regular development.
**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.

#### Core Features

- **FCPXML I/O**: Read, create, modify documents (.fcpxml/.fcpxmld bundles); load via `FCPXMLFileLoader` (sync/async); create FCPXML from scratch with events, projects, resources, and clips.
- **Parsing & Validation**: Parse and validate against bundled DTDs (1.5–1.14); structural/reference and DTD schema validation (full DTD on macOS; cross-platform structural validation on iOS via `FCPXMLStructuralValidator`); 877 tests across 58 FCPXML sample files (including empty timeline creation, project-creation export, AEXML parity, reporting, and validation suites).
- **Timecode Operations**: SwiftTimecode integration (`CMTime`, `Timecode`, FCPXML time strings); `FCPXMLTimecode` custom type (arithmetic, frame alignment, conversion); all FCP frame rates (23.976, 24, 25, 29.97, 30, 50, 59.94, 60 fps).
- **Typed Models**: Resources, events, clips, projects, adjustments (Crop, Transform, Blend, Stabilization, Volume, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation), filters (VideoFilter, AudioFilter, VideoFilterMask with FilterParameter), transitions, multicam (Media.Multicam, Angle, MulticamSource, MCClip), captions/titles (Caption, Title with TextStyle/TextStyleDefinition), smart collections (SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type), collections (CollectionFolder, KeywordCollection).
- **Timeline Operations**: Build `Timeline`; create valid projects with custom or preset dimensions and frame rate (via `TimelineFormat`); export to FCPXML/.fcpxmld (including zero-clip/empty timelines); optional event/project UIDs and library location (`FCPXMLUID`); ripple insert, auto lane assignment, clip queries (lane/time range/asset ID), lane range computation; metadata (markers, chapter markers, keywords, ratings, custom metadata, timestamps); secondary storylines; `TimelineFormat` presets and computed properties.
- **Media Operations**: Extract asset/locator URLs; copy with deduplication; MIME type detection (`UTType`/`AVFoundation`); asset validation (existence, lane compatibility); silence detection; duration measurement; parallel file I/O; still image asset support.
- **Analysis & Conversion**: Cut detection (edit points, transitions, gaps); typed element filtering (`FCPXMLElementType`); version conversion (strip elements, validate, save as .fcpxml/.fcpxmld); per-version DTD validation; element stripping based on target version DTDs.
- **Animation**: KeyframeAnimation, Keyframe with interpolation, FadeIn/FadeOut; integrated with FilterParameter; auxValue support (FCPXML 1.11+).
- **Extensions**: CMTime Codable (FCPXML time string encoding/decoding); CollectionFolder and KeywordCollection for organization; Live Drawing (FCPXML 1.11+); HiddenClipMarker (FCPXML 1.13+); Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps).
- **Excel Reporting**: Production's Best Friend–style multi-sheet `.xlsx` workbooks from an FCPXML/FCPXMLD via `FinalCutPro.FCPXML.buildReport(options:)` (XLKit-backed). Sheets for Role Inventory (Selected Roles + per-role), Markers, Keywords, Titles & Generators, Transitions, Video & Audio Effects, Speed Change Effects, and a Summary sheet with per-role duration totals and percentages; role exclusions, project-name filtering, and progress callbacks.
- **CLI**: `OpenFCPXMLKit-CLI` with `--check-version`, `--convert-version`, `--validate`, `--media-copy`, `--create-project` (new empty FCPXML project with width/height/rate/version), `--report` (Excel report; `--report-full` and per-section flags), logging options (see CLI README).
- **Architecture**: Protocol-oriented, dependency-injected; sync/async APIs; Swift 6 concurrency-safe design; comprehensive test suite with file-based and logic tests.
- **Documents & validation** – Read, create, and modify `.fcpxml`/`.fcpxmld` files with support for FCPXML 1.5–1.14, semantic and DTD validation, version conversion, and cut detection
- **Timecode & timing** – SwiftTimecode integration with `CMTime`, arithmetic, frame alignment, and support for common frame rates
- **Typed models** – Resources, events, clips, projects, transitions, multicam, adjustments, filters, captions, keyframe animation, and more
- **Timeline** – Build and export timelines with ripple insert, auto lane, clip queries, markers, and metadata
- **Detached authoring** – A value-graph approach to authoring without live XML ownership
- **Extraction & media** – Presets for captions, markers, roles, titles, effects, plus media extraction and validation
- **Timeline projection** – A mid-layer bridging extraction and reporting, handling channels, lanes, retiming, and overlap analysis
- **Excel & PDF reporting** – Generate detailed reports (role inventory, markers, keywords, titles, effects, etc.) with filtering and export options
- **CLI** – A single portable binary for check, convert, validate, media-copy, create-project, and report commands
- **Architecture** – Protocol-oriented with dependency injection, layered from XML through parsing, modelling, extraction, projection, to reporting

[!button text="View on GitHub" target="blank" variant="info"](https://github.com/TheAcharya/OpenFCPXMLKit)
40 changes: 12 additions & 28 deletions docs/_includes/tools/openfcpxmlkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,36 +2,20 @@

![](/static/openfcpxmlkit-social-card.png)

**OpenFCPXMLKit** is modern Swift 6 framework for working with Final Cut Pro's FCPXML with full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration.

OpenFCPXMLKit provides a comprehensive API for parsing, creating, and manipulating FCPXML files with advanced timecode operations, async/await patterns, and robust error handling. Built with Swift 6.3 and targeting **macOS 26+** and **iOS 26+**, it offers type-safe operations, comprehensive test coverage (877 tests), and seamless integration with SwiftTimecode and XLKit for professional video editing workflows. A cross-platform XML abstraction layer (Foundation on macOS, AEXML on iOS) keeps the library usable on both platforms.

OpenFCPXMLKit is currently in an experimental stage. It covers most core FCPXML attributes and parameters and provides a solid foundation for parsing, creation, and manipulation, with room for future expansion and additional feature coverage.

This codebase is developed using AI agents.

> [!IMPORTANT]
> OpenFCPXMLKit is highly experimental and has not yet been extensively tested in production environments, real-world workflows, or application integration. Report generation, in particular, remains at a very early and experimental stage. This library serves as a modernised foundation for AI-assisted development and experimentation with FCPXML processing capabilities.

> [!CAUTION]
> The codebase's API is still evolving and may change without notice between versions. Please consult the documentation for API usage. Use with caution in any workflow you rely on.

> [!NOTE]
> This project is shared as is and is not under active or regular development.
**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Calling the project merely “experimental” drops the concrete warning that production workflows and report generation are not extensively tested and that the API may change without notice. Because this page advertises reporting and a broad API, retaining a concise production/API-stability warning would reduce the risk of readers treating it as production-ready.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/_includes/tools/openfcpxmlkit.md, line 5:

<comment>Calling the project merely “experimental” drops the concrete warning that production workflows and report generation are not extensively tested and that the API may change without notice. Because this page advertises reporting and a broad API, retaining a concise production/API-stability warning would reduce the risk of readers treating it as production-ready.</comment>

<file context>
@@ -2,36 +2,20 @@
-
-> [!NOTE]
-> This project is shared as is and is not under active or regular development.
+**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.
 
 #### Core Features
</file context>
Suggested change
**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.
**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion; production workflows and report generation are not extensively tested, and the API may change without notice.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Readers may infer that XLKit is also the PDF backend, but PDF export uses CoreGraphics. Separating the Excel/XLKit and PDF capabilities would keep the integration description accurate.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/_includes/tools/openfcpxmlkit.md, line 5:

<comment>Readers may infer that XLKit is also the PDF backend, but PDF export uses CoreGraphics. Separating the Excel/XLKit and PDF capabilities would keep the integration description accurate.</comment>

<file context>
@@ -2,36 +2,20 @@
-
-> [!NOTE]
-> This project is shared as is and is not under active or regular development.
+**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.
 
 #### Core Features
</file context>
Suggested change
**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.
**OpenFCPXMLKit** is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel reporting, and PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.


#### Core Features

- **FCPXML I/O**: Read, create, modify documents (.fcpxml/.fcpxmld bundles); load via `FCPXMLFileLoader` (sync/async); create FCPXML from scratch with events, projects, resources, and clips.
- **Parsing & Validation**: Parse and validate against bundled DTDs (1.5–1.14); structural/reference and DTD schema validation (full DTD on macOS; cross-platform structural validation on iOS via `FCPXMLStructuralValidator`); 877 tests across 58 FCPXML sample files (including empty timeline creation, project-creation export, AEXML parity, reporting, and validation suites).
- **Timecode Operations**: SwiftTimecode integration (`CMTime`, `Timecode`, FCPXML time strings); `FCPXMLTimecode` custom type (arithmetic, frame alignment, conversion); all FCP frame rates (23.976, 24, 25, 29.97, 30, 50, 59.94, 60 fps).
- **Typed Models**: Resources, events, clips, projects, adjustments (Crop, Transform, Blend, Stabilization, Volume, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation), filters (VideoFilter, AudioFilter, VideoFilterMask with FilterParameter), transitions, multicam (Media.Multicam, Angle, MulticamSource, MCClip), captions/titles (Caption, Title with TextStyle/TextStyleDefinition), smart collections (SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type), collections (CollectionFolder, KeywordCollection).
- **Timeline Operations**: Build `Timeline`; create valid projects with custom or preset dimensions and frame rate (via `TimelineFormat`); export to FCPXML/.fcpxmld (including zero-clip/empty timelines); optional event/project UIDs and library location (`FCPXMLUID`); ripple insert, auto lane assignment, clip queries (lane/time range/asset ID), lane range computation; metadata (markers, chapter markers, keywords, ratings, custom metadata, timestamps); secondary storylines; `TimelineFormat` presets and computed properties.
- **Media Operations**: Extract asset/locator URLs; copy with deduplication; MIME type detection (`UTType`/`AVFoundation`); asset validation (existence, lane compatibility); silence detection; duration measurement; parallel file I/O; still image asset support.
- **Analysis & Conversion**: Cut detection (edit points, transitions, gaps); typed element filtering (`FCPXMLElementType`); version conversion (strip elements, validate, save as .fcpxml/.fcpxmld); per-version DTD validation; element stripping based on target version DTDs.
- **Animation**: KeyframeAnimation, Keyframe with interpolation, FadeIn/FadeOut; integrated with FilterParameter; auxValue support (FCPXML 1.11+).
- **Extensions**: CMTime Codable (FCPXML time string encoding/decoding); CollectionFolder and KeywordCollection for organization; Live Drawing (FCPXML 1.11+); HiddenClipMarker (FCPXML 1.13+); Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps).
- **Excel Reporting**: Production's Best Friend–style multi-sheet `.xlsx` workbooks from an FCPXML/FCPXMLD via `FinalCutPro.FCPXML.buildReport(options:)` (XLKit-backed). Sheets for Role Inventory (Selected Roles + per-role), Markers, Keywords, Titles & Generators, Transitions, Video & Audio Effects, Speed Change Effects, and a Summary sheet with per-role duration totals and percentages; role exclusions, project-name filtering, and progress callbacks.
- **CLI**: `OpenFCPXMLKit-CLI` with `--check-version`, `--convert-version`, `--validate`, `--media-copy`, `--create-project` (new empty FCPXML project with width/height/rate/version), `--report` (Excel report; `--report-full` and per-section flags), logging options (see CLI README).
- **Architecture**: Protocol-oriented, dependency-injected; sync/async APIs; Swift 6 concurrency-safe design; comprehensive test suite with file-based and logic tests.
- **Documents & validation** – Read, create, and modify `.fcpxml`/`.fcpxmld` files with support for FCPXML 1.5–1.14, semantic and DTD validation, version conversion, and cut detection

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: On iOS, this bullet overstates validation support: full DTD validation is macOS-only and iOS falls back to structural validation. Keeping the platform qualifier here would prevent iOS users from expecting schema/DTD validation.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/_includes/tools/openfcpxmlkit.md, line 9:

<comment>On iOS, this bullet overstates validation support: full DTD validation is macOS-only and iOS falls back to structural validation. Keeping the platform qualifier here would prevent iOS users from expecting schema/DTD validation.</comment>

<file context>
@@ -2,36 +2,20 @@
-- **Excel Reporting**: Production's Best Friend–style multi-sheet `.xlsx` workbooks from an FCPXML/FCPXMLD via `FinalCutPro.FCPXML.buildReport(options:)` (XLKit-backed). Sheets for Role Inventory (Selected Roles + per-role), Markers, Keywords, Titles & Generators, Transitions, Video & Audio Effects, Speed Change Effects, and a Summary sheet with per-role duration totals and percentages; role exclusions, project-name filtering, and progress callbacks.
-- **CLI**: `OpenFCPXMLKit-CLI` with `--check-version`, `--convert-version`, `--validate`, `--media-copy`, `--create-project` (new empty FCPXML project with width/height/rate/version), `--report` (Excel report; `--report-full` and per-section flags), logging options (see CLI README).
-- **Architecture**: Protocol-oriented, dependency-injected; sync/async APIs; Swift 6 concurrency-safe design; comprehensive test suite with file-based and logic tests.
+- **Documents & validation** – Read, create, and modify `.fcpxml`/`.fcpxmld` files with support for FCPXML 1.5–1.14, semantic and DTD validation, version conversion, and cut detection
+- **Timecode & timing** – SwiftTimecode integration with `CMTime`, arithmetic, frame alignment, and support for common frame rates
+- **Typed models** – Resources, events, clips, projects, transitions, multicam, adjustments, filters, captions, keyframe animation, and more
</file context>
Suggested change
- **Documents & validation** – Read, create, and modify `.fcpxml`/`.fcpxmld` files with support for FCPXML 1.5–1.14, semantic and DTD validation, version conversion, and cut detection
- **Documents & validation** – Read, create, and modify `.fcpxml`/`.fcpxmld` files with support for FCPXML 1.5–1.14, semantic and DTD validation on macOS (structural validation on iOS), version conversion, and cut detection

- **Timecode & timing** – SwiftTimecode integration with `CMTime`, arithmetic, frame alignment, and support for common frame rates
- **Typed models** – Resources, events, clips, projects, transitions, multicam, adjustments, filters, captions, keyframe animation, and more
- **Timeline** – Build and export timelines with ripple insert, auto lane, clip queries, markers, and metadata
- **Detached authoring** – A value-graph approach to authoring without live XML ownership
- **Extraction & media** – Presets for captions, markers, roles, titles, effects, plus media extraction and validation
- **Timeline projection** – A mid-layer bridging extraction and reporting, handling channels, lanes, retiming, and overlap analysis
- **Excel & PDF reporting** – Generate detailed reports (role inventory, markers, keywords, titles, effects, etc.) with filtering and export options
- **CLI** – A single portable binary for check, convert, validate, media-copy, create-project, and report commands
- **Architecture** – Protocol-oriented with dependency injection, layered from XML through parsing, modelling, extraction, projection, to reporting


[!button text="View on GitHub" target="blank" variant="info"](https://github.com/TheAcharya/OpenFCPXMLKit)
14 changes: 5 additions & 9 deletions docs/developers/fcpxml.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,11 @@ You can read [Demystifying Final Cut Pro XMLs by Philip Hodgetts and Gregory Cla

---

## swift-daw-file-tools
## SwiftFCPXML

[Steffan Andrews](https://github.com/orchetect) has created an amazing Swift Framework called [swift-daw-file-tools](https://github.com/orchetect/swift-daw-file-tools), which can read and process FCPXML.
Created by [Steffan Andrews](https://github.com/orchetect), SwiftFCPXML is a Swift library for efficiently parsing and extracting timeline events from FCPXML (Final Cut Pro XML) files, with limited authoring support. It focuses on two main areas: reading and authoring FCPXML using a fast, lightweight data model that wraps the XML objects, and reasoning on FCPXML data to extract information such as timeline events and markers. The library is currently macOS-only, a limitation of Apple's XMLDocument API, and is under active development, with substantial (though not complete) coverage of the FCPXML DTD.

You can learn more about [SwiftFCPXML](https://github.com/orchetect/swift-fcpxml).

---

Expand All @@ -64,13 +66,7 @@ You can learn more about [SwiftSecuencia](https://github.com/intrusive-memory/Sw

## OpenFCPXMLKit

**OpenFCPXMLKit** is modern Swift 6 framework for working with Final Cut Pro's FCPXML with full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration.

OpenFCPXMLKit provides a comprehensive API for parsing, creating, and manipulating FCPXML files with advanced timecode operations, async/await patterns, and robust error handling. Built with Swift 6.3 and targeting **macOS 26+** and **iOS 26+**, it offers type-safe operations, comprehensive test coverage (877 tests), and seamless integration with SwiftTimecode and XLKit for professional video editing workflows. A cross-platform XML abstraction layer (Foundation on macOS, AEXML on iOS) keeps the library usable on both platforms.

OpenFCPXMLKit is currently in an experimental stage. It covers most core FCPXML attributes and parameters and provides a solid foundation for parsing, creation, and manipulation, with room for future expansion and additional feature coverage.

This codebase is developed using AI agents.
OpenFCPXMLKit is a modern Swift 6 framework for working with Final Cut Pro's FCPXML, offering full concurrency support, SwiftTimecode integration, and [XLKit](https://github.com/TheAcharya/XLKit) integration for Excel/PDF reporting. It provides a type-safe API for parsing, creating, and manipulating FCPXML using async/await, and targets macOS 26+ and iOS 26+. The project is currently experimental, developed using AI agents, and covers most core FCPXML attributes with room for future expansion.

You can learn more about [OpenFCPXMLKit](https://github.com/TheAcharya/OpenFCPXMLKit).

Expand Down