# Install and set up Retune

Retune supports these native packages:

Retune follows the macOS releases Apple currently supports; macOS 15 is the
current floor.

| Platform | Supported architecture | Minimum runtime |
| --- | --- | --- |
| macOS | Apple Silicon | macOS 15+ (Apple-supported releases) |
| Windows 10/11 | x64, ARM64 | WebView2 105 (the installer updates older runtimes) |
| Ubuntu 22.04 | amd64, arm64 | Distribution WebKitGTK 4.1 |
| Compatible Debian/Ubuntu systems | amd64, arm64 | WebKitGTK 4.1 |

Homebrew, Winget, and APT are recommended because they manage updates and verify
published package metadata.

## Direct downloads

The [latest Retune release](https://github.com/open-cli-collective/Retune/releases/latest)
provides these fallback downloads. Use the version shown on that release page
in each artifact name:

| Platform | Architecture | Asset |
| --- | --- | --- |
| macOS | Apple Silicon | `Retune-<version>-aarch64.zip` |
| Windows | x64 | `Retune-<version>-windows-x64-setup.exe` |
| Windows | ARM64 | `Retune-<version>-windows-arm64-setup.exe` |
| Debian/Ubuntu | amd64 | `retune_<version>_amd64.deb` |
| Debian/Ubuntu | arm64 | `retune_<version>_arm64.deb` |

Download `checksums.txt` from that same latest release and verify the matching
asset before installing. The macOS artifact uses the Open CLI Collective's
self-signed certificate and is not Apple-notarized. Windows installers and
their application payloads are unsigned. The checksums are the release's
transport-integrity check. These files support only the targets listed above.

After verifying the download, install the matching package:

```sh
# macOS (replace VERSION with the latest release version)
VERSION=latest-version
/usr/bin/ditto -x -k "Retune-${VERSION}-aarch64.zip" .
sudo mv Retune.app /Applications/

# Debian/Ubuntu amd64 (use the arm64 filename on ARM64)
sudo apt install "./retune_${VERSION}_amd64.deb"
```

On Windows, run the downloaded `.exe` installer from File Explorer or
PowerShell, for example `./Retune-<version>-windows-x64-setup.exe`.
On first macOS launch, try to open Retune once, then choose **Open Anyway** in
System Settings → Privacy & Security (Security & Privacy → General on older
macOS). Only approve the app after verifying its release checksum; Apple
documents this flow in [Open a Mac app from an unknown developer](https://support.apple.com/guide/mac-help/mh40616/mac).

## macOS with Homebrew

Install:

```sh
brew install --cask open-cli-collective/tap/retune
```

Upgrade or uninstall:

```sh
brew update
brew upgrade --cask retune
brew uninstall --cask retune
```

The app uses the Open CLI Collective's long-lived self-signed certificate but
is not Apple-notarized. Homebrew leaves quarantine metadata intact; approve the
first launch through Privacy & Security after Homebrew verifies the cask
checksum.

## Windows with Winget

Install:

```powershell
winget install --exact --id OpenCLICollective.Retune
```

Upgrade or uninstall:

```powershell
winget upgrade --exact --id OpenCLICollective.Retune
winget uninstall --exact --id OpenCLICollective.Retune
```

The installer and installed Retune executable are unsigned, so Windows may show
**Unknown Publisher** or Microsoft Defender SmartScreen warnings. Winget
verifies the published installer hash. New Winget submissions can take time to
appear while Microsoft publishes the manifest; if Winget reports that no
package was found, use the checksum-verified direct download or retry later.

## Debian or Ubuntu with APT

Add the signed Open CLI Collective repository, then install Retune:

```sh
curl -fsSL https://open-cli-collective.github.io/linux-packages/keys/gpg.asc \
  | sudo gpg --dearmor --yes -o /usr/share/keyrings/open-cli-collective.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/open-cli-collective.gpg] https://open-cli-collective.github.io/linux-packages/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/open-cli-collective.list
sudo apt update
sudo apt install retune
```

Upgrade or uninstall:

```sh
sudo apt update
sudo apt install --only-upgrade retune
sudo apt remove retune
```

Release builds encrypt Spotify tokens. The encryption key is stored in the
desktop session's Linux Secret Service; local files still work if Spotify is
signed out or that credential store is unavailable.

## Connect Spotify

Spotify access is optional. You can import and play local files while signed
out. Spotify library access and playback require Spotify Premium and a Spotify
developer application:

1. Open the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard),
   create an app following Spotify's [app guidance](https://developer.spotify.com/documentation/web-api/concepts/apps),
   and select **Web API**.
2. In the app settings, follow Spotify's [redirect URI guidance](https://developer.spotify.com/documentation/web-api/concepts/redirect_uri)
   and register exactly
   `http://127.0.0.1:8898/callback`. Use the literal `127.0.0.1`, with the exact
   path, no trailing slash, and no `localhost` substitution. Do **not** register
   `http://127.0.0.1:8898/login`; `/login` is Retune's separate internal
   built-in-playback callback.
3. Copy the app's Client ID. Retune uses Authorization Code with PKCE, so it
   does not need or store the client secret.
4. In Retune's setup window, enter the Client ID, leave **Web API enabled**
   selected, choose **Connect…**, approve access in the browser, then choose
   **Sync**.
5. The first time built-in playback starts, approve the separate one-time
   **Authorize Spotify playback** prompt. This does not replace or disconnect
   the Web API grant.

Spotify Development Mode currently requires the application owner to have
Premium and limits each app to five authenticated users. Anyone other than the
owner must be added to the app allowlist in the Dashboard. Spotify may also
apply Development Mode quota limits; see its current [quota-mode
documentation](https://developer.spotify.com/documentation/web-api/concepts/quota-modes).

## Troubleshooting

- **Invalid redirect URI or the browser never returns:** compare the Dashboard
  entry character-for-character with `http://127.0.0.1:8898/callback`. Remove a
  trailing slash, `localhost`, or any `/login` entry, save, and reconnect.
- **User not registered, forbidden, or quota errors:** confirm the app owner has
  Premium, add the signing-in Spotify account to the app allowlist, and keep the
  total at five users or fewer. Quota exhaustion must clear at Spotify; repeated
  reconnects do not bypass it.
- **macOS first-launch warning:** verify the checksum, try to open the app once,
  then choose **Open Anyway** in Privacy & Security. The self-signed app does
  not pass Apple's notarization assessment.
- **Windows publisher warning:** the installer is unsigned. Verify it against
  `checksums.txt` before accepting an **Unknown Publisher** or SmartScreen
  prompt.
- **Credential-store unavailable:** unlock macOS Keychain, Windows Credential
  Manager, or Linux Secret Service and relaunch. Local-only use remains
  available without stored Spotify credentials.
- **Verify a direct download:** download `checksums.txt` beside the package and
  run `sha256sum -c checksums.txt --ignore-missing` on Linux, `shasum -a 256`
  on macOS, or `Get-FileHash -Algorithm SHA256` in PowerShell and compare the
  result.