merged upstream/master

Author: yausername

README.md

@@ -1,6 +1,6 @@
 # NewPipe Extractor
 
-[![Build Status](https://travis-ci.org/TeamNewPipe/NewPipeExtractor.svg?branch=master)](https://travis-ci.org/TeamNewPipe/NewPipeExtractor) [![JIT Pack Badge](https://jitpack.io/v/TeamNewPipe/NewPipeExtractor.svg)](https://jitpack.io/#TeamNewPipe/NewPipeExtractor) [Documentation](https://teamnewpipe.github.io/NewPipeExtractor/javadoc/)
+[![Build Status](https://travis-ci.org/TeamNewPipe/NewPipeExtractor.svg?branch=master)](https://travis-ci.org/TeamNewPipe/NewPipeExtractor) [![JIT Pack Badge](https://jitpack.io/v/TeamNewPipe/NewPipeExtractor.svg)](https://jitpack.io/#TeamNewPipe/NewPipeExtractor) [Documentation](https://teamnewpipe.github.io/documentation/)
 
 NewPipe Extractor is a library for extracting things from streaming sites. It is a core component of [NewPipe](https://github.com/TeamNewPipe/NewPipe), but could be used independently.
 

extractor/src/main/java/org/schabi/newpipe/extractor/MediaFormat.java

@@ -36,7 +36,14 @@ public enum MediaFormat {
     M4A         (0x3,   "m4a",   "m4a",  "audio/mp4"),
     WEBMA       (0x4,   "WebM",  "webm", "audio/webm"),
     MP3         (0x5,   "MP3",   "mp3",  "audio/mpeg"),
-    OPUS        (0x6,   "opus",  "opus", "audio/opus");
+    OPUS        (0x6,   "opus",  "opus", "audio/opus"),
+    // subtitles formats
+    VTT         (0x7,   "WebVTT",                      "vtt",   "text/vtt"),
+    TTML        (0x8,   "Timed Text Markup Language",  "ttml",  "application/ttml+xml"),
+    TRANSCRIPT1 (0x9,   "TranScript v1",               "srv1",  "text/xml"),
+    TRANSCRIPT2 (0xA,   "TranScript v2",               "srv2",  "text/xml"),
+    TRANSCRIPT3 (0xB,   "TranScript v3",               "srv3",  "text/xml"),
+    SRT         (0xC,   "SubRip file format",          "srt",   "text/srt");
 
     public final int id;
     public final String name;

extractor/src/main/java/org/schabi/newpipe/extractor/ServiceList.java

@@ -8,6 +8,24 @@
 import static java.util.Arrays.asList;
 import static java.util.Collections.unmodifiableList;
 
+/*
+ * Copyright (C) Christian Schabesberger 2018 <chris.schabesberger@mailbox.org>
+ * ServiceList.java is part of NewPipe.
+ *
+ * NewPipe is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * NewPipe is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with NewPipe.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 /**
  * A list of supported services.
  */
@@ -19,6 +37,10 @@ private ServiceList() {
     public static final YoutubeService YouTube;
     public static final SoundcloudService SoundCloud;
 
+    /**
+     * When creating a new service, put this service in the end of this list,
+     * and give it the next free id.
+     */
     private static final List<StreamingService> SERVICES = unmodifiableList(
             asList(
                     YouTube = new YoutubeService(0),

extractor/src/main/java/org/schabi/newpipe/extractor/StreamingService.java

@@ -20,11 +20,38 @@
 import org.schabi.newpipe.extractor.subscription.SubscriptionExtractor;
 import org.schabi.newpipe.extractor.utils.Localization;
 
+/*
+ * Copyright (C) Christian Schabesberger 2018 <chris.schabesberger@mailbox.org>
+ * StreamingService.java is part of NewPipe.
+ *
+ * NewPipe is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * NewPipe is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with NewPipe.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 public abstract class StreamingService {
+
+    /**
+     * This class holds meta information about the service implementation.
+     */
     public static class ServiceInfo {
         private final String name;
         private final List<MediaCapability> mediaCapabilities;
 
+        /**
+         * Creates a new instance of a ServiceInfo
+         * @param name the name of the service
+         * @param mediaCapabilities the type of media this service can handle
+         */
         public ServiceInfo(String name, List<MediaCapability> mediaCapabilities) {
             this.name = name;
             this.mediaCapabilities = Collections.unmodifiableList(mediaCapabilities);
@@ -43,6 +70,10 @@ public enum MediaCapability {
         }
     }
 
+    /**
+     * LinkType will be used to determine which type of URL you are handling, and therefore which part
+     * of NewPipe should handle a certain URL.
+     */
     public enum LinkType {
         NONE,
         STREAM,
@@ -53,6 +84,16 @@ public enum LinkType {
     private final int serviceId;
     private final ServiceInfo serviceInfo;
 
+    /**
+     * Creates a new Streaming service.
+     * If you Implement one do not set id within your implementation of this extractor, instead
+     * set the id when you put the extractor into
+     * <a href="https://teamnewpipe.github.io/NewPipeExtractor/javadoc/org/schabi/newpipe/extractor/ServiceList.html">ServiceList</a>.
+     * All other parameters can be set directly from the overriding constructor.
+     * @param id the number of the service to identify him within the NewPipe frontend
+     * @param name the name of the service
+     * @param capabilities the type of media this service can handle
+     */
     public StreamingService(int id, String name, List<ServiceInfo.MediaCapability> capabilities) {
         this.serviceId = id;
         this.serviceInfo = new ServiceInfo(name, capabilities);
@@ -74,25 +115,94 @@ public String toString() {
     ////////////////////////////////////////////
     // Url Id handler
     ////////////////////////////////////////////
+
+    /**
+     * Must return a new instance of an implementation of LinkHandlerFactory for streams.
+     * @return an instance of a LinkHandlerFactory for streams
+     */
     public abstract LinkHandlerFactory getStreamLHFactory();
+
+    /**
+     * Must return a new instance of an implementation of ListLinkHandlerFactory for channels.
+     * If support for channels is not given null must be returned.
+     * @return an instance of a ListLinkHandlerFactory for channels or null
+     */
     public abstract ListLinkHandlerFactory getChannelLHFactory();
+
+    /**
+     * Must return a new instance of an implementation of ListLinkHandlerFactory for playlists.
+     * If support for playlists is not given null must be returned.
+     * @return an instance of a ListLinkHandlerFactory for playlists or null
+     */
     public abstract ListLinkHandlerFactory getPlaylistLHFactory();
+
+    /**
+     * Must return an instance of an implementation of SearchQueryHandlerFactory.
+     * @return an instance of a SearchQueryHandlerFactory
+     */
     public abstract SearchQueryHandlerFactory getSearchQHFactory();
     public abstract ListLinkHandlerFactory getCommentsLHFactory();
 
 
     ////////////////////////////////////////////
     // Extractor
     ////////////////////////////////////////////
+
+    /**
+     * Must create a new instance of a SearchExtractor implementation.
+     * @param queryHandler specifies the keyword lock for, and the filters which should be applied.
+     * @param localization specifies the language/country for the extractor.
+     * @return a new SearchExtractor instance
+     */
     public abstract SearchExtractor getSearchExtractor(SearchQueryHandler queryHandler, Localization localization);
+
+    /**
+     * Must create a new instance of a SuggestionExtractor implementation.
+     * @param localization specifies the language/country for the extractor.
+     * @return a new SuggestionExtractor instance
+     */
     public abstract SuggestionExtractor getSuggestionExtractor(Localization localization);
+
+    /**
+     * Outdated or obsolete. null can be returned.
+     * @return just null
+     */
     public abstract SubscriptionExtractor getSubscriptionExtractor();
+
+    /**
+     * Must create a new instance of a KioskList implementation.
+     * @return a new KioskList instance
+     * @throws ExtractionException
+     */
     public abstract KioskList getKioskList() throws ExtractionException;
 
+    /**
+     * Must create a new instance of a ChannelExtractor implementation.
+     * @param linkHandler is pointing to the channel which should be handled by this new instance.
+     * @param localization specifies the language used for the request.
+     * @return a new ChannelExtractor
+     * @throws ExtractionException
+     */
     public abstract ChannelExtractor getChannelExtractor(ListLinkHandler linkHandler,
                                                          Localization localization) throws ExtractionException;
+
+    /**
+     * Must crete a new instance of a PlaylistExtractor implementation.
+     * @param linkHandler is pointing to the playlist which should be handled by this new instance.
+     * @param localization specifies the language used for the request.
+     * @return a new PlaylistExtractor
+     * @throws ExtractionException
+     */
     public abstract PlaylistExtractor getPlaylistExtractor(ListLinkHandler linkHandler,
                                                            Localization localization) throws ExtractionException;
+
+    /**
+     * Must create a new instance of a StreamExtractor implementation.
+     * @param linkHandler is pointing to the stream which should be handled by this new instance.
+     * @param localization specifies the language used for the request.
+     * @return a new StreamExtractor
+     * @throws ExtractionException
+     */
     public abstract StreamExtractor getStreamExtractor(LinkHandler linkHandler,
                                                        Localization localization) throws ExtractionException;
     public abstract CommentsExtractor getCommentsExtractor(ListLinkHandler linkHandler,
@@ -192,6 +302,11 @@ public CommentsExtractor getCommentsExtractor(String url) throws ExtractionExcep
 
 	/**
      * figure out where the link is pointing to (a channel, video, playlist, etc.)
+    /**
+     * Figures out where the link is pointing to (a channel, a video, a playlist, etc.)
+     * @param url the url on which it should be decided of which link type it is
+     * @return the link type of url
+     * @throws ParsingException
      */
     public final LinkType getLinkTypeByUrl(String url) throws ParsingException {
         LinkHandlerFactory sH = getStreamLHFactory();

extractor/src/main/java/org/schabi/newpipe/extractor/Subtitles.java

@@ -172,13 +172,13 @@ public List<VideoStream> getVideoOnlyStreams() throws IOException, ExtractionExc
 
     @Override
     @Nonnull
-    public List<Subtitles> getSubtitlesDefault() throws IOException, ExtractionException {
+    public List<SubtitlesStream> getSubtitlesDefault() throws IOException, ExtractionException {
         return Collections.emptyList();
     }
 
     @Override
     @Nonnull
-    public List<Subtitles> getSubtitles(SubtitlesFormat format) throws IOException, ExtractionException {
+    public List<SubtitlesStream> getSubtitles(MediaFormat format) throws IOException, ExtractionException {
         return Collections.emptyList();
     }
 
@@ -188,12 +188,12 @@ public StreamType getStreamType() {
     }
 
     @Override
-    public StreamInfoItem getNextVideo() throws IOException, ExtractionException {
+    public StreamInfoItem getNextStream() throws IOException, ExtractionException {
         return null;
     }
 
     @Override
-    public StreamInfoItemsCollector getRelatedVideos() throws IOException, ExtractionException {
+    public StreamInfoItemsCollector getRelatedStreams() throws IOException, ExtractionException {
         StreamInfoItemsCollector collector = new StreamInfoItemsCollector(getServiceId());
 
         String apiUrl = "https://api-v2.soundcloud.com/tracks/" + urlEncode(getId()) + "/related"

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

@@ -53,14 +53,19 @@ public YoutubeSearchExtractor(StreamingService service,
     @Override
     public void onFetchPage(@Nonnull Downloader downloader) throws IOException, ExtractionException {
         final String site;
-        final String url = getUrl() + "?gl="+ getLocalization().getCountry();
+        final String url = getUrl();
         //String url = builder.build().toString();
         //if we've been passed a valid language code, append it to the URL
         site = downloader.download(url, getLocalization());
 
         doc = Jsoup.parse(site, url);
     }
 
+    @Override
+    public String getUrl() throws ParsingException {
+        return super.getUrl() + "&gl="+ getLocalization().getCountry();
+    }
+
     @Override
     public String getSearchSuggestion() {
         final Element el = doc.select("div[class*=\"spell-correction\"]").first();
@@ -79,7 +84,7 @@ public InfoItemsPage<InfoItem> getInitialPage() throws ExtractionException {
 
     @Override
     public String getNextPageUrl() throws ExtractionException {
-        return getUrl() + "&page=" + 2 + "&gl=" + getLocalization().getCountry();
+        return getUrl() + "&page=" + 2;
     }
 
     @Override