diff --git a/docs/_includes/developer-tools-and-frameworks/openfcpxmlkit.md b/docs/_includes/developer-tools-and-frameworks/openfcpxmlkit.md index 1339c5151d8..6e5462584b9 100644 --- a/docs/_includes/developer-tools-and-frameworks/openfcpxmlkit.md +++ b/docs/_includes/developer-tools-and-frameworks/openfcpxmlkit.md @@ -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) diff --git a/docs/_includes/tools/openfcpxmlkit.md b/docs/_includes/tools/openfcpxmlkit.md index 934b9c35b02..3cf16460aa0 100644 --- a/docs/_includes/tools/openfcpxmlkit.md +++ b/docs/_includes/tools/openfcpxmlkit.md @@ -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. #### 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) \ No newline at end of file diff --git a/docs/developers/fcpxml.md b/docs/developers/fcpxml.md index 87f4ecb761a..d9072922ed4 100644 --- a/docs/developers/fcpxml.md +++ b/docs/developers/fcpxml.md @@ -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). --- @@ -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).