ytdlp-react-native 1.0.0 → 1.1.0-beta.0

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,21 @@
-<manifest>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <!-- Foreground-service promotion for active downloads (issue #3).
+       Normal permissions: granted automatically at install time. -->
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+  <!-- Required on API 34+ for the dataSync foreground-service type. -->
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+  <!-- Partial wake lock keeps screen-off downloads moving. -->
+  <uses-permission android:name="android.permission.WAKE_LOCK" />
+
+  <!-- Note: POST_NOTIFICATIONS is intentionally *not* declared here. It is a
+       dangerous permission that the host app must request at runtime on
+       API 33+ if it wants the progress notification to be visible. The
+       service still runs without it; the notification is then suppressed. -->
+
+  <application>
+    <service
+      android:name="expo.modules.ytdlp.YtDlpForegroundService"
+      android:exported="false"
+      android:foregroundServiceType="dataSync" />
+  </application>
 </manifest>

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

@@ -47,6 +47,14 @@ class ExpoYtDlpModule : Module() {
       manager().cancel(taskId)
     }
 
+    Function("pauseDownload") { taskId: String ->
+      manager().pause(taskId)
+    }
+
+    Function("resumeDownload") { taskId: String ->
+      manager().resume(taskId)
+    }
+
     Function("getDownloadStatus") { taskId: String ->
       manager().statusOf(taskId)
     }

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

@@ -11,16 +11,39 @@ 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).
+ *
+ * Pause/resume (issue #4): `pause()` asks yt-dlp to abort via the progress
+ * hook; the `.part` file stays on disk and the task stays registered with
+ * status `PAUSED`. `resume()` re-runs the exact same download and yt-dlp
+ * continues from the partial file by default (`--continue`), so no extra
+ * options are needed. a [runGeneration] counter per task ensures a stale
+ * runner thread (the one that just paused) can never overwrite the fresh run.
+ *
+ * Background execution (issue #3, AGENTS.md §38): while at least one run is
+ * active the manager promotes the process with [YtDlpForegroundService]
+ * (type `dataSync`) and feeds it progress for the ongoing notification. When
+ * the last run ends the service is stopped again.
  */
 internal class YtDlpDownloadManager(
   private val context: Context,
   private val onEvent: (Map<String, Any>) -> Unit,
 ) {
 
+  private val appContext: Context = context.applicationContext
   private val tasks = ConcurrentHashMap<String, YtDlpTask>()
+  private val resumeOptions = ConcurrentHashMap<String, Map<String, Any?>>()
   private val executor: ExecutorService = Executors.newCachedThreadPool()
 
+  /** Runs currently executing on a background thread. Guarded by `this`. */
+  @Volatile
+  private var activeRuns = 0
+
+  init {
+    YtDlpForegroundService.setManager(this)
+  }
+
   /** Creates, registers and starts a download. Returns the public task info. */
+  @Synchronized
   fun start(options: Map<String, Any?>): Map<String, Any> {
     YtDlpEngine.ensureInitialized(context)
 
@@ -35,21 +58,75 @@ internal class YtDlpDownloadManager(
     val task = YtDlpTask(
       id = UUID.randomUUID().toString(),
       outputDirectory = outputDirectory,
-      onEvent = onEvent,
+      onEvent = ::emit,
     )
 
+    val generation = task.beginRun()
     tasks[task.id] = task
+    resumeOptions[task.id] = options
     task.setStatus(YtDlpStatus.EXTRACTING)
     task.emitState()
-    executor.execute { runTask(task, options, outputDirectory) }
+    executor.execute { runTask(task, outputDirectory, generation) }
+    runStarted()
     return mapOf("taskId" to task.id, "directory" to outputDirectory.absolutePath)
   }
 
+  /**
+   * Pause an in-flight download. Returns `false` when the task is unknown,
+   * already paused, or already in a terminal state.
+   */
+  @Synchronized
+  fun pause(taskId: String): Boolean {
+    val task = tasks[taskId] ?: return false
+    return task.requestPause()
+  }
+
+  /**
+   * Resume a paused download. Returns `false` when the task is unknown or not
+   * in the `PAUSED` state.
+   */
+  @Synchronized
+  fun resume(taskId: String): Boolean {
+    val task = tasks[taskId] ?: return false
+    if (task.status != YtDlpStatus.PAUSED) return false
+    val options = resumeOptions[taskId] ?: return false
+    val generation = task.beginRun()
+    task.setStatus(YtDlpStatus.EXTRACTING)
+    task.emitState()
+    executor.execute { runTask(task, task.outputDirectory, generation) }
+    runStarted()
+    return true
+  }
+
+  /**
+   * Cancel a download. A paused task is finalized immediately (there is no
+   * runner alive to observe the cancel request).
+   */
+  @Synchronized
   fun cancel(taskId: String): Boolean {
     val task = tasks[taskId] ?: return false
+    if (task.status == YtDlpStatus.PAUSED) {
+      task.emitCancelled()
+      releaseTask(task.id)
+      runFinished()
+      return true
+    }
     return task.requestCancel()
   }
 
+  /**
+   * Cancel every registered download (notification Cancel action). Returns
+   * how many tasks were asked to stop.
+   */
+  @Synchronized
+  fun cancelAll(): Int {
+    var cancelled = 0
+    for (taskId in tasks.keys.toList()) {
+      if (cancel(taskId)) cancelled++
+    }
+    return cancelled
+  }
+
   fun statusOf(taskId: String): Map<String, Any?>? {
     val task = tasks[taskId] ?: return null
     return mapOf<String, Any?>(
@@ -66,32 +143,116 @@ internal class YtDlpDownloadManager(
 
   fun shutdown() {
     executor.shutdownNow()
+    synchronized(this) {
+      activeRuns = 0
+      tasks.clear()
+      resumeOptions.clear()
+    }
+    YtDlpForegroundService.setManager(null)
+    YtDlpForegroundService.stop(appContext)
   }
 
-  private fun runTask(task: YtDlpTask, options: Map<String, Any?>, outputDirectory: File) {
+  /** Forwards native events to JS and mirrors progress into the notification. */
+  private fun emit(payload: Map<String, Any>) {
+    updateServiceNotification(payload)
+    onEvent(payload)
+  }
+
+  private fun updateServiceNotification(payload: Map<String, Any>) {
+    when (payload["type"]) {
+      "progress" -> {
+        val progress = payload["progress"] as? Map<*, *> ?: return
+        val percent = (progress["percent"] as? Number)?.toDouble()
+        val filename = (progress["filename"] as? String)?.substringAfterLast('/')
+        YtDlpForegroundService.update(activeRuns, percent, filename)
+      }
+      "state" -> {
+        if ((payload["status"] as? String) == "extracting") {
+          YtDlpForegroundService.update(activeRuns, null, "Extracting info")
+        }
+      }
+    }
+  }
+
+  private fun runStarted() {
+    activeRuns += 1
+    YtDlpForegroundService.start(appContext, activeRuns)
+  }
+
+  private fun runFinished() {
+    if (activeRuns > 0) activeRuns -= 1
+    if (activeRuns == 0) {
+      YtDlpForegroundService.stop(appContext)
+    } else {
+      YtDlpForegroundService.update(activeRuns, null, null)
+    }
+  }
+
+  private fun runTask(task: YtDlpTask, outputDirectory: File, generation: Int) {
+    val options = resumeOptions[task.id]
+    if (options == null) {
+      synchronized(this) {
+        if (task.runGeneration == generation) releaseTask(task.id)
+        runFinished()
+      }
+      return
+    }
     try {
       YtDlpEngine.executeDownload(task, options, outputDirectory)
+      completeRun(task, generation, outputDirectory)
+    } catch (e: YtDlpNativeException) {
+      failRun(task, generation, e.errorCode, e.message ?: "Download failed")
+    } catch (e: Throwable) {
+      failRun(task, generation, "DOWNLOAD_FAILED", e.message ?: "Download failed")
+    }
+  }
+
+  private fun completeRun(task: YtDlpTask, generation: Int, outputDirectory: File) {
+    synchronized(this) {
+      if (task.runGeneration != generation) {
+        runFinished()
+        return
+      }
       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")
+      releaseTask(task.id)
+      runFinished()
+    }
+  }
+
+  private fun failRun(task: YtDlpTask, generation: Int, code: String, message: String) {
+    synchronized(this) {
+      if (task.runGeneration != generation) {
+        runFinished()
+        return
       }
-    } catch (e: Throwable) {
-      if (task.isCancelRequested()) {
-        task.emitCancelled()
-      } else {
-        task.emitError("DOWNLOAD_FAILED", e.message ?: "Download failed")
+      when {
+        // Cancel has priority over pause when both were requested.
+        task.isCancelRequested() || code == "CANCELLED" -> {
+          task.emitCancelled()
+          releaseTask(task.id)
+        }
+        task.isPauseRequested() || code == "PAUSED" -> {
+          // Keep the task registered so it can be resumed; the `.part` file
+          // stays on disk and yt-dlp continues from it on the next run.
+          task.emitPaused()
+        }
+        else -> {
+          task.emitError(code, message)
+          releaseTask(task.id)
+        }
       }
-    } finally {
-      tasks.remove(task.id)
+      runFinished()
     }
   }
 
+  private fun releaseTask(taskId: String) {
+    tasks.remove(taskId)
+    resumeOptions.remove(taskId)
+  }
+
   private companion object {
     const val SUB_DIRECTORY = "yt-dlp"
   }
-}
+}

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

@@ -115,6 +115,9 @@ internal object YtDlpEngine {
       if (task.isCancelRequested() || message.contains(CANCEL_SENTINEL)) {
         throw YtDlpNativeException("CANCELLED", "Download cancelled.")
       }
+      if (task.isPauseRequested() || message.contains(PAUSE_SENTINEL)) {
+        throw YtDlpNativeException("PAUSED", "Download paused.")
+      }
       throw YtDlpNativeException(classifyDownloadFailure(message), message, e)
     } catch (e: Exception) {
       throw YtDlpNativeException("DOWNLOAD_FAILED", "Download failed: ${e.message}", e)
@@ -133,6 +136,18 @@ internal object YtDlpEngine {
 
     (options["referer"] as? String)?.takeIf { it.isNotBlank() }?.let { opts["http_referer"] = it }
 
+    ffmpegLocationOf(options)?.let { location ->
+      if (!File(location).exists()) {
+        throw YtDlpNativeException(
+          "PROCESSING_FAILED",
+          "The FFmpeg binary at \"$location\" does not exist. Provide the path to an ffmpeg executable or a directory containing it.",
+        )
+      }
+      // yt-dlp accepts either the binary path or its containing directory, so
+      // the caller's value is passed through unchanged.
+      opts["ffmpeg_location"] = location
+    }
+
     val playlist = options["playlist"] as? Map<*, *>
     if (playlist?.get("enabled") != true) opts["noplaylist"] = true
     (playlist?.get("start") as? Number)?.takeIf { it.toInt() > 0 }?.let { opts["playliststart"] = it.toInt() }
@@ -153,29 +168,42 @@ internal object YtDlpEngine {
     return opts
   }
 
-  /** Anything we cannot honestly support is rejected up front (AGENTS.md §19). */
+  /**
+   * Rejects FFmpeg-dependent features up front when no FFmpeg binary is
+   * available (AGENTS.md §19). When the caller supplies `ffmpeg.location`,
+   * these features are handed to yt-dlp instead of being refused.
+   */
   private fun rejectUnsupportedFeatures(options: Map<String, Any?>) {
+    if (ffmpegLocationOf(options) != null) return
     if (options["merge"] == true) {
       throw YtDlpNativeException(
         "PROCESSING_FAILED",
-        "Merging video and audio requires FFmpeg, which is not bundled with yt-dlp-android.",
+        "Merging video and audio requires FFmpeg, which is not bundled. " +
+          "Provide an ffmpeg executable via the `ffmpeg.location` download option.",
       )
     }
     val audio = options["audio"] as? Map<*, *>
     if (audio?.get("only") == true || audio?.get("format") != null || audio?.get("quality") != null) {
       throw YtDlpNativeException(
         "PROCESSING_FAILED",
-        "Audio extraction and re-encoding require FFmpeg, which is not bundled with yt-dlp-android.",
+        "Audio extraction and re-encoding require FFmpeg. " +
+          "Provide an ffmpeg executable via the `ffmpeg.location` download option.",
       )
     }
     if (options["metadata"] != null || options["thumbnail"] != null) {
       throw YtDlpNativeException(
         "PROCESSING_FAILED",
-        "Metadata and thumbnail embedding are not supported in this version.",
+        "Metadata and thumbnail embedding require FFmpeg. " +
+          "Provide an ffmpeg executable via the `ffmpeg.location` download option.",
       )
     }
   }
 
+  private fun ffmpegLocationOf(options: Map<String, Any?>): String? {
+    val ffmpeg = options["ffmpeg"] as? Map<*, *>
+    return (ffmpeg?.get("location") as? String)?.trim()?.takeIf { it.isNotEmpty() }
+  }
+
   private fun classifyDownloadFailure(message: String): String {
     val haystack = message.lowercase()
     return when {
@@ -248,6 +276,7 @@ internal object YtDlpEngine {
   }
 
 private const val CANCEL_SENTINEL = "YTDLP_CANCELLED"
+private const val PAUSE_SENTINEL = "YTDLP_PAUSED"
 
   /**
    * Drive the bundled yt-dlp directly. Importing is deferred so our first
@@ -258,6 +287,8 @@ private const val CANCEL_SENTINEL = "YTDLP_CANCELLED"
     def _expo_ytdlp_hook(task, d):
         if task.isCancelRequested():
             raise RuntimeError("YTDLP_CANCELLED")
+        if task.isPauseRequested():
+            raise RuntimeError("YTDLP_PAUSED")
         downloaded = int(d.get('downloaded_bytes') or 0)
         total = int(d.get('total_bytes') or d.get('total_bytes_estimate') or 0)
         speed = int(d.get('speed') or 0)

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

@@ -0,0 +1,241 @@
+package expo.modules.ytdlp
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.os.Build
+import android.os.IBinder
+import android.os.PowerManager
+import java.lang.ref.WeakReference
+
+/**
+ * Foreground service that keeps the process alive while downloads are active
+ * (issue #3, AGENTS.md §38).
+ *
+ * Architecture: `ExpoYtDlpModule` → [YtDlpDownloadManager] → this service →
+ * yt-dlp. The manager starts the service when the first run begins and stops
+ * it when the last run ends, so the notification is only visible while there
+ * is real work. The service itself never downloads; it only promotes the
+ * process to foreground, shows progress, and forwards the notification's
+ * Cancel action to the manager.
+ *
+ * Only framework APIs are used (no new Gradle dependencies). All
+ * version-gated calls are branched on [Build.VERSION.SDK_INT]; the module's
+ * `minSdk` is 24.
+ *
+ * Honest limits (documented in the README): the service keeps a *running*
+ * process alive when the app is backgrounded or the screen is off, but it
+ * cannot resurrect downloads after the process is killed or the device
+ * reboots — tasks are process-local by design.
+ */
+internal class YtDlpForegroundService : Service() {
+
+  private var wakeLock: PowerManager.WakeLock? = null
+
+  override fun onBind(intent: Intent?): IBinder? = null
+
+  override fun onCreate() {
+    super.onCreate()
+    instance = WeakReference(this)
+    // Keep the CPU awake during screen-off downloads; released in onDestroy,
+    // and dies with the process if the system kills us.
+    val powerManager = getSystemService(POWER_SERVICE) as PowerManager
+    wakeLock = powerManager.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, WAKE_LOCK_TAG).also {
+      it.acquire()
+    }
+  }
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    if (intent?.action == ACTION_CANCEL_ALL) {
+      manager()?.cancelAll()
+      return START_NOT_STICKY
+    }
+    ensureChannel()
+    promote(buildNotification())
+    return START_NOT_STICKY
+  }
+
+  override fun onDestroy() {
+    try {
+      wakeLock?.let { if (it.isHeld) it.release() }
+    } catch (_: Throwable) {
+      // Best effort; the lock dies with the process regardless.
+    }
+    wakeLock = null
+    if (instance?.get() === this) instance = null
+    super.onDestroy()
+  }
+
+  /** Rebuilds the notification from the latest snapshot (no-op pre-promotion). */
+  private fun refresh() {
+    try {
+      notificationManager().notify(NOTIFICATION_ID, buildNotification())
+    } catch (_: Throwable) {
+      // Notification updates are best effort.
+    }
+  }
+
+  private fun promote(notification: Notification) {
+    if (Build.VERSION.SDK_INT >= 29) {
+      startForeground(
+        NOTIFICATION_ID,
+        notification,
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+      )
+    } else {
+      @Suppress("DEPRECATION")
+      startForeground(NOTIFICATION_ID, notification)
+    }
+  }
+
+  private fun buildNotification(): Notification {
+    val (title, text, percent) = content(activeCount, lastPercent, lastTitle)
+    val cancelIntent = PendingIntent.getService(
+      this,
+      REQUEST_CANCEL,
+      Intent(this, YtDlpForegroundService::class.java).setAction(ACTION_CANCEL_ALL),
+      PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+    )
+    val builder = if (Build.VERSION.SDK_INT >= 26) {
+      Notification.Builder(this, CHANNEL_ID)
+    } else {
+      @Suppress("DEPRECATION")
+      Notification.Builder(this)
+    }
+    builder
+      .setContentTitle(title)
+      .setContentText(text)
+      .setSmallIcon(android.R.drawable.stat_sys_download)
+      .setOngoing(true)
+      .setOnlyAlertOnce(true)
+      .setProgress(100, percent ?: 0, percent == null)
+      .addAction(android.R.drawable.ic_menu_close_clear_cancel, "Cancel", cancelIntent)
+    contentIntent()?.let { builder.setContentIntent(it) }
+    if (Build.VERSION.SDK_INT < 26) {
+      @Suppress("DEPRECATION")
+      builder.priority = Notification.PRIORITY_LOW
+    }
+    return builder.build()
+  }
+
+  /** Tapping the notification reopens the host app when possible. */
+  private fun contentIntent(): PendingIntent? {
+    val launch = packageManager.getLaunchIntentForPackage(packageName) ?: return null
+    return PendingIntent.getActivity(
+      this,
+      REQUEST_OPEN,
+      launch,
+      PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+    )
+  }
+
+  private fun ensureChannel() {
+    if (Build.VERSION.SDK_INT < 26) return
+    val manager = notificationManager()
+    if (manager.getNotificationChannel(CHANNEL_ID) == null) {
+      manager.createNotificationChannel(
+        NotificationChannel(CHANNEL_ID, CHANNEL_NAME, NotificationManager.IMPORTANCE_LOW).apply {
+          description = "Shows active yt-dlp downloads."
+          setShowBadge(false)
+        },
+      )
+    }
+  }
+
+  private fun notificationManager(): NotificationManager {
+    return getSystemService(NotificationManager::class.java)
+  }
+
+  companion object {
+    const val ACTION_START = "expo.modules.ytdlp.action.START"
+    const val ACTION_CANCEL_ALL = "expo.modules.ytdlp.action.CANCEL_ALL"
+
+    private const val CHANNEL_ID = "ytdlp_downloads"
+    private const val CHANNEL_NAME = "Downloads"
+    private const val NOTIFICATION_ID = 1001
+    private const val WAKE_LOCK_TAG = "ytdlp-react-native:download"
+    private const val REQUEST_CANCEL = 1
+    private const val REQUEST_OPEN = 2
+
+    private var instance: WeakReference<YtDlpForegroundService>? = null
+    private var managerRef: WeakReference<YtDlpDownloadManager>? = null
+
+    @Volatile
+    private var activeCount = 0
+
+    @Volatile
+    private var lastPercent: Double? = null
+
+    @Volatile
+    private var lastTitle: String? = null
+
+    /** Called once by the owning [YtDlpDownloadManager]; held weakly. */
+    fun setManager(manager: YtDlpDownloadManager?) {
+      managerRef = manager?.let { WeakReference(it) }
+    }
+
+    private fun manager(): YtDlpDownloadManager? = managerRef?.get()
+
+    /**
+     * Promote the process to foreground. Best effort: when the system refuses
+     * (e.g. background-start restrictions on API 31+), the download still
+     * proceeds without the promotion.
+     */
+    fun start(context: Context, active: Int) {
+      activeCount = active
+      val intent = Intent(context.applicationContext, YtDlpForegroundService::class.java)
+        .setAction(ACTION_START)
+      try {
+        if (Build.VERSION.SDK_INT >= 26) {
+          context.applicationContext.startForegroundService(intent)
+        } else {
+          @Suppress("DEPRECATION")
+          context.applicationContext.startService(intent)
+        }
+      } catch (_: Throwable) {
+        // Best effort (see KDoc).
+      }
+    }
+
+    fun stop(context: Context) {
+      activeCount = 0
+      lastPercent = null
+      lastTitle = null
+      try {
+        context.applicationContext.stopService(
+          Intent(context.applicationContext, YtDlpForegroundService::class.java),
+        )
+      } catch (_: Throwable) {
+        // Best effort.
+      }
+    }
+
+    /** Refreshes the notification from the latest progress snapshot. */
+    fun update(active: Int, percent: Double?, title: String?) {
+      activeCount = active
+      if (percent != null) lastPercent = percent
+      if (!title.isNullOrBlank()) lastTitle = title
+      try {
+        instance?.get()?.refresh()
+      } catch (_: Throwable) {
+        // Notification updates are best effort.
+      }
+    }
+
+    private fun content(active: Int, percent: Double?, title: String?): Triple<String, String, Int?> {
+      val pct = percent?.coerceIn(0.0, 100.0)?.toInt()
+      return if (active > 1) {
+        val sub = listOfNotNull(pct?.let { "$it%" }, title)
+          .joinToString(" • ").ifBlank { "In progress" }
+        Triple("Downloading $active files", sub, pct)
+      } else {
+        Triple(title ?: "Downloading", pct?.let { "$it%" } ?: "In progress", pct)
+      }
+    }
+  }
+}