Palmier Pro API Documentation: Complete Guide to the macOS Video Editing SDK

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
Document Model	Persistent document format (*.palmier-pro package) with NSDocument integration	VideoProject, ProjectRegistry, Project	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
Media Management	URL resolution, thumbnail caching, waveform generation, and asset restoration	MediaResolver, MediaAsset, DiskCache, ImageEncoder	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
Compositing	Metal/CI kernel pipelines for real-time and export effects	CustomVideoCompositor, EffectRegistry	Sources/PalmierPro/Compositing/CustomVideoCompositor.swift
Settings	User preferences via UserDefaults and secure Keychain storage	SettingsView, PrivacyPane, AccountPane	Sources/PalmierPro/Settings/SettingsView.swift

Core API Components

Loading and Saving Projects

The VideoProject class in 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:

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:

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 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:

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<T> defined in 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:

var opacityTrack = KeyframeTrack<Double>()
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 converts media references to on-disk URLs and manages thumbnail caching via DiskCache and ImageEncoder.

To resolve a media reference and generate a thumbnail:

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 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:

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. 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:

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:

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:

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<Double>()
    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.
• Timeline Editing: Manipulate Timeline, Track, and Clip structs directly through the editor view model, then call updateChangeCount to persist state.
• Animation: Apply KeyframeTrack<T> to clip properties for frame-accurate interpolation stored in 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.
• AI Generation: Invoke text-to-video or image-to-video pipelines through GenerationBackend.generateVideo in Sources/PalmierPro/Generation/GenerationBackend.swift.
• Effects: Register and apply Metal-based effects via EffectRegistry and CustomVideoCompositor in 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 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. 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}