partially document newplayer interface

new-player/src/main/java/net/newpipe/newplayer/NewPlayer.kt

@@ -28,8 +28,6 @@ import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.flow.StateFlow
 import net.newpipe.newplayer.data.Chapter
-import net.newpipe.newplayer.data.Stream
-import net.newpipe.newplayer.data.StreamSelection
 import net.newpipe.newplayer.data.StreamTrack
 import kotlin.Exception
 
@@ -52,18 +50,63 @@ enum class RepeatMode {
 
 interface NewPlayer {
     // preferences
+
+    /**
+     * Sets the default languages the user prefers. This can be overridden per stream
+     * via [currentStreamLanguageConstraint].
+     */
     var preferredStreamLanguages: List<String>
+
+    /**
+     * The Icon that should be shown in the media notification.
+     */
     val notificationIcon: IconCompat
+
+    /**
+     * The class of the activity that holds the NewPlayerUI.
+     */
     val playerActivityClass: Class<Activity>
 
+    /**
+     * The exoPlayer NewPlayer uses.
+     * Since NewPlayer might kill its exoplayer depending on the playback state,
+     * the player itself is wrapped in a StateFlow. This way the NewPlayerUI can be notified
+     * of a new ExoPlayer being created once the playback state switches away from IDLE.
+     */
     val exoPlayer: StateFlow<Player?>
+
+    /**
+     * Same as ExoPlayer's playWhenReady. See [Player.setPlayWhenReady]
+     */
     var playWhenReady: Boolean
+
+    /**
+     * Same as ExoPlayer's duration. See [Player.getDuration]
+     */
     val duration: Long
+
+    /**
+     * Same as ExoPlayer's bufferedPercentage. See [Player.getBufferedPercentage]
+     */
     val bufferedPercentage: Int
+
+    /**
+     * Same as ExoPlayer's currentPosition. See [Player.getCurrentPosition]
+     */
     var currentPosition: Long
+
+    /**
+     * Amount of seconds that should be skipped on a fast seek action.
+     */
     var fastSeekAmountSec: Int
+
     val playBackMode: MutableStateFlow<PlayMode>
+
+    /**
+     * Same as ExoPlayer's shuffle. See [Player.getShuffleModeEnabled]
+     */
     var shuffle: Boolean
+
     var repeatMode: RepeatMode
     val repository: MediaRepository
 
@@ -76,6 +119,14 @@ interface NewPlayer {
     val currentlyPlayingTracks: StateFlow<List<StreamTrack>>
     val currentlyAvailableTracks: StateFlow<List<StreamTrack>>
 
+    /**
+     * Overrides the [preferredStreamLanguages] and picks one specific language
+     * This value then only works for the current stream. If the stream changes this
+     * value switches back to null, and the [preferredStreamLanguages] are used for stream selection.
+     * This is used to pick one specific stream.
+     */
+    var currentStreamLanguageConstraint: String?
+
     // callbacks
 
     val errorFlow: SharedFlow<Exception>

new-player/src/main/java/net/newpipe/newplayer/NewPlayerImpl.kt

@@ -61,7 +61,7 @@ import net.newpipe.newplayer.data.StreamSelection
 import net.newpipe.newplayer.logic.ReplaceStreamSelectionResponse
 import net.newpipe.newplayer.data.StreamTrack
 import net.newpipe.newplayer.logic.ReplaceItemResponse
-import net.newpipe.newplayer.logic.StreamSelector
+import net.newpipe.newplayer.logic.AutoStreamSelector
 import net.newpipe.newplayer.logic.TrackUtils
 import kotlin.random.Random
 
@@ -177,6 +177,8 @@ class NewPlayerImpl(
     override val currentlyPlayingTracks: StateFlow<List<StreamTrack>> =
         mutableCurrentlyPlayingTracks.asStateFlow()
 
+    override var currentStreamLanguageConstraint: String? = null
+
     private fun setupNewExoplayer() {
         val newExoPlayer = ExoPlayer.Builder(app)
             .setAudioAttributes(AudioAttributes.DEFAULT, true)
@@ -466,11 +468,11 @@ class NewPlayerImpl(
     @OptIn(UnstableApi::class)
     private suspend
     fun toMediaSource(item: String): MediaSource {
-        val streamSelector = StreamSelector(
+        val autoStreamSelector = AutoStreamSelector(
             preferredLanguages = preferredStreamLanguages
         )
 
-        val selection = streamSelector.selectStreamAutomatically(
+        val selection = autoStreamSelector.selectStreamAutomatically(
             item,
             availableStreams = repository.getStreams(item),
         )

new-player/src/main/java/net/newpipe/newplayer/logic/StreamSelector.kt → new-player/src/main/java/net/newpipe/newplayer/logic/AutoStreamSelector.kt

@@ -31,7 +31,7 @@ import net.newpipe.newplayer.logic.TrackUtils.tryAndGetMedianAudioOnlyTracks
 import net.newpipe.newplayer.logic.TrackUtils.tryAndGetMedianCombinedVideoAndAudioTracks
 import net.newpipe.newplayer.logic.TrackUtils.tryAndGetMedianVideoOnlyTracks
 
-internal class StreamSelector(
+internal class AutoStreamSelector(
     /**
      * Must be in IETF-BCP-47 format
      */