This app is a single front end for two servers you already run.

Audiobookshelf holds three sections. Your podcasts live in a podcast-type library. Your audiobooks and ebooks live together in one book-type library — that's not a quirk of this app, it's how Audiobookshelf models them. A title with an audio file is an audiobook, a title with an EPUB or PDF is an ebook, and a title with both is one item that appears in both sections.

Plex holds five. Music, Movies, TV Shows, Radio and Live TV all read your Plex server directly and have nothing to do with Audiobookshelf. Radio isn't a separate library — it builds endless stations out of the music you already have. Live TV needs a tuner attached to your server, and is the one section that isn't finished; see its own page.

You don't need both servers. Connect one and that half of the app works.

Why the sections are separate

They look similar but behave differently underneath, and that's deliberate.

Podcasts are episodic and disposable — you subscribe, new things arrive, you listen once and they're archived. Audiobooks are long, single works split across many files, and you return to the same position for weeks. Ebooks aren't audio at all. Music is a different server with a different API and a different idea of what a library is. A film is one long thing you watch once; a television series is a hundred short ones you watch in order.

Sharing one screen across all of that would have meant compromising all of it. Instead each section has its own tab bar, its own settings, and its own player, and the drawer switches between them.

The one place they meet

A book you own as both an audiobook and an ebook is one item on your server with two independent positions. Audiobookshelf tracks how far you've listened and how far you've read as separate fields on the same progress record.

So you can be four hours into the audio and sixty percent through the text, and neither one moves the other. The book's detail screen in each section offers a jump to the other, because hunting for the same title in a different part of the app would be silly.

Playing things your phone can't normally open

A lot of video — most television, a good deal of film — is stored in formats an iPhone won't open by itself. Castaway carries its own player for those, so they play on the phone rather than making your server convert them. See Why Won't My Film Play? for what this changes.

What's stored where

Nothing meaningful is stored only on your phone.

• Progress, played state, and reading position live on Audiobookshelf. Your phone caches them and writes back.
• Watched state and playback position for video live on Plex, and sync both ways.
• Music favorites and playlists live on Plex, with one exception noted in the Music help.
• App settings sync through iCloud, so your phone and iPad agree.
• Downloads and cover art are local only, and regenerable — deleting them costs you nothing but bandwidth.

The drawer

Tap the menu button at the top left of any screen to slide out the drawer. It lists your libraries — podcasts, audiobooks, ebooks, music, movies, TV shows, radio and live TV — then, below a divider, the things that aren't libraries: Downloads, History, Favorites, Bookmarks, Requests, Stats, Help and Settings.

You can reorder the libraries and hide any you don't use, under Settings → Appearance. Each row can also carry a live count of your choosing underneath it.

Downloads and Stats sit here rather than inside a library because they span all of them. Downloads used to live separately in each section, which meant several places to look when the phone was full.

The Podcasts row shows a live unplayed count, or "All caught up" when there isn't one. The other library rows don't, because "how many audiobooks do you own" isn't a number that needs watching.

There is deliberately no edge-swipe to open the drawer. It was built, and then removed — a gesture that captures the left edge of every screen fights with horizontal scrolling and with the reader's page turns, and it caused a genuinely maddening dead-zone bug. The button is the only way in.

Swiping right-to-left anywhere on the open drawer closes it, as does tapping the dimmed area beside it.

Tab bars

Each section has its own tab bar along the bottom.

• Podcasts — Podcasts, Up Next, Playlists, Discover, More
• Audiobooks — Books, Listening, Series, Authors, More
• Ebooks — Books, Reading, Series, More
• Music — Music, Browse, Playlists, Discover. The queue and everything downloaded are pinned rows at the top of Playlists.

Switching sections keeps each one exactly where you left it. All tabs stay mounted, so returning to a section doesn't reload it or scroll it back to the top.

Why the bottom bar collapses

Scroll down and the tab bar shrinks; scroll up and it comes back. That's to give long lists the full screen without hiding navigation permanently.

Tapping the icon of the tab you're already on scrolls that screen back to the top.

Screen titles

Each screen's title sits in a rounded pill below the navigation bar rather than in the bar itself. That's a styling choice for the frosted-glass look, and it's why the title scrolls away with the content instead of staying pinned.

The mini player

When something's playing, a compact bar sits above the tab bar showing artwork, title, and transport controls. Tap it to open the full player.

It follows you across sections, so audio started in Podcasts keeps showing while you're browsing Music or reading. The Ebooks section has no player of its own — reading isn't audio — but the mini player still appears there if something's playing.

Only one thing plays at a time. Starting a track in Music pauses an audiobook, and starting a film pauses both. Every engine pauses every other, which sounds obvious but wasn't always true.

The mini player's background is the artwork, blurred. That artwork is drawn much larger than the bar and clipped to fit — and clipping affects only what you see, not what receives taps, which is why the blurred layer explicitly ignores touches. Without that, it swallowed taps across a wide band of the screen.

Now Playing

Tap the mini player to open the full-screen player. Each audio section has one, and they share a family resemblance: artwork, title, scrubber, one row of transport controls, then a tabbed information area below. Video has its own full-screen player instead, with no mini player — a film isn't something you keep half-watching while you browse.

The scrubber is draggable and tappable. In Podcasts and Audiobooks it carries chapter tick marks where the source provides chapters, and tapping a mark jumps to that chapter.

The information tabs

Below the transport row, an underlined tab bar switches between panels without leaving the player.

• Podcasts — show info, show notes, chapters, bookmarks, details
• Audiobooks — chapters and bookmarks
• Music — artist information, similar artists, and live lyrics

Tabs switch by tapping or swiping sideways.

Swiping took three goes to get right. An early paging container broke the scrubber's layout badly, because it imposed its own sizing on everything inside it. The fix was the blurred background: applied as a background modifier rather than as a stacked sibling layer, it no longer influences how the rest of the screen is measured.

Transport controls

One row, left to right. In Music: shuffle, previous track, back fifteen seconds, play/pause, forward fifteen seconds, next track, repeat.

Podcasts and Audiobooks use your configured skip amounts rather than a fixed fifteen seconds, and they're set separately for the two sections — thirty seconds suits a book where ten suits a podcast.

The second row (Music)

Under the transport row, the Music player has three more controls: favorite, download, and Up Next.

They're a separate row on purpose. The seven controls above are all playback navigation; these three change what the track is to you. Podcasts and Audiobooks use the same split.

The download button shows a spinner while downloading and fills in once the track is on the device.

On the lock screen

While something's playing you get a Live Activity — a card on the lock screen and, on phones that have one, the Dynamic Island. It shows what's playing, a progress bar, and skip back / play / skip forward.

It works for all three players, with a different icon each so you can tell at a glance which is going. Turn it off in Settings → Lock Screen.

The numbers tick along on their own between updates rather than being pushed every second. iOS strictly limits how often a Live Activity may update, and one that spent its budget would freeze for the rest of the episode.

The Podcasts tab shows everything you subscribe to on Audiobookshelf.

Sorting and layout

The "..." menu at the top right controls both.

Sort by — recently played, recently added, title, unplayed count, or a manual order you drag into place yourself.

Layout — grid or list. Grid is artwork-led; list adds episode counts and detail beside each cover.

Both settings persist and sync through iCloud.

The unplayed badge

Each cover carries a count of unplayed episodes in a filled circle at its top right. It updates live — marking an episode played, finishing one, or a background refresh finding new episodes all redraw it immediately, with no pull-to-refresh needed.

You can turn the badge off in Settings → Podcast Settings if a high number on a show you're deliberately behind on bothers you more than it helps.

Adding and removing

Adding is done from the Discover tab.

Removing a subscription isn't possible from this app — that's an Audiobookshelf server operation, and doing it from a client risks deleting a library you meant to keep. Use the Audiobookshelf web interface.

Per-podcast settings

Tap into a podcast, then the "..." menu in its header. That sheet holds overrides that apply to that show only — playback speed, skip amounts, trim silence, volume boost, skip intro and outro, auto-download, and how many downloads to keep.

Anything you set there beats the global default in Settings. If a setting seems not to be taking effect, check here first — see the "What Overrides What" topic.

Pull to refresh

Pull down on the library to re-fetch from the server. The app also refreshes on its own when it regains a network connection, and periodically in the background.

The Discover tab is where new subscriptions come from.

Search

Type a show name. Results come from Apple's podcast directory, not from your server — you're looking for shows you don't have yet.

Tapping a result opens a preview: artwork, description, recent episodes, and the feed URL. Nothing is added until you say so.

Charts

Below search, the top podcast charts. The picker switches between chart types, and tapping a category filters the chart by genre rather than opening a separate browse screen.

Adding a show

From the preview sheet, add the podcast. The app resolves the RSS feed URL through Apple's lookup service and asks your Audiobookshelf server to create the podcast in your podcast library.

Immediately afterwards, a download-options sheet appears, offering to backfill recent episodes and to set auto-download for future ones. You can skip it and set both later from the podcast's own settings.

Why it sometimes finds nothing

Apple's directory is the search index. A private or self-hosted feed won't be in it. There's no add-by-URL field in this app — adding an arbitrary feed is best done from the Audiobookshelf web interface, which is also where you'd manage the library folder it lands in.

The episode row

Each row shows the title, publication date in US format with Eastern times, the runtime, and a progress bar once you've started it.

Icons on the row indicate downloaded, played, and in-progress states. A dedicated play button starts the episode without opening it — tapping the row itself opens the episode detail instead.

