diff --git a/docs/08_getting_started.md b/docs/08_getting_started.md index 8e2187d..1cf4742 100644 --- a/docs/08_getting_started.md +++ b/docs/08_getting_started.md @@ -1,7 +1,110 @@ # Getting Started -This section provides you with the steps that are required to use the extractor. +This section provides you with the steps that are required to use the extractor in your android app. -### Implement a Downloader + +## Configure project. +### Add dependencies to gradle: + +1. **project** `settings.gradle`: + +```gradle +... +buildscript { + repositories { + ... + maven { url 'https://jitpack.io' } + } + ... +} +``` + + + +2. module/app build.gradle: + +```gradle +// NewPipe Libraries +implementation 'com.github.TeamNewPipe:NewPipeExtractor:0.21.12' +implementation 'com.github.TeamNewPipe:nanojson:1d9e1aea9049fc9f85e68b43ba39fe7be1c1f751' + + +// HTTP client +implementation "com.squareup.okhttp3:okhttp:3.12.13" +``` + +Note that you could use any http client other then okhttp, but it used here for more simplicity. + + +### Make sure you use Java 11 + +Change this in your module `build.gradle`: + +```gradle +android { + ... + compileOptions { + // enabling desugaring seems required. + coreLibraryDesugaringEnabled true + + // java version: + sourceCompatibility JavaVersion.VERSION_11 + targetCompatibility JavaVersion.VERSION_11 + } + + // if you are using kotlin: + kotlinOptions { + jvmTarget = JavaVersion.VERSION_11 + useIR = true + } +} + +dependencies { + ... + + // desugar + coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.5' +} +``` + + +### Proguard rules + +If you've `minifyEnabled` to `true` you should enable this rules: + +```pro +# .... +# For NewPipeExtractor +-dontobfuscate +-keep class org.schabi.newpipe.extractor.timeago.patterns.** { *; } +-keep class org.ocpsoft.prettytime.i18n.** { *; } + +-keep class org.mozilla.javascript.** { *; } + +-keep class org.mozilla.classfile.ClassFileWriter +-keep class com.google.android.exoplayer2.** { *; } + +-dontwarn org.mozilla.javascript.tools.** +-dontwarn android.arch.util.paging.CountedDataSource +-dontwarn android.arch.persistence.room.paging.LimitOffsetDataSource + + + +# Rules for OkHttp. Copy paste from https://github.com/square/okhttp +-dontwarn okhttp3.** +-dontwarn okio.** +-dontwarn javax.annotation.** +# A resource is loaded with a relative path so the package of this class must be preserved. +-keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase +-keepclassmembers class * implements java.io.Serializable { + static final long serialVersionUID; + !static !transient ; + private void writeObject(java.io.ObjectOutputStream); + private void readObject(java.io.ObjectInputStream); +} +``` + + +## Implement a Downloader The extractor needs to fetch websites and JSON files. Its entire network activity is going through the downloader you pass to it. @@ -36,6 +139,99 @@ public Response execute(@Nonnull Request request) throws IOException, ReCaptchaE } ``` +
+simple implementation + +Here is a simple implementation for the `Downloader`, assumes that you are using `okhttp`. + +```java +package gh.cloneconf.newpipe_android_example; + +import org.schabi.newpipe.extractor.downloader.Downloader; +import org.schabi.newpipe.extractor.downloader.Request; +import org.schabi.newpipe.extractor.downloader.Response; +import org.schabi.newpipe.extractor.exceptions.ReCaptchaException; + +import java.io.IOException; +import java.util.List; +import java.util.Map; +import java.util.concurrent.TimeUnit; + +import okhttp3.OkHttpClient; +import okhttp3.RequestBody; +import okhttp3.ResponseBody; + +public final class DownloaderImpl extends Downloader { + private static final String USER_AGENT + = "Mozilla/5.0 (Windows NT 10.0; rv:78.0) Gecko/20100101 Firefox/78.0"; + + private final OkHttpClient okhttp; + + public DownloaderImpl() { + okhttp = new OkHttpClient.Builder() + .readTimeout(30, TimeUnit.SECONDS) + .build(); + } + + @Override + public Response execute(final Request request) + throws IOException, ReCaptchaException { + final String httpMethod = request.httpMethod(); + final String url = request.url(); + final Map> headers = request.headers(); + final byte[] dataToSend = request.dataToSend(); + + RequestBody requestBody = null; + if (dataToSend != null) { + requestBody = RequestBody.create(null, dataToSend); + } + + final okhttp3.Request.Builder requestBuilder = new okhttp3.Request.Builder() + .method(httpMethod, requestBody).url(url) + .addHeader("User-Agent", USER_AGENT); + + for (Map.Entry> pair : headers.entrySet()) { + final String headerName = pair.getKey(); + final List headerValueList = pair.getValue(); + + if (headerValueList.size() > 1) { + requestBuilder.removeHeader(headerName); + for (String headerValue : headerValueList) { + requestBuilder.addHeader(headerName, headerValue); + } + } else if (headerValueList.size() == 1) { + requestBuilder.header(headerName, headerValueList.get(0)); + } + + } + + final okhttp3.Response response = okhttp.newCall(requestBuilder.build()).execute(); + + if (response.code() == 429) { + response.close(); + + throw new ReCaptchaException("reCaptcha Challenge requested", url); + } + + final ResponseBody body = response.body(); + String responseBodyToReturn = null; + + if (body != null) { + responseBodyToReturn = body.string(); + } + + final String latestUrl = response.request().url().toString(); + return new Response(response.code(), response.message(), response.headers().toMultimap(), + responseBodyToReturn, latestUrl); + } +} + + +``` + +
+ + You can find two example implementations of the Downloader below. Both use an old OkHttp version (version 3) to support Android 4. However, you do not need to use OkHttp. In case you want to use it and do not need to support old Android versions, @@ -87,3 +283,47 @@ NewPipe.init( ``` + +## Using Service + +We can any service that NewPipe supports from `ServiceList`. + +```java +YoutubeService youtube = ServiceList.YouTube; +// SoundcloudService soundCloud = ServiceList.SoundCloud; +// ... +``` + +### Some examples for **youtube** service: + + +- Suggestions + +```java +youtube.getSuggestionExtractor().suggestionList("Hello"); +``` + +- Search results + +```java +SearchExtractor page = youtube.getSearchExtractor("Hello"); +page.fetchPage(); + +// results list +page.getInitialPage().getItems(); +``` + + +- get video stream links: + +```java +StreamExtractor page = youtube.getStreamExtractor("https://www.youtube.com/watch?v=1YGCQRTSOSI"); +page.fetchPage(); + +// list of streams +page.getVideoStreams(); +``` + +## Examples: +- [Android example](https://github.com/cloneconf/newpipe-android-example) by @cloneconf. +- [Java example](https://github.com/cloneconf/newpipe-java-example) by @cloneconf. \ No newline at end of file