Reference

How AudioPaper works, with the numbers. Every figure here is a value in the source code, so you can check it. The Privacy and Network pages cover what is sent where.

Settings

Open with Settings… in the menu, or ⌘ ,. Settings reopens on the pane you used last.

General

Sources

Switches for each player (Apple Music and Spotify) and each fan-art source. New players and sources start switched on. Switching a source off takes its images out of the rotation straight away, even ones found earlier; they stay in the cache, and come back if you switch it on again. A source that needs credentials says so until you add them; Brave Search is marked as the fallback it is.

Accounts

Keys for fanart.tv (the downloaded app has its own project key; a personal key is optional), TheAudioDB (optional), Brave Search and DeviantArt (client ID and secret). They’re saved to your Keychain half a second after you stop typing, and each is sent only to its own service. How to get them is on the Help page.

About

Version and build; the update switches (Check for updates automatically, Download and install updates automatically), when it last checked, and Check Now; links to the source, help, privacy and sponsorship.

Album covers

When a new album starts, its cover is looked up from these in order; the first confident match wins, and the rest aren’t asked.

1. Apple’s iTunes Search, at up to 3000 × 3000.
2. MusicBrainz and the Cover Art Archive, at 1200 px, when Apple doesn’t have the release.
3. The player’s own artwork: Music’s, read on your Mac, or for Spotify, the cover Spotify shows, from its image server (i.scdn.co).

A Spotify podcast episode, when During podcasts is set to Podcast cover art, skips the catalogs and uses Spotify’s cover directly. Spotify’s ads are never looked up.

A match is scored on both artist and album name, with edition noise (“Deluxe Edition”, “2011 Remaster”, “- Single”) removed first, so a tribute album with the same title doesn’t win.

Identifying the artist

Fan-art services file images under an exact artist, not a name, because names collide. So AudioPaper first asks MusicBrainz which artist recorded this song. That’s how ROSÉ of BLACKPINK and Rose, the French singer, stay apart. If the song search doesn’t settle it, it searches by artist name. Names are matched exactly, accents included.

• Collaborations (“LE SSERAFIM & j-hope”, “A feat. B”, “A x B”, “A with B”) are looked up as a whole first; if that finds no art, each credited artist is tried.
• Featured artists named in the title (“feat. Ludacris, Mystikal & I-20”) are tried next, for credits like a label crew that has no art of its own.
• Identities are remembered on disk. Names that couldn’t be resolved are retried after 7 days.

Fan art sources

The first four are asked together. Brave Search is asked afterwards, and only if fewer than 3 images have passed the filters.

Each source returns at most 30 candidates. A web result is used only if its title or address names the artist as a whole phrase (“Ray Noir” doesn’t match “Blu-ray Noir”), with the same accents (“ROSÉ”, not “Rose”). A one-word name must also come with the song, the album or a word about music; a name of two or more words is specific enough on its own.

When a service is down or busy

If a service is offline, returns a server error, or answers 429 Too Many Requests, AudioPaper sends it nothing more for as long as its Retry-After header asks: a minute if it doesn’t say, at most an hour. The song isn’t marked as searched, so it’s searched again on its next play. The same goes for a song you skip mid-search. At most 60 new songs are searched an hour.

The filters

Every candidate is checked on your Mac, with Apple’s Vision framework, before it can be shown. Candidates are downloaded 4 at a time, and checking stops once 8 have passed.

What passes is ranked by Vision’s aesthetics score, plus a boost equal to Vision’s confidence that the image is artwork (art, illustration, painting, graffiti).

The artist’s pool

• Each song is searched once, the first time it plays. What it finds joins its artist’s pool.
• A pool holds up to 24 images. Once it’s full, new songs by that artist don’t search at all.
• Each play shows up to 8 images from the pool: the ones you’ve seen least recently first. So repeat plays look different without going back online.
• When nothing is found for a song, that’s remembered for 7 days.

Putting it on screen

• The cover is drawn centred over a blurred, colour-matched wash of itself, at the size of each display.
• Fan art fills the screen edge to edge. When filling would crop more than 15% (Automatic), or you chose Fit, the whole image is shown and its edges are feathered into a blurred extension of itself.
• Order and timing: on a new song, the cover goes up first: at once if AudioPaper has downloaded it before, otherwise after a short pause (1.5 seconds, so skipping through songs doesn’t look each one up) and the lookup. It holds the place for about 10 seconds while the artist’s images load; then the fan art takes over and rotates at the interval you set. The menu, Mini Player and widgets switch to each new image the moment it’s chosen; the wallpaper follows as soon as it’s drawn, a fraction of a second, plus the 1.6-second cross-fade.
• The change is a cross-fade, drawn in a click-through window just above the desktop; then the real wallpaper is set underneath it. So the picture stays after you quit, and appears on every Space, every display and in Mission Control. It’s re-applied when you switch Spaces.
• Your original wallpaper is saved, per display, the first time AudioPaper changes it, and put back by Restore Original Wallpaper.

