-
-
Notifications
You must be signed in to change notification settings - Fork 20
Trimmed Writing for OpenFCPXMLKit #548
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -2,36 +2,20 @@ | |||||
|
|
||||||
|  | ||||||
|
|
||||||
| **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. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Suggested change
|
||||||
|
|
||||||
| #### 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 | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Suggested change
|
||||||
| - **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) | ||||||
There was a problem hiding this comment.
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