Documentation - Secret Library

Mobile App

Your complete guide to Secret Library for iOS and Android

Getting Started

Connecting to Your Server

When you first open Secret Library, you'll need to connect to your Audiobookshelf server.

Field	Description	Example
Server URL	Your Audiobookshelf server address	`https://abs.mydomain.com`
Username	Your Audiobookshelf account username	`john`
Password	Your Audiobookshelf account password	`••••••••`

Connection Tips

Include https:// or http:// in your URL
Don't include a trailing slash
If using a custom port, include it: http://server.com:13378
For local servers, use your server's local IP address

Home Tab

Your personalized dashboard for quick access to your audiobooks.

Continue Listening

Shows your currently in-progress audiobook with cover art, title, author, progress, and a large play button for instant resume.

Recently Played

Horizontal scroll of books you've listened to recently with progress indicators.

Continue Series

Series you're actively reading with the next unplayed book highlighted.

Recently Added

New books added to your library.

Recommended For You

Personalized suggestions based on your listening history.

Library Tab

Your complete audiobook collection with powerful filtering and sorting.

View Modes

All Books — Complete library
In Progress — Books you've started (1-95% complete)
Finished — Completed books (95%+)
Downloaded — Offline books only

Sort Options

Sort By	Description
Title	Alphabetical A-Z
Author	Grouped by author name
Recently Played	Most recently listened first
Recently Added	Newest additions first
Duration	Shortest to longest
Progress	By completion percentage

Discover Tab

Explore your library by author, narrator, series, genre, and more.

Authors — Alphabetical list with book counts
Narrators — All narrators in your library
Series — All series with progress tracking
Genres — Browse by category
Collections — Custom collections from ABS

Profile Tab

Your account, settings, and app management.

Option	Description
Downloads	Manage offline books
Listening Stats	Detailed statistics
Playback Settings	Speed, skip intervals
Appearance	Theme and display
Storage	Manage app storage
Sign Out	Disconnect from server

Player

The full-screen audio player with all playback controls.

Main Controls

Control	Action
Play/Pause	Start or pause playback
Skip Back	Jump back 30 seconds (configurable)
Skip Forward	Jump forward 30 seconds (configurable)
Previous Chapter	Go to previous chapter
Next Chapter	Go to next chapter

Secondary Controls

Control	Description
Speed	Adjust playback speed (0.5x - 3.0x)
Sleep Timer	Set auto-stop timer
Chapters	View and navigate chapters
Bookmarks	Save and view bookmarks
Queue	View upcoming books
AirPlay	Cast to external speakers

Sleep Timer

Set a timer: 5, 10, 15, 30, 45, 60, 90 minutes, End of Chapter, or custom.

Shake to Extend — Shake phone to add 5 minutes
Fade Out — Gradually lower volume before stopping

Book Detail Screen

Comprehensive view of a single audiobook.

Action Buttons

Button	Action
Play	Start or resume playback
Download	Save for offline listening
Favorite	Add to favorites
Mark Finished	Mark as complete

Information Tabs

Overview — Description, publication details
Chapters — Complete chapter list
Details — Full metadata, series info

Series Detail Screen

View and manage an entire book series with progress tracking, book list in reading order, and actions like Play Next, Download All, Mark All Finished.

Author Detail Screen

Explore all books by a specific author with biography, book list, and series by this author.

Search

Find anything in your library: book titles, author names, narrator names, series names, descriptions.

Downloads

Manage your offline audiobook library.

Setting	Description
WiFi Only	Only download on WiFi connections
Auto-Download	Download next book in series automatically
Storage Limit	Maximum space for downloads

Queue

Manage your upcoming listening queue. Add books, reorder by drag and drop, remove by swiping. Queue persists across app restarts.

All Settings

Playback Settings

Setting	Options
Skip Forward/Back Duration	10, 15, 30, 45, 60 sec
Default Playback Speed	0.5x - 3.0x
Remember Speed Per Book	On/Off
Auto-Rewind on Pause	Off, 5, 10, 15, 30 sec
Continuous Playback	On/Off

Sleep Timer Settings

Setting	Options
Default Timer	15, 30, 45, 60 min, End of Chapter
Shake to Extend	On/Off
Fade Out Audio	On/Off
Fade Duration	15, 30, 60 sec

Sync Settings

