- Rust 53.5%
- Svelte 34.9%
- TypeScript 9.1%
- Shell 1.6%
- PowerShell 0.5%
- Other 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .cargo | ||
| .github/workflows | ||
| docs | ||
| packaging/flatpak | ||
| release-notes | ||
| scripts | ||
| src | ||
| src-tauri | ||
| static | ||
| .gitattributes | ||
| .gitignore | ||
| .prettierignore | ||
| .prettierrc | ||
| CLAUDE.md | ||
| LICENSE | ||
| package.json | ||
| PLAN.md | ||
| pnpm-lock.yaml | ||
| README.md | ||
| svelte.config.js | ||
| tsconfig.json | ||
| vite.config.js | ||
Cushion
A desktop client for Audiobookshelf on Linux and Windows. It looks like Absorb and is laid out like Spotify's desktop app.
Status: 0.1.0, the first release. You can log in, browse and search your library, and play books and podcast episodes with progress sync. It works like a native media app (OS media controls, tray, mini player, shortcuts) and has the listening toolbox: sleep timer, auto-rewind, bookmarks, speed per book, equalizer and playing on through a series. It also works offline: download books and podcast episodes, listen without a connection, and your progress syncs when you are back online. Listening stats, playlists, collections and ten themes round it off, and server admins can manage libraries and fix metadata, covers and chapters from the app. See PLAN.md for the roadmap.
Install
Download from the releases page:
- Fedora:
Cushion-<version>-1.x86_64.rpm, thensudo dnf install ./Cushion-*.rpm(pulls inmpv-libs). - Debian, Ubuntu:
Cushion_<version>_amd64.deb, thensudo apt install ./Cushion_*.deb(pulls inlibmpv2). - Any Linux with Flatpak:
Cushion-<version>.flatpak, thenflatpak install --user Cushion-*.flatpak. Updates mean installing the next bundle the same way. - Windows 10/11:
Cushion_<version>_x64-setup.exe. It installs for the current user, no admin needed.
The .deb, .rpm and Windows versions look for updates at start and install them when you agree (on Linux after asking for your password). This can be turned off under Settings → Updates.
Features
- Sign in to Audiobookshelf 2.26 or newer. Tokens are stored in the OS keyring, and custom proxy headers are supported.
- Home shelves for books, series and authors
- Library as a grid or a list, with filters (progress, genre, author, series, narrator) and sorting
- Series and author pages, and search across books, series, authors and narrators (Ctrl+K or Ctrl+F)
- Podcasts: podcast libraries, podcast pages with episodes and show notes, progress per episode, mark played
- Book pages with details and chapters
- Pages open instantly from a local cache, and stay browsable when the server is unreachable
- A Spotify-style player bar and a "Now Absorbing" full view, with a side panel for chapters, bookmarks and what's up next
- Starts where you left off: the last book or episode waits paused in the player bar
- Chapter navigation, ±30 s skips and speed changes, with pitch kept at every speed
- Themes: dark, OLED, light, Catppuccin (Latte, Frappé, Macchiato, Mocha), Nord, Dracula and Spotify. The accent comes from the cover (as in Absorb), the theme's own palette or a colour you pick; Spotify always uses its green
- Progress synced every 15 s, plus live updates from your other devices
- Multi-file books play as one seamless timeline (libmpv)
- Media keys and OS media controls (MPRIS on Linux, SMTC on Windows) with cover, title, author and position. Next/previous skip a chapter or 30 s, as you choose in the settings
- Tray icon with play/pause, ±30 s, show/hide and quit; closing the window keeps playing in the tray (can be turned off)
- Mini player (360×120, optionally always on top) that replaces the main window while it is open: from the player bar or the tray menu
- Keyboard shortcuts (listed in the settings): Space, ←/→, Shift+←/→,
[/],Bto bookmark, Ctrl+K or Ctrl+F for search - Window size and position are remembered
- Sleep timer: 5–90 minutes or the end of the chapter, with an optional 10-second fade-out. It runs in the background, so it works from the tray too
- Auto-rewind after a pause: a few seconds after a short break, up to 30 s after an hour or more (adjustable)
- Bookmarks: add (
B), rename and delete from the side panel; they sync with Audiobookshelf - Speed is remembered per book (per podcast for episodes); new books start at a default speed you choose
- Downloads: books and podcast episodes download one after the other, can be paused and resumed, and are size-checked per file. Cover and details are stored with them. The folder can be changed in the settings (existing downloads move along), which also show the space used and free
- Offline: with no connection (or with offline mode switched on) the app shows only the Downloads page and plays downloaded items from local files. What you listen to is recorded and uploaded when the server is back; whichever copy of the progress is newer wins. A download whose files changed on the server is marked "Update available"
- Equalizer with 10 bands, built-in presets (voice boost, bass, treble, loudness…) and your own saved presets
- When a book ends, the next one in the series (or the next unplayed episode) starts after a 10-second countdown you can cancel
- Listening stats: total time, days listened, finished items, today, days in a row, the last 7 days as a chart, most listened books, top authors and genres, and recent sessions
- Playlists (yours alone, books or episodes): create, rename, reorder, remove, and play through in order; Up Next follows the playlist. Add to them from a book or episode with "Add to"
- Collections (shared in the library): the same, for users allowed to edit them on the server
- Library admin (server admins only): create, edit and delete libraries, with folders picked by browsing the server; name, icon, metadata provider, scheduled scans, folder watching, when an item counts as finished and more. Scan or force a rescan and watch the result arrive live; list missing or broken items and remove them (files stay on the server)
- Item editing (users allowed to edit on the server): book details (title, authors, narrators, series, genres, tags, year, publisher, description, ISBN/ASIN…) and podcast details; covers from a file, a URL or a provider's cover search, or none; match a book against a provider and pick field by field what to take over; a chapter editor with Audnexus lookup (preview, time shift or titles only); quick match of a whole library from the Admin page
Development
Releases: see docs/release.md.
You need Rust (stable), Node 22, pnpm 10 and libmpv.
Linux (Debian/Ubuntu):
sudo apt install libwebkit2gtk-4.1-dev libmpv-dev libayatana-appindicator3-dev librsvg2-dev
Linux (Fedora):
sudo dnf install gcc pkgconf-pkg-config 'pkgconfig(webkit2gtk-4.1)' 'pkgconfig(mpv)' 'pkgconfig(librsvg-2.0)' libayatana-appindicator-gtk3
The tray icon needs a status notifier host. KDE has one; GNOME needs the AppIndicator extension, and without it "close to tray" leaves no way back to the window (turn it off in the settings).
Fedora's mpv is built against ffmpeg-free. If a book won't play because of a missing codec, switch to the full ffmpeg from RPM Fusion:
sudo dnf swap ffmpeg-free ffmpeg --allowerasing
Windows: download an mpv-dev-x86_64-*.7z build from
shinchiro/mpv-winbuild-cmake,
create mpv.lib from libmpv-2.dll (see .github/workflows/ci.yml), set
MPV_LIB_DIR to that folder, and put it on PATH.
Then:
pnpm install
pnpm tauri dev
Tests
pnpm check && pnpm lint
cargo test --manifest-path src-tauri/Cargo.toml
The live tests run against a throwaway Audiobookshelf in Docker with generated test books:
scripts/test-server.sh
CUSHION_TEST_SERVER=http://localhost:13378 CUSHION_TEST_USER=root CUSHION_TEST_PASS=cushion-test \
cargo test --manifest-path src-tauri/Cargo.toml --test live_server
cargo test also regenerates the TypeScript types in src/lib/bindings from the Rust structs.
Troubleshooting
- Blank window on Linux: some GPU/driver setups (and Xvfb) need
WEBKIT_DISABLE_DMABUF_RENDERER=1. - No sound device:
CUSHION_MPV_AO=nullmakes mpv play silently.