Backup & Sync

Back up your FableFrog data manually or sync it across devices with iCloud. Covers export/import, iCloud sync, what data is included, and cross-server imports.

Overview

FableFrog stores some data locally on your device that doesn't sync to your Audiobookshelf server — per-book playback settings, ratings, playlists, followed series, and abandoned series. The Backup & Sync feature ensures this data is safe and portable.

There are two ways to protect your local data:

• Manual backup: export a JSON file you can save anywhere and import later
• iCloud sync: automatic, continuous sync across all your devices signed into the same iCloud account

Both are accessible from Settings > Backup & Restore.

What's Included in a Backup

A backup captures everything FableFrog stores locally:

Global Settings

Your app-wide preferences:

• Appearance: selected theme, text size, cover icon visibility, condensed row mode, hide abandoned toggle
• Playback defaults: speed, volume boost, skip forward/backward durations, headphone double-press action, player timeframe (chapter vs. book)
• Scrubber auto-lock: enabled state and delay
• Recap/rewind: enabled state, duration, mini duration, threshold
• Sleep timer: shake-to-extend preference
• Smart downloads: enabled state, threshold, auto-remove finished downloads
• Network: Wi-Fi only mode
• Reader: ebook reader settings
• Stats: daily listening goal, week start day

Per-Book Settings

Playback overrides you've set for individual books:

• Speed, volume boost, skip forward/backward durations
• Recap/rewind settings
• Scrubber auto-lock delay
• Headphone double-press action

Ratings

All your book and series ratings (half-star scale, 0.5 to 5.0) and any review text you've written.

Playlists

All your playlists and their contents, including system playlists that track your followed series and abandoned series/books.

Manual Backup

Manual backup lets you export your data to a file and import it on any device. This is useful for one-time transfers, before server migrations, or as an offline safety net.

Exporting

1. Go to Settings > Backup & Restore
2. Tap Export Backup
3. FableFrog generates a FableFrog-Backup-YYYY-MM-DD.json file
4. A share sheet appears — save the file to Files, iCloud Drive, AirDrop it, or send it however you like

The file is a human-readable JSON document containing all the data described above.

Importing

1. Go to Settings > Backup & Restore
2. Tap Import Backup
3. Select a .json backup file from the file picker
4. FableFrog shows a confirmation dialog summarizing what the backup contains — the creation date, and counts of book settings, ratings, playlists, and followed series
5. Tap Restore to apply

After restoring, the app reloads all affected services immediately. Your theme, playback settings, and other preferences take effect without restarting.

Cross-Server Import

If the backup was created on a different server connection (e.g., you changed your domain or moved to a new server), FableFrog detects the mismatch and shows a "Restore from Different Account?" warning. You can still proceed — FableFrog re-identifies ratings and playlists so they don't collide with existing data on the new connection. Per-book settings are keyed by library item ID and transfer directly.

iCloud Sync

iCloud sync keeps your data in sync across all your devices automatically. When you change a setting or add a rating on one device, it appears on your others.

Enabling iCloud Sync

1. Go to Settings > Backup & Restore
2. Toggle iCloud Sync on

iCloud sync requires that you're signed into iCloud on your device. If no iCloud account is detected, the toggle shows as unavailable.

When you first enable sync, FableFrog pushes your current local data to iCloud and pulls any existing data from iCloud. After that, sync happens continuously in the background.

How It Works

iCloud sync uses two complementary mechanisms:

• Global settings sync via iCloud key-value storage. Changes are pushed with a short delay and pulled immediately when a remote change is detected. This covers all your app-wide preferences — theme, speed, skip durations, and so on.
• Per-account data (book settings, ratings, playlists) syncs via an iCloud Drive document. Each server connection gets its own sync file. Changes are written after a 30-second debounce to batch rapid edits, and remote changes are detected and merged automatically.

Conflict Resolution

When the same data is modified on two devices before a sync completes:

• Ratings and playlists: last-write-wins based on the update timestamp. The most recently modified version is kept.
• Book settings: remote always wins, since per-book settings don't carry individual timestamps.
• Global settings: the most recently changed value for each individual setting is kept.

Sync Now

If you want to force an immediate sync, tap the Sync Now button in Settings > Backup & Restore. The last sync timestamp is displayed below the button so you can confirm it's working.

What Doesn't Sync

• Downloaded audiobook files — downloads are device-specific and not included in iCloud sync
• Server-side data — listening progress, bookmarks, and library metadata are synced by your Audiobookshelf server, not by FableFrog's backup system
• Credentials — your server URL and login are stored in the iOS Keychain and managed separately