Credits

Every image keeps where it came from. The menu, the Mini Player and the widgets show:

• the person who made or took it, when the source says (DeviantArt artists, Commons photographers), with a link to their profile where there is one;
• the licence, for Wikimedia Commons photos;
• the page it came from, and the service that found it.

For web results, the credit names the artist the image was matched to and the site, since wallpaper sites’ titles rarely say who is pictured.

What’s stored, and where

Untrusted replies

Web search results can point anywhere, so everything a service sends back is treated as untrusted:

• Requests go only to https addresses on named internet hosts, redirects included. IP addresses, localhost, .local and other local-network names are refused, so a result can’t reach anything on your network.
• The Brave key and DeviantArt token are dropped if a redirect leads to another host.
• Responses over 40 MB are abandoned, and each request gets 60 seconds in all.
• Images must be JPEG, PNG, HEIC, WebP or TIFF, at most 16,384 px on a side and 50 megapixels, checked from the header before decoding.
• Credit links open only if they’re web links (https or http); a source can’t make a credit open a file, a network share or another app.
• “Now playing” notifications are acted on only while Music is running, with each field capped at 256 characters.

Security reports go to the address in SECURITY.md.

Accessibility

AudioPaper aims for WCAG 2.2 AA as W3C’s WCAG2ICT applies it to desktop software, and for Apple’s accessibility guidelines for macOS. This site aims for WCAG 2.2 AA directly.

• VoiceOver: every control, image and link has a spoken name. The artwork says what’s on the desktop (“Photo by …, from Wikimedia Commons”). Settings fields include their service (“fanart.tv personal API key”), and the rotation slider speaks its value (“45 seconds”).
• Keyboard: the Mini Player and Settings use standard controls, which Full Keyboard Access can reach, and the “…” menu opens under its button however it’s pressed. See Keyboard shortcuts.
• Motion: the wallpaper changes with a cross-fade, never movement. With Reduce Motion on, the Mini Player’s image strip jumps instead of scrolling. Pause Wallpaper Changes stops the rotation altogether.
• Transparency and contrast: the Liquid Glass surfaces are the system’s own, so they follow Reduce Transparency and Increase Contrast.

These were checked with the macOS accessibility API and, for this site, automated audits. They haven’t yet been tested by a VoiceOver user; if something is hard to use, please open an issue.

Updates

AudioPaper updates itself with Sparkle. On the second launch it asks whether to check automatically; if you agree, it reads the update feed about once a day. Settings → About has the same switch, plus Download and install updates automatically (off unless you turn it on; the update is installed when AudioPaper quits) and when it last checked. Check for Updates…, in the menu bar menu and the AudioPaper menu, checks now. Every update is verified against the EdDSA public key built into the app before it’s installed. No system profile is sent. Your settings, keys and downloaded art are kept.

Siri, Shortcuts and AppleScript

Five App Intents, available to Siri (with ready-made phrases), Shortcuts and Spotlight:

AppleScript (the dictionary is in Script Editor’s library): the properties current song, image count, current image (its position in the strip, from 1), current credit and paused (settable), and the commands show image n and next image.

tell application "AudioPaper"
    get {current song, image count, current image, current credit}
    show image 3        -- the third image in the strip, on the desktop now
    next image
    set paused to true  -- the same as Pause in the Mini Player
end tell

macOS asks you before another app or script may send these (System Settings → Privacy & Security → Automation). Nothing here controls playback, and nothing leaves your Mac.

Permissions

AudioPaper runs in the App Sandbox, with the hardened runtime, and asks for only this:

• Outgoing network connections, for the lookups. It accepts no incoming ones.
• Automation of Music and Spotify, to read what’s playing at launch, and the player’s artwork as a last resort (for Spotify, also podcast covers). It never controls playback.
• An App Group, shared with its own widgets.

No location, contacts, camera, microphone, photos or files.

For developers

AudioPaper is a Swift package (AudioPaperKit) with a thin SwiftUI app and a WidgetKit extension on top. Players, cover providers, fan-art sources and image filters are plugins, each a small Swift protocol; adding one is a single file and one line of registration. See CONTRIBUTING.md.

The package includes apctl, a command-line tool that runs the same code as the app. From Packages/AudioPaperKit, with keys in a .env file (see .env.example):

swift run apctl cover "Radiohead" "In Rainbows"      # which provider found the cover, and the score
swift run apctl fanart "BABYMONSTER" "DRIP" [outDir]  # every candidate, every filter verdict, the ranking
swift run apctl labels image.jpg …                   # Vision's classification labels for images
swift run apctl render image.jpg 3024 1964 automatic # compose a wallpaper exactly as the app would

The tests run with swift test in the same folder.