added: documentations to MediaItemTags.

Author: karyogamy

app/src/main/java/org/schabi/newpipe/player/Player.java

@@ -2486,6 +2486,7 @@ private void setMuteButton(@NonNull final ImageButton button, final boolean isMu
     //////////////////////////////////////////////////////////////////////////*/
     //region ExoPlayer listeners (that didn't fit in other categories)
 
+    @Override
     public void onEvents(@NonNull final com.google.android.exoplayer2.Player player,
                          @NonNull final com.google.android.exoplayer2.Player.Events events) {
         Listener.super.onEvents(player, events);

app/src/main/java/org/schabi/newpipe/player/mediaitem/ExceptionTag.java

@@ -10,6 +10,16 @@
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
+/**
+ * This {@link MediaItemTag} object is designed to contain metadata for a stream
+ * that has failed to load. It supplies metadata from an underlying
+ * {@link PlayQueueItem}, which is used by the internal players to resolve actual
+ * playback info.
+ *
+ * This {@link MediaItemTag} does not contain any {@link StreamInfo} that can be
+ * used to start playback and can be detected by checking {@link ExceptionTag#getErrors()}
+ * when in generic form.
+ **/
 public final class ExceptionTag implements MediaItemTag {
     @NonNull
     private final PlayQueueItem item;

app/src/main/java/org/schabi/newpipe/player/mediaitem/MediaItemTag.java

@@ -4,6 +4,7 @@
 
 import com.google.android.exoplayer2.MediaItem;
 import com.google.android.exoplayer2.MediaMetadata;
+import com.google.android.exoplayer2.Player;
 
 import org.schabi.newpipe.extractor.stream.StreamInfo;
 import org.schabi.newpipe.extractor.stream.StreamType;
@@ -16,6 +17,13 @@
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
+/**
+ * Metadata container and accessor used by player internals.
+ *
+ * This interface ensures consistency of fetching metadata on each stream,
+ * which is encapsulated in a {@link MediaItem} and delivered via ExoPlayer's
+ * {@link Player.Listener} on event triggers to the downstream users.
+ **/
 public interface MediaItemTag {
 
     List<Throwable> getErrors();

app/src/main/java/org/schabi/newpipe/player/mediaitem/PlaceholderTag.java

@@ -10,6 +10,12 @@
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
+/**
+ * This is a Placeholding {@link MediaItemTag}, designed as a dummy metadata object for
+ * any stream that has not been resolved.
+ *
+ * This object cannot be instantiated and does not hold real metadata of any form.
+ * */
 public final class PlaceholderTag implements MediaItemTag {
     public static final PlaceholderTag EMPTY = new PlaceholderTag(null);
     private static final String UNKNOWN_VALUE_INTERNAL = "Placeholder";

app/src/main/java/org/schabi/newpipe/player/mediaitem/StreamInfoTag.java

@@ -1,5 +1,7 @@
 package org.schabi.newpipe.player.mediaitem;
 
+import com.google.android.exoplayer2.MediaItem;
+
 import org.schabi.newpipe.extractor.stream.StreamInfo;
 import org.schabi.newpipe.extractor.stream.StreamType;
 import org.schabi.newpipe.extractor.stream.VideoStream;
@@ -11,6 +13,12 @@
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
+/**
+ * This {@link MediaItemTag} object contains metadata for a resolved stream
+ * that is ready for playback. This object guarantees the {@link StreamInfo}
+ * is available and may provide the {@link Quality} of video stream used in
+ * the {@link MediaItem}.
+ **/
 public final class StreamInfoTag implements MediaItemTag {
     @NonNull
     private final StreamInfo streamInfo;

app/src/main/java/org/schabi/newpipe/player/mediasource/FailedMediaSource.java

@@ -23,7 +23,15 @@
 import androidx.annotation.Nullable;
 
 public class FailedMediaSource extends CompositeMediaSource<Void> implements ManagedMediaSource {
-    private static final long SILENCE_DURATION_US = TimeUnit.SECONDS.toMicros(2);
+    /**
+     * Play 2 seconds of silenced audio when a stream fails to resolve due to a known issue,
+     * such as {@link org.schabi.newpipe.extractor.exceptions.ExtractionException}.
+     *
+     * This silence duration allows user to react and have time to jump to a previous stream,
+     * while still provide a smooth playback experience. A duration lower than 1 second is
+     * not recommended, it may cause ExoPlayer to buffer for a while.
+     * */
+    public static final long SILENCE_DURATION_US = TimeUnit.SECONDS.toMicros(2);
 
     private final String TAG = "FailedMediaSource@" + Integer.toHexString(hashCode());
     private final PlayQueueItem playQueueItem;
@@ -32,7 +40,7 @@ public class FailedMediaSource extends CompositeMediaSource<Void> implements Man
     private final MediaSource source;
     private final MediaItem mediaItem;
     /**
-     * Permanently fail the play queue item associated with this source, with no hope of retrying.
+     * Fail the play queue item associated with this source, with potential future retries.
      *
      * The error will be propagated if the cause for load exception is unspecified.
      * This means the error might be caused by reasons outside of extraction (e.g. no network).