https://github.com/michaeldvinci/swiftshelf-androidtv
AndroidTV client for Audiobookshelf not built in Swift
https://github.com/michaeldvinci/swiftshelf-androidtv
androidtv androidtv-app audiobookshelf nvidia-shield self-hosted selfhosted
Last synced: 2 days ago
JSON representation
AndroidTV client for Audiobookshelf not built in Swift
- Host: GitHub
- URL: https://github.com/michaeldvinci/swiftshelf-androidtv
- Owner: michaeldvinci
- Created: 2025-11-02T23:01:49.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-03-16T07:00:20.000Z (3 months ago)
- Last Synced: 2026-03-16T19:09:45.589Z (3 months ago)
- Topics: androidtv, androidtv-app, audiobookshelf, nvidia-shield, self-hosted, selfhosted
- Language: Kotlin
- Homepage: https://michaeldvinci.com
- Size: 25.7 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# SwiftShelf for Android TV
A native Android TV client for [Audiobookshelf](https://www.audiobookshelf.org/), offering a sleek, remote-friendly interface for browsing and playing your audiobooks.
## Features
### Authenticated Connection & Secure Storage
- Logs in with Audiobookshelf host and API key
- Credentials securely stored using Android's EncryptedSharedPreferences
- Seamless reconnection after app relaunch
### Library Selection & Persistence
- Choose from available Audiobookshelf libraries
- Select multiple libraries to browse at once
- Remembers your selected libraries
### Recent & Continue Listening Carousels
- Browse recently added audiobooks
- Pick up where you left off with in-progress items
- Cover artwork with author, duration, and playback progress
- Smooth horizontal scrolling carousels
### Search
- Query your library with natural search
- Results display books with cover art and metadata
- Quick access to search functionality
### Detailed Item Popup & Quick Play
- Material Design dialog with book details
- Author, narrator, series information
- Duration and progress tracking
- Chapter selection for direct playback
- Play and Read buttons for audiobooks with ebooks
### Full-Screen Media Player
- Immersive playback experience with blurred cover background
- Transport controls: play/pause, skip forward/back (30s/10s)
- Playback speed adjustments (0.5x - 3.0x)
- Chapter navigation with expandable chapter list
- Progress scrubbing with time display
- D-pad optimized for Android TV remotes
### EPUB Reader
- Two-page landscape layout optimized for TV
- Sepia reading theme for comfortable viewing
- Chapter navigation menu
- Swipe or button navigation between pages
### Customizable Experience
- Adjust library item fetch count (default: 10)
- Choose carousel progress-bar color
- Set default playback speed
- Persistent settings across sessions
### Authenticated Cover Fetching
- Securely fetch cover images with authentication
- Cached for smooth browsing performance
- High-quality artwork display
### Android TV Optimized
- Remote-friendly navigation
- D-pad and touch support
- Focus-aware UI elements
- Material Design 3 components
- Landscape-optimized layouts
## Technical Features
- **Progress Sync**: Automatically syncs playback progress to Audiobookshelf (session sync every 15s, progress sync every 90s)
- **Session Management**: Proper playback session handling with Audiobookshelf server
- **MediaSession Integration**: System-level playback controls and notifications
- **ExoPlayer**: High-quality audio playback with chapter support
- **EPUB Support**: Built-in EPUB parser and reader for ebook content
- **Jetpack Compose**: Modern, declarative UI framework
- **Material Design 3**: Latest Android design guidelines
## Requirements
- Android TV device or Android device running Android 8.0 (API 26) or higher
- Audiobookshelf server instance with API access
- Network connection to your Audiobookshelf server
## Installation
### From Release
1. Download the latest APK from the [Releases](https://github.com/michaeldvinci/swiftshelf-android/releases) page
2. Install via ADB: `adb install swiftshelf-.apk`
3. Or sideload using your preferred method
### Building from Source
1. Clone the repository
2. Open in Android Studio
3. Ensure you have JDK 17 installed
4. Build and run on your Android TV device or emulator
```bash
./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk
```
## Configuration
### First Launch
1. Launch SwiftShelf on your Android TV
2. Enter your Audiobookshelf host URL (e.g., `https://abs.example.com`)
3. Enter your API key (found in Audiobookshelf settings)
4. Select one or more libraries to browse
### Debug Configuration (Development)
For testing during development, you can create a config file:
```json
// .swiftshelf-config.json
{
"host": "https://your-abs-server.com",
"apiKey": "your-api-key-here"
}
```
## Architecture
- **MVVM Pattern**: Clean separation of concerns
- **Repository Pattern**: Data layer abstraction
- **Kotlin Coroutines**: Asynchronous operations
- **StateFlow**: Reactive state management
- **Retrofit**: Network communication
- **Room** (planned): Local caching
- **Coil**: Image loading and caching
## Development
### Project Structure
```
app/src/main/java/com/swiftshelf/
├── MainActivity.kt # Main entry point
├── SwiftShelfViewModel.kt # App state management
├── audio/
│ ├── GlobalAudioManager.kt # Audio playback management
│ └── MediaSessionManager.kt # System media controls
├── data/
│ ├── model/ # Data models
│ ├── network/ # API client
│ └── repository/ # Data repositories
├── epub/
│ └── EPUBParser.kt # EPUB file parsing
├── ui/
│ ├── screens/ # Composable screens
│ │ ├── BookDetailsDialog.kt # Book info popup
│ │ ├── CompactPlayer.kt # Mini player banner
│ │ ├── EpubReaderScreen.kt # EPUB reader
│ │ ├── LibraryBrowseScreen.kt # Main browse UI
│ │ ├── MediaPlayerScreen.kt # Full-screen player
│ │ └── ...
│ └── theme/ # App theming
└── util/
└── SecurePreferences.kt # Encrypted storage
```
### Building
- Minimum SDK: 26 (Android 8.0)
- Target SDK: 34 (Android 14)
- Kotlin: 1.9.20
- Gradle: 8.11.1
- Android Gradle Plugin: 8.10.1
## Roadmap
- [ ] Offline playback support
- [ ] Sleep timer
- [ ] Playback queue management
- [ ] Bookmarks
- [ ] Android Auto integration
- [ ] Cast support
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
[License information to be added]
## Acknowledgments
- [Audiobookshelf](https://www.audiobookshelf.org/) - The amazing audiobook server
- The Android and Jetpack Compose communities
## Support
For issues and feature requests, please use the [GitHub Issues](https://github.com/michaeldvinci/swiftshelf-android/issues) page.