Overview
Good to know
- A cloud drive source can only read files in the account you authorize for Primuse. The authorization is stored in the device's keychain.
- Each source stores separate credentials. Cancelling or a failed authorization leaves existing connections unchanged.
- A cloud drive scan first reads only file names; song details are filled in later in the background, in batches (see "Saving data" below).
Where to start
Settings › Manage Sources (in the Library group) › +, then choose a drive under Cloud Drive. On Mac you can also add it in the Sources section of the sidebar.
Three ways to sign in
| Method | Drives | What you need |
|---|---|---|
| Browser authorization | Baidu Pan, Aliyun Drive, Google Drive, OneDrive, Dropbox, 123 Pan, GuangYa Pan, pCloud | Your drive account; some builds also need your own developer credentials (see below) |
| API access token | Drime | A token created in Drime's web settings |
| App password | InfiniCLOUD | Your InfiniCLOUD account and an app password |
After you add 115 Drive, it shows "… not yet available": Primuse is applying for official access to the … open platform. Once approved you'll be able to sign in directly — stay tuned. If you already have a developer app on that platform, you can enter the credentials below to try it now.
Browser authorization steps
- Choose the drive type and save; the connection page opens and first shows "Checking authorization status…".
- If it shows Authorize:
- iPhone / iPad: Tap the button below to open the authorization page in your browser. After signing in and granting access, Primuse can read your files.
- Mac: Tap “Authorize” to open the authorization page in your system browser. After signing in and granting access, you'll return to Primuse automatically.
- Sign in to your drive account in the browser and approve access. While waiting, Primuse shows "Waiting for the system browser to return the authorization code…". On Mac it lists "Authorization steps"; This window will open the directory browser automatically once authorization completes. Don't close the callback page in your system browser.
- When authorization succeeds, folder browsing opens. Select the folders that hold your music and start the scan.
If a drive of the same type is already signed in on the device, you see two options: Use Signed-In Account and Sign In to Another Account.
When developer credentials are required
If the connection page shows "Developer credentials required", this build has no built-in credentials for that drive, and you need to apply for your own on the drive's open platform. The page shows four steps:
- Platform instructions, for example: Go to pan.baidu.com/union to register a developer app; Go to alipan.com/developer to apply for access; Go to console.cloud.google.com to create OAuth credentials; Go to entra.microsoft.com to register an app; Go to dropbox.com/developers/apps to create an app; Go to 123pan.cn/developer to apply for a developer app; Go to app.guangyapan.com/pan/docs/open-api to apply for a developer app; Go to docs.pcloud.com/my_apps to create an app and allow implicit grant
- Create an app and obtain the Client ID (and Client Secret)
- Return to Primuse, edit this source, and enter the credentials (the fields are Client ID / App Key and Client Secret or Client Secret (optional))
- Tap “Connect” again to authorize
The source code can't tell which drives have built-in credentials in the App Store release (it depends on the release build's configuration). Go by what the connection page actually shows.
If authorization fails
The failure page is titled "Connection failed" with the specific reason below. Tap Retry authorization to authorize again, or Re-check to re-check the saved authorization. Common reasons:
- "Client ID not configured": enter developer credentials as described above.
- "The password is temporarily unavailable. Unlock your device and try again.": unlock the device, then tap Re-check.
- "The saved password couldn’t be read securely. Try again or update the credential.": authorize again.
- "Failed to save authorization token": retry authorization; if it still fails, collect diagnostics, see Collect and send diagnostics to the author.
- pCloud shows "pCloud authorization is no longer valid. Please authorize again.": authorize again.
- Guangya shows "This build has no GuangYa open platform credentials (client ID, project ID, signing secret)": this version can't connect to Guangya; wait for a new version.
Drime: use an API access token
- Choose Drime. The connection page shows "Connect to Drime": Paste the API access token created in Drime Settings → Developer. Primuse validates it before opening your drive.
- Paste the token into API access token and tap Connect to Drime.
- Create a token in Drime Settings → Developer, then paste it here. The token is stored securely in Keychain.
Permission guide: All supports playback, writes, and deletion; Read Only supports browsing and playback; Restricted requires Files: Read, plus Files: Write for sidecars and deletion. When editing the source, Leave blank to keep the existing Drime token, or enter a new token to replace it.
If you see "The current Drime token cannot read files." or "The current Drime token is read-only or cannot write and delete files.", change the token's permissions in Drime and connect again.
InfiniCLOUD: use an app password
Enter your InfiniCLOUD user name and app password. In InfiniCLOUD My Page, enable external app connections and enter the generated app password. If you see "InfiniCLOUD is not configured in this build.", this version can't connect to InfiniCLOUD.
Saving data: load details only on Wi-Fi
Go to Settings › Storage (in the Library group) › Wi-Fi only for cloud details.
Cloud scans only fetch filenames upfront. Track details (artist, album, cover, duration) are loaded in the background — about 256KB per song. With this on, loading pauses on cellular and resumes when you reconnect to Wi-Fi.
Signing in to a cloud drive on Apple TV
Apple TV has no browser, so cloud drives sign in with a QR code:
- Most drives: the TV shows a QR code; the prompt reads, for example: "Scan with the camera on your iPhone or iPad to sign in to … in Primuse. The sign-in goes straight to this Apple TV over your local network." The phone needs Primuse installed and must be on the same local network as Apple TV.
- Your phone shows "Sign In to … on Apple TV": After you sign in on this device, the authorization is encrypted and handed to Apple TV over your local network. No source is added on this device, and the authorization isn’t kept here. Make sure the code on Apple TV matches the one below
- When done: Done. Apple TV will now ask you to choose the folders to scan.
- If the phone says "This version of Primuse can’t yet sign in to this service on behalf of Apple TV.", this drive can't be signed in from a phone yet.
Common failures: "Apple TV isn’t connected to a local network, so it can’t show a QR code.", "Couldn’t reach Apple TV. Make sure both devices are on the same local network and the QR code is still showing on Apple TV.", "Apple TV didn’t accept this sign-in; the QR code may have changed. Scan the code on Apple TV again.".
Limitations
- The first scan reads only file names. Details such as artist, album, artwork and duration are filled in later in batches, which takes a while for large libraries. With Wi-Fi only for cloud details on, this pauses on cellular.
- If you revoke access on the drive's website or the authorization expires, authorize again in Primuse.
- For playback, cache and offline download settings, see Offline downloads, audio cache and storage management.