Help

Add photo sources

Aardvark plays photos from folders you point it at — on your local disk, an external drive, or a mounted network share — and from albums in the Mac's Photos app.

Watch a folder or import once

In the web admin, open Source Folders and stay on the Photos tab. There are two ways to add a folder:

• Watch a folder… — the folder is rescanned automatically, so photos you add to it later show up on their own.
• Import once… — a one-time import of what's in the folder right now.

Either way, a folder browser opens that walks the disks of the computer running the server. Click into folders (or ⬆ up to go back), choose the folder you're in, and give it a name. Scan now rescans your folders immediately instead of waiting.

Importing copies your photos into the library (identical photos are only stored once, even if they're in several folders) and makes display-sized copies for the Apple TV. Your originals are never changed.

Supported photo formats: JPEG (.jpg/.jpeg), PNG, HEIC/HEIF, TIFF, WebP, GIF, and BMP. Live Photos are picked up automatically when a HEIC has a matching .mov next to it.

Sync a Photos album (Mac)

Add Photos album… keeps a source folder in sync with an album in the Photos app on the Mac running the server. You can pick your own albums (including ones inside Photos folders), Shared Albums, and smart albums like Favorites, Recently Added or All Photos.

• Permission: the first time, choose Allow access and approve the prompt on the Mac's screen. If you said no, turn Aardy on under System Settings → Privacy & Security → Photos.
• Stays in sync: new photos import on their own, and a photo you edit in Photos is imported again with your edits. A photo you remove from the album leaves the source folder but stays in packs that already use it. Use originals imports the unedited versions instead.
• iCloud: with "Optimize Mac Storage" on, the first sync downloads originals from iCloud, which takes a while for a big album.
• Shared Albums are stored by Apple at about 2048 pixels, below 4K, so they look softer on a large screen.
• Favorites in Photos get a Favorite tag in every pack that holds them, and it follows the heart in Photos.
• Packs built from albums show a Photos badge in the web admin and a small photo icon in the TV's pack list.
• People and Memories can't be synced, because Apple doesn't make them available to other apps. Your Photos library is only ever read, never changed.
• On a Mac shared with all users, an album belongs to the user whose Photos library holds it, and syncs only while that user's session is serving. Otherwise it shows Other user, and its photos keep playing.

Browse and hide photos

Each source folder can be viewed as a Grid of thumbnails or as a Metadata table. Hiding a photo here hides it everywhere — in every pack and on every Apple TV.

4K TVs and photo enhancement

Each Apple TV gets photos sized for its screen: 4K when it outputs 4K, 1080p otherwise. You can pin a TV to either under Apple TVs → Configure → Photo resolution.

Photos too small for a 4K screen are upscaled on the server with the Real-ESRGAN model, in the background, and the sharper version is sent to 4K TVs. Your originals are never changed. Switch it off under Settings → Photo enhancement, or for one pack in that pack's settings. Photos marked Enhanced have an Original / Enhanced switch in the zoom view, so you can compare.

Add a network drive / NAS / SMB share

The server can read photos straight off a NAS — but it can only see a share that's mounted on the computer running the server.

• macOS: in Finder, Go → Connect to Server, enter smb://nas.local/Photos, and mount it. It appears under /Volumes/Photos; browse to that path in the folder browser. Tip: add the share to Login Items so it re-mounts automatically — Aardy (running as you) will then see it after every reboot.
• Windows (coming with the public release): map the share to a drive letter or use its UNC path (\\nas\Photos). If you run the server as a Windows service, give the service an account that has network credentials, or keep sources on a locally-mounted drive.
• NAS/Docker (coming with the public release): mount the photo volume into the container — no network hop at all. This will be the most reliable setup: the photos and the server live on the same box.

"Unreachable" folders

If the server can't reach a source folder — a NAS share that isn't mounted, a drive that's unplugged, or (when Aardy is shared with all users on the Mac) a folder only another user's session can see — the folder shows an Unreachable badge on Source Folders. Imports from it pause until it's reachable again; photos already imported keep playing.