Descriptions

Episode descriptions are HTML in the feed and are stripped to plain text for display. Tap one to expand it in full.

Swipe actions

Swipe a row left or right for a quick action. Both directions are configurable in Settings → Podcast Settings → Episode Row Swipe Actions — mark played or unplayed, download, delete download, add to Up Next, play next, or add to a playlist.

Marking several at once

Long-press an episode to enter multi-select, then tap others and mark the whole set played in one action.

The podcast header's "..." menu also offers "mark all played", which asks for confirmation first — it's not undoable in one step.

Sorting

Each podcast remembers its own sort order, set from the sort icon in its header. That's per-show, so a daily news podcast can run newest-first while a serialized narrative runs oldest-first.

About durations

Some episodes arrive from the server with no duration. When that happens the app measures the file itself during playback and caches the result, which is why a runtime can appear on an episode that previously showed none. It also falls back to reading durations directly from the RSS feed when the server hasn't scanned them yet.

Up Next is the play queue — a working list, not a view of your library. It's the first row on the Playlists tab, above All unplayed, and the number beside the Playlists icon in the bottom bar is how many episodes are waiting in it.

How things get in

Three routes, two of them automatic:

• You add them — from an episode's row menu, "Play Next" puts it at the top and "Add to Up Next" puts it at the bottom.
• Switching episodes — if you leave an episode partway through and start something else, the one you abandoned is queued so you don't lose it. Controlled by "Queue paused episodes automatically" in Settings → Podcast Settings → Up Next.
• In-progress seeding — episodes you're partway through, according to the server, are added once so a fresh install or a new device picks up where you were. Controlled by "Add in-progress episodes automatically".

The currently-playing episode is never queued behind itself, and anything marked played elsewhere drops out of the queue automatically.

How things leave

Finishing an episode removes it and, if "Auto-play next in Up Next" is on, starts the next one.

Swipe to remove manually. To reorder, press and hold a row and drag it — there's no Edit button to tap first, and the handle on the right of each row is just a reminder that dragging works.

Where it lives

The queue itself syncs through iCloud, so it's the same list on your phone and iPad. It's one of the few things in this app that isn't stored on Audiobookshelf — the server has no concept of a queue.

Playing from the top

The large play button at the top of the queue starts playback from the first item rather than resuming whatever was last playing.

Playlists here are real Audiobookshelf playlists — created, edited, and stored on your server, so they're the same lists in the web interface.

Making one

The "+" button on the Playlists tab creates a playlist and opens a track picker so you can fill it immediately.

Add episodes later from any episode row's menu, or from the podcast detail screen.

Reordering

Tap Edit on a playlist to get drag handles. Reordering writes back to the server.

Smart playlists

A smart playlist adds episodes automatically based on rules rather than by hand — for example, everything unplayed from a set of shows, or anything added in the last two weeks.

Rules are evaluated by the app, not the server. That means a smart playlist stays current as long as the app runs and refreshes; it isn't a server-side feature that keeps working when your phone is off.

The virtual playlists

Two entries aren't real server playlists at all:

• All unplayed — every unplayed episode across every subscription, assembled on the fly.
• Favorites — episodes you've hearted.

Both are pinned and behave like playlists for playback purposes, but they don't exist on Audiobookshelf and can't be edited there. They're computed fresh each time you open them.

Downloads let episodes play with no network, and they're what makes trim-silence work at all.

Downloading

Download a single episode from its row menu or swipe action. A podcast's "..." menu offers Download all unplayed for the whole show.

Transfers use a background session, so they continue when the app isn't in the foreground and survive it being suspended.

Auto-download

Turn on "Auto-download new episodes" in Settings → Podcast Settings → Downloads for a global default, or override it per podcast. New episodes found during a refresh download automatically.

Limits

Maximum downloads to keep caps how many downloaded episodes a podcast holds. When a new one arrives and the cap is reached, the oldest downloaded episode is deleted. Set globally, overridable per podcast. Zero means no limit.

Wi-Fi only blocks downloads on cellular. Global only — there's no per-podcast version, because the constraint is about your data plan, not about any particular show.

Delete when finished

Off by default. Switch it on under Settings → Podcast Settings → Downloads, and finishing an episode deletes its downloaded file. The episode stays in your library and on the server; only the local audio goes. That's what stops a heavily-subscribed phone filling up.

"Finished" means any of the ways an episode gets marked played — reaching the end, or marking it yourself from the player, the episode list, or a bulk action. It's the same rule everywhere, so the setting doesn't behave differently depending on how you got there.

Individual podcasts can override it, so a show you keep can hold on to its episodes while everything else clears itself.

This is separate from Max downloads to keep above it, and they do different jobs. That one caps how many a podcast hoards and removes the oldest when the cap is passed — which can throw away something you haven't heard. This one only ever removes episodes you're done with, however many there are.

Audiobooks have their own version of this, under Settings → Audiobook Settings, called "Delete after finishing".

Managing what's stored

Drawer → Downloads → Podcasts lists every podcast with downloaded episodes. Tap a row to expand it and see the individual episodes; the trash icon deletes independently of the expansion.

Why some features need a download

Trim silence analyzes the entire file before playback to find the quiet stretches. That requires the whole file on disk — you can't sensibly decide whether to skip a gap using only the few seconds that have buffered. Streamed episodes play with trim silence quietly inactive rather than half-working.

Chapters

Where a podcast provides chapters, they appear as a tab in Now Playing and as tick marks on the scrubber. Tap a chapter to jump to it. The current chapter's title also shows under the episode title.

Skip back and forward become chapter-aware at chapter boundaries, so a skip near the start of a chapter lands at the chapter start rather than an arbitrary number of seconds earlier.

Bookmarks

Drop a bookmark at the current position from the Now Playing bookmarks tab. Bookmarks are per-episode and listed with their timestamps; tap one to jump back.

Drawer → Bookmarks collects them across all episodes, and across every library that has them.

Favorites

Heart an episode to favorite it. Drawer → Favorites lists them, and they double as a virtual playlist.

History

Drawer → History is a chronological record of what you listened to and when, built from playback sessions rather than from progress records — so it reflects actual listening, not just position changes.

Stats

Drawer → Stats summarises listening and reading time across every library, not only podcasts.

Worth knowing: this app opens a real Audiobookshelf playback session when you play something and syncs elapsed time back to it. That means your listening also lands in Audiobookshelf's own statistics, not just this app's. Your server's numbers stay correct whether you listened here or in the web player.

Audiobooks reads the book-type library on your Audiobookshelf server — the same library the Ebooks section reads. A title with playable audio shows up here; a title with only an EPUB or PDF shows up only in Ebooks; a title with both appears in each.

Books

The main shelf. Covers carry markers for what you've done with them:

• In progress — a progress bar across the bottom of the cover
• Finished — a green checkmark, dimmed artwork, sorted to the bottom
• Downloaded — a badge on the cover

Your existing progress and finished states come straight from the server on first load. Nothing needs re-marking after installing.

Listening

Books you're partway through, so you don't have to find them on the main shelf.

Series

Books grouped by the series they belong to, with the series artwork and a percentage showing how much of the whole series you've listened to. That percentage is time-weighted — a series with one short book and one long one weights them by duration, not by counting books equally.

Series membership and sequence numbers come from Audiobookshelf's own metadata. Where a series name arrives as something like Harry Potter #3, the sequence is parsed out of it.

Authors

Books grouped by author.

The book detail screen

Cover, metadata, and a chapter list. Chapters you've already listened past carry a checkmark, so a book you're mid-way through shows you where you are at a glance.

If the book is also an ebook, there's a link across to reading it — and the reading position is tracked entirely separately from the listening position.

One timeline, many files

Your audiobooks are multi-file — a book might be twenty MP3s. Audiobookshelf stores position as a single number of seconds into the whole book, and so does everything you see here: the scrubber, chapter starts, saved progress.

The app maps between the two. Each file knows where it begins on the book-length timeline, so a position of four hours resolves to "file seven, twelve minutes in". Crossing a file boundary during playback loads the next file and continues, which is why the scrubber never resets partway through a book.

Chapters

Chapters come from the server's metadata and appear as a tab in Now Playing and as tick marks on the scrubber. Tap to jump.

Skip and resume

Audiobooks have their own settings, separate from Podcasts. The defaults reflect the difference: thirty-second skips rather than ten, and a resume rewind that scales with how long you were away — coming back after a week rewinds further than coming back after lunch, because you've lost more context.

Your server's statistics

Playing a book here opens a real Audiobookshelf playback session and syncs listened time back to it. Your listening counts toward Audiobookshelf's own stats exactly as it would in the web player.

This is why closing the app mid-chapter doesn't lose the position — progress is written on pause, on switching books, and periodically during playback, not only at the end.

Bookmarks

Drop a bookmark at the current position from the Now Playing bookmarks tab. Positions are stored against the whole-book timeline, so they survive regardless of which file they fell in.

Only one thing at a time

Starting music or a podcast pauses the audiobook. This was briefly not true — music would play over an audiobook — and it's fixed.

Audiobook downloads are whole-book. There's no per-file or per-chapter option, because a book with half its files present is a book you can't listen to.

Downloading

From a book's detail screen. Transfers run in a background session, so they continue when the app isn't in the foreground.

These are large. A long book across twenty files can run to several gigabytes, and the download screen shows the size before you commit.

Managing storage

Drawer → Downloads → Audiobooks lists what's on the device so you can delete individual books.

