mirror of
https://github.com/JustinZeus/Wholphin.git
synced 2026-07-08 15:50:16 +02:00
An OSS Android TV client for Jellyfin
aeaecc0f59
## Description This PR aims to fix #638 where the "Suggestions" row was mixing up content from different libraries that shared the same library type. For example you were in the Anime library, you'd see regular TV shows showing up, as the TV Shows and Anime libraries would both be "Show" libraries. As @damontecres mentioned in the issue discussion, the `/Items/Suggestions` endpoint Wholphin is using just returns random items from the same library type, with no special logic or recommendation algorithm. I also looked at how the official WebUI handles this. It basically just mixes "Resume," "Next Up," and "Latest Items" together. That felt a bit redundant since we usually have dedicated rows for those things anyway; I wanted to try something that helps discover new content. I replaced the broken endpoint with a few custom `GetItemsRequest` calls. These work correctly with the `ParentId` filter, so we only get results from the library we are actually looking at. Additionally, I added in some logic that takes into account what the user has been watching to tailor the suggestions a little bit. The new logic uses a 40/30/30 mix (this can of course be tweaked as needed) - Tailored (40%): Grabs your recently watched items from this library, checks their genres, and returns items from the same genre. - Random (30%): Random unwatched stuff from this library. - New (30%): Recently added items. This is implemented using only `GetItemsRequest` API calls using filters, rather than any specialized endpoints like the `/Items/Suggestions` endpoint. This means the feature should be predictable and stable. If Jellyfin ever adds an actual recommendation algorithm and endpoint to call it, I imagine we would want to switch to that in the future though. I also added some failsafe logic to make sure there will be diversity in the "recently watched" items that get pulled, in case a user might have recently binged a TV show. We wouldn't want every single recommendation to be based off of that one show. To fix this, I changed the query to fetch the last 20 history items instead of just the top 3. Then, we filter that list client-side to find unique Series IDs. If the user watched 10 episodes of One Piece in a row, the logic collapses them into a single "One Piece" entry and moves on to the next distinct show they watched. This guarantees we get variety in the source material for recommendations. This is a work in progress right now, mainly due to performance. For my server it takes about 10-15 seconds to load the Suggestions row when I tested. This is unacceptable in my opinion, especially if we ever intend to add a Suggestions row like this to the home page like Plex does. I have some ideas on how to improve performance, but I'm open to suggestions. ### Related issues Resolves #638 ### Screenshots Before: <img width="1953" height="1162" alt="suggestions1" src="https://github.com/user-attachments/assets/6e301c67-1a46-46b5-8184-3adb9e52b330" /> After: <img width="1937" height="1108" alt="suggestions3" src="https://github.com/user-attachments/assets/b9563865-4055-40b6-b452-f94c26c8b6e9" /> ### AI/LLM usage I used Claude Code to help write the Kotlin Coroutines so the API calls run at the same time. I also used it to write the tests in `TestSuggestionsLogic.kt`. --------- Co-authored-by: Damontecres <damontecres@gmail.com> |
||
|---|---|---|
| .github | ||
| app | ||
| gradle | ||
| scripts | ||
| .editorconfig | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| build.gradle.kts | ||
| CONTRIBUTING.md | ||
| DEVELOPMENT.md | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| LICENSE | ||
| README.md | ||
| settings.gradle.kts | ||
Wholphin - an OSS Android TV client for Jellyfin
"Never half-phin two jellies. Always wholphin one jelly."
Wholphin is an open-source Android TV client for Jellyfin. It aims to provide a different app UI that's inspired by Plex for users interested in migrating to Jellyfin.
This is not a fork of the official client. Wholphin's user interface and controls have been written completely from scratch. Wholphin supports playing media using either ExoPlayer or MPV.
Features
User interface
- A navigation drawer for quick access to libraries, favorites, search, and settings from almost anywhere in the app
- Integration with Jellyseerr to discover new movies and TV shows
- Option to combine Continue Watching & Next Up rows
- Show Movie/TV Show titles when browsing libraries
- Play theme music, if available
- Customize subtitle style for plain text subtitles
- Search & download subtitles (requires compatible server plugin such as OpenSubtitles)
- Customize layout grids for libraries
- Multiple app color themes
- Protect user profile switches with PIN code
Playback
- Different media playback engines:
- ExoPlayer w/ optional extra audio & AV1 software decoding
- MPV for direct playing anything plus ASS subtitle support
- Plex inspired playback controls:
- Using D-Pad left/right for seeking during playback
- Quickly access video chapters & queue during playback
- Optionally skip back a few seconds when resuming playback
- Live TV & DVR support
- Auto play next episodes with pass out protection
- Option for automatic refresh rate & resolution switching on supported displays
- Trickplay support
- Subtly show playback position along the bottom of the screen while seeking w/ D-Pad
Roadmap
Installation
Using Google Play or Amazon appstore are the fastest way to install. But you can follow these instructions to install without needing an app store
Downloader Code: 8668671
- Enable side-loading "unknown" apps
- https://androidtvnews.com/unknown-sources-chromecast-google-tv/
- https://www.xda-developers.com/how-to-sideload-apps-android-tv/
- https://developer.android.com/distribute/marketing-tools/alternative-distribution#unknown-sources
- https://www.aftvnews.com/how-to-enable-apps-from-unknown-sources-on-an-amazon-fire-tv-or-fire-tv-stick/
- Install the APK on your Android TV device with one of these options:
- Install a browser program such as Downloader, use it to get the latest apk with short code
8668671or URL: http://aftv.news/8668671 - Download the latest APK release from the releases page or http://aftv.news/8668671
- Put the APK on an SD Card/USB stick/network share and use a file manager app from the Google Play Store / Amazon AppStore (e.g.
FX File Explorer). Android's preinstalled file manager probably will not work! - Use
Send files to TVfrom the Google Play Store on your phone & TV - (Expert) Use ADB to install the APK from your computer (guide)
- Put the APK on an SD Card/USB stick/network share and use a file manager app from the Google Play Store / Amazon AppStore (e.g.
- Install a browser program such as Downloader, use it to get the latest apk with short code
Upgrading the app
After the initial install above, the app will automatically check for updates. The updates can be installed in settings.
The first time you attempt an update, the OS should guide you through enabling the required additional permissions for the app to install updates.
Note: if installed via an app store, the app store will handle updates.
Compatibility
Requires Android 6+ (or Fire TV OS 6+) and Jellyfin server 10.10.x or 10.11.x (tested on primarily 10.11).
The app is tested on a variety of Android TV/Fire TV OS devices, but if you encounter issues, please file an issue!
Jellyseerr integration is tested with v2.7.3. Older versions may not work.
Contributions
Issues and pull requests are always welcome! Please check before submitting that your issue or pull request is not a duplicate.
If you plan to contribute, please read the contributing guide!
You can help translate Wholphin!
Acknowledgements
- Thanks to the Jellyfin team for creating and maintaining such a great open-source media server
- Thanks to the official Jellyfin Android TV client developers, some code for creating the device direct play profile is adapted from there
- Thanks to the Jellyfin Kotlin SDK developers for making it easier to interact with the Jellyfin server API
- Thanks to numerous other libraries that make app development even possible