Adding your first source

Add Apple Photos or a folder to start browsing photographs in Frames.

The welcome photograph introduces the app before you connect a source. The photograph is bundled and available offline. The welcome screen scrolls in a short window or with larger text so the source actions remain reachable.

1. Click Photos Library or Choose Folder… on the first-run screen. You can also drop a folder onto the window.
2. Grant access when macOS requests it. The folder picker accepts several folders at once.
3. Wait for the first photograph to appear. Cataloguing continues while you browse.

Adding a source does not copy, move or rename its files. Frames stores ratings, verdicts and edits in its catalogue. The first-run screen remains until a source contains a photograph. It shows the source name and progress while reading, and reports an empty source if no photographs were found, including after a failed scan. Progress shows a percentage only when the total is known.

The grid appears when a source contains a photograph, even if an active filter hides it. For example, RAW ONLY can leave a JPEG library looking empty.

Photos access. Frames requests permission when Photos Library is chosen. On iPhone and iPad, it also requests permission when Library Sync brings the Photos source from another device, as soon as Frames is active. If access is denied or restricted, change it in System Settings › Privacy & Security › Photos. The screen explains this and keeps the folder option available. Limited access works with the photographs selected in the permission grant.

Only one Photos library can be added. On iPhone and iPad, choose Photos Library… from the Library’s ＋ menu, even when another source is already present. If Photos access was denied, that action opens Settings. On Mac, add sources from ＋ in the SOURCES header.

Refreshing a source. Click ⟳ beside a source to sync it. Hold ⌥ while clicking to rescan from scratch. The source menu has the same commands:

• Photos: Sync Now and Rescan.
• Folders: Scan Now and Rescan File Contents.
• Remove Missing Photographs…, when missing photographs exist.
• Show in Finder, when a directory is available, and Remove Source….

Source issues on Mac. Right-click a source and choose Review Source Issues… to inspect missing originals, failed previews and scan failures. The compact table sorts by file, problem or location. Filter by filename, problem or path; select a row to see its full path and recovery actions, including files that never reached the catalogue. Copy Path copies the location; Show Location in Finder reveals the file or its nearest available folder. Retry Folder rereads that folder’s files and renews failed preview attempts; Retry Source rereads the folder source, or refreshes a Photos source. Retry is unavailable while a scan runs or the folder needs reconnecting or access restored. Source Settings… opens those recovery options. Opening the view does not scan or download originals. Scan issues are retained for the current session; missing originals and failed previews are read from the catalogue. Ratings and edits remain in Frames.

Source issues on iPhone and iPad. Touch and hold a source in the Library and choose Review Source Issues…. iPad shows File, Problem and Location columns; iPhone and accessibility text sizes use compact rows with the same information. Filter by file, problem or path and use Sort Issues to choose a column or reverse the order. Locations within a connected folder source are shortened to the folder inside that source; file details retain the exact recorded path. The sort menu marks the current column and direction. Tap a row for its complete path, Copy Path and Retry Folder. Returning to the table keeps the filter and order. Retry Source checks the whole source. Reconnect a disconnected drive, or use Choose Folder… in Files to restore folder access from the table or a file’s details. Copy and retry controls appear above the full path. This view uses the same recorded issues and retry rules as Mac; opening it does not read or download originals.

With automatic Photos sync enabled and full Photos access, the next sync rechecks the whole library when the last complete scan is more than a day old. This recovers photographs or departures missed by change history without downloading originals. Missing photographs with saved work remain in Frames; empty departed entries are removed from the catalogue.

Folder scans skip file contents when size, timestamps and filesystem identity are unchanged. Rescan File Contents reads every file again. The first scan after upgrading builds this cache; renaming a mounted volume preserves it. On exFAT and FAT32, use Rescan File Contents to detect edits that preserve file size and date.

Local drives report filesystem changes automatically. SMB and other network sources compare stored file and directory metadata on launch and mount, then scan changed directories. Use Scan Now after adding files to a share that is already mounted; network shares are not polled. While a folder scan runs, the source row has a pause button. Resume continues the same scan after the current filesystem operation finishes.

Source status. The second line shows current activity or an access error. When idle, it shows the photograph count, last sync and missing or unreadable counts. Before the first manual sync, it also shows outstanding photographs and estimated download size.

Double-click a source in the sidebar to open its panel. It lists photograph, album and folder counts; pending previews and their size; missing and unreadable photographs; last sync; automatic-sync permission; date added; and the folder path where applicable.

A disconnected source remains browsable through its proxies. The panel distinguishes an unmounted volume from denied or revoked access. Counts remain visible in either case.

Press ? to see shortcuts. Once photographs appear, small tips point at Choose, Keep and Develop in turn. Open the companion from Help › Getting Started.

See Getting started.