Deleting a download removes only the local audio. The book stays in your library and your position stays on the server, so re-downloading picks up exactly where you were.

Automatic downloading and deleting — both off by default

Under Settings → Audiobook Settings → Downloads:

• Download next in series — when you finish a book that's part of a series, fetch the next one ready for you.
• Delete after finishing — remove a book's local audio once you've finished it. The book, and your position, stay on the server.
• Keep at most N books offline — a cap, with the oldest removed when it's passed. Zero means no limit.

All three start switched off, and that's deliberate. Podcasts are disposable and arrive constantly; an audiobook is a considered choice, and a several-gigabyte transfer is not something that should happen without you asking. Switch them on if the trade suits you.

Podcasts have their own equivalents, under Settings → Podcast Settings, named slightly differently — "Delete when finished" there against "Delete after finishing" here.

Ebooks reads the same book library on Audiobookshelf that Audiobooks does, selecting on a different axis: anything with an ebook file, whether or not it also has audio.

Books

The main shelf. Covers carry:

• Reading — a filled circle badge at the top left with the same glyph the Reading tab uses, plus a progress bar across the bottom
• Finished — a green checkmark badge, dimmed artwork, sorted to the bottom
• Format — a small badge for anything that isn't a plain EPUB, so an unsupported file says so on the shelf rather than at the moment you try to open it

Reading

Books you're partway through.

Series

Ebooks grouped by series, derived from each book's own metadata.

The book detail screen

Full cover artwork, the title and author line, then a Read or Continue Reading button. Below it, your progress as a percentage and a bar.

Under that, three tabs:

• About — the synopsis
• Details — published year, publisher, genres, series and sequence, narrator, format, ISBN, file size
• Author — other books by the same author in your library. Audiobookshelf doesn't store author biographies, so rather than leave the tab empty this links to what you actually own.

If the book is also an audiobook, there's a row offering to switch to listening. The two positions are independent.

At the bottom, storage — whether the file is on this device and how large it is.

About "finished"

Audiobookshelf has no explicit finished flag for reading the way it does for listening. So finished here means ninety-nine percent or more. The last one percent is back matter — acknowledgements, about-the-author, advertisements — which means a book you've genuinely finished rarely reaches the literal last page.

Turning pages

Tap the left third of the screen to go back a page, the right third to go forward. Tap the middle third to show or hide the reader's controls.

Swipe left or right to turn pages.

Both work past the end of a chapter — running off either edge loads the adjacent chapter rather than stopping dead, which is what makes a book feel continuous despite being a series of separate documents.

Pinch

Pinch to change the text size. Note this changes the font size, not zoom — zooming a paginated layout would break the column arithmetic the pagination depends on, so the gesture reflows the text instead. Clamped to the same range as the settings slider.

Appearance

The controls give you theme, font family, font size, and line height. Themes cover light, sepia, and dark.

Theme colors are applied forcefully. Book stylesheets routinely set colors directly on paragraphs and headings, and any such rule beats an inherited body color — which is why an earlier version left text nearly unreadable on some books and fine on others.

Contents

The contents list is built from the book's own navigation — EPUB 3 navigation documents or EPUB 2 NCX, whichever the book ships. Entries are marked read, current, or unread.

Tapping an entry jumps there, including to a point mid-chapter where the entry points at one.

Your position

Position is saved as you read and written back to Audiobookshelf, so picking the book up on another device continues where you left off.

PDFs

PDFs open in a separate viewer built on PDFKit rather than the EPUB reader. Paging and position saving work; the appearance settings don't, because a PDF is a fixed layout with no reflowable text to restyle.

Keeping the screen on

There's a setting to stop the screen dimming while reading. It's off by default.

What opens

• EPUB — fully supported, reflowable, themed, paginated.
• PDF — supported through a separate PDFKit viewer. Fixed layout, so no font or theme control.
• MOBI / AZW / AZW3 — not supported. These appear on the shelf with a format badge and their detail screen explains why rather than offering a button that does nothing.

MOBI is a proprietary Amazon format with no usable open parser on iOS. Converting them to EPUB on your server with Calibre is the practical fix.

How the format is detected

Audiobookshelf reports the format inconsistently — sometimes a bare extension, sometimes a MIME type, sometimes only a filename. The app tries each in turn. If everything showed as "Unknown" at some point, that was this detection being too strict.

Downloading and storage

Opening a book downloads its file once and caches it. Ebooks are small — a few megabytes — so this is a plain fetch rather than the background-session machinery audiobooks need.

Files are stored in Application Support rather than Caches. iOS can purge Caches under disk pressure, and a book you deliberately downloaded to read offline shouldn't vanish precisely when you have no signal.

Managing what's stored

Drawer → Downloads → Ebooks shows the count and total size, and lists every cached book with its individual size and a delete button. The book detail screen also has a storage row at the bottom.

Deleting asks for confirmation. Your reading position stays on the server either way — the book simply downloads again next time you open it.

The reader can speak an EPUB aloud, highlighting each word as it goes and turning the page itself.

It's off by default. Switch it on under Settings → Ebook Settings → Read aloud, and a play button appears in the reader. Leaving it off means no button, which is the point — a control you'll never use shouldn't sit in a reading screen.

What it uses

The speech voices already installed on your iPhone. Nothing is sent anywhere, and it works with no connection at all.

Choosing a voice

Once the feature is on, a voice picker appears under the same setting. It lists what's installed on this device and nothing more.

This matters, because the default voices are noticeably worse than the ones Apple ships separately. An app cannot download or install speech voices on your behalf — that only happens in:

iOS Settings → Accessibility → Read & Speak → Voices

Look for the ones marked Premium or Enhanced. They're a few hundred megabytes each and they are a large improvement over the default. Download one there, come back, and it appears in the picker.

Your choice of voice is kept on this device rather than synced, because a voice you've downloaded here may not exist on your iPad.

While it's reading

• Each word highlights as it's spoken.
• The page turns itself at the end.
• Tapping the button again stops it.

The highlight is drawn over the text rather than inserted into it, so nothing on the page moves or reflows while it reads.

Does it count as reading?

Yes. Time spent listening to a book read aloud is counted into Stats exactly as time spent reading it is.

That's a deliberate choice rather than an accident of how it's measured: a book you got through is a book you got through, and nothing else in the app distinguishes reading a thing from being read to. Long pauses are capped the same way they are for reading, so a phone left face-up on a table doesn't quietly inflate anything, and backgrounding the app ends the session.

What it won't do

• PDFs. EPUB only — a PDF has no reliable text flow to follow.
• Play in the background. Reading aloud stops when you leave the reader. It's a reading feature, not a substitute for the audiobook.
• Replace an audiobook. If a title has audio on your server, the Audiobooks section will always sound better.

Music is the one section that has nothing to do with Audiobookshelf. It reads your Plex server directly.

Signing in

Drawer → Settings → Servers & Accounts walks through it. Authentication uses Plex's own PIN flow rather than asking for your password — the app requests a code, you approve it with Plex, and the app receives a token.

That token is stored in the iOS keychain, not in preferences.

Picking a library

Once connected, choose which Plex library is your music. If you have only one music section it's selected for you.

Before you connect

Until a server is connected, the Music section shows a "connect your server" placeholder instead of the tab bar. Everything else in the app works normally without Plex.

How the app identifies itself

Your Plex server sees this app as a client named after the app, and it appears in Plex's authorized devices list. Playback from here shows up in Plex's activity like any other client.

Artwork and memory

Cover art is fetched at source resolution and downsampled on the device rather than going through Plex's photo transcoder. That sounds backwards, but the transcoder route was causing serious memory pressure — large grids of transcoded images were the single worst offender in the whole app.

Music

The first tab is shelves of your own listening rather than a wall of artists: what you played recently, what's newly added, what you play most, the artists behind it, and your playlists. It fills in as you listen.

Browse

Your whole library, as artists, albums or the folder tree.

The chevron beside the Browse tab switches between the three — the same control the first tab uses to switch libraries. The screen title says which one you're in.

The filter icon in the top bar holds sorting, layout, and the filters — it shows a small dot while any filter is on.

Artist pages carry a description where Plex has one — tap to expand it — plus Play All and Shuffle All.

Album pages have a transport row in the header so you can start the album without picking a track — the same five controls, in the same order, as the Now Playing screen.

The heart and the download button sit either side of the album title, again matching Now Playing. The download button takes the whole album offline. The ⋯ button in the top right holds Add All to Playlist.

The heart is the only album-level favorite control, and it has three states: empty (nothing here is favorited), a circled heart (some tracks are), and filled (all of them). Tapping a circled heart favorites the rest; tapping a filled one removes only the tracks the heart added, leaving anything you hearted individually alone.

Track rows

Each row has a play button and a heart. A track that's currently playing shows an animated indicator.

Long-press for a menu, or swipe. Both swipe directions are configurable in Music settings — favorite, play next, add to queue, or add to a playlist.

Discover

Search, plus Plex's own genre and mood tags over your real library. The shelves of your own listening moved to the first tab; this one is for turning up something you weren't already thinking of.

Below those, the Apple Music charts as plain text — top songs, albums, and music videos, with a picker to switch between them. This is a "what's out there" list rather than anything connected to your library; nothing in it is playable here.

Search

Searches your Plex library across artists, albums, and tracks.

Badges while browsing

Artists and albums can carry two small badges on their artwork.

• A pink heart — something in here is favorited.
• An accent-colored arrow — something in here is downloaded.

