justinzeus/Wholphin
1
0
Fork 0
mirror of https://github.com/JustinZeus/Wholphin.git synced 2026-07-08 23:51:21 +02:00
Code Issues Projects Packages Wiki Activity Actions
Wholphin/DEVELOPMENT.md
damontecres 20bef8fb6a
Automatic refresh rate switching setting (#382) 
Adds an advanced playback setting to enable automatic refresh rate
switching during playback

When enabled, the app looks at the available display modes, chooses the
best candidate, and attempts to switch to it. After playback ends, the
display is switched back to the original mode.

Closes #62
Closes #379
2025-12-06 16:35:43 -05:00

3.5 KiB
Raw Blame History

Wholphin developer's guide

See also the Contributing guide for general information on contributing to the project.

Overview

This project is an Android TV client for Jellyfin. It is written in Kotlin and uses the official Jellyfin Kotlin SDK to interact with the server.

The app is a single Activity (MainActivity) with MVVM architecture.

The app uses:

Getting started

We follow GitHub's fork & pull request model for contributions.

After forking and cloning your fork, you can import the project into Android Studio.

You need a compatible Android Studio version for the configured AGP. This is generally Narwhal 3 Feature Drop | 2025.1.3 or newer. See https://developer.android.com/build/releases/gradle-plugin and `libs.versions.toml.

Code organization

Code is split into several packages:

  • data - app-specific data models and services
  • preferences - Non-UI related code for user settings and preferences
  • services - hilt injectable services often used by ViewModels for API calls
  • ui - User interface code and ViewModels
  • util - Utility classes and functions

Native components

FFmpeg decoder module

Wholphin ships with media3 ffmpeg decoder module.

It is not required to build the extension in order to build the app locally.

You can build the module on MacOS or Linux with the build_ffmpeg_decoder.sh script.

MPV player backend

Wholphin has a playback engine that uses libmpv. The app uses JNI code from mpv-android and has an implementation of androidx.media3.common.Player to swap out for ExoPlayer.

See the build scripts for details on building this component.

App settings

App settings are available with the AppPreferences object and defined by different AppPreference objects (note the s differences).

The AppPreference objects are used to create the UI for configuring settings using the composable functions in com.github.damontecres.wholphin.ui.preferences.

How to add a new app setting

  1. Add entry in WholphinDataStore.proto & build to generate classes
  2. Add new AppPreference object in AppPreference.kt
  3. Add new object to a PreferenceGroup (listed in AppPreference.kt)
  4. Update AppPreferencesSerializer to set the default value for new installs
  5. If needed, update AppUpgradeHandler to set the default value for app upgrades
    • Since preferences use proto3, the default values are zero, false, or the first enum, so only need this step if the default value is different