Setting	Options
Auto-Sync Progress	On/Off
Sync on WiFi Only	On/Off
Sync Frequency	Real-time, 1 min, 5 min

CarPlay & Android Auto

Listen safely while driving with full car integration.

Setup

CarPlay: Connect iPhone to CarPlay, Secret Library appears automatically.

Android Auto: Connect phone, open Secret Library from launcher.

Available Features

Browse Library, Continue Listening, Play/Pause, Skip, Chapter Navigation, Playback Speed — all available. Search is limited, Downloads and Settings not available.

Tips for Car Use

Download books before your trip. Set up your queue before driving. Use voice commands: "Hey Siri, skip forward".

Troubleshooting

Connection Issues

"Cannot connect to server"

Verify server URL (include http:// or https://). Check if server is running. Try accessing in a web browser first.

"Authentication failed"

Double-check username and password. Try logging into web interface first.

Playback Issues

"Audio won't play"

Check device volume and silent switch. Try force-closing and reopening app. Download the book for offline play.

"Wrong playback position"

Pull down to sync with server. Force sync: Profile → Sync → Sync Now.

Download Issues

"Download won't start"

Check available storage space. Verify WiFi connection (if WiFi-only enabled). Cancel and restart download.

Keyboard Shortcuts (iPad)

Shortcut	Action
Space	Play/Pause
← / →	Skip back / forward
↑ / ↓	Volume up / down
⌘ F	Search
⌘ 1-4	Switch tabs

Audiobook Tagger

Desktop metadata manager for your audiobook library

System Requirements

macOS

macOS 12 (Monterey) or later
Apple Silicon (M1/M2/M3) or Intel
200 MB free disk space

Windows

Windows 10 (version 1809) or later
64-bit processor
200 MB free disk space

Installation

macOS

Download Secret Library_1.0.0.dmg
Double-click the DMG file to open it
Drag Secret Library to your Applications folder
First launch: Right-click the app → Open (required once for unsigned apps)

Windows

Download Secret Library_1.0.0_x64.exe
Double-click to run — no installation required
If Windows SmartScreen appears, click More info → Run anyway

First Launch Setup

Before scanning your library, configure your connections in Settings:

Launch Secret Library
Click the Settings tab
Enter your AudiobookShelf server details (if you use ABS)
Add your OpenAI API key (optional, enables AI features)
Click Save Settings

The Library Page

The Library page is where you'll spend most of your time. It has three main sections:

┌─────────────────────────────────────────────────────────────┐ │ ACTION BAR │ ├──────────────────────┬──────────────────────────────────────┤ │ │ │ │ BOOK LIST │ METADATA PANEL │ │ │ │ │ (Left sidebar) │ (Right detail view) │ │ │ │ └──────────────────────┴──────────────────────────────────────┘

Action Bar

The action bar at the top contains all your main controls:

Load from AudiobookShelf

Icon: Download arrow
What it does: Pulls your entire library from your AudiobookShelf server
When to use: First time setup, or when you want to sync changes from ABS

Enrich Menu (Sparkle icon)

Click to open a dropdown with metadata enhancement tools:

Option	What It Does
Clean Genres	Normalizes all genres to the approved list (e.g., "Sci-Fi" → "Science Fiction")
AI Tags	Uses GPT to generate descriptive tags based on the book's description
Fix Titles	AI-powered title cleanup — removes series info, fixes capitalization
Fix Series	Detects and corrects series names and book numbers
Fix Descriptions	Cleans up messy descriptions, removes promotional text
Lookup Age	Fetches age/content ratings from Goodreads
Lookup ISBN	Finds missing ISBN numbers
Run All	Executes all of the above in sequence
Generate DNA	Creates unique content fingerprints for matching

Note

AI features require an OpenAI API key in Settings

Validate Menu (Search icon)

Click to open analysis tools:

Option	What It Does
Scan Errors	Checks all books for metadata problems (missing fields, invalid data)
Analyze Authors	Finds author name inconsistencies (e.g., "J.K. Rowling" vs "Rowling, J.K.")
Analyze Series	Detects series issues like missing books, wrong numbering
Fix All Issues	Batch-fixes all detected problems (appears when issues are found)

A red dot appears on this menu when issues are detected.

Push to AudiobookShelf

Icon: Upload arrow
What it does: Sends your metadata changes to your ABS server
When to use: After editing metadata, to sync changes back to ABS

Selection Controls (Right side)

Force Fresh toggle (circular arrow): When orange, forces re-processing of all books even if unchanged
Select All: Selects every book in your library
Configure ABS →: Quick link to Settings (shows when ABS isn't configured)

Book List (Left Panel)

Your audiobooks appear here after loading from ABS.

Understanding the List

Books are grouped by folder/directory
Each entry shows: Title, Author, and file count
Click a book to select it and view details
Cmd/Ctrl + Click to select multiple books
Use the search bar at the top to filter by title, author, or series

Status Badges

Books may show colored indicators:

Red dot — Has errors (missing required fields)
Yellow dot — Has warnings (potential issues)
No dot — Passes validation

Metadata Panel (Right Panel)

When you select a book, its details appear here.

Header Section

Cover Art — The book's cover image (shows file size in bottom corner)
Title — Main book title with source badge
Series — Series name and position (if applicable)
Author/Narrator — Creator credits

Edit Button

Click Edit to open the full metadata editor where you can modify title, author, narrator(s), series name and position, description, genres, publisher, ISBN/ASIN, and more.

Validation Issues

If the book has problems, they appear as colored alert boxes:

Red — Errors that should be fixed
Yellow — Warnings to review
Blue — Informational notes

Confidence Card

Shows how reliable the metadata is:

Overall score — Combined confidence percentage
Per-field scores — Individual confidence for each field
Sources — Where the metadata came from

Color coding: Green (85%+) = High confidence, Yellow (60-84%) = Medium, Red (<60%) = Low confidence.

Cover Actions

Button	What It Does
Find Better Cover	Searches Google, Audible, and other sources for cover art options
Upload Custom Cover	Opens file picker to upload your own image (JPG, PNG, WebP)

Cover Search Modal

When you click "Find Better Cover":

The app searches multiple sources automatically
Results appear in a grid showing cover image preview, source (Google, Audible, etc.), and dimensions
Hover over a cover and click Use This to apply it
Or click Upload Custom if none are suitable

The Settings Page

AudiobookShelf Connection

Field	Description
Server URL	Your ABS server address (e.g., http://192.168.1.100:13378 or https://abs.example.com)
API Token	Your personal API token from ABS
Library ID	The specific library to sync with (e.g., lib_xxxxx)

To find your API Token:

Open AudiobookShelf in a browser
Go to Settings → Users
Click your username
Copy the API Token

API Keys

OpenAI: Your OpenAI API key (starts with sk-). Enables AI-powered features like smart tagging, title fixing, and description cleanup.

Performance Preset

Preset	Description
Conservative	Slower, uses minimal resources. Good for older machines.
Balanced	Default setting. Good performance without overwhelming your system.
Performance	Faster processing, uses more CPU/memory.
Extreme	Maximum speed. Best for high-end systems (M2/M3 Pro/Max).

Common Workflows

Initial Library Setup

Go to Settings
Enter your ABS Server URL, API Token, and Library ID
Click Test connection to verify
Click Save Settings
Go to Library tab
Click the Download button to load from ABS
Wait for the scan to complete

Cleaning Up Metadata

Load your library from ABS
Click Select All
Open the Enrich menu (sparkle icon)
Click Run All to process everything
Review changes in the metadata panel
Click Push to ABS to sync back

Finding Better Covers

Select a book with a missing or low-quality cover
In the metadata panel, click Find Better Cover
Browse the search results
Click Use This on your preferred cover
Push to ABS to sync cover changes

Keyboard Shortcuts

Shortcut	Action
Cmd/Ctrl + A	Select all books
Escape	Clear selection / Close modal

Troubleshooting

"Configure ABS" keeps showing

Go to Settings and enter your server URL, API token, and library ID. Click Test connection to verify, then Save Settings.

Books won't load from ABS

Verify your server URL is correct (include http:// or https://). Check that your API token hasn't expired.

AI features are grayed out

Add your OpenAI API key in Settings, then Save Settings and return to Library.

Metadata changes don't appear in ABS

Make sure you clicked Push to ABS after making changes. Check that your API token has write permissions.

Tips for Best Results

Start with Clean Genres — Run "Clean Genres" first to standardize your library.

Check confidence scores — Low confidence (red) means metadata may be wrong. Review manually.

Keep backups enabled — The "Backup Tags" setting protects against mistakes.