Both mean "some of this," not "all of it." Favorites are per-track, and knowing whether an album is completely downloaded means loading its full track list, which doesn't happen until you open it. The album and playlist headers, which do hold the track list, make the stronger claim: their download button fills in only when everything is local.

Songs with no album

A file with no album tag still has to live somewhere in Plex's artist → album → track structure, so Plex invents one container per artist to hold them. Those aren't records — no cover, no year, nothing in common between the tracks except who made them.

They now appear as a Songs Not In Albums list on the artist's page, below their albums and singles.

The Albums grid hides the containers by default. Browse → Albums → filter → Show Untagged Songs brings them back, and the number beside it is how many artists have songs like this — a quick answer to "how much of my library is untagged?" without turning the filter on. Each card names the artist it belongs to, since the title is the same on all of them.

An artist you know you own, missing from Artists

Plex builds its artist list from each file's Album Artist tag, not the track artist. A song whose Album Artist says "Various Artists" — common on compilations and on loose files — belongs to no artist as far as Plex is concerned, so there's nothing for the Artists list to show.

Castaway fills that gap itself. It reads the track credits across your whole library, works out which performers have no artist in Plex, and adds them to Browse → Artists alongside everyone else. They carry a small marker so you know where they came from.

Their page is a list of their songs, with Play All and Shuffle. There's no discography, no bio and no album grid — not an omission, just that Plex has none of it to give.

This runs once by itself when you first connect Plex, and never on a timer: it reads every track in the library in one pass, which is quick but not something to repeat in the background. After you add music or fix tags, Music Settings → Missing Artists → Scan Now brings it up to date. The same section has the switch to turn the whole thing off.

Two other ways to reach that music:

• Search finds the tracks by performer name, and on a compilation you can tap the artist under a track to search for them.
• Browse → Folders shows your library the way it sits on disk, so a folder named after the artist is right there regardless of tagging.

The permanent fix is on the server: set the Album Artist tag on those files and rescan. Plex will create the artist properly, with albums and everything else, and they'll appear like anyone else.

Favoriting a whole album

The heart in an album's header favorites every track on it. A filled heart means all of them; a circled heart means some, and tapping it finishes the job.

Tapping a filled heart removes only the tracks that heart added. Songs you favorited one at a time stay favorited — un-favoriting an album is meant to undo the bulk action, not wipe the record.

Downloaded Only

The filter menu has a Downloaded Only option, which narrows the list to what's on the device.

It resets every launch, deliberately. A filter that hides most of your library and survives a relaunch is how you come back a week later convinced your music has vanished. The filter icon carries a dot while it's on.

The Downloaded screen

Music → Playlists → Downloaded lists everything offline, grouped by album, with play and shuffle. It works with no server connection at all — that's the point of it.

Storage management stays in Drawer → Downloads.

Adding a Last.fm key

Some Music features use Last.fm to fill in what Plex doesn't know. It's optional and free.

Get a key at last.fm/api, then paste it into Settings → Music Settings → Popular Tracks. It's stored in your keychain and only ever used for lookups.

That section also shows the result of the most recent lookup — "Loaded 100 tracks for…", or an explanation if something went wrong. Without that line, a bad key and an obscure artist look exactly the same: nothing appears.

The dots in front of album tracks

On an album, a small mark before some tracks means they stand out. There are two different signals, and they often disagree.

• Filled dot — popular with the world. This is the song on the album, from Last.fm play counts.
• Hollow ring — popular with you, from your own Plex play counts.
• Filled dot inside a ring — both.

They're kept separate on purpose. Merged into one score you'd lose the interesting case: the deep cut you love that nobody else plays.

The personal half works with no key at all. Only the global half needs Last.fm.

Both are relative to the album, not absolute. A play count that's enormous for an obscure record is unremarkable for a stadium act, so a fixed threshold would mark everything or nothing depending on who you're listening to. An album you've played evenly all the way through gets no marks — that isn't a preference, it's just having listened to the record.

Similar artists

The player has a Similar tab, between Artist and Lyrics. It splits into two lists.

• In your library — tappable. Tapping one closes the player and takes you to that artist.
• Not in your library — plain text. There's nothing to open, but on a collection you own, knowing who you're missing is half the value.

Matching is by name, since Last.fm has never heard of your Plex server.

Artist bios

Where Plex has written a bio, you get Plex's. Where it hasn't, the app falls back to Last.fm.

That order is deliberate. Last.fm bios aren't better — they're broader. Plex's metadata agent writes well for artists it recognizes and nothing at all for the rest, and that gap is what the fallback fills. Swapping a good agent-written bio for a community-written one would be a downgrade as often as an upgrade.

Very short Last.fm entries are discarded rather than shown. Two words in place of silence isn't an improvement.

What you're missing

At the bottom of an artist's page, Not In Your Library lists up to six of their well-known albums that aren't on your server.

Titles are matched loosely, so a collector's edition doesn't read as a separate record you don't own. The section disappears entirely when there's nothing to say.

When nothing appears

Every one of these degrades quietly rather than erroring. If a feature is blank:

• Check the status line in Music Settings first — it names the actual problem.
• Obscure artists genuinely aren't in Last.fm's data.
• Track and album matching is by title, so heavily-tagged releases can miss.

The queue

Playing an album or artist builds a real queue. Up Next in the player shows it; drag to reorder, swipe to remove.

"Play next" and "add to queue" are available from any track's row menu.

Shuffle and repeat live on the transport row in the player, at either end.

Playlists

Real Plex playlists — created, edited, and reordered here, and stored on your server.

The "+" button creates one and opens a track picker. Tap Edit for drag handles.

Favorites

Hearting a track marks it as a favorite. It appears as a pinned playlist at the top of the Playlists tab.

Favorites is a real Plex playlist, named "Favorites". It shows up in Plex and Plexamp like any other, and it behaves like any other playlist here too — same header, working download button, drag to reorder.

It used to be a local list, which is why its download button didn't work and its screen looked different from every other playlist. Making it real fixed both at once.

Things worth knowing:

• The heart is instant. Your tap updates the screen immediately and the server call follows behind. Heart things with no signal and they sync when you're back; the pinned row shows "Syncing…" while that's happening.
• The playlist is created when you need it. Plex can't make an empty playlist, so it doesn't exist until your first favorite.
• Delete it in Plex and it comes back on your next heart. That's a reset, not a permanent break.
• Un-hearting never deletes a download. Remove the file in Downloads if you want the space.

Track rows

Every track row has a "..." button with the full set of actions: download, play next, add to queue, add to playlist, favorite.

Those used to be on a long press. They moved because long press is also how you drag a track to reorder a playlist, and the two gestures arbitrated badly — hold still and you got a menu, twitch and you got a drag, with no way to tell which you were about to get.

Reordering a playlist

Long-press a row and drag. There's no Edit button to press first.

The grip on the right is a signpost, not a handle — the drag works on the whole row.

Lyrics

The player's second information tab shows lyrics, fetched from LRCLIB by matching track, artist, and duration.

Where the source provides timed lyrics, they scroll in sync with playback. Where it provides only plain text, you get plain text. Where it has nothing, the tab says so — many tracks simply aren't in the database.

Volume normalization

Normalize volume in Music settings evens out loudness differences between tracks, using real-time audio processing rather than a fixed per-track gain. Useful on shuffle across albums mastered decades apart.

It costs a little battery, which is why it's off by default.

Radio builds endless stations out of your own library. It isn't a streaming service and it won't introduce you to music you don't own — it's a way of listening without having to choose an album.

Radio is a section in the main menu. If you don't want it there, you can hide or reorder it in Settings → Drawer, same as any other library.

The stations

For You — built from what you play most, what you've hearted, and what's arrived recently. This one needs nothing but your own listening history, so it works even if your library has no tags at all.

Genres and Moods — every genre and mood your Plex server has tagged. Plex applies these when it matches your music, so the lists reflect your library rather than a fixed set.

Formats — Live, Remix, DJ Mix, Soundtrack, Spoken Word, Compilation. This one is unusual: most music apps can't offer "play me live recordings" at all, because they don't have the tagging. Plex does.

Artist and song radio — start from something already playing. That begins with the artist and moves outward through artists Last.fm considers similar, limited to ones you actually own. Without a Last.fm key it becomes a shuffle of that artist's own music.

How the queue behaves

A station is endless and visible. The upcoming tracks appear in Up Next exactly like any other queue — reorder them, remove them, skip them — and when the queue starts running low the station quietly adds more.

Stopping the station doesn't stop the music. Whatever's already queued keeps playing; it just stops being topped up. That's usually what you want mid-track.

Why it doesn't repeat much

Two things are happening that you'd notice if they weren't:

• Artists are spaced out. A plain shuffle plays six tracks off one album in a row and feels broken. Radio keeps a gap between tracks by the same artist.
• Each refill re-samples. Rather than shuffling one fixed list forever, the station draws a fresh selection as it goes, so a long listen doesn't loop the same forty tracks.

If a station won't start

"Couldn't find enough music in your library for that station" means exactly that — the genre, mood or format you picked has too little behind it. That's most common with narrow tags like Spoken Word on a library that's mostly albums.

For artist radio specifically: if you don't own anything by the similar artists Last.fm suggests, the station falls back to just that artist. That's not a failure, it's the honest limit of building radio from a personal collection.

If you've connected Lidarr, Castaway can ask it to go and find music for you. Anywhere the app shows you something you don't have — the gaps in an artist's discography, the "not in your library" half of similar artists — there's a request button.

What happens after you tap Request

Castaway walks you through it rather than leaving you at a confirmation:

