From 3806c3514003e08b1823a321e7088a0cd57f2a66 Mon Sep 17 00:00:00 2001 From: Kharec Date: Tue, 6 Jan 2026 07:29:54 +0100 Subject: [PATCH] docs: production readme --- README.md | 165 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 110 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 6f6f064..6030cc9 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,130 @@ # auditui -A terminal-based user interface (TUI) client for Audible, written in Python 3 : listen to your audiobooks (even offline), browse and manage your library, and more! +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](https://github.com/catppuccin/catppuccin/blob/main/docs/style-guide.md), as it's my preferred theme across most of my tools. -Look at the [roadmap](#roadmap) for more details. +## Features -It's still a work in progress, so expect bugs and missing 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 -## How to run +## Requirements + +- [Python](https://www.python.org/) 3.10-3.12 (3.13+ is not yet supported by `audible` module) +- [ffmpeg](https://ffmpeg.org/) installed to play audio files. + +## Installation + +Use [`pipx`](https://pipx.pypa.io/latest/installation/) to install `auditui`: + +```bash +pipx install git+https://git.kharec.info/Kharec/auditui.git +``` + +Check the version to ensure installation was successful: + +```bash +auditui --version +``` + +All set, run `auditui configure` to set up authentication, and then `auditui` to start the TUI. + +## 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: + +```bash +du -sh ~/.cache/auditui/books +``` + +Or the size of individual books: + +```bash +du -h ~/.cache/auditui/books/* +``` + +Clean all the cache (if necessary) with: + +```bash +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](https://github.com/astral-sh/uv) for dependency management. ```bash # install dependencies (creates .venv) $ uv sync - -# run the TUI +# modify the code... +# ...and run the TUI $ uv run python -m auditui.cli ``` -Please also note that as of now, you need to have [ffmpeg](https://ffmpeg.org/) installed to play audio files. +## Testing -### Bindings - -| Key | Action | -| ------------ | -------------------------- | -| `?` | Show help screen | -| `n` | Sort by name | -| `p` | Sort by progress | -| `a` | Show all/unfinished | -| `enter` | Play the selected book | -| `space` | Pause/resume the playback | -| `left` | Seek backward 30 seconds | -| `right` | Seek forward 30 seconds | -| `ctrl+left` | Go to the previous chapter | -| `ctrl+right` | Go to the next chapter | -| `up` | Increase playback speed | -| `down` | Decrease playback speed | -| `f` | Mark as finished | -| `d` | Download/delete from cache | -| `r` | Refresh view | -| `s` | Show stats screen | -| `/` | Filter library | -| `q` | Quit the application | - -## Roadmap - -- [x] list your library -- [x] list your unfinished books with progress information -- [x] play/pause a book -- [x] catppuccin mocha theme -- [x] print chapter and progress in the footer of the app while a book is playing -- [x] chapter progress bar in footer -- [x] add a control to jump 30s earlier/later -- [x] add control to go to the previous/next chapter -- [x] save/resume playback of a book from the last position, regardless of which device was used previously -- [x] download/remove a book in the cache without having to play it -- [x] add a help screen with all the keybindings -- [x] increase/decrease reading speed -- [x] mark a book as finished -- [x] make ui responsive -- [x] get your stats in a separated pane -- [x] search/filter within your library -- [ ] installation setup - -## Auth / credentials - -Login is handled and credentials are stored in `~/.config/auditui/auth.json`. - -OTP is supported if you use a two-factor authentication device. +WIP. ## License