auditui/README.md

auditui

A terminal-based user interface (TUI) client for Audible, written in Python 3: listen to your audiobooks (even offline), browse your library, and more!

Currently, the only available theme is Catppuccin Mocha, following their style guide, as it's my preferred theme across most of my tools.

Features

• Browse your library: View all your Audible audiobooks in a clean, terminal-based interface
• Offline playback: Download audiobooks to your local cache and listen without an internet connection
• Playback controls: Play, pause, seek, adjust playback speed, and navigate between chapters
• Library management: Filter your library, sort by name or progress, and mark books as finished
• Progress tracking: See your listening progress for each book and resume where you left off
• Statistics: View listening statistics and library overview
• Keyboard-driven: Fully navigable with keyboard shortcuts for efficient use
• Two-factor authentication: Supports OTP for secure login

Requirements

• Python 3.10-3.12 (3.13+ is not yet supported by audible module, according to master branch it'll be done for next version)
• ffmpeg installed to play audio files.

Installation

Use pipx to install auditui:

pipx install git+https://git.kharec.info/Kharec/auditui.git

Check the version to ensure installation was successful:

auditui --version

All set, run auditui configure to set up authentication, and then auditui to start the TUI.

Workaround for Python 3.13 linux distribution

On some Linux distributions, Python 3.13 is already the default. So you have to install Python 3.12 manually before using pipx.

Workaround for Arch Linux:

yay -S python312
pipx install git+https://git.kharec.info/Kharec/auditui.git --python python3.12

Keybindings

Key	Action
/	Filter library
?	Show help screen
enter	Play the selected book
space	Pause/resume the playback
escape	Clear filter
ctrl+left	Go to the previous chapter
ctrl+right	Go to the next chapter
up	Increase playback speed
down	Decrease playback speed
left	Seek backward 30 seconds
right	Seek forward 30 seconds
a	Show all/unfinished
d	Toggle download/delete
f	Mark as finished
n	Sort by name
p	Sort by progress
q	Quit the application
r	Refresh view
s	Show stats screen

Cache

Books are downloaded to ~/.cache/auditui/books.

The d key toggles the download state for the selected book: if the book is not cached, pressing d will download it; if it's already cached, pressing d will delete it from the cache.

To check the total size of your cache:

du -sh ~/.cache/auditui/books

Or the size of individual books:

du -h ~/.cache/auditui/books/*

Clean all the cache (if necessary) with:

rm -rf ~/.cache/auditui/books/*

Authentication / credentials

Login is handled and credentials are stored in ~/.config/auditui/auth.json.

When running auditui configure, you will be prompted for:

• Email: Your Audible account email address
• Password: Your Audible account password (input is hidden)
• Marketplace locale: The regional marketplace you want to connect to (defaults to US if left empty)

The marketplace locale determines which Audible region you access, affecting available audiobooks in your library. Common marketplace codes include:

• US - United States (default)
• UK - United Kingdom
• DE - Germany
• FR - France
• CA - Canada
• AU - Australia
• IT - Italy
• ES - Spain
• JP - Japan

To change your marketplace after initial configuration, simply run auditui configure again and select a different locale when prompted. But you should probably just stick with the marketplace you used when you first created your Audible account.

OTP is supported if you use a two-factor authentication device.

Hacking

This project uses uv for dependency management.

# install dependencies (creates .venv)
$ uv sync
# modify the code...
# ...and run the TUI
$ uv run python -m auditui.cli

Testing

WIP.

License

This project is licensed under the GPLv3+ License. See the LICENSE file for details.