1. Requesting — the album is added to Lidarr.
2. Searching indexers — Castaway asks Lidarr to search, and watches that search rather than guessing at it.
3. Downloading — with a progress bar, once your download client has something.
4. Unpacking and importing — Lidarr moving the finished files into your library.
5. Added to your library — done.

You can close the window as soon as a download starts. The transfer is running on your Lidarr server, not on your phone, so closing Castaway — or force-quitting it — won't stop anything.

"Nothing grabbed automatically"

This is the commonest outcome and it isn't a failure. Lidarr searched, found nothing it was willing to take, and put the album on its Wanted list. It'll keep trying on its own schedule.

Usually it means every result was below your quality profile, or your indexers had nothing at all. The window offers See what's actually out there, which lists every release your indexers returned — including the ones Lidarr rejected — and lets you grab one by hand.

Why it isn't in Music yet

A finished download is not the same as an album in your library. Once Lidarr imports the files, Plex still has to notice them, and how long that takes is a Plex setting, not a Castaway one. Some libraries scan the moment a file appears; others scan on a timer; some only scan when you tell them to.

If new music takes a long time to show up, that's the setting to look at — in Plex, under your music library's settings.

Getting told when it lands

Turn on new music alerts in Settings → Notifications. Castaway checks both servers periodically and will notify you once Plex has picked the album up. Tapping that notification opens the album directly.

Without alerts on, there's nothing to tell you it arrived — you'd have to go and look.

History

Lidarr Activity has two tabs:

• Active — what your download client is working on right now, including anything stuck. A download that finished but couldn't be imported sits at 100% and looks like success; this is where the real reason shows.
• History — everything you've requested from this device, with a coloured dot each.

A yellow dot on "No release grabbed" isn't a failure — see above. Red means Lidarr genuinely gave up or errored.

History lives on this device only and keeps the 50 most recent requests. It's a record of what Castaway asked for, not a control panel — removing things is done in Lidarr itself.

Requesting an artist instead of an album

Requesting an artist monitors their whole discography, which is a much larger grab than one album, and Lidarr manages it on its own schedule. That one doesn't get the step-by-step window — there's no single download to follow.

Most films and episodes now play straight from your server without it doing any work. This page covers the cases where something else happens.

"Converted by your Plex server as it plays"

This isn't an error — the film plays normally. It's telling you what your server is doing behind the scenes.

You should see this far less than you used to. Castaway carries its own video player, which opens formats an iPhone can't — MKV most importantly, which is how a great deal of television and film is stored. Those now play directly on the phone, with your server sending the file untouched and doing nothing else.

Conversion still happens in two situations:

• The file is unusual enough that neither player can open it. Rare.
• You're sending the picture to a television. See below.

When it does convert, you can set how good the picture should be under Settings → Movie Settings → Converted playback. That setting only affects films that need converting; anything playing directly is always sent untouched at full quality.

Sending it to a television

Playing to an AirPlay device or an external display deliberately uses your server's conversion instead of the phone's own player.

The reason: AirPlay is something Apple's player does and Castaway's own player can't — it draws its own picture rather than handing a video stream to the system. Rather than lose AirPlay, the app asks your server for a stream the television can take. So choosing an AirPlay target may make your server work where playing on the phone wouldn't.

Sound but no picture

If a film plays with audio over a blank or placeholder screen, that's a particular kind of file rather than a broken download or a broken app.

Some tools — including Plex's own optimiser — write HEVC video with a tag Apple's player silently refuses to draw, while playing the sound quite happily. Castaway checks downloaded files for this and hands them to its own player, which doesn't care. If you saw this on an older download, deleting and downloading it again is the fix.

"Needs a Plex subscription"

This one is a limit set by Plex, not by this app.

Since 2025, Plex requires a subscription to stream your own videos when you're away from home. Either:

• the person who owns the server has a Plex Pass, which covers everyone who watches from their server, or
• you have your own Remote Watch Pass, a cheaper subscription that lets you stream from any server you have access to.

Some things worth knowing:

• Music, podcasts, audiobooks and ebooks are not affected. This applies to video only.
• On your home Wi-Fi, it doesn't apply. Films play normally on the same network as the server.
• Downloads aren't affected either. Something already on your device plays without touching the server at all — which is a good reason to download before a trip.
• If it's someone else's server, it depends on them. Their subscription is what decides, and this app can't see it — which is why the status may say it can't tell.

You can see what this app has worked out about your own account under Settings → Movie Settings → Watching away from home, and change it in Settings → Servers & Accounts → Plex Server.

Castaway doesn't charge for anything and doesn't add restrictions of its own. Where Plex limits something, the app tries to say so plainly rather than letting playback fail with no explanation.

"Nothing playable found"

Plex reported the film but no actual video file with it. This usually means the file was moved or deleted on the server but the library hasn't been rescanned, or a download or import didn't finish.

Rescanning that library in Plex normally clears it up.

A live channel won't play

That's a different thing entirely, and it's a known gap rather than a fault with your setup. See Live TV.

Movies reads the movie-type libraries on your Plex server. If you have more than one — a main library and a kids' one, say — you choose which appear under Settings → Movie Settings → Movie libraries. Hiding one here hides it everywhere in the app, including search.

Layouts and sorting

Three layouts: a poster grid, a small grid that fits more on screen, and a detailed list with year, runtime and rating on each row.

Sort by title, year, date added, rating or recently played. Whichever sort you choose, an index rail runs down the right edge so you can jump rather than scroll — it follows the sort, so sorting by year gives you years rather than letters.

Filter by genre, or switch on Hide watched if you're looking for something you haven't seen.

Continue Watching

The first shelf is whatever you're part-way through, and it's synced both ways with Plex. Start something on your television, and it's at the top here with the right position. Stop half-way here, and the television knows.

An item leaves this shelf when you finish it, or when you mark it watched.

A film's page

Under the poster and the Play button:

• About — the summary, and the technical details of the file itself.
• Cast & Crew — everyone Plex knows about, each with their own page.
• Details — resolution, codecs, file size, audio tracks.
• Similar — other films from your own library, not a catalogue of things you don't have.

Tap anyone in the cast for their filmography. Films already on your server are marked and open straight from there; the rest are listed so you can see the gaps. Biographies come from TMDb if you've added a key — see Settings → Servers & Accounts → TMDb.

The badges on a poster

A green downward arrow in the top-right corner means the film is on your device. See What the Badges Mean for the full set, which is the same in every library.

Requesting films not yet in your library

If you run Seerr, the Requests screen lets you ask for films and television your server doesn't have, and shows what's already on the way. With no Seerr address set, nothing about requesting appears anywhere in the app.

The Download button sits under Play on a film's page. Tapping it doesn't start anything — it opens a sheet that tells you how big the file is first.

That's deliberate. A 4K remux can be forty or eighty gigabytes, and a download that begins the instant you touch a button is a download you find out about when your phone is full.

The size, and why it leads

If the file is over about 8 GB, the sheet leads with the number in large type rather than with the button. Below that threshold it's a normal-looking sheet.

The threshold is fixed rather than based on your free space. A warning that changes depending on how much room you happen to have is one nobody can learn.

Asking for a smaller copy

When a film is too large to be worth carrying, the sheet offers Make a smaller version. This asks your Plex server to build one — the app isn't doing the work, and your phone isn't involved.

Some things worth knowing:

• It takes a while. An hour or more is normal, and the app can't speed it up.
• You don't have to wait in the app. Close it, use the phone, come back later.
• You'll be told when it's ready — a notification arrives the next time you open the app, and the film appears under Ready to download at the top of the Downloads screen.
• It's offered once. Once a smaller copy exists, the option disappears, because a second one helps nobody.

The smaller copy lives on your server alongside the original. Deleting it is done in Plex, under the film's version list — not here.

Which copy you're actually getting

The download sheet says so, in words:

• "Optimized copy — the smaller one your server built" — you're getting the small one.
• "Original file — not the optimized copy" — a smaller copy exists but isn't what's about to be fetched. Worth reading if you see it.

Left to itself the app prefers the optimized copy whenever one exists, because that's the only reason it exists. The message is there so you never have to work it out from the number of gigabytes.

While it's downloading

The button becomes a progress bar with a percentage and a ✕ to cancel. Downloads continue while the app is in the background, and survive the app being closed.

Playing what you downloaded

A downloaded film plays from the device. It doesn't touch your server, doesn't need a connection, and doesn't count against the away-from-home restrictions described in Why Won't My Film Play?

If a downloaded film plays with sound but shows no picture, that's a known kind of file rather than a broken download — see that same topic.

Getting the space back

Remove on the film's page deletes the local copy. The Downloads screen does the same, and shows what every library is costing you in one place.

TV Shows reads the show-type libraries on your Plex server. Which ones appear is under Settings → TV Settings → Libraries, the same arrangement Movies uses.

Layouts and what's on a cover

Three layouts — poster grid, small grid and list. On each cover:

• A number is how many episodes you haven't watched. It shows on every unfinished show, including ones you've never started, because "how much am I taking on?" is exactly the question about something unstarted.
• A green tick replaces the number once you've finished the whole show.
• A green downward arrow means some episodes are on your device.
• A hollow ring means an episode has been converted and is waiting to be downloaded — see Downloading Episodes.

The full set of markers, and where each one sits, is in What the Badges Mean.

Shows, seasons, episodes

Tapping a show gives you its seasons; tapping a season gives you its episodes. Each episode row carries its still, its number, how long it runs, and one of:

