### Basic PhotoScript Usage Example

Source: https://github.com/rhettbull/photoscript/blob/master/docs/index.md

Demonstrates fundamental operations in PhotoScript, including initializing the library, activating Photos, retrieving photos from an album, modifying keywords, creating a new album, and importing photos. This example requires an existing album named 'Album1' and a file at '/Users/rhet/Downloads/test.jpeg'.

```python
""" Simple example showing use of photoscript """

import photoscript

photoslib = photoscript.PhotosLibrary()

photoslib.activate()
print(f"Running Photos version: {photoslib.version}")

album = photoslib.album("Album1")
photos = album.photos()

for photo in photos:
    photo.keywords = ["travel", "vacation"]
    print(f"{photo.title}, {photo.description}, {photo.keywords}")

new_album = photoslib.create_album("New Album")
photoslib.import_photos(["/Users/rhet/Downloads/test.jpeg"], album=new_album)

photoslib.quit()

```

--------------------------------

### Start Slideshow

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Starts an ad-hoc slideshow from a list of media items, an album, or a folder.

```APIDOC
## POST /slideshow/start

### Description
Starts an ad-hoc slideshow.

### Method
POST

### Endpoint
/slideshow/start

### Parameters
#### Request Body
- **list_of_media_item** (array[object] or string) - Required - The media items to show, can be a list of media items, an album identifier, or a folder identifier.
```

--------------------------------

### Interact with Photos Library using Python

Source: https://github.com/rhettbull/photoscript/blob/master/README.md

This example demonstrates how to initialize the Photos library, access albums, modify photo metadata like keywords, and import new images into a specific album.

```python
""" Simple example showing use of photoscript """

import photoscript

photoslib = photoscript.PhotosLibrary()

photoslib.activate()
print(f"Running Photos version: {photoslib.version}")

album = photoslib.album("Album1")
photos = album.photos()

for photo in photos:
    photo.keywords = ["travel", "vacation"]
    print(f"{photo.title}, {photo.description}, {photo.keywords}")

new_album = photoslib.create_album("New Album")
photoslib.import_photos(["/Users/rhet/Downloads/test.jpeg"], album=new_album)

photoslib.quit()
```

--------------------------------

### Manage Photos Library and Albums with PhotoScript

Source: https://github.com/rhettbull/photoscript/blob/master/docsrc/source/index.md

This example demonstrates how to initialize the Photos library, access specific albums, update photo keywords, and import new media files into a library. It highlights the basic workflow of using the library to interact with the Photos application.

```python
import photoscript

# Initialize the library
photoslib = photoscript.PhotosLibrary()
photoslib.activate()
print(f"Running Photos version: {photoslib.version}")

# Access an album and update photo metadata
album = photoslib.album("Album1")
photos = album.photos()
for photo in photos:
    photo.keywords = ["travel", "vacation"]
    print(f"{photo.title}, {photo.description}, {photo.keywords}")

# Create a new album and import photos
new_album = photoslib.create_album("New Album")
photoslib.import_photos(["/Users/rhet/Downloads/test.jpeg"], album=new_album)

# Close the application
photoslib.quit()
```

--------------------------------

### Install PhotoScript using pip

Source: https://context7.com/rhettbull/photoscript/llms.txt

Installs the PhotoScript library using the pip package installer. This is the primary method for adding the library to your Python environment.

```bash
pip install photoscript
```

--------------------------------

### Access Albums using album() and albums()

Source: https://context7.com/rhettbull/photoscript/llms.txt

Explains how to access albums within the Photos library. It shows retrieving albums by name or UUID, and how to get a list of all top-level albums.

```python
import photoscript

photoslib = photoscript.PhotosLibrary()

# Get album by name
album = photoslib.album("My Album")
if album:
    print(f"Found album: {album.name} with {len(album)} photos")
else:
    print("Album not found")

# Get album by UUID
album = photoslib.album(uuid="ABC123-DEF456-GHI789")

# Get only top-level albums (not in folders)
top_album = photoslib.album("Top Level Album", top_level=True)
```

--------------------------------

### Control Slideshow Playback in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Commands to start, stop, navigate, pause, and resume slideshows in the Photos application.

```applescript
start slideshow using list of media item : The media items to show.
stop slideshow
next slide
previous slide
pause slideshow
resume slideshow
```

