Native Jellyfin client for Android, Android TV & Fire TV · Material 3 Expressive · ExoPlayer, libmpv & LibVLC · Self-hosted, no tracking
JellyPlay is a high-performance, feature-rich, and open-source Jellyfin client app for Android devices. Built entirely from the ground up using Kotlin and Jetpack Compose (Material 3/Expressive), JellyPlay delivers a premium, smooth, and native media streaming experience. Designed with an adaptive responsive interface, it adapts flawlessly to Android mobile phones, tablets, foldables, and Android TV.
Whether you want to stream movies, play music with synchronized lyrics, manage your server via an integrated Admin Dashboard, edit library metadata on the go, request content via Jellyseerr/Overseerr (with full request management), download media for offline playback, catch up with a weekly Newsletter digest, join real-time SyncPlay watch parties, track your viewing habits with a Watch Progress Heatmap, or get notified when new content arrives — JellyPlay has you covered with built-in multi-engine support (ExoPlayer, libmpv, LibVLC), remote control from the server, 4 home screen widgets, and a guided Onboarding Wizard for personalized setup.
Key Features • Why JellyPlay? • Comparison • Tech Stack • Requirements • Building & Flavors • Permissions • Project Structure • Docs • Website
 |
 |
 |
 |
 |
 |
 |
 |
 |
