Skip to content

Getting Started

Jump to bottom
LucQuebec edited this page Jul 4, 2026 · 4 revisions

Getting Started

Requirements

  • Android 7.0+ (API level 24)
  • INTERNET permission in your manifest

Installation

Step 1 — Add JitPack

In your settings.gradle (or settings.gradle.kts):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

Step 2 — Add the dependency

// app/build.gradle
dependencies {
    implementation 'com.github.ffmpegkit-maintained:yt-dlp-android:1.0.1'
}

Step 3 — Add the INTERNET permission

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

Initialization

Initialize the library once, before any download. The best place is your Application class or the first Activity:

import dev.ffmpegkit_maintained.ytdlp.YtDlp;
import dev.ffmpegkit_maintained.ytdlp.YtDlpException;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
            YtDlp.init(this);
        } catch (YtDlpException e) {
            Log.e("YtDlp", "Initialization failed", e);
        }
    }
}

Your first download

import dev.ffmpegkit_maintained.ytdlp.YtDlp;
import dev.ffmpegkit_maintained.ytdlp.YtDlpRequest;
import dev.ffmpegkit_maintained.ytdlp.YtDlpResponse;
import dev.ffmpegkit_maintained.ytdlp.YtDlpException;

// Build the request
String outputPath = getExternalFilesDir(null).getAbsolutePath() + "/%(title)s.%(ext)s";

YtDlpRequest request = new YtDlpRequest("https://example.com/video")
        .setOutputTemplate(outputPath)
        .addOption("-f", "best[height<=720]");  // max 720p

// Execute asynchronously (runs on a background thread)
YtDlp.executeAsync(request, (progress, etaInSeconds, line) -> {
    // Called on the background thread — use runOnUiThread() to update UI
    runOnUiThread(() -> {
        progressBar.setProgress((int) progress);
        etaTextView.setText("ETA: " + etaInSeconds + "s");
    });
});

The %(title)s.%(ext)s template is a yt-dlp output template — it fills in the video title and file extension automatically. See yt-dlp output templates for all options.

Selecting video quality

// Best quality available
request.addOption("-f", "best");

// Best quality up to 1080p
request.addOption("-f", "best[height<=1080]");

// Audio only (mp3)
request.addOption("-f", "bestaudio")
       .addOption("--extract-audio")
       .addOption("--audio-format", "mp3");

// Specific format code (get format list first)
request.addOption("-f", "137+140");  // 1080p video + audio merged

Keeping yt-dlp up to date

Sites change their APIs regularly. Because yt-dlp is bundled as Python bytecode inside the AAR, in-app updates are not supported — YtDlp.updateYtDlp() always returns an error.

To update yt-dlp, bump the library version in your build.gradle:

implementation 'dev.ffmpegkit-maintained:yt-dlp-android:NEW_VERSION'

Then sync Gradle — the new AAR will contain the latest yt-dlp build.

Next steps

Clone this wiki locally