--------------------------------

### Initialize and Control Photos App with PhotosLibrary

Source: https://context7.com/rhettbull/photoscript/llms.txt

Demonstrates how to initialize the PhotosLibrary, which acts as the main interface to the Photos application. It shows how to control the app (activate, hide, quit), retrieve library information, and access selected photos and the Favorites album.

```python
import photoscript

# Initialize PhotosLibrary (launches Photos if not running)
photoslib = photoscript.PhotosLibrary()

# Control the Photos application
photoslib.activate()  # Bring Photos to foreground
print(f"Photos version: {photoslib.version}")
print(f"Library name: {photoslib.name}")
print(f"Is running: {photoslib.running}")
print(f"Is frontmost: {photoslib.frontmost}")
print(f"Total photos in library: {len(photoslib)}")

# Hide the Photos window
photoslib.hide()
print(f"Is hidden: {photoslib.hidden}")

# Open a different Photos library
photoslib.open("/Users/username/Pictures/MyLibrary.photoslibrary", delay=10)

# Get currently selected photos
selected_photos = photoslib.selection
for photo in selected_photos:
    print(f"Selected: {photo.filename}")

# Access the Favorites album
favorites = photoslib.favorites
print(f"Favorites contains {len(favorites)} photos")

# Quit Photos when done
photoslib.quit()
```

--------------------------------

### Create Object

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Creates a new album or folder.

```APIDOC
## POST /make

### Description
Creates a new object, either an album or a folder.

### Method
POST

### Endpoint
/make

### Parameters
#### Query Parameters
- **named** (string) - Optional - The name of the new object.
- **at_folder** (string) - Optional - The parent folder for the new object.

#### Request Body
- **new_type** (string) - Required - The class of the new object, allowed values are 'album' or 'folder'.

### Response
#### Success Response (200)
- **album or folder** (object) - The newly created album or folder.
```

--------------------------------

### Create Folder Hierarchies and Nested Albums

Source: https://context7.com/rhettbull/photoscript/llms.txt

Demonstrates creating complex folder structures similar to os.makedirs and initializing albums within those paths.

```python
new_folder = photoslib.create_folder("Projects")
folder_path = ["Travel", "2024", "Summer", "Beach Trips"]
deepest_folder = photoslib.make_folders(folder_path)
album = photoslib.make_album_folders("Hawaii Photos", ["Travel", "2024", "Summer"])
```

--------------------------------

### Create and Delete Albums

Source: https://context7.com/rhettbull/photoscript/llms.txt

Shows how to create new albums at the root level or within specific folders, and how to delete existing albums without removing the underlying photos.

```python
new_album = photoslib.create_album("New Album 2024")

folder = photoslib.folder("Travel")
if folder:
    nested_album = photoslib.create_album("Paris Trip", folder=folder)

album_to_delete = photoslib.album("Old Album")
if album_to_delete:
    photoslib.delete_album(album_to_delete)
```

--------------------------------

### List and Retrieve Albums using PhotosLibrary

Source: https://context7.com/rhettbull/photoscript/llms.txt

Demonstrates how to list album names and retrieve Album objects from the library, with options to filter by top-level status.

```python
all_album_names = photoslib.album_names()
print(f"Albums: {all_album_names}")

top_level_names = photoslib.album_names(top_level=True)

all_albums = photoslib.albums()
for album in all_albums:
    print(f"{album.name}: {len(album)} photos, path: {album.path_str()}")

top_level_albums = photoslib.albums(top_level=True)
```

--------------------------------

### Import Photos into Library using import_photos()

Source: https://context7.com/rhettbull/photoscript/llms.txt

Demonstrates importing photos from the filesystem into the Photos library. It covers importing into the main library and directly into a specified album, with an option to skip duplicate checks.

