# Palmier Pro API Documentation: Complete Guide to the macOS Video Editing SDK > Explore the Palmier Pro API documentation. Master macOS video editing with our Swift SDK for timeline control, keyframes, and AI generation. Your complete guide awaits. - Repository: [Palmier/palmier-pro](https://github.com/palmier-io/palmier-pro) - Tags: api-reference - Published: 2026-06-23 --- **Palmier Pro is a Swift 6.2 macOS-only video editing application built on AppKit and AVFoundation that exposes a comprehensive API for document management, timeline manipulation, keyframe animation, and AI-driven video generation.** Palmier Pro is an open-source professional video editor developed by palmier-io. The codebase provides a fully document-based architecture that developers can interact with programmatically to build custom automation workflows and integrations. This Palmier Pro API documentation covers the core interfaces for project persistence, timeline composition, media handling, and AI generation as implemented in the public repository. ## Architecture Overview The Palmier Pro SDK is organized into distinct architectural layers, each with clearly defined responsibilities: | Layer | Responsibility | Representative Types | Key Source | |-------|----------------|----------------------|------------| | **UI & Presentation** | SwiftUI views wrapped in AppKit windows, custom title-bar accessories, and theming | `EditorView`, `TitleBarLeadingView`, `AppTheme` | [`Sources/PalmierPro/UI/AppTheme.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/UI/AppTheme.swift) | | **Document Model** | Persistent document format (`*.palmier-pro` package) with NSDocument integration | `VideoProject`, `ProjectRegistry`, `Project` | [`Sources/PalmierPro/Project/VideoProject.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Project/VideoProject.swift) | | **Timeline Model** | Core data structures for tracks, clips, keyframes, and animation utilities | `Timeline`, `Track`, `Clip`, `KeyframeTrack`, `Effect` | [`Sources/PalmierPro/Models/Timeline.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Models/Timeline.swift) | | **Media Management** | URL resolution, thumbnail caching, waveform generation, and asset restoration | `MediaResolver`, `MediaAsset`, `DiskCache`, `ImageEncoder` | [`Sources/PalmierPro/MediaPanel/MediaResolver.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/MediaPanel/MediaResolver.swift) | | **Generation Engine** | AI-driven video generation and remote service communication (Convex, Clerk, HuggingFace) | `GenerationBackend`, `EditSubmitter`, `VideoCompressor` | [`Sources/PalmierPro/Generation/GenerationBackend.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Generation/GenerationBackend.swift) | | **Compositing** | Metal/CI kernel pipelines for real-time and export effects | `CustomVideoCompositor`, `EffectRegistry` | [`Sources/PalmierPro/Compositing/CustomVideoCompositor.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Compositing/CustomVideoCompositor.swift) | | **Settings** | User preferences via UserDefaults and secure Keychain storage | `SettingsView`, `PrivacyPane`, `AccountPane` | [`Sources/PalmierPro/Settings/SettingsView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Settings/SettingsView.swift) | ## Core API Components ### Loading and Saving Projects The `VideoProject` class in [`Sources/PalmierPro/Project/VideoProject.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Project/VideoProject.swift) subclasses `NSDocument` and implements the complete read/write lifecycle for `*.palmier-pro` packages. These packages store the timeline, media manifest, generation log, and thumbnails. To load an existing project from disk: ```swift let url = URL(fileURLWithPath: "/path/to/project.palmier-pro") let project = try await VideoProject.load(from: url) ``` To persist modifications, invoke the standard NSDocument save method: ```swift project.save( to: destinationURL, ofType: VideoProject.typeIdentifier, for: .saveOperation, completionHandler: { error in // Handle completion } ) ``` After mutating the timeline, call `project.updateChangeCount(.changeDone)` to mark the document as dirty and enable auto-save functionality. ### Timeline Manipulation The timeline model is defined in [`Sources/PalmierPro/Models/Timeline.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Models/Timeline.swift) as a plain Swift struct containing an array of `Track` instances. Each track holds `Clip` objects that reference media via string identifiers and support frame-accurate positioning. To add a video track and insert a clip at frame 120: ```swift var timeline = project.editorViewModel.timeline let newTrack = Track(type: .video) let clip = Clip( mediaRef: "myVideo.mp4", mediaType: .video, startFrame: 120, durationFrames: 180 // 3 seconds at 60fps ) newTrack.clips.append(clip) timeline.tracks.append(newTrack) project.editorViewModel.timeline = timeline project.updateChangeCount(.changeDone) ``` ### Keyframe-Based Animation Animatable properties including opacity, position, scale, rotation, crop, and volume use `KeyframeTrack` defined in [`Sources/PalmierPro/Models/Keyframe.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Models/Keyframe.swift). Each track manages `Keyframe` instances that interpolate values between specific frames. To create a fade-in animation over 30 frames: ```swift var opacityTrack = KeyframeTrack() opacityTrack.upsert(Keyframe(frame: 0, value: 0.0)) opacityTrack.upsert(Keyframe(frame: 30, value: 1.0)) clip.opacityTrack = opacityTrack ``` ### Media Resolution and Caching The `MediaResolver` class in [`Sources/PalmierPro/MediaPanel/MediaResolver.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/MediaPanel/MediaResolver.swift) converts media references to on-disk URLs and manages thumbnail caching via `DiskCache` and `ImageEncoder`. To resolve a media reference and generate a thumbnail: ```swift if let url = project.editorViewModel.mediaResolver.expectedURL(for: clip.mediaRef) { let thumbnail = ImageEncoder.thumbnail(url: url, maxPixelSize: 200) } ``` ### AI-Driven Generation The `GenerationBackend` class in [`Sources/PalmierPro/Generation/GenerationBackend.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Generation/GenerationBackend.swift) provides the API for AI-powered video creation. It communicates with remote services including Convex, Clerk, and HuggingFace to execute text-to-video and image-to-video operations. To generate video from a text prompt: ```swift let backend = GenerationBackend() backend.generateVideo( prompt: "A sunrise over mountains", style: .cinematic, durationSeconds: 5 ) { result in switch result { case .success(let asset): let newClip = Clip( mediaRef: asset.id, mediaType: .video, startFrame: 0, durationFrames: asset.durationFrames ) project.editorViewModel.timeline.tracks[0].clips.append(newClip) case .failure(let error): print("Generation failed: \(error)") } } ``` ### Custom Compositing Effects Effects are registered in `EffectRegistry` and applied through `CustomVideoCompositor` in [`Sources/PalmierPro/Compositing/CustomVideoCompositor.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Compositing/CustomVideoCompositor.swift). The system uses Metal compute kernels and Core Image filters for LUTs, grain, color wheels, and vignettes. To attach a film LUT effect to a clip: ```swift let effect = Effect.lut(name: "FilmLook") clip.effects?.append(effect) ``` Kernel implementations reside in `Sources/PalmierPro/Compositing/Kernels/`. ### Settings and Preferences Application settings are managed through the `Settings` singleton and persisted via `UserDefaults`, with sensitive data such as API keys stored in the macOS Keychain. Accessing application preferences from [`Sources/PalmierPro/Settings/SettingsView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Settings/SettingsView.swift): ```swift Settings.shared.isTelemetryEnabled = true let apiKey = Settings.shared.clerkAPIKey // Securely retrieved from Keychain ``` ## End-to-End Workflow Example The following complete example demonstrates loading a project, adding a track with an animated clip, and saving: ```swift import PalmierPro func editProject() async throws { // Load existing project let projectURL = URL(fileURLWithPath: "/Users/demo/project.palmier-pro") let project = try await VideoProject.load(from: projectURL) // Configure timeline with new track var timeline = project.editorViewModel.timeline var videoTrack = Track(type: .video) let clip = Clip( mediaRef: "footage.mov", mediaType: .video, startFrame: 0, durationFrames: 300 // 5 seconds at 60fps ) // Animate opacity fade-in var opacityTrack = KeyframeTrack() opacityTrack.upsert(Keyframe(frame: 0, value: 0.0)) opacityTrack.upsert(Keyframe(frame: 60, value: 1.0)) clip.opacityTrack = opacityTrack videoTrack.clips.append(clip) timeline.tracks.append(videoTrack) // Commit and save project.editorViewModel.timeline = timeline project.updateChangeCount(.changeDone) try await project.save( to: projectURL, ofType: VideoProject.typeIdentifier, for: .saveOperation ) } ``` ## Summary - **Project Management**: Use `VideoProject.load(from:)` and `NSDocument` methods to handle `*.palmier-pro` files via [`Sources/PalmierPro/Project/VideoProject.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Project/VideoProject.swift). - **Timeline Editing**: Manipulate `Timeline`, `Track`, and `Clip` structs directly through the editor view model, then call `updateChangeCount` to persist state. - **Animation**: Apply `KeyframeTrack` to clip properties for frame-accurate interpolation stored in [`Sources/PalmierPro/Models/Keyframe.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Models/Keyframe.swift). - **Media Handling**: Resolve asset URLs and generate thumbnails using `MediaResolver.expectedURL(for:)` and `ImageEncoder` from [`Sources/PalmierPro/MediaPanel/MediaResolver.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/MediaPanel/MediaResolver.swift). - **AI Generation**: Invoke text-to-video or image-to-video pipelines through `GenerationBackend.generateVideo` in [`Sources/PalmierPro/Generation/GenerationBackend.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Generation/GenerationBackend.swift). - **Effects**: Register and apply Metal-based effects via `EffectRegistry` and `CustomVideoCompositor` in [`Sources/PalmierPro/Compositing/CustomVideoCompositor.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Compositing/CustomVideoCompositor.swift). ## Frequently Asked Questions ### Is Palmier Pro available on iOS or iPad? No. According to the source configuration in [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) and platform-specific implementation files, Palmier Pro is a **macOS-only** application requiring AppKit and AVFoundation frameworks. It targets macOS using Swift 6.2 and does not support iOS, iPadOS, or other mobile platforms. ### How does the AI generation API handle authentication? The `GenerationBackend` class communicates with remote services including Convex, Clerk, and HuggingFace. API keys are stored securely in the macOS Keychain, accessible via `Settings.shared.clerkAPIKey` as implemented in [`Sources/PalmierPro/Settings/SettingsView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Settings/SettingsView.swift). The backend manages token refresh and secure transmission internally through the networking layer. ### What file format does Palmier Pro use for projects? Palmier Pro uses the `*.palmier-pro` package format, which is a directory structure containing the timeline JSON, media manifest, generation log, and cached thumbnails. The `VideoProject` class in [`Sources/PalmierPro/Project/VideoProject.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Project/VideoProject.swift) handles serialization through standard `NSDocument` read/write methods, making it compatible with macOS document management features like Versions and iCloud. ### How are real-time effects processed during playback? The `CustomVideoCompositor` in [`Sources/PalmierPro/Compositing/CustomVideoCompositor.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Compositing/CustomVideoCompositor.swift) implements the `AVVideoCompositing` protocol from AVFoundation. It processes effects per-frame using Metal compute kernels and Core Image filters. Effects registered in `EffectRegistry` are compiled into a render pipeline that applies LUTs, grain, and color corrections during both preview playback and final export.