FxGrip is an Objective-C framework for Apple's FxPlug 4 SDK. It adds features and functionality to Final Cut Pro and Motion plug-ins beyond Apple's implementation.
FxGrip wraps the FxPlug host API protocols and adds its own APIs, a parameter model, plug-in registrars, and host-integration extensions. It is macOS-only, because FxPlug hosts are macOS applications.
- Effect and generator base classes.
FxGripTileableEffectandFxGripTileableGeneratordrive the parameter subsystem, the extensions, presets, analysis, and the render pass. - Versioned host API wrappers. Parameter creation, retrieval, setting, grouping, tags, and timing mirror each FxPlug protocol version.
- FxGrip APIs. Presets (
FxGripPresetsAPI_v1, with FxFactory.fxpresetinteroperability), parameter tags (FxGripParameterTagsAPI_v1), and FCPXML capture and apply (FxGripFCPXMLAPI_v1). - Custom parameter controls. Sections, dividers, banners, switches, curves, live images, web views, video, and progress and status displays.
- On-screen controls. Cursors, curves, HUDs, and editable polygons.
- Frame analysis. An
FxAnalyzerpass with per-frame data storage. - Extensions. About and debug menus, internationalization, instance tracking, metadata, and regression support.
- Inference. Pluggable inference backends and an ML image-effect template.
- 3D space. An engine-neutral scene base with a SceneKit engine and a Swift-only RealityKit engine (
FxGripRealityKit, macOS 15+). - FCPXML. A model of Final Cut Pro's interchange format, versions 1.0 through 1.14, with schema and DTD validation,
.fcpxmland.fcpxmldfiles, the pasteboard types, and conversion between an effect's parameters and afilter-video. - Workflow extensions. A mailbox between a plug-in's instances and a Final Cut Pro workflow extension, the plug-in-side relay, and the
FxGripWorkflowcompanion framework the extension links.
FxGrip is adoptable in layers. A plug-in links one utility, wraps the host API, adopts the parameter subsystem through a host, or subclasses the effect base for the whole framework. The DocC catalog's Adoption article maps the levels.
- macOS 13.5 or later (
FxGripRealityKitrequires macOS 15.0) - A current Xcode
- FxPlug 4 SDK, installed at
/Library/Developer/SDKs/FxPlug.sdk - FxFactory, which installs
/Library/Frameworks/FxFactory.framework
Apple distributes the FxPlug SDK to Apple Developer accounts. This repository includes neither the FxPlug SDK nor FxFactory.
xcodebuild -project FxGrip.xcodeproj -scheme FxGrip -configuration Debug -destination 'platform=macOS' buildThe FxGrip scheme builds and tests every target: the FxGrip framework, the FxGripRealityKit, FxGripStoreKit, and FxGripWorkflow companion frameworks, and their test bundles.
xcodebuild -project FxGrip.xcodeproj -scheme FxGrip -configuration Debug -destination 'platform=macOS' testUnit tests run without an FxPlug host. The FxPlugStub target stands in for the SDK's FxPlug.framework, which ships headers and a linker stub only.
A change is ready to merge when the Full Check in AGENTS.md passes: arm64 build and test, x86_64 test, AddressSanitizer test, and DocC. CI runs the same four checks.
The DocC catalog is FxGrip/FxGrip.docc. Build it with:
xcodebuild docbuild -project FxGrip.xcodeproj -scheme FxGrip -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NOIn Xcode, choose Product › Build Documentation.
GitHub Actions runs the Full Check on every push to main and on every pull request. Neither Apple's FxPlug SDK nor Noise Industries' FxFactory framework can be redistributed, so CI installs each from its own private repository through a read-only deploy key:
| Repository | Contents | Secret |
|---|---|---|
belisoful/FxPlug-SDK |
Apple's FxPlugSDK.pkg at the root, one commit per SDK version, tagged v<version> |
FXPLUG_SDK_DEPLOY_KEY |
belisoful/FxFactory-SDK |
A link-only FxFactory.framework stub (headers, module map, .tbd), tagged v<version> |
FXFACTORY_SDK_DEPLOY_KEY |
Pull requests from forks receive no secrets, so their macOS jobs are skipped and a maintainer runs them.
Scripts/make-fxfactory-stub.sh builds the FxFactory stub from the installed /Library/Frameworks/FxFactory.framework. With --publish <clone> it commits, tags, and pushes the stub to a clone of belisoful/FxFactory-SDK.
These Actions variables are optional overrides:
| Variable | Default | Effect |
|---|---|---|
FXPLUG_SDK_REPOSITORY |
belisoful/FxPlug-SDK |
Repository that holds the FxPlug SDK installers. |
FXPLUG_SDK_VERSION |
4.3.5 |
FxPlug SDK version to install. Selects the tag v<version>. |
FXFACTORY_REPOSITORY |
belisoful/FxFactory-SDK |
Repository that holds the FxFactory stubs. |
FXFACTORY_VERSION |
9.0.7 |
FxFactory stub version to install. Selects the tag v<version>. |
XCODE_VERSION |
newest release Xcode on the runner | Xcode to select, e.g. 26.2. |
The Dependency watch workflow checks https://fxfactory.com/download/ daily and opens an issue when an FxFactory release is newer than the newest stub. Apple lists FxPlug SDK releases only behind an Apple Developer sign-in, so a weekly scheduled Claude task on a maintainer's Mac checks the downloads page and opens an issue for a newer SDK.
- FxPlug.framework and PluginManager.framework from the FxPlug SDK
- FxFactory.framework, weak-linked, from FxFactory (the
FxGripFxFactoryProviderlicensing provider) - StoreKit.framework (the Swift
FxGripStoreKitframework, the Mac App Store licensing provider) - Security.framework, for the process entitlements the workflow mailbox reads
- BEFoundation.framework, vendored as a binary in
Frameworks/from belisoful/BEFoundation
See CONTRIBUTING.md. Report security issues as SECURITY.md describes.
FxGrip is available under the MIT License. See LICENSE.
FxPlug, Final Cut Pro, and Motion are trademarks of Apple Inc. FxGrip is not affiliated with Apple.