```python
import photoscript
from pathlib import Path

photoslib = photoscript.PhotosLibrary()

# Import photos into the library (no specific album)
photo_paths = [
    "/Users/username/Downloads/photo1.jpg",
    "/Users/username/Downloads/photo2.png",
    Path("/Users/username/Downloads/photo3.heic")  # pathlib.Path works too
]
imported = photoslib.import_photos(photo_paths)
print(f"Imported {len(imported)} photos")
for photo in imported:
    print(f"  - {photo.filename} (UUID: {photo.uuid})")

# Import directly into an album
album = photoslib.album("Vacation 2024")
if album is None:
    album = photoslib.create_album("Vacation 2024")

imported = photoslib.import_photos(
    ["/Users/username/Downloads/beach.jpg"],
    album=album,
    skip_duplicate_check=True  # Skip Photos' duplicate dialog
)
print(f"Added {len(imported)} photos to {album.name}")
```

--------------------------------

### Add Media to Album

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Adds a list of media items to a specified album.

```APIDOC
## POST /add

### Description
Adds media items to an album.

### Method
POST

### Endpoint
/add

### Parameters
#### Request Body
- **list_of_media_item** (array[object]) - Required - The list of media items to add.
- **to_album** (string) - Required - The album to add to.
```

--------------------------------

### Create New Album or Folder in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Creates a new album or folder within the Photos application. Allows specifying the name and parent folder.

```applescript
make
new type : The class of the new object, allowed values are album or folder
[ named text] : The name of the new object.
[ at folder] : The parent folder for the new object.
→ album or folder : The new object.
```

--------------------------------

### Manage Album Contents and Properties

Source: https://context7.com/rhettbull/photoscript/llms.txt

Covers accessing album metadata, renaming albums, retrieving photos, adding existing photos, and importing new files into an album.

```python
album = photoslib.album("Vacation")
album.name = "Summer Vacation 2024"
photos = album.photos()
photos_to_add = list(photoslib.photos(search="beach"))
album.add(photos_to_add)
imported = album.import_photos(["/path/to/photo1.jpg"], skip_duplicate_check=True)
```

--------------------------------

### Export Album Photos

Source: https://context7.com/rhettbull/photoscript/llms.txt

Shows how to export photos from an album to a local directory, supporting options for original vs. edited versions, overwriting, and Finder integration.

```python
exported_paths = album.export(
    export_path="/Users/username/Desktop/exported",
    original=False,
    overwrite=False,
    timeout=120,
    reveal_in_finder=True
)

original_paths = album.export(
    export_path="/Users/username/Desktop/originals",
    original=True,
    overwrite=True
)
```

--------------------------------

### Next Slide

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Skips to the next slide in the currently playing slideshow.

```APIDOC
## POST /slideshow/next

### Description
Skips to the next slide in the currently playing slideshow.

### Method
POST

### Endpoint
/slideshow/next
```

--------------------------------

### Access and Manage Folders

Source: https://context7.com/rhettbull/photoscript/llms.txt

Provides methods to retrieve folders by name, path, or UUID, and list folder hierarchies within the library.

```python
folder = photoslib.folder(name="Travel")
nested_folder = photoslib.folder(path=["Travel", "2024", "Europe"])
all_folder_names = photoslib.folder_names()
top_folders = photoslib.folders(top_level=True)
```

--------------------------------

### Access and Modify Photo Metadata

Source: https://context7.com/rhettbull/photoscript/llms.txt

Explains how to read and write photo metadata such as titles, descriptions, keywords, favorites, dates, and location coordinates.

```python
photo.title = "Beach Sunset"
photo.description = "Beautiful sunset at the beach"
photo.keywords = ["sunset", "beach", "vacation", "2024"]
photo.favorite = True
photo.date = datetime(2024, 7, 15, 18, 30, 0)
photo.location = (37.7749, -122.4194)

photo.title = None
photo.keywords = []
photo.location = None
```

--------------------------------

### Retrieve Photos from Library using photos()

Source: https://context7.com/rhettbull/photoscript/llms.txt

Shows how to use the `photos()` method to retrieve Photo objects from the library. It supports iterating through all photos, searching by text, retrieving by UUID, and fetching photos within a specified range.

