From a1c5c9475371128054be5535d9544daa23dcba7e Mon Sep 17 00:00:00 2001
From: TiA4f8R <74829229+TiA4f8R@users.noreply.github.com>
Date: Sat, 27 Nov 2021 16:52:54 +0100
Subject: [PATCH] Add some comments and a JavaDoc

---
 .../org/schabi/newpipe/player/Player.java     | 26 +++++++++++++++++--
 .../resolver/VideoPlaybackResolver.java       |  8 +++---
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/app/src/main/java/org/schabi/newpipe/player/Player.java b/app/src/main/java/org/schabi/newpipe/player/Player.java
index 3cfa74ac2..791f8efc7 100644
--- a/app/src/main/java/org/schabi/newpipe/player/Player.java
+++ b/app/src/main/java/org/schabi/newpipe/player/Player.java
@@ -3295,9 +3295,18 @@ public final class Player implements
         } else {
             if (isAudioOnly
                     && !videoResolver.wasLastResolvedVideoAndAudioSeparated().orElse(false)) {
+                // If the current info has only video streams with audio and if the stream is
+                // played as audio, we need to use the audio resolver, otherwise the video stream
+                // will be played in background.
                 return audioResolver.resolve(info);
             }
 
+            // Even if the stream is played in background, we need to use the video resolver if the
+            // info played is separated video-only and audio-only streams; otherwise, if the audio
+            // resolver was called when the app was in background, the app will only stream audio
+            // when the user come back to the app and will never fetch the video stream.
+            // Note that the video is not fetched when the app is in background because the video
+            // renderer is fully disabled (see useVideoSource method).
             return videoResolver.resolve(info);
         }
     }
@@ -4160,8 +4169,8 @@ public final class Player implements
         }
 
         isAudioOnly = !videoEnabled;
-        // When a user returns from background controls could be hidden
-        // but systemUI will be shown 100%. Hide it
+        // When a user returns from background, controls could be hidden but SystemUI will be shown
+        // 100%. Hide it.
         if (!isAudioOnly && !isControlsVisible()) {
             hideSystemUIIfNeeded();
         }
@@ -4198,9 +4207,13 @@ public final class Player implements
             final TrackGroupArray videoTrackGroupArray = Objects.requireNonNull(
                     trackSelector.getCurrentMappedTrackInfo()).getTrackGroups(videoRenderIndex);
             if (videoEnabled) {
+                // Clearing the null selection override enable again the video stream (and its
+                // fetching).
                 trackSelector.setParameters(trackSelector.buildUponParameters()
                         .clearSelectionOverride(videoRenderIndex, videoTrackGroupArray));
             } else {
+                // Using setRendererDisabled still fetch the video stream in background, contrary
+                // to setSelectionOverride with a null override.
                 trackSelector.setParameters(trackSelector.buildUponParameters()
                         .setSelectionOverride(videoRenderIndex, videoTrackGroupArray, null));
             }
@@ -4436,6 +4449,15 @@ public final class Player implements
     }
     //endregion
 
+    /**
+     * Get the video renderer index of the current playing stream.
+     *
+     * This method returns the video renderer index of the current
+     * {@link MappingTrackSelector.MappedTrackInfo} or {@link #RENDERER_UNAVAILABLE} if the current
+     * {@link MappingTrackSelector.MappedTrackInfo} is null or if there is no video renderer index.
+     *
+     * @return the video renderer index or {@link #RENDERER_UNAVAILABLE} if it cannot be get
+     */
     private int getVideoRendererIndex() {
         final MappingTrackSelector.MappedTrackInfo mappedTrackInfo = trackSelector
                 .getCurrentMappedTrackInfo();
diff --git a/app/src/main/java/org/schabi/newpipe/player/resolver/VideoPlaybackResolver.java b/app/src/main/java/org/schabi/newpipe/player/resolver/VideoPlaybackResolver.java
index 8085e4b3e..654f91334 100644
--- a/app/src/main/java/org/schabi/newpipe/player/resolver/VideoPlaybackResolver.java
+++ b/app/src/main/java/org/schabi/newpipe/player/resolver/VideoPlaybackResolver.java
@@ -128,11 +128,11 @@ public class VideoPlaybackResolver implements PlaybackResolver {
     }
 
     /**
-     * Determines if the last resolved StreamInfo had separated audio and video streams
-     * (or only audio).
+     * Determine if the last resolved {@link StreamInfo} had separated audio and video streams (or
+     * only audio).
      *
-     * @return {@link Optional#empty()} if nothing was resolved
-     * otherwise <code>true</code> or <code>false</code>
+     * @return {@link Optional#empty()} if nothing was resolved, otherwise {@code true} or
+     * {@code false}
      */
     public Optional<Boolean> wasLastResolvedVideoAndAudioSeparated() {
         return Optional.ofNullable(wasLastResolvedVideoAndAudioSeparated);