• a progress bar across the bottom of the still, if you're part-way through it
• a green tick, if you've finished it

An episode that's next up but unstarted shows neither, rather than a bar sitting at zero.

Shows also have the same Cast & Crew and Similar tabs the films do, drawn from your own library.

Continue Watching

The shelf at the top of the section is per episode, not per show, and syncs both ways with Plex. Stop half-way through an episode on the television and it's here, at the right position.

Filtering

Alongside sort and genre, there's a Downloads only filter, which narrows the shelf to shows with something on the device. That's the one to reach for at an airport.

Requesting shows not yet in your library

If you run Seerr, television can be requested the same way films are, from the Requests screen. With no Seerr address configured, none of it appears.

Episodes download one at a time. There's a download control on each episode row in a season, and no button anywhere that takes a whole season.

That's a deliberate limit rather than a missing feature. A season is ten or twenty separate files and, if you asked for smaller copies of them, ten or twenty separate conversion jobs on your server — hours of work started by one tap, with no way to see or stop it from your phone.

Starting one

Tap the download control on an episode row. As with films, this opens a sheet showing the size before anything begins, and offers Make a smaller version if the episode is large.

While it downloads, the row shows a progress bar with a percentage and a ✕ to cancel.

Asking for a smaller copy

Exactly as for films: your Plex server does the work, it takes a while, and you don't have to wait in the app. You'll get a notification the next time you open it, and the episode appears under Ready to download at the top of the Downloads screen.

The sheet tells you which copy you're getting — the optimized one or the original — rather than leaving you to work it out from the file size.

Finding them again

Three places, depending on what you're doing:

• On the show's cover. A green downward arrow means something in this show is on your device. A hollow ring means something has been converted and is waiting for you to fetch it.
• The Downloads-only filter in the TV Shows browse screen, which narrows the shelf to shows with something on the device.
• The Downloads screen, where episodes are grouped by show rather than listed as twenty rows called "Episode 3".

Playing them

A downloaded episode plays from the device — no server, no connection, and none of the away-from-home restrictions that apply to streaming.

Getting the space back

Delete an episode from the Downloads screen, or from the episode's own row. The Downloads screen also shows what TV is costing you against every other library.

Playing a channel isn't working yet. Everything else in this section does. The app says so on a banner at the top of the screen rather than letting you find out by tapping a channel, and this page explains what's going on.

What you need

This is the one part of Castaway with a hardware requirement: a tuner attached to your Plex server, plus Plex's guide data. If your server has no tuner, the section shows a message saying so and there is nothing to set up.

What works

• The channel lineup — every channel your tuner picks up.
• What's on now, across the guide, arranged in shelves.
• Search, across the lineup and the guide together. It's entirely local: the whole lineup is already on your phone, so results appear as you type.
• Tuner status. If everything in the house is watching or recording, the app says "all tuners in use" rather than failing with no explanation. A tuner is a scarce physical thing and running out of them is a normal condition, not a fault.

That's genuinely useful on its own — it answers "what's on?" without opening Plex.

What doesn't

Playing a channel. Tapping one starts the sequence and it fails at the last step.

To be precise about it, because the failure is an odd shape: your server accepts the request and hands back a working session. The transcode starts. Then the request for the actual stream is refused, and only that request. From outside it looks like the app failing, which is why the banner exists.

This has had several rounds of investigation and isn't solved. Watch live in Plex meanwhile — the same channels, the same tuner.

Why the section ships at all

Hiding it would throw away the guide, the lineup and the search to avoid admitting the last step is missing. Shipping it silently would mean you discovering the gap by tapping something. Saying so plainly seemed better than either.

Not built

Recording. Your server advertises the ability, so it's reachable whenever it's wanted, but it's a project of its own and hasn't been started.

Small markers appear on artwork throughout the app. They mean the same thing in every library and sit in the same corner, so you only have to learn them once.

The corners

Top right — what you have.

When two apply, downward arrow sits on top and the tick or number beneath it. That order is fixed on purpose: "is this on my device" keeps one position regardless of how far through you are, so it isn't somewhere different each time you look.

Top left — what's new. The NEW flash, and nothing else competes with it. How long something counts as new is per library, under Settings → New Badges.

Bottom left — one thing specific to that library. A heart in Music, the format tag on an ebook that isn't an EPUB, a book glyph on one you're part-way through.

Across the bottom — how far through. A progress bar, never a badge.

Section by section

• Podcasts — unplayed count.
• Audiobooks — downloaded, finished, NEW, and a progress bar with the time remaining under the title.
• Ebooks — downloaded, finished, NEW, plus a format tag (PDF, MOBI) on anything that isn't a plain EPUB, and a book glyph while you're part-way through one.
• Music — downloaded on an artist or album means some of it is on the device, since downloads are per track. The heart means something in there is a favourite, for the same reason.
• Movies — downloaded.
• TV Shows — downloaded means some episodes; the number is episodes left; a hollow ring means an episode has been converted and is waiting to be downloaded.
• Live TV — none. Channels aren't things you own.

Two that look similar

On TV shows specifically:

• Filled green arrow — already on your device.
• Hollow ring — converted on your server and not yet fetched.

Ready versus here. The hollow one is the one with something to do.

Why they're all the same size

They didn't used to be. An audit found five different sizes across three different constructions, which is what happens when six screens each solve the same problem. There's one now: 21 points, a filled shape, a white glyph, a shadow so it reads over any artwork.

The same applies to position. Screens no longer choose a corner — they state what's true about an item, and one shared piece of code decides where each marker goes. It's why the meanings above hold everywhere rather than mostly.

One screen for everything offline

Drawer → Downloads shows what's on this device across every library. It used to live separately inside each section, which meant several places to check when the phone was full and no way to see the total.

The card at the top gives the combined figure, with a segmented bar showing how it splits between podcasts, audiobooks, ebooks, music, films and TV. Below that, a picker switches to one library at a time.

Ready to download

If anything sits at the top of this screen under Ready to download, it's a film or episode your server has finished converting at your request and you haven't fetched yet. Tapping a row opens the item; the ✕ dismisses it if you've changed your mind.

It's here because a notification is a single moment — miss it, or have notifications off, and the fact that a conversion finished is gone. This is where that fact lives instead. Rows clear themselves once you download them.

On the device vs. the whole library

Each section shows two numbers, and they mean different things.

• On this device — actual bytes on disk, measured. This is the number that matters when you're freeing up space.
• Library size — how big the whole thing is on your server, if you downloaded all of it.

The music library figure isn't fetched automatically — it means walking every track on the Plex server, so there's a button to calculate it when you want it. The Audiobookshelf figures come back with the library listing, so they're already there. If a figure shows as a dash, your server didn't report a size for those items.

Managing what's stored

Rows expand to show individual files with their own sizes. Tapping a row expands it; the trash button works independently, so you can delete a whole podcast's downloads without expanding it first.

Deleting a download never touches anything on your server. It's a local file, and the item stays in your library.

Films and episodes

Video downloads work differently from the rest, because the files are so much larger.

• Tapping Download opens a sheet first, showing the size before anything starts. Above about 8 GB the sheet leads with that number.
• Where a film or episode is too big to be worth carrying, you can ask your server to build a smaller copy — see Taking Films Offline and Downloading Episodes.
• The sheet says which copy you're getting, in words, rather than leaving you to infer it from the size.
• Episodes are grouped by show here, rather than listed as twenty rows called "Episode 3".

A downloaded film or episode plays without touching your server — which also means the away-from-home subscription limits don't apply to it.

Music downloads

Music downloads the original file, not a transcode. A lossless album is exactly as large on your phone as it is on your server. That's deliberate — you asked for it offline, so you get the version you have.

Two ways to get music onto the device:

• The download button on any album, playlist, or Favorites header. It fills in and turns your accent color once everything in that list is local.
• Automatically when you favorite something, if you've turned that on in Settings → Music Settings. It's off by default. This covers the album heart as well as a single track's, so one tap can start a whole album downloading.

Removing a heart from a track deliberately does not delete the file. Un-favoriting is a light action, and having it silently throw away a download you might be relying on offline would be a nasty surprise. Delete it here instead.

Finding what you've downloaded

This screen is about storage. If you want to play what's offline, Music → Playlists → Downloaded is the browsable version — same files, organized for listening, with play and shuffle rather than delete.

While you're browsing Music, a small arrow badge on an artist or album means some of it is on the device. The Library tab's overflow menu also has a Downloaded Only filter.

What you've been doing, across everything

Drawer → Stats covers every library in one place rather than separate tallies that never add up to anything.

You get totals, a per-day chart, top items by section, and streaks.

Where each number comes from

The libraries know different amounts about themselves, and the screen says so rather than pretending otherwise.

• Podcasts and audiobooks — from Audiobookshelf's own listening sessions. The server records real playback, so these are measured.
• Ebooks — from a local reading timer. There's no server-side equivalent for reading, so the app times it here.
• Music — from Plex play counts multiplied by track length. Plex counts plays, not seconds, so this is an estimate.
• Movies — from Plex's watched state and each film's runtime. A film you're part-way through counts the position you actually reached rather than its whole length, which is the one figure on that card that isn't a multiplication.

• TV Shows — episodes watched, multiplied by the show's typical episode length. Rougher than the others, for a reason worth knowing: Plex tells the app how many episodes of a show you've seen, but not how long each one ran. A show with a feature-length finale, or one that changed episode length partway through, will be off.