```python
import photoscript

photoslib = photoscript.PhotosLibrary()

# Iterate through all photos (generator - memory efficient)
for photo in photoslib.photos():
    print(f"{photo.filename}: {photo.title}")
    if photo.filename == "target.jpg":
        break  # Stop early if needed

# Search photos by text (searches titles, descriptions, keywords)
vacation_photos = list(photoslib.photos(search="vacation"))
print(f"Found {len(vacation_photos)} vacation photos")

# Get specific photos by UUID
photo_uuids = ["ABC123-DEF456", "GHI789-JKL012"]
specific_photos = list(photoslib.photos(uuid=photo_uuids))

# Get photos by range (useful for batching large libraries)
# range_=[10] returns first 10 photos
# range_=[5, 15] returns photos 5-14 (0-indexed start, exclusive end)
first_batch = list(photoslib.photos(range_=[10]))
second_batch = list(photoslib.photos(range_=[10, 20]))
print(f"First 10 photos: {[p.filename for p in first_batch]}")
```

--------------------------------

### Previous Slide

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Skips to the previous slide in the currently playing slideshow.

```APIDOC
## POST /slideshow/previous

### Description
Skips to the previous slide in the currently playing slideshow.

### Method
POST

### Endpoint
/slideshow/previous
```

--------------------------------

### Import Media

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Imports a list of files into the Photos library, optionally into a specific album and with duplicate checking disabled.

```APIDOC
## POST /import

### Description
Imports a list of files into the Photos library.

### Method
POST

### Endpoint
/import

### Parameters
#### Query Parameters
- **into_album** (string) - Optional - The album to import into.
- **skip_check_duplicates** (boolean) - Optional - Skip duplicate checking and import everything, defaults to false.

#### Request Body
- **list_of_file** (array[string]) - Required - The list of files to import.

### Response
#### Success Response (200)
- **list_of_media_item** (array[object]) - The imported media items in an array
```

--------------------------------

### Resume Slideshow

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Resumes the currently playing slideshow.

```APIDOC
## POST /slideshow/resume

### Description
Resumes the currently playing slideshow.

### Method
POST

### Endpoint
/slideshow/resume
```

--------------------------------

### Media Item Properties in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Details the properties of a 'media item' object, such as keywords, name, description, date, dimensions, and GPS location. It also lists responsibilities like duplication and spotlight.

```applescript
ELEMENTS
contained by application, albums.
PROPERTIES
keywords (list of text) : A list of keywords to associate with a media item
name (text) : The name (title) of the media item.
description (text) : A description of the media item.
favorite (boolean) : Whether the media item has been favorited.
date (date) : The date of the media item
id (text, r/o) : The unique ID of the media item
height (integer, r/o) : The height of the media item in pixels.
width (integer, r/o) : The width of the media item in pixels.
filename (text, r/o) : The name of the file on disk.
altitude (real, r/o) : The GPS altitude in meters.
size (integer) : The selected media item file size.
location (list of real or list of missing value) : The GPS latitude and longitude, in an
ordered list of 2 numbers or missing values. Latitude in range -90.0 to 90.0,
longitude in range -180.0 to 180.0.
RESPONDS TO
duplicate, spotlight.
```

--------------------------------

### Search Media Items in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Searches for media items within the Photos library based on a provided text string. Returns references to found items.

```applescript
search for text : The text to search for
→ list of media item : reference(s) to found media item(s)
```

--------------------------------

### Spotlight Media

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Shows an image in the application, used to display spotlight search results.

```APIDOC
## POST /spotlight

### Description
Shows an image in the application, used to display spotlight search results.

### Method
POST

### Endpoint
/spotlight

### Parameters
#### Request Body
- **path** (string) - Required - The full path to the image.
```

--------------------------------

### Import Media Files into Photos Library

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Imports a list of files into the Photos library, optionally into a specific album and with duplicate checking.

```applescript
import list of file : The list of files to copy.
[ into album] : The album to import into.
[ skip check duplicates boolean] : Skip duplicate checking and import everything,
defaults to false.
→ list of media item : The imported media items in an array
```

--------------------------------

### Search Media

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Searches for media items matching a given search string.

```APIDOC
## GET /search

### Description
Searches for items matching the search string. Identical to entering search text in the Search field in Photos.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to search for.

### Response
#### Success Response (200)
- **list_of_media_item** (array[object]) - Reference(s) to found media item(s).
```

--------------------------------

### Duplicate Photos and Spotlight with Photo.duplicate() and spotlight()

Source: https://context7.com/rhettbull/photoscript/llms.txt

Demonstrates duplicating photos and revealing them in the Photos app interface. The duplicate photo can then be modified, including its title and keywords. The spotlight() method brings a specific photo into view within the Photos application.

