Tauri Plugin iOS Photos

查看中文

A Tauri plugin for accessing and managing iOS Photos albums and assets using the native Photos framework.

This plugin allows Tauri applications to request photo permissions, read albums, access photos, and perform basic album/photo management on iOS devices.

⚠️ iOS only. This plugin relies on Apple Photos APIs and is not available on other platforms.

---

Features

• Request and check photo library authorization
• List user photo albums
• Access photos from albums
• Filter albums
• Check album permission
• Create and remove albums
• Create, access, and delete photos
• Create, access, and delete videos

---

Requirements

• Tauri 2.x (or compatible version)
• Xcode with iOS SDK
• Proper Photo Library permissions configured in Info.plist

---

iOS Permissions

This plugin requires access to the user’s photo library.

Make sure the following keys are added to your iOS Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>Allow access to your photo library</string>

<key>NSPhotoLibraryAddUsageDescription</key>
<string>Allow saving photos to your photo library</string>

---

Installation

pnpm add @gbyte/tauri-plugin-ios-photos
# or
npm install @gbyte/tauri-plugin-ios-photos
# or
yarn add @gbyte/tauri-plugin-ios-photos

Add the plugin to your Tauri project's Cargo.toml:

[dependencies]
tauri-plugin-ios-photos = "0.3"

Or use cargo add tauri-plugin-ios-photos.

Configure the plugin permissions in your capabilities/default.json:

{
  "permissions": ["ios-photos:default"]
}

Register the plugin in your Tauri app:

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_ios_photos::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

---

Usage (Conceptual Example)

import {
  requestPhotosAuth,
  PhotosAuthorizationStatus,
  requestAlbums,
  PHAssetCollectionType,
  PHAssetCollectionSubtype
} from '@gbyte/tauri-plugin-ios-photos'

let photoAuth = ''
let albums = []

requestPhotosAuth()
  .then((status) => {
    switch (status) {
      case PhotosAuthorizationStatus.authorized:
        photoAuth = 'authorized'
        break
      case PhotosAuthorizationStatus.denied:
        photoAuth = 'denied'
        break
      case PhotosAuthorizationStatus.limited:
        photoAuth = 'limited'
        break
      case PhotosAuthorizationStatus.restricted:
        photoAuth = 'restricted'
        break
      case PhotosAuthorizationStatus.notDetermined:
        photoAuth = 'notDetermined'
        break
    }
  })
  .then(() => {
    requestAlbums({
      with: PHAssetCollectionType.smartAlbum,
      subtype: PHAssetCollectionSubtype.albumRegular
    }).then((value) => {
      albums = value
    })
  })

---

APIs

Methods

requestPhotosAuth(): Promise<PhotosAuthorizationStatus | null>

Request photo library authorization.

getPhotosAuthStatus(): Promise<PhotosAuthorizationStatus | null>

Get the current photo library authorization status.

requestAlbums(payload: RequestAlbumRequest): Promise<AlbumItem[]>

Request user device albums.

requestAlbumMedias(payload: RequestAlbumMediasRequest): Promise<MediaItem[]>

Request user medias by album.

checkAlbumCanOperation(payload: CheckAlbumCanOperationRequest): Promise<boolean>

Check album support operation status.

createAlbum(payload: CreateAlbumRequest): Promise<Identifier | null>

Create album.

createPhotos(payload: CreateMediaRequest): Promise<Identifiers | null>

Create photo to album.

createVideos(payload: CreateMediaRequest): Promise<Identifiers | null>

Create videos to album.

deleteAlbum(payload: DeleteAlbumRequest): Promise<boolean>

Delete album, is forever.

deleteAlbumMedias(payload: DeleteAlbumMediasRequest): Promise<boolean>

Delete medias from album, is forever.

removeAlbumMedias(payload: DeleteAlbumMediasRequest): Promise<boolean>

Remove medias from album, is not forever.

Type Definitions

PhotosAuthorizationStatus

/**
 * Information about your app’s authorization to access the user’s photo library.
 *
 * @see [PHAuthorizationStatus](https://developer.apple.com/documentation/photos/phauthorizationstatus)
 */
export declare const PhotosAuthorizationStatus: {
  readonly notDetermined: 0
  readonly restricted: 1
  readonly denied: 2
  readonly authorized: 3
  readonly limited: 4
}

PHCollectionEditOperation

/**
 * Values identifying possible actions that a collection can support.
 *
 * @see [PHCollectionEditOperation](https://developer.apple.com/documentation/photos/phcollectioneditoperation)
 */
