Skip to content

Commit 43e0e6a

Browse files
AudricVAudricV
committed
Add missing JavaDocs for Stream classes
1 parent 76e2a27 commit 43e0e6a

4 files changed

Lines changed: 311 additions & 34 deletions

File tree

‎extractor/src/main/java/org/schabi/newpipe/extractor/stream/AudioStream.java‎

Lines changed: 103 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ public class AudioStream extends Stream {
3030
public static final int UNKNOWN_BITRATE = -1;
3131

3232
private final int averageBitrate;
33-
// Fields for Dash
33+
// Fields for DASH
3434
private int itag;
3535
private int bitrate;
3636
private int initStart;
@@ -41,10 +41,14 @@ public class AudioStream extends Stream {
4141
private String codec;
4242

4343
/**
44-
* Create a new audio stream
45-
* @param url the url
46-
* @param format the format
47-
* @param averageBitrate the average bitrate
44+
* Create a new audio stream.
45+
*
46+
* @param id the ID which uniquely identifies the stream, e.g. for YouTube this
47+
* would be the itag
48+
* @param url the URL of the stream
49+
* @param format the {@link MediaFormat} used by the stream
50+
* @param averageBitrate the average bitrate of the stream (which can be unknown, see
51+
* {@link #UNKNOWN_BITRATE})
4852
*/
4953
public AudioStream(final String id,
5054
final String url,
@@ -54,13 +58,18 @@ public AudioStream(final String id,
5458
}
5559

5660
/**
57-
* Create a new audio stream
58-
* @param id the ID which uniquely identifies the file, e.g. for YouTube this would be the itag
59-
* @param content the content or URL, depending on whether isUrl is true
60-
* @param isUrl whether content is the URL or the actual content of e.g. a DASH manifest
61-
* @param format the format
62-
* @param deliveryMethod the delivery method
63-
* @param averageBitrate the average bitrate
61+
* Create a new audio stream.
62+
*
63+
* @param id the ID which uniquely identifies the stream, e.g. for YouTube this
64+
* would be the itag
65+
* @param content the content or the URL of the stream, depending on whether isUrl is
66+
* true
67+
* @param isUrl whether content is the URL or the actual content of e.g. a DASH
68+
* manifest
69+
* @param format the {@link MediaFormat} used by the stream
70+
* @param deliveryMethod the {@link DeliveryMethod} of the stream
71+
* @param averageBitrate the average bitrate of the stream (which can be unknown, see
72+
* {@link #UNKNOWN_BITRATE})
6473
*/
6574
public AudioStream(final String id,
6675
final String content,
@@ -72,6 +81,23 @@ public AudioStream(final String id,
7281
this.averageBitrate = averageBitrate;
7382
}
7483

84+
/**
85+
* Create a new audio stream.
86+
*
87+
* @param id the ID which uniquely identifies the stream, e.g. for YouTube this
88+
* would be the itag
89+
* @param content the content or the URL of the stream, depending on whether isUrl is
90+
* true
91+
* @param isUrl whether content is the URL or the actual content of e.g. a DASH
92+
* manifest
93+
* @param format the {@link MediaFormat} used by the stream
94+
* @param deliveryMethod the {@link DeliveryMethod} of the stream
95+
* @param averageBitrate the average bitrate of the stream (which can be unknown, see
96+
* {@link #UNKNOWN_BITRATE})
97+
* @param itag the {@link ItagItem} corresponding to the stream, which cannot be null
98+
* @param baseUrl the base URL of the stream (see {@link Stream#getBaseUrl()} for more
99+
* information)
100+
*/
75101
public AudioStream(final String id,
76102
final String content,
77103
final boolean isUrl,
@@ -92,7 +118,20 @@ public AudioStream(final String id,
92118
this.averageBitrate = averageBitrate;
93119
}
94120

95-
public AudioStream(final String id, final String url, @Nonnull final ItagItem itag) {
121+
/**
122+
* Create a new audio stream.
123+
* <p>
124+
* The average bitrate will be set by using {@link ItagItem#avgBitrate}.
125+
* </p>
126+
*
127+
* @param id the ID which uniquely identifies the stream, e.g. for YouTube this
128+
* would be the itag
129+
* @param url the URL of the stream
130+
* @param itag the {@link ItagItem} corresponding to the stream, which cannot be null
131+
*/
132+
public AudioStream(final String id,
133+
final String url,
134+
@Nonnull final ItagItem itag) {
96135
this(id, url, itag.getMediaFormat(), itag.avgBitrate);
97136
this.itag = itag.id;
98137
this.quality = itag.getQuality();
@@ -104,48 +143,98 @@ public AudioStream(final String id, final String url, @Nonnull final ItagItem it
104143
this.codec = itag.getCodec();
105144
}
106145

146+
/**
147+
* {@inheritDoc}
148+
*/
107149
@Override
108150
public boolean equalStats(final Stream cmp) {
109151
return super.equalStats(cmp) && cmp instanceof AudioStream
110152
&& averageBitrate == ((AudioStream) cmp).averageBitrate;
111153
}
112154

113155
/**
114-
* Get the average bitrate.
156+
* Get the average bitrate of the stream.
157+
*
115158
* @return the average bitrate or {@link #UNKNOWN_BITRATE} if it is unknown
116159
*/
117160
public int getAverageBitrate() {
118161
return averageBitrate;
119162
}
120163

164+
/**
165+
* Get the itag of the stream.
166+
*
167+
* @return the number of the {@link ItagItem} passed in the constructor of the stream.
168+
*/
121169
public int getItag() {
122170
return itag;
123171
}
124172

173+
/**
174+
* Get the bitrate of the stream.
175+
*
176+
* @return the bitrate set from the {@link ItagItem} passed in the constructor of the stream.
177+
*/
125178
public int getBitrate() {
126179
return bitrate;
127180
}
128181

182+
/**
183+
* Get the initialization start of the stream.
184+
*
185+
* @return the initialization start value set from the {@link ItagItem} passed in the
186+
* constructor of the
187+
* stream.
188+
*/
129189
public int getInitStart() {
130190
return initStart;
131191
}
132192

193+
/**
194+
* Get the initialization end of the stream.
195+
*
196+
* @return the initialization end value set from the {@link ItagItem} passed in the constructor
197+
* of the stream.
198+
*/
133199
public int getInitEnd() {
134200
return initEnd;
135201
}
136202

203+
/**
204+
* Get the index start of the stream.
205+
*
206+
* @return the index start value set from the {@link ItagItem} passed in the constructor of the
207+
* stream.
208+
*/
137209
public int getIndexStart() {
138210
return indexStart;
139211
}
140212

213+
/**
214+
* Get the index end of the stream.
215+
*
216+
* @return the index end value set from the {@link ItagItem} passed in the constructor of the
217+
* stream.
218+
*/
141219
public int getIndexEnd() {
142220
return indexEnd;
143221
}
144222

223+
/**
224+
* Get the quality of the stream.
225+
*
226+
* @return the quality label set from the {@link ItagItem} passed in the constructor of the
227+
* stream.
228+
*/
145229
public String getQuality() {
146230
return quality;
147231
}
148232

233+
/**
234+
* Get the codec of the stream.
235+
*
236+
* @return the codec set from the {@link ItagItem} passed in the constructor of the stream.
237+
*/
149238
public String getCodec() {
150239
return codec;
151240
}

‎extractor/src/main/java/org/schabi/newpipe/extractor/stream/Stream.java‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -45,32 +45,37 @@ public Stream(final String id,
4545
this.baseUrl = baseUrl;
4646
}
4747

48+
/**
49+
* Check if the list already contains one stream with equals stats.
50+
*
51+
* @param stream the stream which will be compared to the streams in the stream list
52+
* @param streamList the list of {@link Stream Streams} which will be compared
53+
*/
54+
public static boolean containSimilarStream(final Stream stream,
55+
final List<? extends Stream> streamList) {
56+
if (isNullOrEmpty(streamList)) return false;
57+
for (final Stream cmpStream : streamList) {
58+
if (stream.equalStats(cmpStream)) return true;
59+
}
60+
return false;
61+
}
62+
4863
/**
4964
* Reveals whether two streams have the same stats (format and bitrate, for example).
65+
* @param cmp the stream object to be compared to this stream object
5066
*/
5167
public boolean equalStats(final Stream cmp) {
5268
return cmp != null && getFormat().id == cmp.getFormat().id;
5369
}
5470

5571
/**
5672
* Reveals whether two streams are equal.
73+
* @param cmp the stream object to be compared to this stream object
5774
*/
5875
public boolean equals(final Stream cmp) {
5976
return equalStats(cmp) && content.equals(cmp.content);
6077
}
6178

62-
/**
63-
* Check if the list already contains one stream with equals stats.
64-
*/
65-
public static boolean containSimilarStream(final Stream stream,
66-
final List<? extends Stream> streamList) {
67-
if (isNullOrEmpty(streamList)) return false;
68-
for (final Stream cmpStream : streamList) {
69-
if (stream.equalStats(cmpStream)) return true;
70-
}
71-
return false;
72-
}
73-
7479
/**
7580
* Gets the ID for this stream, e.g. itag for YouTube.
7681
* @return the id
@@ -98,6 +103,12 @@ public String getContent() {
98103
return content;
99104
}
100105

106+
/**
107+
* Return if the content is a URL or not.
108+
*
109+
* @return {@code true} if the content of this stream content is a URL, {@code false}
110+
* if it is the actual content
111+
*/
101112
public boolean isUrl() {
102113
return isUrl;
103114
}
@@ -131,10 +142,11 @@ public DeliveryMethod getDeliveryMethod() {
131142
/**
132143
* Gets the base URL of a stream.
133144
* <p>
134-
* If the stream is not a DASH stream or an HLS stream, this value will be null.
145+
* If the stream is not a DASH stream or an HLS stream, this value will always be null.
146+
* It may be also null for these streams too.
135147
* </p>
136148
*
137-
* @return the base URL of the stream or null
149+
* @return the base URL of the stream or {@code null}
138150
*/
139151
@Nullable
140152
public String getBaseUrl() {

‎extractor/src/main/java/org/schabi/newpipe/extractor/stream/SubtitlesStream.java‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,18 @@ public class SubtitlesStream extends Stream implements Serializable {
1212
private final boolean autoGenerated;
1313
private final String code;
1414

15+
/**
16+
* Create a new subtitles stream.
17+
* <p>
18+
* The id of the stream will be set by concatenating the {@code languageCode} param with
19+
* {@link MediaFormat#suffix the suffix of the {@code format} param} using a dot.
20+
* </p>
21+
*
22+
* @param url the URL of the stream
23+
* @param format the {@link MediaFormat} used by the stream
24+
* @param languageCode the language code of the stream
25+
* @param autoGenerated whether the subtitles are auto-generated by the streaming service
26+
*/
1527
public SubtitlesStream(final String url,
1628
final MediaFormat format,
1729
@Nonnull final String languageCode,
@@ -20,6 +32,16 @@ public SubtitlesStream(final String url,
2032

2133
}
2234

35+
/**
36+
* Create a new subtitles stream.
37+
*
38+
* @param id the ID which uniquely identifies the stream, e.g. for YouTube this
39+
* would be the itag
40+
* @param url the URL of the stream
41+
* @param format the {@link MediaFormat} used by the stream
42+
* @param languageCode the language code of the stream
43+
* @param autoGenerated whether the subtitles are auto-generated by the streaming service
44+
*/
2345
public SubtitlesStream(final String id,
2446
final String url,
2547
final MediaFormat format,
@@ -50,29 +72,60 @@ public SubtitlesStream(final String id,
5072
this.autoGenerated = autoGenerated;
5173
}
5274

75+
/**
76+
* Get the extension of the subtitles.
77+
*
78+
* @return the extension of the subtitles
79+
*/
5380
public String getExtension() {
5481
return format.suffix;
5582
}
5683

84+
/**
85+
* Return whether if the subtitles are auto-generated.
86+
* <p>
87+
* Some streaming services can generate subtitles for their contents, like YouTube.
88+
* </p>
89+
*
90+
* @return {@code true} if the subtitles are auto-generated, {@code false} otherwise
91+
*/
5792
public boolean isAutoGenerated() {
5893
return autoGenerated;
5994
}
6095

96+
/**
97+
* {@inheritDoc}
98+
*/
6199
@Override
62100
public boolean equalStats(final Stream cmp) {
63101
return super.equalStats(cmp) && cmp instanceof SubtitlesStream
64102
&& code.equals(((SubtitlesStream) cmp).code)
65103
&& autoGenerated == ((SubtitlesStream) cmp).autoGenerated;
66104
}
67105

106+
/**
107+
* Get the display language name of the subtitles.
108+
*
109+
* @return the display language name of the subtitles
110+
*/
68111
public String getDisplayLanguageName() {
69112
return locale.getDisplayName(locale);
70113
}
71114

115+
/**
116+
* Get the language tag of the subtitles.
117+
*
118+
* @return the language tag of the subtitles
119+
*/
72120
public String getLanguageTag() {
73121
return code;
74122
}
75123

124+
/**
125+
* Get the {@link Locale locale} of the subtitles.
126+
*
127+
* @return the {@link Locale locale} of the subtitles
128+
*/
76129
public Locale getLocale() {
77130
return locale;
78131
}

0 commit comments

Comments
 (0)