```python
import photoscript

photoslib = photoscript.PhotosLibrary()
album = photoslib.album("Favorites")
photos = album.photos()

# Duplicate a photo
original = photos[0]
duplicate = original.duplicate()
print(f"Created duplicate: {duplicate.uuid}")

# Modify the duplicate
duplicate.title = f"Copy of {original.title}"
duplicate.keywords = original.keywords + ["duplicate"]

# Spotlight (reveal) a photo in Photos
photo = photos[0]
photo.spotlight()  # Photos will scroll to and highlight this photo
```

--------------------------------

### Manage Album Content and Organization

Source: https://context7.com/rhettbull/photoscript/llms.txt

Demonstrates how to remove photos from an album by keyword or ID, and how to move albums between folders or to the top level of the library.

```python
photos = album.photos()
photos_to_remove = [p for p in photos if "delete_me" in p.keywords]
if photos_to_remove:
    album = album.remove(photos_to_remove)

photo_ids_to_remove = ["ABC123/L0/001", "DEF456/L0/001"]
album = album.remove_by_id(photo_ids_to_remove)

destination_folder = photoslib.folder("Archive")
if destination_folder:
    album = album.move(destination_folder)

album = album.move(None)
```

--------------------------------

### Manage Folder Hierarchies

Source: https://context7.com/rhettbull/photoscript/llms.txt

Covers the Folder class functionality, including creating, renaming, navigating parent/child relationships, and accessing nested albums.

```python
folder = photoslib.folder("Travel") or photoslib.create_folder("Travel")
folder.name = "Travel Photos"
parent = folder.parent
path_folders = folder.path()

for album in folder.albums:
    print(f"Album: {album.name}")

new_album = folder.create_album("New Destination")
new_subfolder = folder.create_folder("2025")
folder.spotlight()
```

--------------------------------

### Spotlight Media Item in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Displays a media item at a given path in the Photos application, often used for spotlight search results.

```applescript
spotlight text, media item, or container : The full path to the image
```

--------------------------------

### Duplicate Media Item

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Duplicates a given media item.

```APIDOC
## POST /duplicate

### Description
Duplicates a media item.

### Method
POST

### Endpoint
/duplicate

### Parameters
#### Request Body
- **media_item** (object) - Required - The media item to duplicate.

### Response
#### Success Response (200)
- **media_item** (object) - The duplicated media item.
```

--------------------------------

### Add Media Items to Album in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Adds a list of media items to a specified album within the Photos library.

```applescript
add list of media item : The list of media items to add.
to album : The album to add to.
```

--------------------------------

### Export Media

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Exports a list of media items to a specified file location, with an option to use original files.

```APIDOC
## POST /export

### Description
Exports media items to the specified location as files.

### Method
POST

### Endpoint
/export

### Parameters
#### Query Parameters
- **using_originals** (boolean) - Optional - Export the original files if true, otherwise export rendered jpgs. defaults to false.

#### Request Body
- **list_of_media_item** (array[object]) - Required - The list of media items to export.
- **to_file** (string) - Required - The destination of the export.
```

--------------------------------

### Duplicate Media Item in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Creates a duplicate of a given media item within the Photos library.

```applescript
duplicate media item : The media item to duplicate
→ media item : The duplicated media item
```

--------------------------------

### Container Object Properties in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Defines the properties for 'container' objects, which are base classes for collections like albums and folders. Includes ID, name, and parent properties.

```applescript
ELEMENTS
contained by application, folders.
PROPERTIES
id (text, r/o) : The unique ID of this container.
name (text) : The name of this container.
parent (folder, r/o) : This container's parent folder, if any.
RESPONDS TO spotlight.
```

--------------------------------

### Photos Application Properties

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Describes the properties of the top-level Photos application object, including its elements and read-only properties like selection and favorites album.

```applescript
ELEMENTS
contains containers, albums, folders, media items.
PROPERTIES
selection (list of media item, r/o) : The currently selected media items in the
application
favorites album (album, r/o) : Favorited media items album.
slideshow running (boolean, r/o) : Returns true if a slideshow is currently running.
recently deleted album (album, r/o) : The set of recently deleted media items
```

--------------------------------