|||
Note
JellyPlay is currently in Active Beta. 🧪 The application is under active development. While the core features (such as playback, multi-server support, and offline downloads) are functional and stable, you may encounter occasional visual bugs or edge-case issues. We highly appreciate any bug reports, feedback, and contributions!
JellyPlay is built for people who self-host a Jellyfin media server and want a truly native, beautiful, and capable client on every screen — phone, tablet, foldable, Android TV, and Amazon Fire TV.
- Native, not a web wrapper. Written from scratch in Kotlin and Jetpack Compose, with Compose for TV on the big screen. No Cordova, no embedded browser, no compromises.
- Three video engines. Pick ExoPlayer / Media3, libmpv, or LibVLC per device — each has its own strengths for codec support, post-processing, and ASS/SSA subtitle rendering.
- One app, every form factor. Adaptive layouts across phones, tablets, foldables, and Android TV with a dedicated Leanback launcher. Edge-to-edge immersive mode, predictive back gesture, and Material 3 dynamic theming from your artwork.
- Self-hosted first. No accounts, no telemetry, no cloud dependency. Multi-server, multi-user support with Quick Connect and token-based auth. Offline downloads with HTTP Range resumption for travel.
- Beyond streaming. SyncPlay watch parties, Jellyseerr / Overseerr requests, a full metadata editor, an in-app server admin dashboard, synchronized lyrics via LRCLIB, 10-band equalizer with night mode, and a weekly newsletter digest of your library activity.
If you're looking for a Kodi alternative, a Plex alternative, or a self-hosted media player for Android & Android TV — give JellyPlay a try.
- Multi-server Jellyfin support with auto-discovery
- Token-based and Quick Connect authentication
- Multi-user support with per-server user switching
- Material 3 UI with dynamic theming from artwork
- Expressive animations and spring-based motion specifications
- Shared element transitions between screens
- Performance Mode (disables animations for low-end devices)
- Predictive back gesture support
- Edge-to-edge immersive layouts
- Adaptive layouts for phone, tablet, foldable, and TV
- Android TV support with D-pad navigation and Leanback launcher
- Android TV screensaver (Daydream) with configurable slideshow and Ken Burns effect
- PIN lock and biometric authentication (fingerprint/face) with auto-lock timer
- Kids Mode with content filtering
- 4 theme variants: Standard (Material 3 dynamic), Synthwave (neon/retro), Soothing (GitHub-dark-inspired), and Monochrome (black-and-white)
- 8 accent color swatches (Dynamic, Brand, Sapphire Blue, Emerald Green, Amethyst Purple, Rose Pink, Coral Orange, Amber Gold, Crimson Red)
- 3 contrast levels (Default, Medium, High) with full light/dark variants
- OLED mode for AMOLED displays
- Home screen widgets with configurable sources:
- Now Playing — album art, transport controls (play/pause, next/prev, rewind/forward), and a 7-zone seek bar
- Continue Watching — list of in-progress media items
- Library Recommendations — poster grid with selectable source (Similar to Recent, Latest, Favorites, Surprise Me)
- Seerr Recommendations — poster grid with selectable source (Trending, Popular Movies/TV, Upcoming Movies/TV)
- Quick settings tile launcher
- App shortcuts:
- Static: Continue Watching, Search, Play Music, Downloads
- Dynamic: Continue Listening — auto-updates with the currently playing track and album art
- BlurHash image placeholders for smooth loading
- Localization ready (English; additional translations in progress)
- Deep link support via
jellyplay://andhttps://raulshma.github.io/jellyplay/URI schemes - Settings search — find any setting instantly by name
- New media notifications — real-time per-library notifications when new content is added, with quiet hours, seen-media tracking, grouped notifications, and notification actions
- Accessibility — blue light filter with strength control, reduce motion toggle, haptic feedback intensity, and font scaling
- Global Jellyfin search across movies, shows, music, albums, and more
- Filters for genre, year, and media type
- Voice search support
- Search history persisted per-user with per-item deletion, bulk clear, and hide option
- Three built-in engines: ExoPlayer (Media3), libmpv, and LibVLC
- Video filter controls: Adjust brightness, contrast, saturation, and sharpness in-player (libmpv & LibVLC)
- Enhanced Video Stats Overlay presenting real-time stream bitrate, frame rate, and dropped frames
- External player launching (MX Player, VLC, etc.)
- Direct play, direct stream, and transcoding support with quality/transcoding picker
- Resume playback and progress reporting
- Audio and subtitle track selection with language matching and reset functionality
- Playback speed control (0.25x–4x) with current speed display and estimated end time
- Hold speed — press and hold to temporarily increase playback speed
- Gesture controls for seek, brightness, and volume
- Chapter and episode navigation
- HDR badge indicator
- Picture-in-Picture support
- Mini player overlay
- Trickplay thumbnail seeking (Jellyfin trickplay sprite sheets) with offline caching support
- Frame rate matching for display refresh rate sync
- Adaptive bitrate streaming
- Intro skip and next episode auto-play with segment auto-skip (intro/outro/recap)
- Chromecast support via Google Cast SDK
- Media session integration for lock screen and notifications
- Sleep timer with configurable duration
- Aspect ratio selection
- Hardware/software decoder selection
- Audio delay adjustment (ms)
- Screen orientation toggle
- Player lock screen overlay to prevent accidental touches
- Companion Dashboard — view lyrics alongside video playback
- Tap-to-translate subtitle feature
- External subtitle loading and download
- ASS/SSA and VTT subtitle format parsing with enhanced cue handling
- Subtitle styling (font size, color, background, edge type, position) with persistence
- Subtitle delay offset control
- Preferred subtitle language selection
- Community rating indicator for search results and subtitle download sheet
- Music browsing for artists, albums, tracks, genres, and playlists
- Queue management with drag-to-reorder
- Shuffle and repeat modes
- Playback speed control
- Waveform-style seek bar
- Real-time FFT audio visualizer
- Synced and unsynced lyrics via LRCLIB API
- 10-band equalizer with presets
- Night Mode (loudness enhancement with configurable strength)
- Dialogue Boost (vocal frequency equalization with configurable strength)
- Audio normalization (ReplayGain) and channel mix modes
- Virtualizer (3D audio) and Reverb effect presets
- Gapless playback and crossfade between tracks
- Ambient Mode with animated color blobs derived from album art
- Sleep timer with configurable duration
- Smart playlists with criteria-based filtering (genre, artist, year, rating, play count, tags)
- Mood playlists with 10 presets (Happy Vibes, Chill Out, Energetic, Deep Focus, Workout, Melancholy, Romantic, Party Time, Sleep, Late Night Drive)
- Recently played, frequent artists, and recommended albums
- Home sections: Continue Watching, Next Up, Recently Added, Latest, Favorites, and Surprise Me shuffle
- Library browsing with pagination and folder filtering
- Media detail pages with cast, crew, metadata, and related items
- Person detail pages with filmography browsing
- Collection/box set browsing
- Photo album browsing from Jellyfin libraries
- Full-screen photo viewer with zoom and pan
- Swipe navigation between photos
- EXIF metadata display
- Jellyseerr and Overseerr connection support
- Discover trending, popular, and upcoming content
- Request content via Radarr/Sonarr directly from the app
- Full request management screen with:
- Filter by request status (Pending, Approved, Declined, Processing, etc.)
- Filter by media type (All, Movies, TV)
- Sort by Recent or Modified, with ascending/descending toggle
- "My Requests Only" filter for admins
- Paginated request list with prev/next navigation
- Admin actions: Approve, Decline, Retry, Delete requests (with confirmation timer)
- Remove from Radarr/Sonarr action for processed requests
- Request Detail Bottom Sheet — full metadata: poster, title, status badge, overview, request ID, TMDB ID, requester, date, quality profile, root folder, seasons, and download status
- Per-request TMDB metadata enrichment (title, poster, year, overview)
- Seerr detail pages for unavailable media
- Region configuration for streaming and discover content
- 10-step first-run setup wizard shown after initial authentication
- Appearance: Theme, dynamic theming, OLED mode, contrast level, home hero toggle
- Performance: Performance mode toggle for low-end devices
- Home Layout: Home mode (Video/Music), navigation bar labels, enabled home sections
- Video Player: Preferred engine, streaming quality, seek duration, gestures, orientation, autoplay
- Audio Player: Default speed, gapless playback, crossfade, normalization
- Subtitles: Subtitle style customization (font, size, color, background)
- Security: PIN lock, biometric lock, auto-lock timer
- Seerr: Server URL, API key, feature toggles, regions
- Re-accessible anytime from Settings
- Weekly server digest showing library activity from the past 7 days
- Curated sections: Recently Added, Continue Watching, Next Up, Fresh Picks, Activity Digest, Library Stats
- Prominent banner on Home screen when new newsletter content is available
- Full grid view for each section with navigation to details
- Pull-to-refresh and configurable delivery schedule
- Accessible from Home screen and Settings
- WebSocket-based remote control from Jellyfin server
- Receive Play, Pause, Seek, and general commands remotely
- Media browser service integration for third-party controller apps
- Active player management and remote playback reporting
- Directly accessible from the media detail screen for authorized/admin users
- Comprehensive metadata editing (title, original title, tagline, overview, premiere/release dates, sorting titles, and custom ratings)
- Rich artwork manager: Upload, update, or remove Primary, Backdrop, Banner, Logo, Art, Disc, and Thumb images
- Subtitle editor: View embedded subtitle tracks, upload external subtitle files, and delete unwanted external tracks
- Accessible directly via settings menu for server administrators
- Real-time system health monitor showing server status, CPU/Memory load, OS details, and server controls (restart/shutdown)
- Active User Sessions: View all active devices connected to the server, view session details, and end sessions remotely
- Library stats row: Direct overview of item counts across movies, series, episodes, albums, songs, and books
- Scheduled Tasks manager: Monitor, trigger, and cancel scheduled tasks on the Jellyfin server in real-time
- Server Logs viewer: Browse, view, and download active server logs with severity indicators and recent activity timelines
- Running tasks card tracking background operations with live progress updates
- User Statistics: Per-user playback history and statistics with charts
- Stale Media Scanner: Detect unwatched/stale media with background scan worker
- Watched Media Cleanup: Bulk cleanup of watched media with audit history log
- View installed server plugins with version and status info
- Enable/disable plugins remotely
- Plugin configuration viewer
- Create and join synchronized watch groups
- Real-time playback sync with speed-to-sync and skip-to-sync correction
- Server time synchronization for precise coordination
- In-player group chat
- Group settings for repeat and shuffle modes
- Live TV channel browsing with current program info
- Electronic Program Guide (EPG) with program timeline
- DVR recording management
- Custom URI scheme:
jellyplay://media/{id},jellyplay://newsletter/{section},jellyplay://seerr/{tmdbId}/{type} - HTTPS scheme:
https://raulshma.github.io/jellyplay/media/{id},https://raulshma.github.io/jellyplay/newsletter/{section} - Widgets, notifications, and shortcuts all use deep links for navigation
- Watch Progress Heatmap — GitHub-style year-in-review calendar of watch activity
- Filter by media type (All, Movies, Shows)
- Navigate years (current year back 4 years)
- Streak tracking: current streak, longest streak, and total active days
- Tap any day to view session details (media titles, thumbnails, watch time)
- Share heatmap as a PNG image
- Requires Jellyfin Playback Reporting plugin (banner shown if not detected)
- Real-time per-library notifications when new content is added to Jellyfin
- Configurable check interval (minimum 15 minutes via WorkManager)
- Quiet hours support — suppress notifications during configured hours
- Per-library notification channels with custom names
- Grouped notifications with InboxStyle summaries
- Global summary notification when multiple libraries have new items
- Seen-media tracking to avoid duplicate notifications (30-day pruning)
- Notification actions: Open detail (via deep link), Mark as seen
- Video downloads via WorkManager with progress tracking
- Series downloads with episode selection
- Pause, resume, and retry support with HTTP Range resumption
- Offline playback for completed downloads
- Offline Library browser organized by series
- Offline Series view for downloaded episode browsing
- Foreground notification with speed and ETA
Over 230 configurable options across 26 sections:
- Player: engine selection, decoder mode, audio passthrough, orientation, seek duration, gesture toggles, autoplay, controls timeout, preload buffer
- Audio: default speed, gapless playback, crossfade, night mode, dialogue boost, equalizer, audio normalization, channel mix, virtualizer, reverb
- Subtitles: language, style, trickplay, intro/outro skip (manual and auto), tap-to-translate
- SyncPlay: progress reporting, auto-join, sync correction parameters
- Downloads: connections preference, max cache size (with unlimited/0 option support)
- Storage: offline media management, cache size, download location
- Visual: dynamic theming, theme variant (Standard/Synthwave/Soothing/Monochrome), accent color, contrast level, OLED mode, streaming quality, performance mode
- Security: PIN lock, biometric lock, auto-lock timer
- Kids: mode toggle, max content rating
- Screensaver: interval, Ken Burns effect, transition style, image categories, title overlay
- Newsletter: enable/disable, delivery day, notification badge
- Notifications: new media notifications, quiet hours, per-library channels
- Live TV/DVR: channel sources, EPG refresh, recording defaults
- Widget: per-widget source configuration, refresh interval
- Accessibility: color blind modes, blue light filter, reduce motion, haptic intensity, font scaling
- Experimental: feature flags for in-development capabilities
- Seerr: server URL, API key, feature toggles, regions
- Onboarding: re-run setup wizard anytime
- Settings search: find any setting instantly by name
| Category | Technologies |
|---|---|
| Language | Kotlin 2.3, Java 17 |
| UI | Jetpack Compose (BOM 2026.05), Material 3, Material 3 Expressive |
| TV | Android TV Material, Leanback |
| Navigation | Navigation 3 |
| DI | Hilt (Dagger 2.59) |
| Storage | Room, DataStore Preferences, AndroidX Security-Crypto |
| Background | WorkManager, Coroutines, StateFlow |
| Video Players | Media3/ExoPlayer, libmpv, LibVLC |
| Audio Effects | Android Equalizer, LoudnessEnhancer, Virtualizer, Reverb |
| Media Session | Media3 Session, Media3 Cast |
| Casting | Google Play Services Cast, DLNA/UPnP |
| Networking | OkHttp 5, Jellyfin SDK 1.8, kotlinx.serialization |
| Images | Coil 3 (with BlurHash), Palette (color extraction) |
| Typography | Google Fonts (Compose integration) |
| Pagination | Paging 3 |
| Text Recognition | ML Kit |
| Biometrics | AndroidX Biometric |
| Error Tracking | Sentry |
| Testing | JUnit 4, MockK, Espresso, Compose UI Test, Robolectric, UIAutomator, OkHttp MockWebServer, Room Testing |
| Code Quality | Kover (coverage), R8 Full Mode, KSP2 |
| Performance | Baseline Profiles (Macro Benchmark) |
- Android 9.0 (API 28) or later
- JDK 17
- Android Studio with Android SDK (compileSdk 37)
- A Jellyfin server for authentication and playback
Prerequisites
- Android Studio or Gradle CLI
- JDK 17
# Debug builds (phone and TV)
./gradlew assemblePhoneDebug
./gradlew assembleTvDebug
# Release builds
./gradlew assemblePhoneRelease
./gradlew assembleTvReleaseThe project uses product flavors — phone (standard mobile) and tv (Android TV with Leanback launcher). ABI splits produce arm64-v8a, x86_64, and universal APKs.
A GitHub Actions workflow (.github/workflows/release.yml) automates release builds:
- Triggered on push to
v[0-9]+*orrelease/**branches - Auto-calculates version from branch name with git tag-based patch incrementing
- Builds signed release APKs for both phone and TV flavors
- Publishes APKs to GitHub Releases with auto-generated release notes
| Permission | Purpose |
|---|---|
INTERNET |
Jellyfin API access and media playback |
ACCESS_NETWORK_STATE |
Network connectivity monitoring |
ACCESS_WIFI_STATE |
WiFi state for server discovery and streaming |
CHANGE_WIFI_MULTICAST_STATE |
Jellyfin server auto-discovery |
FOREGROUND_SERVICE |
Foreground service for playback and downloads |
FOREGROUND_SERVICE_MEDIA_PLAYBACK |
Media playback foreground service type |
FOREGROUND_SERVICE_DATA_SYNC |
Download worker foreground service type |
POST_NOTIFICATIONS |
Playback, download, and widget notifications |
USE_BIOMETRIC |
Biometric authentication (fingerprint/face) |
app/ Main Android application module (deep links, widgets, Cast, PiP, shortcuts)
core/model/ Shared data models (55+ model files)
core/designsystem/ Shared theming (4 variants), colors, shapes, typography, motion
core/network/ Jellyfin API clients (12), Seerr client, LRCLIB API, server discovery
core/database/ Room database (16 DAOs), migration schemas
core/datastore/ DataStore preferences (~231 settings), encrypted credentials
core/data/ Repositories, playback managers, audio effects, SyncPlay, Cast, downloads
core/ui/ Shared UI components, adaptive layouts, TV focus, animations, navigation
core/notification/ New media notification system (worker, scheduler, dispatcher, channels)
core/testing/ Shared test utilities
feature/auth/ Server selection and authentication
feature/onboarding/ First-run setup wizard (10-step preferences)
feature/home/ Home screen, Kids home, newsletter banner, and discover sections
feature/library/ Library browsing and media collections
feature/search/ Search experience with history
feature/details/ Media detail, person detail, collection detail, Seerr detail
feature/player/video/ Video playback UI, multi-engine support, SyncPlay integration
feature/player/audio/ Audio playback UI, lyrics, equalizer, ambient mode
feature/downloads/ Download management, offline library, and offline playback
feature/settings/ Settings, server/user management, Seerr configuration, settings search
feature/music/ Music browsing, smart/mood playlists, artist/album details
feature/livetv/ Live TV channels, EPG guide, and DVR
feature/syncplay/ SyncPlay group management and watch party UI
feature/editor/ Metadata, artwork, and subtitle editor for media items
feature/admin/ Admin dashboard for server status, active devices, logs, tasks, user stats
feature/newsletter/ Weekly server digest with library activity, curated picks, and stats
feature/insights/ Watch progress heatmap with streak tracking and share-as-image
feature/requests/ Jellyseerr/Overseerr request management with filter/sort/admin actions
feature/shortcuts/ App shortcuts (static + dynamic, e.g. Continue Listening)
baselineprofile/ Baseline profile generator for startup optimization
website/ Landing page (GitHub Pages)
docs/ Documentation guides
Looking for setup, integration, or troubleshooting guides?
- 📘 Setup guide — install JellyPlay on any device
- 🎬 Android TV & Fire TV setup — sideload & install on the big screen
- 📡 Jellyseerr/Seerr/Overseerr integration — request movies & shows from inside the app
- 👯 SyncPlay watch parties — synchronized group playback
- ⬇️ Offline downloads — download media for travel
- 🎵 Music player & synced lyrics — get the most out of your library
- 🎬 Player engines comparison — ExoPlayer vs libmpv vs LibVLC
Other open-source projects in the Jellyfin ecosystem:
- jellyfin/jellyfin — the free software media system
- jellyfin/jellyfin-android — the official Android client (web wrapper)
- jellyfin/jellyfin-androidtv — the official Android TV client
- jarnedemeulemeester/findroid — third-party native Android client
- damontecres/Wholphin — OSS Android TV client
- MakD/AFinity — modern Compose + LibMPV client
- streamyfin/streamyfin — cross-platform Expo client
- fallensword/awesome-jellyfin — curated list of Jellyfin plugins, themes & clients
| Metric | Value |
|---|---|
| Gradle modules | 30 (app + 9 core + 19 feature + 1 baseline profile) |
| Feature modules | 19 |
| Configurable settings | ~231 |
| Data models | 55+ |
| API clients | 12 |
| Room DAOs | 16 |
| Supported languages | 9 (en, de, es, fr, it, pt, ja, ko, zh) |
| External integrations | Jellyfin, Jellyseerr/Overseerr, LRCLIB, TMDB, Google Cast, Sentry |
| Min SDK | 28 (Android 9.0) |
| Target/Compile SDK | 37 |
| Current version | v0.7.11 (Active Beta) |
We welcome contributions of all sizes — bug reports, feature requests, code, translations, and documentation.
This project is licensed under the GNU General Public License v3.0 — see
the LICENSE file for details.
By contributing to JellyPlay, you agree that your contributions will be licensed under the same GPL-3.0 license.