docs: production readme
This commit is contained in:
165
README.md
165
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user