DeerLibrarian

User Manual — Your personal audiobook library manager for Mac

Overview

DeerLibrarian is a macOS app for managing your personal audiobook library. It works with .m4b audiobook files stored in a folder you choose, and lets you browse, edit metadata, organize books into collections, and share your library with companion devices running DeerReader over your local network.

Your files stay yours. DeerLibrarian never uploads anything — it reads and writes the actual .m4b files in place, using the metadata atoms already embedded in the file itself.

First Launch

The first time you open DeerLibrarian, a setup screen will appear asking you to choose a library folder. This is the folder on your Mac where your .m4b audiobook files live (or where you'd like to put them).

1. Click Choose Library Folder in the setup overlay.
2. Navigate to your audiobooks folder in the Finder panel and click Open.
3. DeerLibrarian scans the folder and imports any .m4b files it finds. This can take a moment for large libraries.
4. Your books appear in the library view. You're ready to go.

If you later move or rename your library folder, DeerLibrarian will detect that access has been lost and show the setup overlay again. Simply choose the new location to reconnect.

Menu Bar

DeerLibrarian lives in the menu bar — you won't find it in the Dock. Click the DeerLibrarian icon in the menu bar to access:

Open DeerLibrarian

Opens the main library window.

Add Audiobooks

Opens a file picker to import new .m4b files or folders directly, without opening the full window first.

Settings

Opens the Settings window.

About DeerLibrarian

Version information.

Quit

Exits the app and stops the local network server if it was running.

Importing Audiobooks

DeerLibrarian supports several ways to add .m4b files to your library.

From the Toolbar

Click the Add Audiobooks button (or use the menu bar shortcut) to open a file picker. You can select individual .m4b files or an entire folder — the app will recursively find all .m4b files inside it.

Drag and Drop

Drag .m4b files or folders containing audiobooks directly onto the library view. DeerLibrarian will queue everything it finds for import.

The Import Queue

While importing, an Import Queue sheet appears showing each file's progress. Files move through the following states:

Duplicate Detection

DeerLibrarian uses SHA-256 hashing to detect when you try to import a file that already exists in your library. If an exact duplicate is found, the import is skipped automatically. If you want to keep both copies anyway, use Keep Both in the duplicate prompt — the new file will be added with a unique name.

Auto-Detection

DeerLibrarian watches your library folder for changes. If you copy new .m4b files into the folder using Finder or any other method, they will be imported automatically — no action required.

Browsing & Searching

Layout Modes

Use the grid/list toggle in the toolbar to switch between:

• Grid view — cover art prominently displayed, useful for visual browsing
• List view — compact rows showing title, author, and metadata at a glance

Search

The search bar filters your library in real time. It matches against title, author, and narrator.

Sorting

Click the sort menu to change the order of your library:

• Title — alphabetical by book title
• Author — alphabetical by author name
• Date Added — newest imports first
• Series — grouped by series name, ordered by series index
• Low Quality Metadata — books with missing required fields float to the top, useful for a metadata cleanup session

Selecting Multiple Books

Click a book to select it. Hold Command or Shift to extend the selection. Press Command A to select all books. With multiple books selected, the detail panel lets you edit shared metadata fields in bulk.

Editing Metadata

Select a book to open it in the detail panel on the right. All metadata fields are editable inline. Changes are not saved until you click Save — click Cancel to discard edits.

Available Metadata Fields

Bulk Editing

Select multiple books to edit their shared fields simultaneously. Any field you change will be applied to all selected books when you save. Fields that differ across the selection are shown with a placeholder indicating mixed values — leave them unchanged to preserve individual values.

Cover Art

DeerLibrarian reads and displays cover art embedded in each .m4b file. The cover appears as a thumbnail in the book list and as a larger image in the detail panel.

Changing a Cover

1. Select a book to open its detail panel.
2. Click Set Cover beneath the cover image.
3. Choose a JPEG or PNG image file.
4. Click Save to write the new cover into the .m4b file.

Removing a Cover

Click Remove Cover in the detail panel to clear the embedded artwork. Save to apply the change.

Playback Preview

Each book's detail panel includes a built-in audio player so you can preview or sample the content without leaving DeerLibrarian.

• Tap Play / Pause to start or stop playback.
• Drag the timeline scrubber to jump to any position.
• The player shows elapsed time and total duration.

Deleting Books

To remove a book from your library:

• Swipe left on a book row and tap Delete.
• Or right-click a book (or selection of books) and choose Delete.

A confirmation dialog lists all the books that will be removed. Confirming moves the .m4b files to the macOS Trash — they are not permanently deleted immediately, so you can recover them from the Trash if needed.

Exporting Files

To save a copy of a book's .m4b file to a different location (for backup, transfer, etc.):

1. Select the book and open its detail panel.
2. Click Export.
3. Choose a destination folder in the save panel.
4. A copy is saved to the chosen location. Your library copy is unchanged.

Collections

Collections let you group books into curated lists — a reading list, a themed set, books for a specific listener, or whatever you like. Collections appear in the sidebar and can be shared independently to different profiles.

Creating a Collection

1. Click Collections in the sidebar.
2. Click the Add Collection button in the toolbar.
3. The new collection opens in edit mode. Give it a name.
4. Click Select Books to open a searchable book picker. Toggle the checkboxes for each book you want to include, then confirm.

Reordering Books in a Collection

By default, books in a collection are ordered by series name, series index, then title. You can override this with a custom order by dragging books up or down in the collection detail view. Once you've manually reordered, the custom order is saved and used going forward.

Collection Cover

Click Set Cover in the collection detail to assign a cover image. This image is shown in the collections list and sent to DeerReader when sharing.

Deleting a Collection

Open the collection detail and click Delete Collection, or right-click the collection in the sidebar list. Deleting a collection does not delete the books inside it — only the grouping is removed.

Collection Permissions

See Permissions for how to control which profiles can access a collection.

Sorting & Filtering

In addition to library-level sorting, collections have their own ordering that you control. The Low Quality Metadata sort option is particularly useful during library setup — it surfaces books with missing fields so you can fill them in efficiently.

The search bar in both the books and collections views filters results instantly as you type.

Profiles

Profiles represent the people who access your library through DeerReader. Each profile has its own playback history, access permissions, and paired devices. Click Profiles in the sidebar to manage them.

Profile Roles

Creating Profiles

Profiles are created automatically when a DeerReader device completes the pairing flow. You don't need to create them manually — the app generates one when a new device connects for the first time.

Managing a Profile

Select a profile from the list to open its detail view. From there you can:

• Rename the profile by editing the name field inline.
• Change the role between Reader and Librarian (Guest role is fixed).
• Manage book permissions — see which books this profile can access.
• Manage collection permissions — control collection access.
• View playback state — see the last-known position for each book.
• View and revoke paired devices — see all devices paired to this profile.

Deleting a Profile

Select the profile and click Delete in the detail view. The Guest profile cannot be deleted.

Permissions

DeerLibrarian gives you fine-grained control over which profiles can access which books and collections.

Book Permissions

Each book has a permissions editor accessible from the book detail panel. Click the permissions button to open a sheet where you can toggle access on or off for each profile.

Collection Permissions

Collections have their own permission sheet. When you save collection permissions, the access settings are automatically propagated to all books in that collection. Books added to a collection later inherit the collection's current permissions at the time they're added.

Default Permissions on Import

Newly imported books are not automatically granted to any profile. You'll need to explicitly grant access, either book-by-book or through a collection.

Local Network Sharing

Enable local network sharing to serve your audiobook library to DeerReader devices on your Wi-Fi network. No internet connection is required or used — everything stays local.

Enabling Sharing

1. Open Settings from the menu bar.
2. Under Local Network Sharing, toggle Enable Local Network Sharing on.
3. The Sharing Status URL is displayed — copy this URL and enter it in DeerReader to connect.

Sharing Status URL

The status URL shown in Settings encodes your Mac's local IP address and port. Copy it using the copy button and paste it into DeerReader's connection setup. If your Mac's IP address changes (common on Wi-Fi), you'll need to copy the updated URL and reconnect DeerReader.

Device Pairing

Before DeerReader can access your library, each device must be paired. Pairing establishes a secure credential that DeerReader uses to authenticate future sync requests.

Pairing Flow

1. Open DeerReader and go to its connection setup.
2. Enter the Sharing Status URL from DeerLibrarian Settings.
3. DeerReader sends a pairing request. A prompt appears in DeerLibrarian asking you to approve or deny it.
4. Approve the request. DeerLibrarian creates a new profile (or associates the device with an existing one if you choose) and issues credentials to DeerReader.
5. DeerReader is now paired and can access books according to the profile's permissions.

Manual Code Pairing

If the automatic pairing flow doesn't work (e.g., a firewall is blocking the request), you can use the manual code method. DeerLibrarian generates a short-lived code that you enter in DeerReader to complete pairing.

Revoking a Device

To revoke a device's access:

1. Go to Profiles and select the relevant profile.
2. In the profile detail, find the Paired Devices section.
3. Click Revoke next to the device you want to disconnect.

The device will no longer be able to sync. To reconnect, it will need to pair again.

Playback Sync

DeerLibrarian tracks playback position for each profile, so DeerReader always knows where a listener left off — across restarts, devices, and sessions.

How Sync Works

As you listen in DeerReader, playback events are sent to DeerLibrarian in the background. The position for your profile is updated in the library index. When you open DeerReader again (on any paired device using the same profile), it picks up from the last recorded position.

Viewing Playback State

To see the current playback position for a profile's books, select the profile in the Profiles view. Each book shows its last-known position, duration, and whether it has been marked as finished.

Conflict Resolution

If playback state arrives from two different devices (e.g., you listened on both a phone and a tablet before syncing), DeerLibrarian resolves conflicts using these rules:

• A book marked finished on any device takes priority.
• Small rewinds (minor differences in position) are tolerated and the more recent position wins.
• Large stale rewinds (a significantly earlier position arriving late) are rejected to avoid losing progress.

Settings Reference

Books

Library Folder

The folder DeerLibrarian reads from and writes to. Click Change… to pick a different folder. Click Reveal in Finder to open the current folder in Finder.

Rebuild Books

Forces a full re-scan of the library folder, reconciling the database with the files on disk. Use this if books seem out of sync or after moving files manually outside the app.

Metadata Quality

Configure which metadata fields are required. Books missing required fields are flagged with a warning badge. By default, Title and Author are required. Click Configure… to change this.

Show Inactive Books

Displays books whose .m4b files have been deleted from disk. Useful for cleaning up stale library records.

Forget Inactive Books

Removes all records for books whose files no longer exist. This operation cannot be undone (though the files themselves are already gone).

General

Start on Login

Registers DeerLibrarian to launch automatically when you log in to your Mac. Enabled by default. Recommended if you use DeerReader regularly, so the library server is always available.

Open Window on Launch

If enabled, the main library window opens automatically when the app starts. Disabled by default — the app starts silently in the menu bar.

Local Network Sharing

Enable Local Network Sharing

Starts or stops the HTTP server that DeerReader connects to. Turn this off when you're not using DeerReader to save resources.

Sharing Port

Fixed at 63337. Cannot be changed.

Sharing Status URL

The URL DeerReader uses to find your library. Copy this and enter it in DeerReader's connection settings.

Metadata Quality

Good metadata makes your library easier to browse and ensures DeerReader can display books correctly. DeerLibrarian can flag books that are missing important information.

Configuring Required Fields

1. Go to Settings → Books → Metadata Quality → Configure…
2. Check the boxes for each field you consider required.
3. Books missing any required field will show an orange warning badge in the library view.

Finding Low-Quality Books

Use the Low Quality Metadata sort option to bring all flagged books to the top of your library. Work through them, fill in the missing fields, and save — the warnings will clear as you go.

Available fields to mark as required:

• Title, Subtitle
• Author, Narrator
• Series, Series Index
• Genre, Comment

Library Maintenance

Rebuilding the Library

If your library appears out of sync with what's on disk — missing books, stale entries, or unexpected state — use Settings → Books → Rebuild Books. This triggers a full reconciliation scan that adds newly discovered files and removes records for files that no longer exist.

Inactive Books

When a .m4b file is deleted outside of DeerLibrarian (e.g., in Finder), the book record remains in the database. These orphaned records are called inactive books. To clean them up:

1. Go to Settings → Books.
2. Click Show Inactive Books to review what will be removed.
3. Click Forget Inactive Books to permanently remove those records.

Changing the Library Folder

You can move your library to a different folder at any time:

1. Move your .m4b files to the new location using Finder.
2. Open DeerLibrarian Settings and click Change… under Library Folder.
3. Select the new folder.
4. DeerLibrarian will scan the new location and rebuild the library index.

Keyboard Shortcuts

Troubleshooting

DeerReader can't connect to my library

• Make sure Local Network Sharing is enabled in Settings.
• Confirm your Mac and the DeerReader device are on the same Wi-Fi network.
• Copy a fresh Sharing Status URL from Settings — your Mac's IP may have changed.
• Check that nothing is blocking port 63337 on your Mac (firewall rules, VPN software, etc.).
• Make sure your Mac is awake and not in sleep mode.

A book I added isn't showing up

• Make sure the file has a .m4b extension. Other formats are not supported.
• Check the Import Queue for error messages — the file may have failed validation.
• Use Settings → Rebuild Books to force a fresh scan of the library folder.

Metadata changes aren't saving

• Make sure you clicked the Save button in the detail panel, not just navigated away.
• If saving fails, check that the .m4b file is not open in another app (e.g., iTunes/Music) and that the library folder is still accessible.

My library folder is showing a "reauthorize" prompt

This happens when the folder DeerLibrarian had permission to access has been moved, renamed, or deleted, or if macOS revoked sandbox access. Click Choose Library Folder and select the correct location to restore access.

Books show an orange warning badge

The badge means the book is missing one or more fields configured as required under Settings → Metadata Quality. Select the book, fill in the missing fields in the detail panel, and save. You can also relax the required fields in Settings if you don't need them.

Import issues and error history

DeerLibrarian keeps a log of import errors and issues. Click the Alerts indicator (shown when there are unread issues) to review the history and see per-file error messages for any failed imports.

Playback position in DeerReader seems wrong

• Make sure DeerReader was connected to the library during your last session so the position was synced.
• View the current recorded position in Profiles → [Profile] → Playback State.
• If two devices are out of sync, the conflict resolution rules described in Playback Sync determine which position wins.

DeerLibrarian — User Manual — 2026