---
title: steliyanh/kadr-photos
framework: Swift Package Catalog
role: article
path: packages/steliyanh/kadr-photos
---

# steliyanh/kadr-photos

**Photos library integration for [Kadr](https://github.com/SteliyanH/kadr) — resolve `PHAsset` videos and stills into kadr clip types, with iCloud download progress reporting.**

## Quick Start

```swift import Kadr import KadrPhotos import Photos

// Resolve a video PHAsset to a VideoClip let videoClip = try await PhotosClipResolver.video(asset: phAsset) { progress in     print("iCloud download: \(progress)") }

// Resolve a still-image PHAsset to an ImageClip let imageClip = try await PhotosClipResolver.image(asset: phAsset, duration: 3.0)

let video = Video {     videoClip     imageClip } ```

## Components

| API | Purpose | |---|---| | `PhotosClipResolver.video(asset:options:progress:)` | Resolve a video `PHAsset` to a `VideoClip` (downloads from iCloud if needed) | | `PhotosClipResolver.image(asset:duration:options:progress:)` | Resolve an image `PHAsset` to an `ImageClip` | | `PhotosClipResolver.livePhotoMotion(asset:progress:)` | Extract the paired-video half of a Live Photo as a `VideoClip` | | `PhotosClipResolver.livePhotoStill(asset:duration:options:progress:)` | Extract the still half of a Live Photo as an `ImageClip` (Live-Photo-guarded wrapper around `image()`) | | `PhotoPicker(selection:configuration:)` *(v0.3)* | SwiftUI wrapper around `PHPickerViewController` | | `PhotoPickerResult` *(v0.3)* | Wraps an `assetIdentifier`; `@MainActor resolveAsset()` returns the `PHAsset` | | `PhotosClipResolver.clip(from:imageDuration:options:progress:)` *(v0.3)* | Resolve a `PhotoPickerResult` to `any Clip` (dispatches on `mediaType`) | | `PhotosClipResolver.clips(from:imageDuration:options:progress:)` *(v0.3)* | Array convenience for batch resolution | | `PhotosClipResolver.metadata(of:)` *(v0.4)* | Synchronous PHAsset property snapshot — `PhotoAssetMetadata` | | `PhotoAssetMetadata` *(v0.4)* | creationDate / location / pixelSize / subtypes / etc. | | `PhotoAssetSubtypes` *(v0.4)* | OptionSet — `.livePhoto` / `.panorama` / `.hdr` / `.screenshot` / etc. | | `PhotosClipResolver.imageOverlay(asset:position:size:...)` *(v0.4)* | PHAsset → `Kadr.ImageOverlay` | | `PhotosClipResolver.stickerOverlay(asset:position:size:rotation:shadow:...)` *(v0.4)* | PHAsset → `Kadr.StickerOverlay` | | `PhotosClipResolver.slowMotion(asset:options:progress:)` *(v0.5)* | High-frame-rate-preserving slow-motion video export | | `PhotosClipResolver.assets(in:mediaType:)` + `smartAlbum(_:)` *(v0.5)* | Programmatic album asset listing | | `PhotosClipResolver.videoHDRMetadata(of:)` *(v0.6)* | Async HDR / Dolby Vision metadata read (`VideoHDRMetadata`) — detect-only, no conversion | | `PhotoPicker(configuration:iOS17AsyncResults:)` *(v0.6)* | iOS 17+ overload delivering picks as an `AsyncStream<PhotoPickerResult>` | | `PhotosClipResolver.depthMap(from:)` *(v0.6)* | Async depth `CVPixelBuffer?` for iPhone 12+ Live Photos (disparity / depth / matte aux) | | `PhotosClipError` | Typed errors for permissions, missing media, iCloud failures, non-Live-Photo asset |

## Roadmap

See [ROADMAP.md](ROADMAP.md). Shipped: video + image resolution (v0.1), Live Photo (v0.2), PhotosUI `PhotoPicker` (v0.3), metadata + overlay helpers (v0.4), slow-motion preservation + album asset listing (v0.5), HDR-aware resolution + iOS 17 picker async results + Live Photos depth extraction (v0.6), iOS 17 platform floor (v0.7.0), DocC catalogue + `.upToNextMinor` pinning (v0.7.1), `LocalizedError` conformance (v0.8.0), kadr 0.17 adoption (v0.9.0). Resolution surface is feature-complete; v1.0 tracks kadr v1.0.

## Installation

```swift .package(url: "https://github.com/SteliyanH/kadr-photos.git", .upToNextMinor(from: "0.11.0")), ```

Add `KadrPhotos` to your target's dependencies. `Kadr` is pulled in transitively — 0.9.x resolves `>=0.17.0, <0.18.0`.

> **Use `.upToNextMinor`, not `from:`.** `from:` means `.upToNextMajor`, and SwiftPM does not special-case `0.x` — so `from: "0.11.0"` would accept every future 0.x release including breaking ones. This package's own kadr dependency is pinned the same way, because kadr's minors do break: 0.15.0 raised the platform floor.

**Required entitlement:** `NSPhotoLibraryUsageDescription` in your app's Info.plist for read access to the user's photo library. Apps using `PHPhotoLibrary.requestAuthorization` to write to the library also need `NSPhotoLibraryAddUsageDescription`.

## Platform support

`Photos.framework` is available on iOS 16+, macOS 13+, and visionOS 1+. **tvOS is excluded** — Apple does not ship the Photos framework on tvOS.

## The kadr ecosystem

| Package | Purpose | |---|---| | [`kadr`](https://github.com/SteliyanH/kadr) | The engine. Declarative video composition and export. | | [`kadr-ui`](https://github.com/SteliyanH/kadr-ui) | SwiftUI components — preview, timeline, transport, inspector, keyframe editor. | | [`kadr-persistence`](https://github.com/SteliyanH/kadr-persistence) | Save a composition to a file and open it again. | | [`kadr-audio`](https://github.com/SteliyanH/kadr-audio) | Music library, voiceover recording, LUFS loudness. | | [`kadr-captions`](https://github.com/SteliyanH/kadr-captions) | SRT, VTT, iTT, ASS and SSA parsing and authoring. | | [`kadr-photos`](https://github.com/SteliyanH/kadr-photos) | Photos library integration. |

And a reference application: [**Kadr Studio**](https://github.com/SteliyanH/kadr-reels-studio), a short-form vertical video editor built on all six.

## License

Apache-2.0. See [LICENSE](LICENSE).

Contributions are accepted under the [Contributor License Agreement](CLA.md), which is signed once and covers all future contributions. It does not transfer ownership — you keep the copyright in your work.

## Package Metadata

Repository: steliyanh/kadr-photos

Default branch: main

README: README.md