Reaching iOS PhotoLibrary, Core Image, and ActivityKit through a Capacitor native plugin — implementing FilmtoneMediaPlugin's nine methods

Capacitor 7.4 hybrid layout

Filmtone iOS is a hybrid app on top of Capacitor 7.4.3. It hosts the web shell (packages/film-lab-ui + React 19.2) inside a WKWebView, and exposes iOS-only APIs (PhotoLibrary, Core Image, AVFoundation, ActivityKit) to TypeScript through the FilmtoneMediaPlugin bridge. Only the things the web layer can't reach become native; UI and editor logic stay in the web side.

Eight bridge methods

// apps/capacitor-film-lab-ios/ios/App/App/FilmtoneMediaPlugin.swift
@objc(FilmtoneMediaPlugin)
final class FilmtoneMediaPlugin: CAPPlugin, CAPBridgedPlugin {
    let identifier = "FilmtoneMediaPlugin"
    let jsName = "FilmtoneMedia"
    let pluginMethods: [CAPPluginMethod] = [
        CAPPluginMethod(name: "pickSource", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "pickLutFile", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "probeSource", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "renderPreviewFrame", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "runExport", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "saveToPhotos", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "shareOutput", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "cancelExport", returnType: CAPPluginReturnPromise),
    ]
    // ...
}

What each method owns

• pickSource — picks a photo or video via PHPickerViewController
• pickLutFile — picks a .cube file via UIDocumentPickerViewController (accepts { slot?: "inputLut" | "creativeLut" })
• probeSource — extracts codec, color, resolution, duration, and input-transform policy from AVAsset
• renderPreviewFrame — renders one Core Image preview frame for the current project state
• runExport — full export (mezzanine, depth, sidecar). Streams progress to TS via the exportProgress notify event
• saveToPhotos — writes the output to PhotoLibrary via PHPhotoLibrary
• shareOutput — presents UIActivityViewController
• cancelExport — stops an in-flight export through ExportCancelController

TypeScript proxy

The TS side calls registerPlugin<FilmtoneMediaPlugin>("FilmtoneMedia", { web: ... }) and pins the contract in the interface type. The web fallback (filmtoneMedia.web.ts) only runs in dev when the web shell is exercised standalone. Export progress is consumed via addListener("exportProgress", ...).

// apps/capacitor-film-lab-ios/src/native/filmtoneMedia.ts
export interface FilmtoneMediaPlugin {
  pickSource(): Promise<SourceInfo | null>;
  pickLutFile(options?: { slot?: "inputLut" | "creativeLut" }): Promise<PickedLutFile | null>;
  probeSource(options: { uri: string }): Promise<SourceProbe>;
  renderPreviewFrame(request: Phase0ExportRequest): Promise<Phase0PreviewRenderResult>;
  runExport(request: Phase0ExportRequest): Promise<Phase0ExportResult>;
  saveToPhotos(options: { uri: string }): Promise<void>;
  shareOutput(options: { uri: string }): Promise<void>;
  cancelExport(): Promise<void>;
  addListener(
    eventName: "exportProgress",
    listenerFunc: (progress: Phase0ExportProgress) => void,
  ): Promise<PluginListenerHandle>;
}

export const filmtoneMedia = registerPlugin<FilmtoneMediaPlugin>(
  "FilmtoneMedia",
  { web: () => import("./filmtoneMedia.web").then((mod) => new mod.FilmtoneMediaWeb()) },
);

runExport — detached Task plus a progress stream

runExport decodes a Phase0ExportRequestDTO, builds a session via FilmtoneMediaRuntime.makeExportSession, then launches runtime.runExport inside a Task.detached(priority: .userInitiated). Progress comes back through a closure and goes to TS as notifyListeners("exportProgress", ...). Concurrent exports are rejected with FilmtoneMediaError.exportBusy if currentExportTask is non-nil — there's no silent fallback.

@objc func runExport(_ call: CAPPluginCall) {
    guard currentExportTask == nil else {
        reject(call, with: FilmtoneMediaError.exportBusy)
        return
    }
    // ...
    currentExportTask = Task.detached(priority: .userInitiated) { [weak self] in
        guard let self else { return }
        do {
            let exportResult = try await runtime.runExport(
                request: request,
                sourceURL: sourceURL,
                session: exportSession,
                collector: benchmarkCollector
            ) { progress in
                let payload: [String: Any] = [
                    "stage": progress.stage.rawValue,
                    "progress": progress.progress,
                    "currentFrame": progress.currentFrame as Any,
                    "totalFrames": progress.totalFrames as Any,
                ]
                DispatchQueue.main.async {
                    self.notifyListeners("exportProgress", data: payload)
                }
            }
            // resolve on main actor...
        } catch { /* reject + benchmark */ }
    }
}

cancelExport and Live Activity share one stop point

cancelExport calls ExportCancelController.shared.cancel(reason: .userViaUI) and idempotently nudges currentExportSession?.cancel() and task?.cancel(). The Live Activity side (Lock Screen and Dynamic Island) routes through CancelExportIntent, which calls the same controller. UI, Lock Screen, and Dynamic Island all funnel into one cancel point with a unified reason vocabulary that ends up in the benchmark record.

Memory warning observer (not exposed to TS)

The plugin subscribes to UIApplication.didReceiveMemoryWarningNotification in load() and increments a counter from @objc private func handleMemoryWarning(). It's deliberately not registered as a pluginMethod (TS shouldn't call it). The current value lands in Phase0ExportBenchmarkRecordDTO.memoryWarningCount for post-export analysis.

override func load() {
    super.load()
    // ... cache / mezzanine / runtime init ...

    NotificationCenter.default.addObserver(
        self,
        selector: #selector(handleMemoryWarning),
        name: UIApplication.didReceiveMemoryWarningNotification,
        object: nil
    )
}

deinit {
    NotificationCenter.default.removeObserver(self)
}

@objc private func handleMemoryWarning() {
    memoryWarningCount += 1
}

Double-save guard for saveToPhotos

saveToPhotos keeps inFlightPhotoSaveURI and lastSavedPhotoURI behind an NSLock, rejecting concurrent saves of the same URI and any second save with FilmtoneMediaError.saveFailed. The app's invariant — never write the same export to Photos twice — is enforced physically at the plugin entry.