API Reference

API Reference

YtDlp

Main entry point for all download operations. All methods are static.

YtDlp.init(Context context)

Initializes the yt-dlp runtime. Must be called once before any other method.

YtDlp.init(context);  // throws YtDlpException on failure

YtDlp.execute(YtDlpRequest, DownloadProgressCallback)

Executes a download synchronously on the calling thread. Do not call from the main thread.

YtDlpResponse response = YtDlp.execute(request, callback);

Returns a YtDlpResponse. Throws YtDlpException on error.

YtDlp.executeAsync(YtDlpRequest, DownloadProgressCallback)

Executes a download on a background thread. Returns a Future<YtDlpResponse>.

Future<YtDlpResponse> future = YtDlp.executeAsync(request, callback);
// Optionally: YtDlpResponse response = future.get(); // blocks until done

YtDlp.updateYtDlp(Context, UpdateCallback)

Updates the bundled yt-dlp binary to the latest version. Runs on a background thread.

YtDlp.updateYtDlp(context, new YtDlp.UpdateCallback() {
    public void onComplete(String status) { }
    public void onError(String error)    { }
});

---

YtDlpRequest

Builder for a download request.

Constructor

YtDlpRequest request = new YtDlpRequest("https://example.com/video");

setOutputTemplate(String template)

Sets the output file path using a yt-dlp template.

request.setOutputTemplate("/sdcard/Movies/%(title)s.%(ext)s");

Common template variables:

Variable	Description
%(title)s	Video title
%(ext)s	File extension (mp4, webm…)
%(id)s	Video ID
%(uploader)s	Channel/uploader name
%(upload_date)s	Upload date (YYYYMMDD)

addOption(String key)

Adds a yt-dlp flag without a value.

request.addOption("--no-playlist");
request.addOption("--extract-audio");

addOption(String key, String value)

Adds a yt-dlp option with a value.

request.addOption("-f", "best[height<=720]");
request.addOption("--cookies", "/path/to/cookies.txt");
request.addOption("--proxy", "socks5://127.0.0.1:1080");

---

YtDlpResponse

Result of a completed download.

response.isSuccess()      // true if exit code == 0
response.getExitCode()    // raw yt-dlp exit code
response.getOutput()      // stdout
response.getErrorOutput() // stderr

---

DownloadProgressCallback

public interface DownloadProgressCallback {
    void onProgressUpdate(float progress, long etaInSeconds, String line);
}

Parameter	Description
progress	0.0 to 100.0
etaInSeconds	Estimated seconds remaining
line	Raw yt-dlp output line

Called from a background thread — marshal to the main thread if updating UI.

---

YtDlpException

Thrown when initialization fails or yt-dlp encounters an unrecoverable error.

try {
    YtDlp.execute(request, null);
} catch (YtDlpException e) {
    Log.e("YtDlp", e.getMessage(), e.getCause());
}

---

Common yt-dlp options

These yt-dlp options can be passed via addOption():

Option	Description
-f FORMAT	Select format/quality
--cookies PATH	Path to Netscape cookies file
--no-playlist	Download single video, not whole playlist
--extract-audio	Extract audio track
--audio-format FORMAT	Audio format: mp3, m4a, wav…
--write-subs	Download subtitles
--sub-lang LANG	Subtitle language (en, fr…)
--proxy URL	Use a proxy
--limit-rate RATE	Limit download speed (e.g. 500K)
--retries N	Number of retries on failure
--extractor-arg KEY:VALUE	Extractor-specific arguments

Full list: yt-dlp options documentation