### Export Media Items from Photos Library

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Exports a list of media items to a specified file destination. Supports exporting original files or rendered JPGs.

```applescript
export list of media item : The list of media items to export.
to file : The destination of the export.
[ using originals boolean] : Export the original files if true, otherwise export
rendered jpgs. defaults to false.
```

--------------------------------

### Error Handling in PhotoScript

Source: https://context7.com/rhettbull/photoscript/llms.txt

Illustrates how to handle various exceptions raised by PhotoScript, including invalid UUIDs for albums and photos, AppleScript errors during operations like album creation, export errors due to invalid paths, and range errors when specifying photo selections.

```python
import photoscript
from photoscript.exceptions import AppleScriptError

photoslib = photoscript.PhotosLibrary()

# Handle invalid album/photo UUIDs
try:
    album = photoscript.Album("invalid-uuid")
except ValueError as e:
    print(f"Invalid album: {e}")

try:
    photo = photoscript.Photo("invalid-uuid")
except ValueError as e:
    print(f"Invalid photo: {e}")

# Handle AppleScript errors
try:
    album = photoslib.create_album("")  # Empty name may fail
except AppleScriptError as e:
    print(f"AppleScript error: {e}")

# Handle export errors
try:
    photo = list(photoslib.photos(range_=[1]))[0]
    photo.export("/nonexistent/path")
except ValueError as e:
    print(f"Export error: {e}")  # "export_path must be a directory"

# Handle range errors
try:
    photos = list(photoslib.photos(range_=[100, 50]))  # Invalid range
except ValueError as e:
    print(f"Range error: {e}")  # "start range must be <= stop range"
```

--------------------------------

### Delete Album or Folder

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Deletes a specified album or folder.

```APIDOC
## DELETE /delete

### Description
Deletes an album or folder.

### Method
DELETE

### Endpoint
/delete

### Parameters
#### Request Body
- **album_or_folder** (string) - Required - The identifier of the album or folder to delete.
```

--------------------------------

### Export Individual Photos with Photo.export()

Source: https://context7.com/rhettbull/photoscript/llms.txt

Exports a photo to the filesystem, supporting both edited and original versions. Options include specifying the export path, whether to export the original, overwriting existing files, setting a timeout, and revealing the exported file in Finder. The function can return multiple files for Live Photos and burst images.

```python
import photoscript

photoslib = photoscript.PhotosLibrary()
photos = list(photoslib.photos(search="sunset"))

for photo in photos:
    # Export edited version as JPEG
    exported = photo.export(
        export_path="/Users/username/Desktop/exports",
        original=False,    # Export edited version
        overwrite=False,   # Don't overwrite existing files
        timeout=120,       # Timeout in seconds
        reveal_in_finder=False
    )
    print(f"Exported to: {exported}")

    # Export original (includes Live Photo .mov and burst images)
    original_exports = photo.export(
        export_path="/Users/username/Desktop/originals",
        original=True,
        overwrite=True
    )
    # May return multiple files for Live Photos and bursts
    for path in original_exports:
        print(f"Original file: {path}")
```

--------------------------------

### Album Object Definition in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Describes an 'album' object, which inherits from 'container' and specifically holds media items. It can be contained by the application.

```applescript
ELEMENTS
contains media items; contained by application.
```

--------------------------------

### Pause Slideshow

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Pauses the currently playing slideshow.

```APIDOC
## POST /slideshow/pause

### Description
Pauses the currently playing slideshow.

### Method
POST

### Endpoint
/slideshow/pause
```

--------------------------------

### Folder Object Definition in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Defines a 'folder' object, which also inherits from 'container'. Folders can contain other containers (albums and folders) but not media items directly.

```applescript
ELEMENTS
contains containers, albums, folders; contained by application.
```

--------------------------------

### Stop Slideshow

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Ends the currently playing slideshow.

```APIDOC
## POST /slideshow/stop

### Description
Ends the currently playing slideshow.

### Method
POST

### Endpoint
/slideshow/stop
```

--------------------------------

### Delete Album or Folder in Photos

Source: https://github.com/rhettbull/photoscript/wiki/Photos-5-AppleScript-Dictionary

Deletes a specified album or folder from the Photos library.

```applescript
delete album or folder : The album or folder to delete.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.