document some data classes

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

@@ -20,6 +20,9 @@
 
 package net.newpipe.newplayer.data
 
+/**
+ * An Exception, but from NewPlayer.
+ */
 class NewPlayerException : Exception {
     constructor(message: String) : super(message)
     constructor(message: String, cause: Throwable) : super(message, cause)

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

@@ -22,6 +22,18 @@ package net.newpipe.newplayer.data
 
 import android.net.Uri
 
+/**
+ * A stream represents one actual video stream that is associated with a video.
+ * Each stream has its own URI (and therefore correspond to one individual video container).
+ * Each stream can contain multiple audio/video tracks.
+ *
+ * @param item The item the stream belongs to.
+ * @param streamUri the URI of the stream.
+ * @param streamTracks the tracks that the stream contains
+ * @param mimeType The mime type of the stream. This may only be set if ExoPlayer might not be
+ * able to infer the type of of the stream from the Uri itself.
+ * @param isDashOrHls depicts wather its a dynamic stream or not.
+ */
 data class Stream(
     val item: String,
     val streamUri: Uri,
@@ -30,9 +42,13 @@ data class Stream(
     val isDashOrHls: Boolean = false
 ) {
 
+    /**
+     * The list of audio languages provided by the stream.
+     */
     val languages: List<String>
         get() = streamTracks.filterIsInstance<AudioStreamTrack>().mapNotNull { it.language }
 
+
     val hasAudioTracks: Boolean
         get() {
             streamTracks.forEach { if (it is AudioStreamTrack) return true }
@@ -52,9 +68,7 @@ data class Stream(
     val audioStreamTrack: List<AudioStreamTrack>
         get() = streamTracks.filterIsInstance<AudioStreamTrack>()
 
-    override fun equals(other: Any?) =
-        other is Stream
-                && other.hashCode() == this.hashCode()
+    override fun equals(other: Any?) = other is Stream && other.hashCode() == this.hashCode()
 
     override fun hashCode(): Int {
         var result = item.hashCode()

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

@@ -20,8 +20,14 @@
 
 package net.newpipe.newplayer.data
 
+import androidx.media3.exoplayer.source.MergingMediaSource
 import net.newpipe.newplayer.logic.TrackUtils
 
+/**
+ * A selection of streams that should be used for playback.
+ * This is used by the stream selection algorithm to depict which streams should be used
+ * to build a MediaSource from and thus forward to the actual ExoPlayer.
+ */
 interface StreamSelection {
     val item: String
 
@@ -31,6 +37,11 @@ interface StreamSelection {
     val isDynamic:Boolean
 }
 
+/**
+ * This is used if only one single stream should be forwarded to ExoPlayer.
+ * This can be either a DASH/HLS stream or a progressive stream that has all the required
+ * tracks already muxed together.
+ */
 data class SingleSelection(
     val stream: Stream
 ) : StreamSelection {
@@ -50,6 +61,17 @@ data class SingleSelection(
         get() = stream.isDashOrHls
 }
 
+/**
+ * This can be used if tracks from multiple streams should be forwarded to ExoPlayer, so
+ * ExoPlayer can mux them together.
+ * This StreamSelection will be made into a [MergingMediaSource].
+ * This stream selection will not depict which of the tracks contained in the StreamSelection
+ * should be muxed together by ExoPlayer. This MultiSelection only depicts that at least all the
+ * tracks that should be played are contained.
+ *
+ * The information to pick the actual tracks out of the available tracks within this selection
+ * bust be given to ExoPlayer through another mechanism. (You see this is still TODO).
+ */
 data class MultiSelection(
     val streams: List<Stream>
 ) : StreamSelection {

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

@@ -20,13 +20,19 @@
 
 package net.newpipe.newplayer.data
 
+/**
+ * Media3 does not provide a class to represent individual tracks. So here we go.
+ */
 interface StreamTrack : Comparable<StreamTrack> {
     val fileFormat: String
 
     fun toShortIdentifierString(): String
     fun toLongIdentifierString(): String
 }
 
+/**
+ * A track representing a video track.
+ */
 data class VideoStreamTrack(
     val width: Int,
     val height: Int,
@@ -74,6 +80,9 @@ data class VideoStreamTrack(
 
 }
 
+/**
+ * A track representing an audio track.
+ */
 data class AudioStreamTrack(
     val bitrate: Int,
     override val fileFormat: String,

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

@@ -22,6 +22,9 @@ package net.newpipe.newplayer.data
 
 import android.net.Uri
 
+/**
+ * TODO
+ */
 data class Subtitle(
     val uri: Uri,
     val identifier: String

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

@@ -21,7 +21,20 @@
 
 package net.newpipe.newplayer.data
 
+/**
+ * This class depicts video sizes. A Media3 implementation ([androidx.media3.common.VideoSize])
+ * could have been used, however because of the pixelWidthHeightRatio stuff I wanted a tool that
+ * I can control better.
+ *
+ * @param width depicts the width of the video with which it is encoded with
+ *      (not with which it is played back with).
+ * @param height depicts the height of the video with which it is encoded with
+ *      (not with which it is played back with).
+ * @param pixelWidthHeightRatio the ratio of each individual pixel. Normally it's 1 but some
+ *      (older) media.ccc videos go wonky.
+ */
 internal data class VideoSize(
+
     val width: Int,
     val height: Int,
     /// The width/height ratio of a single pixel
@@ -39,7 +52,7 @@ internal data class VideoSize(
         }
 
     override fun hashCode() =
-        width + height * 9999999 + (pixelWidthHeightRatio*10000).toInt()
+        width + height * 999999 + (pixelWidthHeightRatio*10000).toInt()
 
     fun getRatio() =
         (width * pixelWidthHeightRatio) / height

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

@@ -4,6 +4,9 @@ import net.newpipe.newplayer.data.Stream
 import net.newpipe.newplayer.data.StreamSelection
 import net.newpipe.newplayer.data.StreamTrack
 
+/**
+ * TODO
+ */
 internal object ConstraintStreamSelector {
     fun selectStream(
         availableStreams: List<Stream>,

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

@@ -36,6 +36,9 @@ import net.newpipe.newplayer.data.SingleSelection
 import net.newpipe.newplayer.data.Stream
 import net.newpipe.newplayer.data.StreamSelection
 
+/**
+ * This class help to transforms a [StreamSelection] into a [MediaSource].
+ */
 @OptIn(UnstableApi::class)
 internal class MediaSourceBuilder
     (