Unlike a film, a part-watched episode contributes nothing — being half-way through one episode of a sixty-episode run is a rounding error, whereas being half-way through a three-hour film isn't.

The confidence badges

Every figure carries one of three labels, and they're worth reading.

• Measured — the source recorded actual playback time.
• Estimated — derived from something else, like play count times duration. Close, not exact.
• Since [date] — the source only has data from that point on. Anything before it isn't missing, it was never recorded.

A guess and a measurement should not look identical on screen. That's the whole reason the badges exist.

How reading time is counted

The ebook timer credits time per page turn, not by wall clock. Leave the reader open on the sofa and walk away, and it doesn't keep counting.

There's also a cap: if more than five minutes pass between page turns, only five minutes is credited. Long enough for a genuinely slow page, short enough that falling asleep mid-chapter doesn't add an hour to your total.

Time spent with a book read aloud counts as reading, exactly as time spent reading it does. That's a decision rather than a quirk of the measurement: nothing else in the app distinguishes reading a thing from being read to. The same cap on long pauses applies, so a phone left face-up doesn't quietly inflate anything.

Reading time is stored on this device only, deliberately. A running tally that two devices both edited would race and produce nonsense.

Podcast history

Podcast time comes from the server rather than from the app's own local history, even though both exist. Counting both would double up — the same episode would appear twice. The local history is a fallback for when the server has nothing to say.

CarPlay gives you a stripped-down version of the app on the car's screen. It appears automatically once connected.

The tabs

Three, and only three: Podcasts, Books, and Music.

Each opens a list of categories that you drill into, rather than dumping every artist and every book into one endless scroll.

Ebooks has no CarPlay tab, for reasons that should be obvious.

Why there are no sub-tabs

CarPlay's tab bar supports exactly one level. That's an Apple constraint, not a decision here — you can't nest a tab inside a tab. Hence the category-list-then-drill-in structure, which achieves the same grouping within what CarPlay allows.

Limits worth knowing

CarPlay caps how many rows a list can show. Long libraries are truncated rather than paginated, which is why drilling in through categories matters — it keeps each individual list under the ceiling.

Now Playing

CarPlay's own Now Playing screen is used rather than a custom one, fed by the same playback information that drives the lock screen. Artwork, title, and transport controls all work from the car's controls and the steering wheel.

Favorites in Music

Your pinned Favorites playlist appears first in the Music tab's playlist list, ahead of the rest.

The entitlement

CarPlay audio apps require a specific entitlement from Apple, tied to the app's bundle identifier. That's already granted and configured. It's also the main reason renaming the app's bundle identifier would be a bad idea.

On the Dashboard

The CarPlay Dashboard — the split screen with Maps on one side — shows what's playing in a compact card: the title, how far through you are, and how long is left.

That card is the same Live Activity that appears on your lock screen, drawn in CarPlay's smaller format. It carries no buttons: the full Now Playing screen is one tap away and has proper controls sized for a car, and duplicating them in a small card in front of a driver isn't a good trade.

If you'd rather not have it, the switch is Settings → Lock Screen → Live Activity — it governs every surface, the lock screen included.

Widgets

Home screen and lock screen widgets in small, medium, and large sizes showing what's currently playing, with controls to act on it directly.

The large widget adds the current chapter, elapsed and remaining time, playback speed, and what's next in Up Next.

Widgets read from a shared App Group container that the app writes to whenever playback changes. That's what lets a separate process show live information — and it's why a widget can briefly lag reality if the app hasn't run in a while.

Siri

Spoken commands for resume, play/pause, skip, and mark played, exposed as App Shortcuts so they work without you configuring anything in the Shortcuts app.

You can also build your own Shortcuts on top of the same actions.

Handoff

Start something on one device and continue it on another. The handoff icon appears on the second device's lock screen or app switcher; opening it resumes at the same position.

Two details worth knowing:

Handoff carries which kind of content was playing, so continuing a podcast doesn't accidentally resume music. That was a real bug — the receiving device would resume whatever it had loaded last rather than what was handed to it.

Continuing on the second device pauses the first, which is what you want and isn't what happens by default.

Live Activity, Dynamic Island & CarPlay

While something plays, a card appears on the lock screen with the title, progress and transport buttons. On phones with a Dynamic Island it lives there too — tap to expand for the full controls.

It also appears on the CarPlay Dashboard, the split screen next to Maps, in a shorter form: what's playing, how far through, and how long is left. No buttons there on purpose — CarPlay's own Now Playing screen is one tap away and has proper controls, and small targets in front of a driver to duplicate them is a poor trade.

It covers all three players, not just podcasts, with a distinct icon for each. Turn it off under Settings → Lock Screen.

Turn it off in Settings → Lock Screen.

A note on the buttons: they act on whichever player is actually playing. That sounds obvious, but the widget's buttons originally only ever reached the podcast player — a leftover from when the widget was the only surface and only ever showed podcasts. Music maps skip to next and previous track rather than a thirty-second seek, since seeking a three-minute song isn't what a forward button means.

Everything lives under Drawer → Settings. It used to be scattered — podcast settings behind the Podcasts "More" tab, music settings behind Music's own — which meant "change the default playback speed" required knowing which section owned it first. It's all in one place now.

Sections on that screen are collapsed when you arrive. Tap a heading to open it. There are six, and opening the screen to a wall of controls made finding anything harder than it needed to be.

The one exception is a podcast's own "..." menu, which holds overrides for that show alone. See What Overrides What.

Appearance

• Theme — light, dark, or follow the system.
• Colorful backgrounds — washes the wordmark's colours faintly behind every screen. Works in both light and dark, which is why it's a switch rather than a fourth theme.
• Accent colour — used for controls, progress and highlights throughout.
• New Badges — how long each library flags something as newly added. Per library, since a podcast episode and a film age differently.
• Alerts & Confirmations — the brief messages that slide up, how long they stay, and how they vibrate.

Lock Screen

What appears on the lock screen and in Control Centre while something is playing, including Live Activities.

Downloads

• Wi-Fi only — applies to any download in any library. Automatic downloads wait for Wi-Fi; a manual one on cellular asks first rather than refusing.
• Downloads — storage used, and what's on this phone, library by library.

Auto-download and per-library limits are deliberately not here. They differ too much between libraries — only podcasts have "new episodes" — so each library's own screen holds its version.

New Content Alerts

Notifications for new episodes, new albums, and anything else that arrives on your servers.

Libraries

One row per library, each opening its own screen:

Podcast Settings

• Episodes — sort order for new podcasts, and how episode rows are laid out.
• Skip & Resume — how far the skip buttons jump, and how far back to rewind when resuming.
• Playback Defaults — speed, trim silence, volume boost.
• Downloads — auto-download new episodes, max downloads to keep, and delete when finished.
• Skip Intro & Outro — seconds trimmed from the start and end of every episode.
• Up Next — auto-advance, and whether paused or in-progress episodes are queued for you.
• Notifications — new-episode alerts.
• Episode Row Swipe Actions — what a left or right swipe does.

Audiobook Settings

• Playback — speed, volume normalisation, auto-play next in series.
• Resume — how far back to rewind when you come back to a book.
• Downloads — Wi-Fi only, delete after finishing, download next in series, and a cap on how many books stay offline.
• Library — shelf sort, layout, grouping by series, whether finished books stay on the shelf.
• Progress — what counts as finished, and whether listening is reported to your server.
• Book Row Swipe Actions.

Ebook Settings

• While reading — page-turn behaviour and what the taps do.
• Read aloud — off by default. Switching it on adds a play button to the reader and reveals a voice picker. See Having a Book Read to You.
• Appearance — default font, size and page theme for books you haven't set individually.
• Notifications.

Music Settings

• Popular Tracks — the Last.fm-derived dots on album tracks.
• Downloads — including whether hearting something downloads it.
• Missing Artists — what to do about artists Plex knows and you don't own.
• New Releases.
• Playback — crossfade, normalisation, queue behaviour.
• Track Row Swipe Actions.

Radio Settings

• Saved Stations, Decade Stations, Playback, and How stations work — what a station is built from.

Movie Settings

• Movie libraries — which Plex libraries appear. Plex reports every library of that type, including recordings and home videos, so this is where you hide the ones you don't want.
• Converted playback — picture quality when your server has to convert. Only applies to films that need converting; anything playing directly is always sent untouched at full quality. Stays on this device rather than syncing, since the right answer on Wi-Fi isn't the right answer on cellular.
• Watching away from home — what the app has worked out about your Plex subscription. See Why Won't My Film Play?

TV Settings

The same three as Movies, applied to show libraries.

Servers & Accounts

• Audiobookshelf — address and sign-in. Powers podcasts, audiobooks and ebooks.
• Plex — sign-in and server choice. Powers music, movies, TV, radio and live TV.
• Lidarr — optional; request music not yet in your library.
• Seerr — optional; request films and television not yet in your library.
• Last.fm — optional free key; artist biographies and similar artists.
• TMDb — optional free key; actor biographies and filmographies.

Each row shows a live status dot, and says the same thing in words underneath — red and green are the pair a colour-blind reader is most likely to miss.

Credentials are held in the iOS Keychain, never in iCloud, and never leave the device.

What syncs and what doesn't

Most settings sync through iCloud, so your phone and iPad agree. Three deliberate exceptions:

• Converted playback quality — the right answer depends on the connection you're on.
• The read-aloud voice — names a voice file downloaded on this device, which may not exist on another.
• Anything in Servers & Accounts — credentials stay in the Keychain on the device.