export declare const PHCollectionEditOperation: {
  readonly deleteContent: 1
  readonly removeContent: 2
  readonly addContent: 3
  readonly createContent: 4
  readonly rearrangeContent: 5
  readonly delete: 6
  readonly rename: 7
}

PHAssetCollectionType

/**
 * Major distinctions between kinds of asset collections.
 *
 * @see [PHAssetCollectionType](https://developer.apple.com/documentation/photos/phassetcollectiontype)
 */
export declare const PHAssetCollectionType: {
  /**
   * An album in the Photos app.
   */
  readonly album: 1
  /**
   * A smart album whose contents update dynamically.
   */
  readonly smartAlbum: 2
}

PHAssetCollectionSubtype

/**
 * Minor distinctions between kinds of asset collections.
 *
 * @see [PHAssetCollectionSubtype](https://developer.apple.com/documentation/photos/phassetcollectionsubtype)
 */
export declare const PHAssetCollectionSubtype: {
  albumRegular: 2
  albumSyncedEvent: 3
  albumSyncedFaces: 4
  albumSyncedAlbum: 5
  albumImported: 6
  albumMyPhotoStream: 100
  albumCloudShared: 101
  smartAlbumGeneric: 200
  smartAlbumPanoramas: 201
  smartAlbumVideos: 202
  smartAlbumFavorites: 203
  smartAlbumTimelapses: 204
  smartAlbumAllHidden: 205
  smartAlbumRecentlyAdded: 206
  smartAlbumBursts: 207
  smartAlbumSlomoVideos: 208
  smartAlbumUserLibrary: 209
  smartAlbumSelfPortraits: 210
  smartAlbumScreenshots: 211
  smartAlbumDepthEffect: 212
  smartAlbumLivePhotos: 213
  smartAlbumAnimated: 214
  smartAlbumLongExposures: 215
  smartAlbumUnableToUpload: 216
  smartAlbumRAW: 217
  smartAlbumCinematic: 218
  smartAlbumSpatial: 219
  any: -1
}

AlbumItem

export type AlbumItem = {
  id: string
  name: string
}

MediaItem

export type MediaItem = {
  id: string
  mediaType: number
  createAt: number
  data?: string
}

RequestAlbumRequest

export type RequestAlbumRequest = {
  with: PHAssetCollectionType
  subtype: PHAssetCollectionSubtype
}

RequestAlbumMediasRequest

export type RequestAlbumMediasRequest = {
  id: string
  height: number
  width: number
  quality: number
}

CheckAlbumCanOperationRequest

export type CheckAlbumCanOperationRequest = {
  id: string
  operation: PHCollectionEditOperation
}

CreateAlbumRequest

export type CreateAlbumRequest = {
  title: string
}

CreateMediaRequest

export type CreateMediaRequest = {
  album: string
  files: string[]
}

Identifier

export type Identifier = string

Identifiers

export type Identifiers = Identifier[]

DeleteAlbumRequest

export type DeleteAlbumRequest = {
  identifiers: Identifiers
}

DeleteAlbumMediasRequest

export type DeleteAlbumMediasRequest = {
  album: string
  identifiers: Identifiers
}

PluginReturnValue

export type PluginReturnValue<T> = {
  value?: T
}

---

About Image Path Access

The image paths returned by this plugin are local file paths, typically pointing to internal iOS sandbox locations.

In Tauri (especially on iOS / WebView environments), these local paths cannot be accessed directly by the frontend (e.g. via file:// or raw filesystem paths). This is due to WebView security and sandbox restrictions.

Before using these images in the frontend, you must expose them through a Tauri custom protocol (URI scheme) so they can be accessed as normal URLs.

Recommended approach:

1. Register a custom URI scheme in Tauri (for example, temp://)

2. When the frontend requests temp://<local-path>:

• Tauri reads the corresponding local file

• Returns the binary data with the correct MIME type

1. The frontend can then use the URL normally (e.g. <img src="temp://..." />)

⚠️ Notes:

• This plugin does not automatically convert local paths into accessible URLs

• Implementing the custom protocol is the responsibility of the application

• For security reasons, it is recommended to restrict the accessible path scope

---

Authorization Status

Possible authorization states:

• notDetermined
• restricted
• denied
• authorized
• limited

The plugin exposes APIs to query and react to these states.

---

Todos / Roadmap

• Request access authorization
• Check authorization type
• List user device albums
• Get photos from album
• Filter album
• Check album permission
• Access photo
• Create album
• Create photo
• Remove album
• Remove photo
• Delete photo
• Documentation improvements
• Example project
• Error handling standardization

---

Notes

• All photo operations follow iOS privacy rules.
• Some actions may fail silently if permission is limited.
• Album and photo identifiers are system-generated.

---

License

MIT