A modern Swift 6 framework for working with Final Cut Pro's FCPXML with full concurrency support and SwiftTimecode integration. Pipeline Neo is a spiritual successor to the original Pipeline, modernised for Swift 6.0 and contemporary development practices.
Pipeline Neo 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.0 and targeting macOS 12+, it offers type-safe operations, comprehensive test coverage, and seamless integration with SwiftTimecode for professional video editing workflows.
Pipeline Neo is currently in an experimental stage and does not yet cover the full range of FCPXML attributes and parameters. It focuses on core functionality while providing a foundation for future expansion and feature completeness.
This codebase is developed using AI agents.
Important
Pipeline Neo has yet to be extensively tested in production environments, real-world workflows, or application integration. This library serves as a modernised foundation for AI-assisted development and experimentation with FCPXML processing capabilities.
- Core Features
- Requirements
- Installation
- Before CLI Usage
- CLI Usage
- API Documentation
- FCPXML Version Support
- Modularity & Safety
- Architecture Overview
- Credits
- License
- Reporting Bugs
- Contribution
- 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; comprehensive test coverage with 628+ tests across 15+ FCPXML sample files.
- Timecode Operations: SwiftTimecode integration (
CMTime,Timecode, FCPXML time strings);FCPXMLTimecodecustom 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; export to FCPXML/.fcpxmld; 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;TimelineFormatpresets 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).
- CLI:
pipeline-neowith--check-version,--convert-version,--validate,--media-copy, 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.
- macOS 12.0+
- Xcode 16.0+
- Swift 6.0+ (strict concurrency compliant; protocols and public types are
Sendablewhere appropriate;@unchecked Sendableonly where required for Foundation/ObjC interop)
Add Pipeline Neo to your project in Xcode:
- File → Add Package Dependencies
- Enter the repository URL:
https://github.com/TheAcharya/pipeline-neo - Select the version you want to use
- Click Add Package
Or add it to your Package.swift:
// swift-tools-version: 6.0
// Add Pipeline Neo as a dependency and link it to your target.
import PackageDescription
let package = Package(
name: "MyPackage",
platforms: [
.macOS(.v12)
],
dependencies: [
.package(url: "https://github.com/TheAcharya/pipeline-neo", from: "2.3.1")
],
targets: [
.target(
name: "MyTarget",
dependencies: ["PipelineNeo"]
)
]
)First, ensure your system is configured to allow the tool to run:
Privacy & Security Settings
Navigate to the Privacy & Security settings and set your preference to App Store and identified developers.
Download the latest release of the CLI universal binary here.
Extract the pipeline-neo-cli-portable-x.x.x.zip file from the release.
Using Homebrew
$ brew install TheAcharya/homebrew-tap/pipeline-neo$ brew uninstall --cask pipeline-neoUpon completion, find the installed binary pipeline-neo located within /usr/local/bin. Since this is a standard directory part of the environment search path, it will allow running pipeline-neo from any directory like a standard command.
Download the latest release of the CLI installer package here.
Use the pipeline-neo-cli.pkg installer to install the command-line binary into your system. Upon completion, find the installed binary pipeline-neo located within /usr/local/bin. Since this is a standard directory part of the environment search path, it will allow running pipeline-neo from any directory like a standard command.
To uninstall, run this terminal command. It will require your account password.
sudo rm /usr/local/bin/pipeline-neoVERSION=2.3.1 # replace this with the git tag of the version you need
git clone https://github.com/TheAcharya/pipeline-neo.git
cd pipeline-neo
git checkout "tags/$VERSION"
swift build -c releaseOnce the build has finished, the pipeline-neo executable will be located at .build/release/.
$ pipeline-neo --help
OVERVIEW: Experimental tool to read and validate Final Cut Pro FCPXML/FCPXMLD.
https://github.com/TheAcharya/pipeline-neo
USAGE: [<options>] <fcpxml-path> [<output-dir>]
ARGUMENTS:
<fcpxml-path> Input FCPXML file / FCPXMLD bundle.
<output-dir> Output directory.
GENERAL:
--check-version Check and print FCPXML document version.
--convert-version <version>
Convert FCPXML to the given version (e.g. 1.10, 1.14) and write to output-dir.
--extension-type <extension-type>
Output format for --convert-version: fcpxmld (bundle) or fcpxml (single file). Default: fcpxmld.
For target versions 1.5–1.9, .fcpxml is used regardless. (values: fcpxml, fcpxmld; default:
fcpxmld)
--validate Perform robust check and validation of FCPXML/FCPXMLD (semantic + DTD).
EXTRACTION:
--media-copy Scan FCPXML/FCPXMLD and copy all referenced media files to output-dir.
LOG:
--log <log> Log file path.
--log-level <log-level> Log level. (values: trace, debug, info, notice, warning, error, critical; default: info) (default:
info)
--quiet Disable log.
OPTIONS:
--version Show the version.
-h, --help Show help information.
Complete manual, usage guide, and examples are in the Documentation folder:
- Manual — Full user manual: loading, modular operations, time conversions, logging, error handling, async/await, task groups, extensions, validation, version conversion, and step-by-step examples.
- CLI — Experimental command-line interface:
--check-version,--convert-version,--validate,--media-copy, building and extending.
Pipeline Neo supports FCPXML versions 1.5 through 1.14. All DTDs for these versions are included. You can validate a document against any version's schema (e.g. document.validateFCPXMLAgainst(version: "1.14")).
- Parsing: Any well-formed FCPXML document parses successfully; the full XML tree is available via Foundation's
XMLDocument/XMLElementAPIs. - Typed element types: Every element from the FCPXML DTDs (1.5–1.14) is represented in
FCPXMLElementType, so you can identify and filter by any element (e.g.locator,import-options,live-drawing,filter-video, alladjust-*, smart-collection match rules, etc.). Structural types like multicam vs compoundmediaare inferred from the first child. - Typed attributes and helpers: The framework also provides typed properties and helpers for a subset of elements (e.g.
fcpxDuration,fcpxOffset, event/project/clip APIs). Other elements are fully accessible viaelement.name,element.attribute(forName:), and the sharedgetElementAttribute/setElementAttributehelpers.
- Protocol-oriented and dependency-injected: core behaviour (parsing, timecode, document ops, error handling) is behind protocols with default implementations you can replace. Inject when creating FCPXMLService or FCPXMLUtility or when using modular extension overloads.
- Extension APIs that can't take a parameter use a single shared instance (FCPXMLUtility.defaultForExtensions) for consistency and concurrency safety; use overloads with a
using:parameter for custom pipelines. - Built with Swift 6 and strict concurrency; Sendable where possible, no unsafe code. Dependencies (SwiftTimecode 3.0.0, SwiftExtensions 2.0.0+) are up to date.
- Protocols define parsing, timecode conversion, document operations, error handling, MIME type detection, asset validation, silence detection, asset duration measurement, and parallel file I/O; each has a default implementation you can swap. FCPXMLService (and FCPXMLUtility) composes these and exposes sync and async APIs. ModularUtilities provides createPipeline, processFCPXML, validateDocument, convertTimecodes, and similar helpers.
- FCPXMLFileLoader handles .fcpxml and .fcpxmld (including bundle Info.fcpxml). FCPXMLValidator and FCPXMLDTDValidator handle structural and schema validation; DTDs for 1.5–1.14 are bundled.
- Extensions on CMTime, XMLElement, and XMLDocument offer convenience APIs; use modular overloads with an explicit dependency to inject your own. Error types are explicit (FCPXMLError, FCPXMLLoadError, export and validation errors); you can inject a custom error handler.
See AGENT.md for a detailed breakdown for AI agents and contributors.
Created by Vigneswaran Rajkumar
Icon Design by Bor Jen Goh
Licensed under the MIT license. See LICENSE for details.
For bug reports, feature requests and suggestions you can create a new issue to discuss.
Community contributions are welcome and appreciated. Developers are encouraged to fork the repository and submit pull requests to enhance functionality or introduce thoughtful improvements. However, a key requirement is that nothing should break—all existing features and behaviours and logic must remain fully functional and unchanged. Once reviewed and approved, updates will be merged into the main branch.
Pipeline Neo is developed using AI agents and we welcome developers who are interested in maintaining or contributing to the project using similar AI-assisted development approaches. If you're passionate about AI-driven development workflows and would like to collaborate on expanding Pipeline Neo's capabilities, we'd love to hear from you.
Developers with experience in AI agent development and FCPXML processing are invited to get in touch. We can provide repository access and collaborate on advancing the framework's functionality.