ytdlp-react-native 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.3] - 2026-08-17
+
+### Fixed
+
+- Downloads no longer fail with `Download failed: null`. The Python `execute`
+  helper was fetched from the exec namespace with attribute access
+  (`PyObject.get`) even though it is a dict item; the downloader now uses
+  container access (`ns.asMap()`), which makes `YtDlp.download(...)` work.
+
+## [0.1.2] - 2026-08-17
+
+### Fixed
+
+- Chaquopy 17 does not convert Java maps/lists to Python dicts/lists
+  automatically. Download and extraction options are now converted explicitly
+  so yt-dlp receives real Python containers.
+
+## [0.1.1] - 2026-08-17
+
+### Fixed
+
+- Progress events now arrive through the native event emitter
+  (`module.addListener`), matching Expo SDK 52+ modules, instead of RN's
+  `NativeEventEmitter`.
+
+## [0.1.0] - 2026-08-16
+
+### Added
+
+- Standalone Expo module for Android with the native yt-dlp engine embedded
+  via `dev.ffmpegkit-maintained:yt-dlp-android:2.0.2` (pinned).
+- `YtDlp.getVersion()` — read the embedded yt-dlp version and the library version.
+- `YtDlp.extractInfo(url, options?)` — extract normalized media information
+  without downloading.
+- `YtDlp.getFormats(url, options?)` — list normalized download formats,
+  reusing the extraction result.
+- `YtDlp.download(options)` — start a concurrent download task backed by a
+  native task registry.
+- `YtDlp.cancel(taskId)` — cancel a task by id.
+- `DownloadTask` with `progress` / `state` / `completed` / `error` listeners,
+  `cancel()`, `getStatus()` and `getProgress()`.
+- Native cancellation via a custom Chaquopy progress hook that aborts yt-dlp.
+- Progress events throttled to ~200 ms with structured numeric fields.
+- Normalized `YtDlpError` codes and safe error translation across the bridge.
+- Safe app-scoped file storage with filename/directory sanitization and
+  path-traversal protection.
+- Supported options: `format`, `output`, `headers`, `userAgent`, `referer`,
+  `proxy`, `cookies.path`, `playlist`, `subtitles`, `network`.
+- Example application (`example/`) for manual integration testing.
+
+### Unsupported
+
+- iOS and web.
+- FFmpeg-dependent features (merging, audio extraction/re-encoding, metadata
+  and thumbnail embedding) are rejected up front with `PROCESSING_FAILED`.
+- Runtime updating of the embedded yt-dlp.
+- Background/foreground-service downloads.
+
+### Security
+
+- Added `SECURITY.md` with a vulnerability reporting policy.
+
+### Pinned dependency
+
+- `dev.ffmpegkit-maintained:yt-dlp-android:2.0.2`

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mehedi Hasan (devusimple)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# ytdlp-react-native
+
+A native **Android** Expo module providing a modern TypeScript API around
+[yt-dlp](https://github.com/yt-dlp/yt-dlp). It embeds the Python runtime,
+yt-dlp and all site extractors through the
+[yt-dlp-android](https://github.com/ffmpegkit-maintained/yt-dlp-android)
+library — no Python, yt-dlp, Chaquopy, FFmpeg or Termux setup is required in
+your app.
+
+```ts
+import YtDlp from 'ytdlp-react-native';
+
+const info = await YtDlp.extractInfo('https://www.youtube.com/watch?v=...');
+console.log(info.title);
+console.log(info.formats);
+
+const task = await YtDlp.download({
+  url: 'https://www.youtube.com/watch?v=...',
+  format: 'bestvideo+bestaudio',
+  output: { directory: 'Movies' },
+});
+
+task.addListener('progress', (progress) => {
+  console.log(progress.percent);
+});
+
+await task.cancel();
+```
+
+## Requirements
+
+- **Platform:** Android only. Importing on iOS/web throws
+  `YtDlpError` with code `UNSUPPORTED_PLATFORM`.
+- **Expo SDK:** 57 (tested against Expo 57 / React Native 0.86).
+- **Minimum Android:** API 24.
+- **Native build required.** This is a custom native module. It does **not**
+  work inside standard Expo Go — Expo Go cannot load arbitrary custom native
+  modules. Use a development build:
+
+  ```bash
+  npx expo prebuild
+  npx expo run:android
+  ```
+
+## Installation
+
+```bash
+npx expo install ytdlp-react-native
+```
+
+If `expo install` does not resolve the package (e.g. before it is indexed),
+fall back to:
+
+```bash
+npm install ytdlp-react-native
+```
+
+## Usage
+
+### Extract media information
+
+```ts
+import YtDlp from 'ytdlp-react-native';
+
+const info = await YtDlp.extractInfo(url);
+console.log(info.title);   // string | undefined
+console.log(info.duration);
+console.log(info.thumbnail);
+console.log(info.formats);
+```
+
+`extractInfo` never downloads media. Fields that a site does not provide are
+`undefined` — no field is guaranteed for every site.
+
+### List formats
+
+```ts
+const formats = await YtDlp.getFormats(url);
+```
+
+`getFormats` reuses the extraction result, so it does not extract twice.
+
+### Download
+
+```ts
+const task = await YtDlp.download({
+  url,
+  format: 'bestvideo+bestaudio', // raw yt-dlp format expression
+  output: {
+    directory: 'Movies',
+    filename: '%(title)s.%(ext)s',
+  },
+});
+
+task.addListener('progress', (progress) => {
+  console.log(progress.percent, progress.speedBytesPerSecond, progress.etaSeconds);
+});
+
+task.addListener('completed', (result) => {
+  console.log(result.path);
+});
+
+task.addListener('error', (error) => {
+  console.log(error.code, error.message);
+});
+```
+
+`download` resolves as soon as the task is registered; progress and the final
+result arrive through the task's listeners. Multiple downloads can run at the
+same time — every event carries a `taskId`.
+
+### Cancel
+
+```ts
+await task.cancel();
+```
+
+Cancellation calls the native cancellation path and aborts the underlying
+yt-dlp download. To cancel a task after your JS task object is gone:
+
+```ts
+await YtDlp.cancel(taskId);
+```
+
+### Version
+
+```ts
+const version = await YtDlp.getVersion();
+// { ytDlp: '2026.xx.xx', library: '0.1.0' }
+```
+
+The embedded yt-dlp version and the npm package version are independent.
+
+## Supported download options
+
+| Option | Description |
+| --- | --- |
+| `url` | Required. Any URL supported by yt-dlp. |
+| `format` | Raw yt-dlp format expression, e.g. `best`, `bestaudio`, `best[height<=720]`. |
+| `output.directory` | Subdirectory under the app's `yt-dlp` folder. Sanitized. |
+| `output.filename` | yt-dlp output template, e.g. `%(title)s.%(ext)s`. Sanitized. |
+| `headers` | Extra HTTP headers, e.g. `{ Referer: '...' }`. |
+| `userAgent` | Custom `User-Agent`. |
+| `referer` | Custom `Referer`. |
+| `proxy` | Proxy URL. |
+| `cookies.path` | Path to a Netscape-format cookies file. |
+| `playlist.enabled` | Default `false` — a playlist URL downloads only the first item unless enabled. |
+| `playlist.start` / `playlist.end` | Playlist item range (1-based). |
+| `subtitles.enabled` | Write subtitles. |
+| `subtitles.languages` | e.g. `['en', 'bn']`. |
+| `subtitles.autoGenerated` | Also write auto-generated subtitles. |
+| `network.timeout` | Socket timeout in seconds. |
+| `network.retries` | Number of retries. |
+
+### Not supported (yet)
+
+The bundled yt-dlp-android build ships no FFmpeg, so the following are
+rejected up front with `PROCESSING_FAILED` rather than silently ignored:
+
+- `merge: true` (e.g. `bestvideo+bestaudio` will fail because merging requires FFmpeg)
+- `audio.*` (audio extraction / re-encoding)
+- `metadata` (embedding)
+- `thumbnail` (embedding)
+
+Use `format: 'best'` or `format: 'bestaudio'` and download a single stream
+that requires no post-processing.
+
+## Download task
+
+A `DownloadTask` exposes:
+
+- `id: string`
+- `cancel(): Promise<void>`
+- `getStatus(): Promise<DownloadStatus>`
+- `getProgress(): Promise<DownloadProgress | null>`
+- `addListener(event, listener): Subscription`
+
+Statuses: `queued | extracting | downloading | processing | completed |
+cancelled | failed`.
+
+Events:
+
+- `progress` → `DownloadProgress` (`percent`, `downloadedBytes`, `totalBytes`,
+  `speedBytesPerSecond`, `etaSeconds`, `filename`, `phase`)
+- `state` → `{ taskId, status }`
+- `completed` → `DownloadResult` (`taskId`, `path`, `filename`, `size`)
+- `error` → `YtDlpError`
+
+Progress events are throttled to ~200 ms and numeric fields are `undefined`
+when the value is unknown (never `NaN`).
+
+## Errors
+
+All failures normalize to `YtDlpError` with a `code`:
+
+`INVALID_URL`, `EXTRACTION_FAILED`, `DOWNLOAD_FAILED`, `CANCELLED`,
+`FORMAT_UNAVAILABLE`, `NETWORK_ERROR`, `AUTHENTICATION_REQUIRED`,
+`GEO_RESTRICTED`, `PRIVATE_CONTENT`, `AGE_RESTRICTED`, `PROCESSING_FAILED`,
+`STORAGE_ERROR`, `INIT_FAILED`, `UNSUPPORTED_PLATFORM`, `UNKNOWN`.
+
+```ts
+import { YtDlpError } from 'ytdlp-react-native';
+
+try {
+  await YtDlp.extractInfo(url);
+} catch (error) {
+  if (error instanceof YtDlpError) {
+    console.log(error.code, error.message);
+  }
+}
+```
+
+Raw native stack traces are never surfaced to the user.
+
+## Storage
+
+Files are written to app-specific external storage:
+
+```
+Android/data/<your-package>/files/yt-dlp/<output.directory>/...
+```
+
+Filenames and directory segments are sanitized against illegal characters,
+path traversal, excessive length and empty names. This avoids dangerous
+permissions like `MANAGE_EXTERNAL_STORAGE`. The returned `DownloadResult.path`
+is an absolute path inside your app's own storage.
+
+## Limitations
+
+- Android only.
+- No FFmpeg-based post-processing (see "Not supported" above).
+- No background/foreground service: downloads pause if the JS/native runtime
+  is destroyed. Persisting task IDs lets you re-issue cancellation later.
+- yt-dlp site support changes frequently. Not every website works forever,
+  and not every site provides every field.
+- This package does **not** bundle or provide a way to update the embedded
+  yt-dlp at runtime.
+- Playlists are opt-in via `playlist.enabled` to avoid accidental bulk
+  downloads.
+
+## Legal & responsible use
+
+`ytdlp-react-native` is a technical wrapper around yt-dlp. It does not circumvent
+DRM (Widevine, FairPlay, PlayReady, ...), bypass authentication, or access
+private or unauthorized content — content that requires DRM or authentication
+will fail with an error.
+
+You are responsible for complying with:
+
+- website terms of service
+- copyright law and content licenses
+- authentication rules
+- platform policies
+
+Do not use this library to download content you do not have the right to
+download.
+
+## Third-party licenses
+
+| Component | License |
+| --- | --- |
+| `ytdlp-react-native` (this package) | MIT |
+| `yt-dlp-android` (Maven `dev.ffmpegkit-maintained:yt-dlp-android`) | MIT |
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | Unlicense |
+| [Chaquopy](https://chaquo.com/chaquopy/) | BSD-style (per the embedded distribution) |
+
+Re-verify third-party licenses at release time.

package/android/build.gradle

@@ -0,0 +1,25 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.ytdlp'
+version = '0.1.0'
+
+android {
+  namespace "expo.modules.ytdlp"
+  compileSdk 35
+  defaultConfig {
+    minSdk 24
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}
+
+dependencies {
+  // yt-dlp embedded via Chaquopy. Pinned exact version (see AGENTS.md §59).
+  implementation 'dev.ffmpegkit-maintained:yt-dlp-android:2.0.2'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/expo/modules/ytdlp/ExpoYtDlpModule.kt

@@ -0,0 +1,74 @@
+package expo.modules.ytdlp
+
+import android.content.Context
+import android.util.Log
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class ExpoYtDlpModule : Module() {
+
+  private var downloadManager: YtDlpDownloadManager? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("ExpoYtDlp")
+
+    Events("downloadEvent")
+
+    AsyncFunction("getVersion") {
+      runCatching {
+        YtDlpEngine.ensureInitialized(requireContext())
+        YtDlpEngine.getYtDlpVersion()
+      }.getOrElse { failure ->
+        Log.w(LOG_TAG, "getVersion failed", failure)
+        throw failure
+      }
+    }
+
+    AsyncFunction("extractInfo") { url: String, options: Map<String, Any?>? ->
+      runCatching {
+        YtDlpEngine.ensureInitialized(requireContext())
+        YtDlpEngine.extractInfoJson(url, options)
+      }.getOrElse { failure ->
+        Log.w(LOG_TAG, "extractInfo failed", failure)
+        throw failure
+      }
+    }
+
+    AsyncFunction("startDownload") { options: Map<String, Any?> ->
+      runCatching {
+        manager().start(options)
+      }.getOrElse { failure ->
+        Log.w(LOG_TAG, "startDownload failed", failure)
+        throw failure
+      }
+    }
+
+    Function("cancelDownload") { taskId: String ->
+      manager().cancel(taskId)
+    }
+
+    Function("getDownloadStatus") { taskId: String ->
+      manager().statusOf(taskId)
+    }
+
+    OnDestroy {
+      downloadManager?.shutdown()
+      downloadManager = null
+    }
+  }
+
+  private fun manager(): YtDlpDownloadManager {
+    downloadManager?.let { return it }
+    return YtDlpDownloadManager(requireContext()) { payload -> sendEvent("downloadEvent", payload) }
+      .also { downloadManager = it }
+  }
+
+  private fun requireContext(): Context {
+    return appContext.reactContext
+      ?: throw YtDlpNativeException("INIT_FAILED", "The React Native context is not available.")
+  }
+
+  private companion object {
+    const val LOG_TAG = "ExpoYtDlp"
+  }
+}

package/android/src/main/java/expo/modules/ytdlp/YtDlpDownloadManager.kt

@@ -0,0 +1,97 @@
+package expo.modules.ytdlp
+
+import android.content.Context
+import java.io.File
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+
+/**
+ * Owns the concurrent download task registry (AGENTS.md §21) and runs each
+ * task on its own background thread so the module call thread is never
+ * blocked for the duration of a download (AGENTS.md §39).
+ */
+internal class YtDlpDownloadManager(
+  private val context: Context,
+  private val onEvent: (Map<String, Any>) -> Unit,
+) {
+
+  private val tasks = ConcurrentHashMap<String, YtDlpTask>()
+  private val executor: ExecutorService = Executors.newCachedThreadPool()
+
+  /** Creates, registers and starts a download. Returns the public task info. */
+  fun start(options: Map<String, Any?>): Map<String, Any> {
+    YtDlpEngine.ensureInitialized(context)
+
+    val url = (options["url"] as? String)?.trim().takeIf { !it.isNullOrBlank() }
+      ?: throw YtDlpNativeException("INVALID_URL", "URL is required.")
+
+    val output = options["output"] as? Map<*, *>
+    val requestedDirectory = output?.get("directory") as? String
+    val baseDir = File(context.getExternalFilesDir(null) ?: context.filesDir, SUB_DIRECTORY)
+    val outputDirectory = YtDlpFileUtil.resolveOutputDirectory(baseDir, requestedDirectory)
+
+    val task = YtDlpTask(
+      id = UUID.randomUUID().toString(),
+      outputDirectory = outputDirectory,
+      onEvent = onEvent,
+    )
+
+    tasks[task.id] = task
+    task.setStatus(YtDlpStatus.EXTRACTING)
+    task.emitState()
+    executor.execute { runTask(task, options, outputDirectory) }
+    return mapOf("taskId" to task.id, "directory" to outputDirectory.absolutePath)
+  }
+
+  fun cancel(taskId: String): Boolean {
+    val task = tasks[taskId] ?: return false
+    return task.requestCancel()
+  }
+
+  fun statusOf(taskId: String): Map<String, Any?>? {
+    val task = tasks[taskId] ?: return null
+    return mapOf<String, Any?>(
+      "taskId" to task.id,
+      "status" to task.status.name.lowercase(),
+      "percent" to task.snapshot.percent,
+      "downloadedBytes" to task.snapshot.downloadedBytes,
+      "totalBytes" to task.snapshot.totalBytes,
+      "speedBytesPerSecond" to task.snapshot.speedBytesPerSecond,
+      "etaSeconds" to task.snapshot.etaSeconds,
+      "filename" to task.snapshot.filename,
+    )
+  }
+
+  fun shutdown() {
+    executor.shutdownNow()
+  }
+
+  private fun runTask(task: YtDlpTask, options: Map<String, Any?>, outputDirectory: File) {
+    try {
+      YtDlpEngine.executeDownload(task, options, outputDirectory)
+      val file = YtDlpFileUtil.findNewestFile(outputDirectory, task.startTime)
+      val secured = file?.let { YtDlpFileUtil.ensureContained(it, outputDirectory) }
+      task.emitCompleted(secured)
+    } catch (e: YtDlpNativeException) {
+      if (task.isCancelRequested() || e.errorCode == "CANCELLED") {
+        task.emitCancelled()
+      } else {
+        task.emitError(e.errorCode, e.message ?: "Download failed")
+      }
+    } catch (e: Throwable) {
+      if (task.isCancelRequested()) {
+        task.emitCancelled()
+      } else {
+        task.emitError("DOWNLOAD_FAILED", e.message ?: "Download failed")
+      }
+    } finally {
+      tasks.remove(task.id)
+    }
+  }
+
+  private companion object {
+    const val SUB_DIRECTORY = "yt-dlp"
+  }
+}