Skip to content

Commit 7129d6d

Browse files
theScrabitheScrabi
committed
add inline documentation for StreamExtractor
1 parent 4de99ae commit 7129d6d

8 files changed

Lines changed: 223 additions & 53 deletions

File tree

‎extractor/src/main/java/org/schabi/newpipe/extractor/services/soundcloud/SoundcloudStreamExtractor.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -188,12 +188,12 @@ public StreamType getStreamType() {
188188
}
189189

190190
@Override
191-
public StreamInfoItem getNextVideo() throws IOException, ExtractionException {
191+
public StreamInfoItem getNextStream() throws IOException, ExtractionException {
192192
return null;
193193
}
194194

195195
@Override
196-
public StreamInfoItemsCollector getRelatedVideos() throws IOException, ExtractionException {
196+
public StreamInfoItemsCollector getRelatedStreams() throws IOException, ExtractionException {
197197
StreamInfoItemsCollector collector = new StreamInfoItemsCollector(getServiceId());
198198

199199
String apiUrl = "https://api-v2.soundcloud.com/tracks/" + urlEncode(getId()) + "/related"

‎extractor/src/main/java/org/schabi/newpipe/extractor/services/youtube/extractors/YoutubeStreamExtractor.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -490,7 +490,7 @@ public StreamType getStreamType() throws ParsingException {
490490
}
491491

492492
@Override
493-
public StreamInfoItem getNextVideo() throws IOException, ExtractionException {
493+
public StreamInfoItem getNextStream() throws IOException, ExtractionException {
494494
assertPageFetched();
495495
try {
496496
StreamInfoItemsCollector collector = new StreamInfoItemsCollector(getServiceId());
@@ -504,7 +504,7 @@ public StreamInfoItem getNextVideo() throws IOException, ExtractionException {
504504
}
505505

506506
@Override
507-
public StreamInfoItemsCollector getRelatedVideos() throws IOException, ExtractionException {
507+
public StreamInfoItemsCollector getRelatedStreams() throws IOException, ExtractionException {
508508
assertPageFetched();
509509
try {
510510
StreamInfoItemsCollector collector = new StreamInfoItemsCollector(getServiceId());

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

Lines changed: 214 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@
2222

2323
import org.schabi.newpipe.extractor.Extractor;
2424
import org.schabi.newpipe.extractor.StreamingService;
25-
import org.schabi.newpipe.extractor.Subtitles;
2625
import org.schabi.newpipe.extractor.exceptions.ExtractionException;
2726
import org.schabi.newpipe.extractor.exceptions.ParsingException;
2827
import org.schabi.newpipe.extractor.linkhandler.LinkHandler;
@@ -34,7 +33,7 @@
3433
import java.util.List;
3534

3635
/**
37-
* Scrapes information from a video streaming service (eg, YouTube).
36+
* Scrapes information from a video/audio streaming service (eg, YouTube).
3837
*/
3938
public abstract class StreamExtractor extends Extractor {
4039

@@ -44,22 +43,234 @@ public StreamExtractor(StreamingService service, LinkHandler linkHandler, Locali
4443
super(service, linkHandler, localization);
4544
}
4645

46+
/**
47+
* The day on which the stream got uploaded/created. The return information should be in the format
48+
* dd.mm.yyyy, however it NewPipe will not crash if its not.
49+
* @return The day on which the stream got uploaded.
50+
* @throws ParsingException
51+
*/
4752
@Nonnull
4853
public abstract String getUploadDate() throws ParsingException;
54+
55+
/**
56+
* This will return the url to the thumbnail of the stream. Try to return the medium resolution here.
57+
* @return The url of the thumbnail.
58+
* @throws ParsingException
59+
*/
4960
@Nonnull
5061
public abstract String getThumbnailUrl() throws ParsingException;
62+
63+
/**
64+
* This is the stream description. On YouTube this is the video description. You can return simple HTML here.
65+
* @return The description of the stream/video.
66+
* @throws ParsingException
67+
*/
5168
@Nonnull
5269
public abstract String getDescription() throws ParsingException;
5370

5471
/**
55-
* Get the age limit
72+
* Get the age limit.
5673
* @return The age which limits the content or {@value NO_AGE_LIMIT} if there is no limit
5774
* @throws ParsingException if an error occurs while parsing
5875
*/
5976
public abstract int getAgeLimit() throws ParsingException;
6077

78+
/**
79+
* This should return the length of a video in seconds.
80+
* @return The length of the stream in seconds.
81+
* @throws ParsingException
82+
*/
6183
public abstract long getLength() throws ParsingException;
84+
85+
/**
86+
* If the url you are currently handling contains a time stamp/seek, you can return the
87+
* position it represents here.
88+
* If the url has no time stamp simply return zero.
89+
* @return the timestamp in seconds
90+
* @throws ParsingException
91+
*/
6292
public abstract long getTimeStamp() throws ParsingException;
93+
94+
/**
95+
* The count of how many people have watched the video/listened to the audio stream.
96+
* If the current stream has no view count or its not available simply return -1
97+
* @return amount of views.
98+
* @throws ParsingException
99+
*/
100+
public abstract long getViewCount() throws ParsingException;
101+
102+
/**
103+
* The Amount of likes a video/audio stream got.
104+
* If the current stream has no likes or its not available simply return -1
105+
* @return the amount of likes the stream got
106+
* @throws ParsingException
107+
*/
108+
public abstract long getLikeCount() throws ParsingException;
109+
110+
/**
111+
* The Amount of dislikes a video/audio stream got.
112+
* If the current stream has no dislikes or its not available simply return -1
113+
* @return the amount of likes the stream got
114+
* @throws ParsingException
115+
*/
116+
public abstract long getDislikeCount() throws ParsingException;
117+
118+
/**
119+
* The Url to the page of the creator/uploader of the stream. This must not be a homepage,
120+
* but the page offered by the service the extractor handles. This url will be handled by the
121+
* <a href="https://teamnewpipe.github.io/documentation/03_Implement_a_service/#channel">ChannelExtractor</a>,
122+
* so be sure to implement that one before you return a value here, otherwise NewPipe will crash if one selects
123+
* this url.
124+
* @return the url to the page of the creator/uploader of the stream or an empty String
125+
* @throws ParsingException
126+
*/
127+
@Nonnull
128+
public abstract String getUploaderUrl() throws ParsingException;
129+
130+
/**
131+
* The name of the creator/uploader of the stream.
132+
* If the name is not available you can simply return an empty string.
133+
* @return the name of the creator/uploader of the stream or an empty String
134+
* @throws ParsingException
135+
*/
136+
@Nonnull
137+
public abstract String getUploaderName() throws ParsingException;
138+
139+
/**
140+
* The url to the image file/profile picture/avatar of the creator/uploader of the stream.
141+
* If the url is not available you can return an empty String.
142+
* @return The url of the image file of the uploader or an empty String
143+
* @throws ParsingException
144+
*/
145+
@Nonnull
146+
public abstract String getUploaderAvatarUrl() throws ParsingException;
147+
148+
/**
149+
* Get the dash mpd url. If you don't know what a dash MPD is you can read about it
150+
* <a href="https://www.brendanlong.com/the-structure-of-an-mpeg-dash-mpd.html">here</a>.
151+
* @return the url as a string or an empty string
152+
* @throws ParsingException if an error occurs while reading
153+
*/
154+
@Nonnull public abstract String getDashMpdUrl() throws ParsingException;
155+
156+
/**
157+
* I am not sure if this is in use, and how this is used. However the frontend is missing support
158+
* for HLS streams. Prove me if I am wrong. Please open an
159+
* <a href="https://github.com/teamnewpipe/newpipe/issues">issue</a>,
160+
* or fix this description if you know whats up with this.
161+
* @return The Url to the hls stream.
162+
* @throws ParsingException
163+
*/
164+
@Nonnull public abstract String getHlsUrl() throws ParsingException;
165+
166+
/**
167+
* This should return a list of available
168+
* <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/org/schabi/newpipe/extractor/stream/AudioStream.html">AudioStream</a>s
169+
* You can also return null or an empty list, however be aware that if you don't return anything
170+
* in getVideoStreams(), getVideoOnlyStreams() and getDashMpdUrl() either the Collector will handle this as
171+
* a failed extraction procedure.
172+
* @return a list of audio only streams in the format of AudioStream
173+
* @throws IOException
174+
* @throws ExtractionException
175+
*/
176+
public abstract List<AudioStream> getAudioStreams() throws IOException, ExtractionException;
177+
178+
/**
179+
* This should return a list of available
180+
* <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/org/schabi/newpipe/extractor/stream/VideoStream.html">VideoStream</a>s
181+
* Be aware this is the list of video streams which do contain an audio stream.
182+
* You can also return null or an empty list, however be aware that if you don't return anything
183+
* in getAudioStreams(), getVideoOnlyStreams() and getDashMpdUrl() either the Collector will handle this as
184+
* a failed extraction procedure.
185+
* @return a list of combined video and streams in the format of AudioStream
186+
* @throws IOException
187+
* @throws ExtractionException
188+
*/
189+
public abstract List<VideoStream> getVideoStreams() throws IOException, ExtractionException;
190+
191+
/**
192+
* This should return a list of available
193+
* <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/org/schabi/newpipe/extractor/stream/VideoStream.html">VideoStream</a>s.
194+
* Be aware this is the list of video streams which do NOT contain an audio stream.
195+
* You can also return null or an empty list, however be aware that if you don't return anything
196+
* in getAudioStreams(), getVideoStreams() and getDashMpdUrl() either the Collector will handle this as
197+
* a failed extraction procedure.
198+
* @return a list of video and streams in the format of AudioStream
199+
* @throws IOException
200+
* @throws ExtractionException
201+
*/
202+
public abstract List<VideoStream> getVideoOnlyStreams() throws IOException, ExtractionException;
203+
204+
/**
205+
* This will return a list of available
206+
* <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/org/schabi/newpipe/extractor/stream/Subtitles.html">Subtitles</a>s.
207+
* If no subtitles are available an empty list can returned.
208+
* @return a list of available subtitles or an empty list
209+
* @throws IOException
210+
* @throws ExtractionException
211+
*/
212+
@Nonnull
213+
public abstract List<Subtitles> getSubtitlesDefault() throws IOException, ExtractionException;
214+
215+
/**
216+
* This will return a list of available
217+
* <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/org/schabi/newpipe/extractor/stream/Subtitles.html">Subtitles</a>s.
218+
* given by a specific type.
219+
* If no subtitles in that specific format are available an empty list can returned.
220+
* @return a list of available subtitles or an empty list
221+
* @throws IOException
222+
* @throws ExtractionException
223+
*/
224+
@Nonnull
225+
public abstract List<Subtitles> getSubtitles(SubtitlesFormat format) throws IOException, ExtractionException;
226+
227+
/**
228+
* Get the <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/">StreamType</a>.
229+
* @return the type of the stream
230+
* @throws ParsingException
231+
*/
232+
public abstract StreamType getStreamType() throws ParsingException;
233+
234+
/**
235+
* should return the url of the next stream. NewPipe will automatically play
236+
* the next stream if the user wants that.
237+
* If the next stream is is not available simply return null
238+
* @return the InfoItem of the next stream
239+
* @throws IOException
240+
* @throws ExtractionException
241+
*/
242+
public abstract StreamInfoItem getNextStream() throws IOException, ExtractionException;
243+
244+
/**
245+
* Should return a list of streams related to the current handled. Many services show suggested
246+
* streams. If you don't like suggested streams you should implement them anyway since they can
247+
* be disabled by the user later in the frontend.
248+
* This list MUST NOT contain the next available video as this should be return through getNextStream()
249+
* If is is not available simply return null
250+
* @return a list of InfoItems showing the related videos/streams
251+
* @throws IOException
252+
* @throws ExtractionException
253+
*/
254+
public abstract StreamInfoItemsCollector getRelatedStreams() throws IOException, ExtractionException;
255+
256+
/**
257+
* Should analyse the webpage's document and extracts any error message there might be. (e.g. GEMA block)
258+
*
259+
* @return Error message; null if there is no error message.
260+
*/
261+
public abstract String getErrorMessage();
262+
263+
//////////////////////////////////////////////////////////////////
264+
/// Helper
265+
//////////////////////////////////////////////////////////////////
266+
267+
/**
268+
* Override this function if the format of time stamp in the url is not the same format as that form youtube.
269+
* Honestly I don't even know the time stamp fromat of youtube.
270+
* @param regexPattern
271+
* @return the sime stamp/seek for the video in seconds
272+
* @throws ParsingException
273+
*/
63274
protected long getTimestampSeconds(String regexPattern) throws ParsingException {
64275
String timeStamp;
65276
try {
@@ -104,42 +315,4 @@ protected long getTimestampSeconds(String regexPattern) throws ParsingException
104315
} else {
105316
return 0;
106317
}};
107-
108-
public abstract long getViewCount() throws ParsingException;
109-
public abstract long getLikeCount() throws ParsingException;
110-
public abstract long getDislikeCount() throws ParsingException;
111-
112-
@Nonnull
113-
public abstract String getUploaderUrl() throws ParsingException;
114-
@Nonnull
115-
public abstract String getUploaderName() throws ParsingException;
116-
@Nonnull
117-
public abstract String getUploaderAvatarUrl() throws ParsingException;
118-
119-
/**
120-
* Get the dash mpd url
121-
* @return the url as a string or an empty string
122-
* @throws ParsingException if an error occurs while reading
123-
*/
124-
@Nonnull public abstract String getDashMpdUrl() throws ParsingException;
125-
@Nonnull public abstract String getHlsUrl() throws ParsingException;
126-
public abstract List<AudioStream> getAudioStreams() throws IOException, ExtractionException;
127-
public abstract List<VideoStream> getVideoStreams() throws IOException, ExtractionException;
128-
public abstract List<VideoStream> getVideoOnlyStreams() throws IOException, ExtractionException;
129-
130-
@Nonnull
131-
public abstract List<Subtitles> getSubtitlesDefault() throws IOException, ExtractionException;
132-
@Nonnull
133-
public abstract List<Subtitles> getSubtitles(SubtitlesFormat format) throws IOException, ExtractionException;
134-
135-
public abstract StreamType getStreamType() throws ParsingException;
136-
public abstract StreamInfoItem getNextVideo() throws IOException, ExtractionException;
137-
public abstract StreamInfoItemsCollector getRelatedVideos() throws IOException, ExtractionException;
138-
139-
/**
140-
* Analyses the webpage's document and extracts any error message there might be.
141-
*
142-
* @return Error message; null if there is no error message.
143-
*/
144-
public abstract String getErrorMessage();
145318
}

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
import org.schabi.newpipe.extractor.exceptions.ExtractionException;
66
import org.schabi.newpipe.extractor.utils.DashMpdParser;
77
import org.schabi.newpipe.extractor.utils.ExtractorHelper;
8-
import org.schabi.newpipe.extractor.utils.Localization;
98

109
import java.io.IOException;
1110
import java.util.ArrayList;
@@ -240,7 +239,7 @@ private static StreamInfo extractOptionalData(StreamInfo streamInfo, StreamExtra
240239
streamInfo.addError(e);
241240
}
242241
try {
243-
streamInfo.setNextVideo(extractor.getNextVideo());
242+
streamInfo.setNextVideo(extractor.getNextStream());
244243
} catch (Exception e) {
245244
streamInfo.addError(e);
246245
}

extractor/src/main/java/org/schabi/newpipe/extractor/Subtitles.java renamed to extractor/src/main/java/org/schabi/newpipe/extractor/stream/Subtitles.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package org.schabi.newpipe.extractor;
1+
package org.schabi.newpipe.extractor.stream;
22

33
import org.schabi.newpipe.extractor.stream.SubtitlesFormat;
44

‎extractor/src/main/java/org/schabi/newpipe/extractor/utils/ExtractorHelper.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ public static <T extends InfoItem> InfoItemsPage<T> getItemsPageOrLogError(Info
2929

3030
public static List<InfoItem> getRelatedVideosOrLogError(StreamInfo info, StreamExtractor extractor) {
3131
try {
32-
InfoItemsCollector<? extends InfoItem, ?> collector = extractor.getRelatedVideos();
32+
InfoItemsCollector<? extends InfoItem, ?> collector = extractor.getRelatedStreams();
3333
info.addAllErrors(collector.getErrors());
3434

3535
//noinspection unchecked

‎extractor/src/test/java/org/schabi/newpipe/extractor/services/soundcloud/SoundcloudStreamExtractorDefaultTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ public void testStreamType() throws ParsingException {
101101

102102
@Test
103103
public void testGetRelatedVideos() throws ExtractionException, IOException {
104-
StreamInfoItemsCollector relatedVideos = extractor.getRelatedVideos();
104+
StreamInfoItemsCollector relatedVideos = extractor.getRelatedStreams();
105105
assertFalse(relatedVideos.getItems().isEmpty());
106106
assertTrue(relatedVideos.getErrors().isEmpty());
107107
}

‎extractor/src/test/java/org/schabi/newpipe/extractor/services/youtube/YoutubeStreamExtractorDefaultTest.java‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@
88
import org.schabi.newpipe.extractor.exceptions.ParsingException;
99
import org.schabi.newpipe.extractor.services.youtube.extractors.YoutubeStreamExtractor;
1010
import org.schabi.newpipe.extractor.stream.*;
11-
import org.schabi.newpipe.extractor.utils.DashMpdParser;
1211
import org.schabi.newpipe.extractor.utils.Localization;
1312
import org.schabi.newpipe.extractor.utils.Utils;
1413

@@ -17,7 +16,6 @@
1716
import static org.junit.Assert.*;
1817
import static org.schabi.newpipe.extractor.ExtractorAsserts.assertIsSecureUrl;
1918
import static org.schabi.newpipe.extractor.ServiceList.YouTube;
20-
import static org.schabi.newpipe.extractor.services.youtube.YoutubeTrendingExtractorTest.extractor;
2119

2220
/*
2321
* Created by Christian Schabesberger on 30.12.15.
@@ -151,7 +149,7 @@ public void testGetDashMpd() throws ParsingException {
151149

152150
@Test
153151
public void testGetRelatedVideos() throws ExtractionException, IOException {
154-
StreamInfoItemsCollector relatedVideos = extractor.getRelatedVideos();
152+
StreamInfoItemsCollector relatedVideos = extractor.getRelatedStreams();
155153
Utils.printErrors(relatedVideos.getErrors());
156154
assertFalse(relatedVideos.getItems().isEmpty());
157155
assertTrue(relatedVideos.getErrors().isEmpty());

0 commit comments

Comments
 (0)