☁️ Private Cloud Drives: Mounting & Sync Guide
JuJu Music connects directly to private cloud drives and local network storage with an advanced Dry-Run delta synchronization engine.
Supported storage (same order as the protocol picker in the Add Cloud Drive dialog): FTP / FTPS, SMB/CIFS, SFTP, WebDAV, Subsonic / Navidrome, S3-compatible object storage, Aliyun Drive. Only Subsonic / Navidrome is a read-only protocol (cloud → device); the others support upload, folder creation and delete. Note that WebDAV / SMB / SFTP / FTPS write access is decided by your own server, and for S3 by the bucket policy behind those access keys — a read-only account is simply refused by the server with an explanatory error.
Where does the port go?
FTP/SFTP/SMBhave a dedicated port field (21 / 22 / 445 by default, usually blank);WebDAV/Subsonic/S3have no port field — their address is the server URL, so the port lives in it (http://192.168.1.10:5005).
🔌 1. Supported Storage Protocols
Go to Settings -> Cloud -> Add Cloud Drive:
1. FTPS (FTP + TLS)
- Works with: FTP servers such as vsftpd / proftpd / IIS, and the "FTP over TLS" (explicit) option found on many NAS boxes.
- FTPS is not SFTP: SFTP is the file-transfer subsystem of SSH (port 22 by default); FTPS is FTP + TLS — the control connection uses the usual TCP 21 and every listing or transfer opens its own separate data connection. A different protocol, sharing no code.
- ⚠️ This app supports explicit FTPS only: a plain greeting first, then an
AUTH TLSupgrade, port 21 by default. Implicit FTPS (TLS from the very first byte, usually port 990) is not supported and will not connect.
- Enter:
- Server address: a host name or IP, e.g.
192.168.1.10ornas.local— do not add anftps://prefix, just the host itself; - Port: optional, defaults to 21;
- Username / password: your FTP account (the password is encrypted at rest like any other password);
- Root directory: optional, e.g.
/data; blank = the directory you land in after signing in. Leave it blank for a chrooted server (common with vsftpd), since you are already confined to your own directory.
- Server address: a host name or IP, e.g.
- 🔐 Certificate trust (TOFU) — the first connection is refused, and that is expected: FTPS runs over TLS too, and a self-signed certificate has no trusted CA behind it, so the app pins one certificate fingerprint per server:
- The first save is refused, and the dialog shows the full SHA-256 certificate fingerprint the server presents;
- Tap Check certificate and the app connects once more to show the fingerprint exactly as the server presents it, along with the subject and issuer;
- Verify it and tap Trust this certificate — only then can the server be saved and used. You can revoke at any time with Stop trusting.
- The fingerprint must match the server's own: cross-check it on the server with
openssl x509 -in /etc/ssl/certs/vsftpd.pem -noout -fingerprint -sha256; - ⚠️ If it says the certificate has changed and you did not replace it yourself, do not trust it — the connection may be intercepted;
- An FTPS client will often take "the connection succeeded" as good enough and accept a self-signed certificate; this app will not — a certificate that is neither pinned nor trusted by the system is always refused.
- ⚠️ Passive-mode ports (the pitfall users hit most): the app supports passive mode only. The server must open a range of passive ports (vsftpd's
pasv_min_port/pasv_max_port), and those ports must be reachable from the phone; behind docker or NAT they must be mapped as well.- Symptom: signing in works, but the first listing or transfer fails — the error points straight at the passive-mode ports, so check that port range on the server rather than suspecting the credentials.
- It is read-write: browse, upload, download (with REST resume), create folder, delete (recursive for folders), and two-way / one-way / mirror sync all work; cloud tracks also stream online, scrubbing included.
- ⚠️ No server-side transcoding: FTPS cannot transcode down to the "online playback bitrate" the way Subsonic does, so that option has no effect here (streaming and local caching still work).
- 💡 Uploads are reliable: an upload goes through a "staging file + resume + rename" flow, so an interrupted transfer keeps its resume point and a retry only sends the missing part instead of starting over.
- ⚠️ 550 carries two meanings: FTP puts "the path does not exist" and "you are not permitted" behind the same
550reply code (the app's error text says so honestly), so confirm the real cause on the server when you see it.
2. SMB / CIFS Network Shares
- Windows shared folders, router-attached USB storage, and home NAS.
- The port has its own field (445 by default, usually blank).
3. SFTP (File Transfer over SSH)
- Works with: anything that speaks SSH — OpenSSH servers, Synology / QNAP NAS, Linux boxes, the macOS Remote Login service, even SSH running on a router.
- SFTP is not FTPS: SFTP is the file-transfer subsystem of SSH (it uses the SSH port, 22 by default); FTPS is FTP + TLS (TCP 21 plus a data connection) — a different protocol, supported here through its own section (see 1 above), and the two share no code.
- Enter:
- Server address: a host name or IP, e.g.
192.168.1.10ornas.local— do not add ansftp://prefix, just the host itself; - Port: optional, defaults to 22;
- Username / password: your SSH account (the password is encrypted at rest like any other password);
- Root directory: optional, e.g.
/data; blank = filesystem root. Leave it blank for a chrooted SFTP server (you are already confined to your own directory); on a self-hosted, non-chrooted server fill in something like/dataexplicitly so nobody wanders into/etcor/bin.
- Server address: a host name or IP, e.g.
- 🔐 Host key trust (TOFU) — the first connection is refused, and that is expected: SFTP has no "trusted CA" system the way HTTPS does, so the app pins one fingerprint per server (trust on first use) to stop man-in-the-middle attacks:
- The first save is refused, and the dialog shows the full SHA-256 host key fingerprint and the key algorithm the server presents (e.g.
ssh-ed25519) — not just a bare "connection failed"; - Tap Check host key and the app connects once more to show the fingerprint exactly as the server presents it;
- Verify it and tap Trust this host key — only then can the server be saved and used. You can revoke at any time with Stop trusting.
- The fingerprint must match the server's own: cross-check it on the server with
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub; - ⚠️ If it says "the host key has changed" and you did not rotate the key yourself, do not trust it — the server may have been reinstalled, or the connection may be intercepted;
- The fingerprint applies to that server only — it never loosens verification for your other cloud drives.
- The first save is refused, and the dialog shows the full SHA-256 host key fingerprint and the key algorithm the server presents (e.g.
- It is read-write: browse, upload, download (with resume), create folder, delete and two-way / one-way / mirror sync all work; cloud tracks also stream online, scrubbing included.
- ⚠️ No server-side transcoding: SFTP cannot transcode down to the "online playback bitrate" the way Subsonic does, so that option has no effect here (streaming and local caching still work).
- ⚠️ Password login only: public-key login has no UI entry point yet (the library supports it; only the entry point and a secure place to store private keys are still open) — that is "not done yet", not "impossible".
- 💡 One usage note: sync performs many SSH handshakes. The app has no connection pool, so every operation does its own SSH handshake. That is deliberate: an SFTP channel is not thread-safe and the sync engine transfers with a concurrent worker pool, so sharing one SFTP channel between several transfers would scramble the message stream. Over a LAN to your own NAS the handshake takes milliseconds and you will not notice it.
4. WebDAV Protocol
- Supported: AList, Synology WebDAV Server, Nextcloud, Nutstore.
- Enter server URL, credentials, and mount directory. Tapping "Save" runs a real HTTP
PROPFINDround-trip first, and the server is only stored once it passes. - 🔐 Self-signed NAS certificates work too (new in v4.5.0): many NAS boxes serve https with a self-signed certificate. Such an address first reports "this server's HTTPS certificate is not trusted" — tap Check certificate in that dialog. The app connects once and shows the certificate fingerprint (SHA-256) and validity period exactly as the server presents them; verify it and tap Trust this certificate.
- The fingerprint applies to that server only — it never loosens validation for your other cloud drives.
- After the server rotates its certificate you confirm once more; you can revoke at any time with Stop trusting.
- Write the
https://scheme in full (without it the app treats the address as http), and for WebDAV put the port inside the address (e.g.https://192.168.1.100:5006/dav) — WebDAV has no separate port field.
5. Subsonic / Navidrome Servers
- Works with: Navidrome, Airsonic(-Advanced), Gonic, Astiga — any server implementing the Subsonic / OpenSubsonic API.
- Enter: the server URL (e.g.
http://navidrome.example.com:4533, a reverse-proxy sub-path works too) plus your Subsonic username and password. The app authenticates witht=md5(password+salt), so the password is never sent in plain text. - Browsing follows your library, not a file tree: three virtual folders — Artists / Albums / Playlists (songs are listed inside them) — and tracks are stored locally as
Artist/Album/Title.ext. - ⚠️ Read-only: Subsonic has no upload API, so sync only runs Cloud → Device. The app keeps only that direction and hides write entry points instead of offering buttons that are bound to fail.
- Bonus: covers and embedded lyrics come straight from your server (no online matching needed), and the weak-network bitrate option lets the server transcode a lower bitrate on demand.
6. S3-Compatible Object Storage
- Works with: MinIO, Ceph RGW, Cloudflare R2, Backblaze B2, Tencent COS, Alibaba OSS, AWS S3 — any S3-compatible object store. You can also type a vendor name as the protocol type (aliases:
s3/minio/r2/b2/cos/oss/ceph, case-insensitive). - Enter:
- Server URL: e.g.
http://192.168.1.10:9000orhttps://s3.us-west-2.amazonaws.com— without a scheme the address is treated as http, so spell outhttps://for public clouds; - Port goes in the address: e.g.
http://192.168.1.10:9000(the form has no separate port field); - Access Key ID: goes in the username field;
- Secret Access Key: goes in the password field (encrypted at rest like any password);
- Bucket: fill it into the Bucket field on its own — do not paste a path-style URL such as
https://host/bucketthere; - Region: may be left blank (defaults to
us-east-1); Cloudflare R2 wantsauto; for AWS use the bucket's own region — when it is wrong, the app puts the region the server asks for into the error message; - Addressing style: Path by default, which MinIO / Ceph / R2 / B2 use; V-Host needs a domain and a wildcard certificate, and cannot be used with an IP address.
- Server URL: e.g.
- It is read-write: browse, upload, download (with resume), create folder, delete and two-way / one-way / mirror sync all work.
- S3 has no real folders, so "create folder" writes a zero-byte
<folder>/marker object — that is what keeps an empty folder visible; uploadingfolder/file.mp3without the marker also makes the folder show up.
- S3 has no real folders, so "create folder" writes a zero-byte
- ⚠️ No server-side transcoding: S3 cannot transcode down to the "online playback bitrate" the way Subsonic does, so that option has no effect here (streaming and local caching still work).
- ⚠️ 5 GB per single upload: multipart upload is not implemented yet, so anything larger fails with an explanatory error (audio files are far below that limit in practice).
- 🔐 Self-signed certificates (common on self-hosted MinIO / Ceph): the same flow as WebDAV — tap Check certificate → Trust this certificate to pin that server's fingerprint. Do not fall back to http just to get a connection.
7. Aliyun Drive (OpenAPI)
- Web login authorization: in Add Cloud Drive, choose Aliyun, then tap Get Token to open the Aliyun web sign-in page; after you sign in, the app extracts and fills in the Refresh Token automatically. You can also paste an existing Refresh Token manually.
- Seamless renewal: built-in Refresh Token rotation keeps the mount alive without repeated sign-ins.
⚡ 2. Cloud Streaming & Smart Cache
- Tap-to-Play Streaming: once mounted, the cloud contents are shown in the shape the protocol provides (a directory tree for file-based protocols; Artists / Albums / Playlists for Subsonic / Navidrome) — tap any track and it is streamed in chunks for instant playback.
- Metadata & Lyrics Matched in Seconds: while playing a cloud track, the app automatically extracts the ID3 tags and matches accurate rolling lyrics online.
- Local Lossless Cache: cloud tracks you have already played are automatically cached under
Download/JuJuDownload/JuJuCacheon the device, so they can be played back later at full fidelity even when offline.
🔄 3. Four Synchronization Modes
Open Cloud Folder Sync from the toolbox (or tap Folder Sync on the Cloud settings page) to pair a local music folder with a folder in the cloud:
| Sync Mode | Logic | Best Use Case |
|---|---|---|
| Two-way Sync | Uploads new local tracks, downloads new cloud tracks. Keeps both mirrored. | Multi-device collaboration between phone and PC/NAS. |
| Local First | Unidirectional push to cloud. Overwrites remote outdated files. | Phone as primary library; backup to cloud. |
| Cloud First | Unidirectional pull to local device. Overwrites local files. | NAS as master repository; phone downloads latest albums. |
| Mirror Delete | Deletions on one end mirror to the other end. | Strict two-way folder mirroring. |
Background Sync: It Keeps Running When You Leave
Sync runs on a dataSync foreground service, which means:
- Screen lock, app switching, and screen-off no longer interrupt it — a whole album can transfer in the background;
- Progress appears in the notification shade (current file + completed count) with a Cancel action right there;
- The "Run in Background" button in the progress dialog frees up the UI, and the dialog is automatically restored when you return to the app;
- When the task ends, a result notification stays in the shade (success / failure counts). A cancelled run is reported as cancelled, never as "completed".
⚠️ Two caveats: (1) on some OEM ROMs, swiping the app away from Recents also kills the process — wait for the sync to finish first; (2) Android 15+ caps
dataSyncforeground services at a cumulative 6 hours per day, after which the sync is cancelled on purpose (split very large libraries into batches).
Automatic Retries on Flaky Networks
A failed transfer is not counted as a failure right away: the app retries up to 2 more times (exponential backoff, or the server's own requested delay when it sends one). While that happens the notification and the progress dialog show "Retrying 2/3" — that means it is healing itself, so don't cancel it. Only errors where a retry is pointless (wrong credentials, missing file, cloud quota, disk full) fail immediately with a clear reason.
🛡️ 4. Dry-Run Difference Preview & Safety Guard
To avoid losing precious lossless music through a careless operation, JuJu Music ships a Dry-Run difference preview engine:
- Pre-flight comparison: after you tap Sync, the engine first compares file paths, sizes, and modification timestamps in memory (allowing a small tolerance of a few seconds) — no hashing is performed;
- Difference listing: a dialog itemizes exactly what will happen:
- 🟢 To Download:
3 tracks (120MB) - 🔵 To Upload:
1 track (45MB) - 🔴 To Delete:
0 tracks(or the specific files pending deletion)
- 🟢 To Download:
- Execution after confirmation: the underlying task writes to the filesystem only after you have reviewed the list and tapped Start Sync.
Physical synchronization starts only after your explicit confirmation.
📲 5. P2P LAN Direct Transfer & 10-Minute Burn-After-Reading Cloud Sharing
Transfer music between two devices at high speed — no data cable required:
- Face-to-Face QR Transfer: the sender picks tracks and generates a dedicated QR code; the receiver opens the app and scans it. Both devices then connect directly over the WiFi LAN, at whatever speed your local network allows.
- 10-Minute Burn-After-Reading Relay: if the two devices are on different networks (across the public internet), the sender can upload to a cloud relay in one tap and receives a 6-digit pickup code. The receiver enters the code to download the track, and the file is physically shredded and destroyed server-side 10 minutes later, or as soon as the download completes. Note that during this window the file is temporarily stored on the relay server — it is never retained there permanently. This protects both copyright and privacy.
Concurrency & Bandwidth
- Concurrent files: how many files are processed at once — 1 / 2 / 4 / 8, default 4. Music libraries are mostly small files, so serial transfers are dominated by per-file round trips; moving from 1 to 4 usually speeds things up noticeably. Set it to 1 for strictly one-at-a-time transfers (useful if you do not want to hammer your NAS).
- Bandwidth limit: a cap on the combined throughput of all concurrent transfers (Unlimited / 512 KB/s / 1 MB/s / 2 MB/s / 5 MB/s). It limits the average rate: if the link itself is only 3 Mbps (about 375 KB/s), a 512 KB/s cap will not make a difference — set it clearly below the link capacity to see an effect. Raising concurrency does not bypass this cap.