This is the topic to read when a setting you changed doesn't seem to be doing anything.

The order

For podcasts, three layers, most specific first:

1. That podcast's own setting — from its "..." menu
2. Your global default — from Settings → Podcast Settings
3. The app's built-in default

A per-podcast override always wins. If you set a global playback speed of 1.5× and a show still plays at 1.0×, it's because that show has an override set. The global setting isn't broken; it's being outranked.

What can be overridden per podcast

• Playback speed
• Skip back and forward amounts
• Trim silence
• Volume boost
• Skip intro and skip outro
• Auto-download
• Maximum downloads to keep

What can't

• Wi-Fi only downloads — a constraint about your data plan, not about any show
• Notification and badge settings
• Swipe actions
• Appearance

These are global only, by design.

The sections don't share settings

Podcasts and Audiobooks have entirely separate playback settings. Changing the podcast skip amount does nothing to audiobooks and vice versa. That's deliberate — ten seconds is right for a podcast and thirty is right for a book.

Music is separate again.

Clearing an override

Set the per-podcast value back to "Use default" in the podcast's settings sheet. It then follows the global setting again, including future changes to it.

What syncs where

Audiobookshelf holds listening progress, played state, reading position, and playlists. It's authoritative — on launch, the server's version wins.

Plex holds music playlists.

iCloud holds app settings, the Up Next queue, and the things Audiobookshelf has no concept of.

This device only holds downloads, cached cover art, and computed data like silence analysis. All of it regenerable.

Offline

The app is usable with no network.

Your library is cached to disk, so it loads from a cold start with no connection. Cover art is cached the same way.

Downloaded episodes, books, albums, films and TV episodes all play normally.

Video is worth calling out: a downloaded film or episode doesn't touch your server at all, which means Plex's away-from-home subscription restrictions don't apply to it. Downloading before a trip sidesteps that entirely.

Progress changes made offline go into a sync queue and are written to the server when the connection returns. You don't need to do anything; there's no manual sync.

Reconnecting

When the network returns the app notices and, without being asked:

• Repairs stalled playback silently
• Re-fetches library and progress data

Why the server wins on load

Progress is read fresh from Audiobookshelf on every launch and nothing is written back unless you actually change something. That's what keeps a second device from clobbering a first device's position with stale data.

The exception is progress you changed while offline, which is queued locally precisely so it doesn't get lost to a refresh before it's been sent.

Background refresh

The app refreshes periodically in the background to find new episodes, download them if configured to, and post notifications. iOS decides when this actually runs — it isn't a fixed schedule and can be delayed considerably if you rarely open the app.

Nothing is loading

Check Drawer → Settings → Servers & Accounts first. If Audiobookshelf is unreachable, the app shows cached data rather than an error, which can look like "everything is stale" instead of "the server is down".

Pull to refresh to force a fetch. The app also refreshes on its own when a connection returns.

A setting isn't taking effect

Almost always a per-podcast override outranking the global default. See "What Overrides What".

Second most likely: you changed a podcast setting expecting it to affect audiobooks. The two sections don't share settings.

Progress isn't showing on the server

Progress writes on pause, on switching items, and periodically during playback. Force-quitting mid-episode without pausing can lose the last stretch.

If you were offline, the change is queued and sends when the connection returns.

An episode has no duration

The server hasn't scanned it. The app measures the file itself during playback and caches the result, and also falls back to the RSS feed. A runtime appearing later on an episode that showed none is this working, not a glitch.

Trim silence isn't doing anything

It only works on downloaded episodes. Streamed episodes play with it inactive. This is deliberate — see the Downloads topic.

A download is stuck

Check whether Wi-Fi only is on and you're on cellular.

Downloads run in a background session and can be paused by iOS under low power or poor connectivity. Deleting and restarting the download is safe.

The CarPlay tab is missing

CarPlay needs the entitlement, which is tied to the app's bundle identifier and provisioning profile. If the app was rebuilt with a profile lacking it, CarPlay won't appear at all.

CarPlay also cannot be tested in the iOS Simulator — a real head unit or a CarPlay-capable car is required.

An ebook won't open

Check the format badge on its cover. MOBI, AZW and AZW3 aren't supported and never will be — convert them to EPUB on the server.

If an EPUB opens but pages won't turn, that's a pagination problem rather than a format one, and it's worth reporting.

Ebook text is hard to read

Try a different theme. Book stylesheets sometimes set their own colors; the reader overrides them forcefully, but a book with unusual markup can still fight it.

Music won't connect

Plex authentication is a token stored in the keychain. If it's been revoked from Plex's side, signing in again is the fix.

If artists load but nothing plays, check that the correct library is selected.

Lyrics say nothing was found

Lyrics come from LRCLIB, matched on track, artist, and duration. Many tracks simply aren't in it, and unusual metadata makes matching fail. Nothing is wrong with your library.

The widget is out of date

Widgets read a snapshot the app writes. If the app hasn't run recently, the snapshot is old. Opening the app updates it.

Something on screen won't respond to taps

Worth reporting with detail about exactly where. Two separate bugs of this kind have been found and fixed, both caused by an invisible layer sitting over content and silently swallowing touches.

No dots on album tracks

Check Settings → Music Settings. The line under the Last.fm key says what the last lookup did — a rejected key and an artist Last.fm has never heard of look identical otherwise.

If it says it loaded tracks and you still see nothing, the album's titles didn't match. Matching is by name, so heavily-tagged releases can miss.

Remember the personal half (the hollow ring) needs no key at all, but does need at least two plays of a track and an album you haven't played evenly all the way through.

A favorite didn't download

Download favorites automatically is off by default. Turn it on in Music Settings, then use the catch-up button beside it for anything you hearted before.

Favorites aren't showing up in Plex

The pinned Favorites row shows "Syncing…" while anything is still queued. If it stays that way, you're offline — hearts replay automatically when you're back.

If the playlist has gone missing in Plex entirely, heart anything and it will be recreated.

A film plays with sound but no picture

A particular kind of file rather than a broken download. Some tools — including Plex's own optimiser — write video with a tag Apple's player refuses to draw while playing the sound happily. The app detects this on downloaded files and uses its own player instead. If you saw it on a download made before that check existed, delete it and download it again.

A downloaded film played the wrong version

The download sheet says which copy it's fetching — "Optimized copy" or "Original file". If you got the large one when a smaller existed, delete it and download again; the app now prefers the optimized copy whenever there is one.

I asked for a smaller copy and nothing happened

Conversions take an hour or more, and your server does the work. You don't need to keep the app open. The notification arrives the next time you open the app, and the item appears under Ready to download at the top of the Downloads screen.

If it's been much longer than expected, check the conversion queue in Plex Web — the app can ask for a conversion but can't see the queue.

A live TV channel won't play

Known, and not something wrong with your setup — see Live TV. The guide and the lineup work; playing a channel doesn't yet.

All tuners in use

Someone in the house is watching or recording on every tuner your server has. A tuner is a physical thing and there are only so many. Nothing to fix; wait, or stop whatever else is using one.

The Live Activity isn't appearing

Check Settings → Lock Screen first, then iOS's own Settings → Castaway Media → Live Activities.

Force-quitting the app while something plays leaves a card behind that nothing updates. Reopening the app clears it.

Audiobookshelf (ABS) — the self-hosted media server behind Podcasts, Audiobooks, and Ebooks.

Book library — an Audiobookshelf library of type book. Yours holds both audiobooks and ebooks; which section an item appears in depends on which files it has.

Chapter — a named position marker within an episode or book, supplied by the source.

Direct play — your server sends the file exactly as it is and the phone opens it. No conversion, no quality loss, no work for the server.

EPG — electronic programme guide. What's on, and when, for each channel.

Handoff — Apple's feature for continuing an activity on another device.

Item — one thing in an Audiobookshelf library. A single item can be an audiobook and an ebook at once.

Locator — a saved position inside an ebook, recording which chapter and how far through it.

Media progress — Audiobookshelf's record of your position in an item. Carries listening position and reading position as separate fields, which is why the two never interfere.

Minified vs expanded item — Audiobookshelf returns less detail when listing a library than when fetching one item. The list form gives flat strings for author and series; the detail form gives structured data with sequence numbers. The app reads both.

MKV (Matroska) — a very common container for film and television. An iPhone can't open one by itself; Castaway carries a player that can.

NCX — the older EPUB 2 table-of-contents format. EPUB 3 uses a navigation document instead. Both are read.

Optimized version — a smaller copy of a film or episode, built by your Plex server on request and stored alongside the original. Made for carrying on a phone, not for watching at home.

Playback session — a record Audiobookshelf opens when you start playing. Syncing time to it is what makes your listening count toward the server's own statistics.

Plex — the media server behind the Music section. Unrelated to Audiobookshelf.

Sequence — a book's position within a series. A string, not a number, because values like "1.5" exist for novellas between numbered entries.

Spine — the ordered list of documents making up an EPUB. Reading position is recorded as a spine index plus a fraction through that document.

Sync queue — changes made offline, held locally until the connection returns.

Transcode — your server converts a file as it sends it, because something at the other end can't open the original. Costs your server real work; see Why Won't My Film Play?

Tuner — the hardware that receives broadcast television, attached to your Plex server. The only hardware Castaway needs for anything, and only for Live TV.

Up Next — the play queue. Exists only in this app and iCloud; Audiobookshelf has no concept of it.

Virtual playlist — a list that behaves like a playlist but isn't stored on any server. "All unplayed" and "Favorites" are both computed fresh each time.