Add runtime yt-dlp version updates without requiring an app rebuild

[fazi-gondal]

Hi @devusimple Add an optional runtime update mechanism that allows applications to update the bundled yt-dlp Python package without requiring a new version of ytdlp-react-native or rebuilding the entire application.

Motivation

Currently, updating the yt-dlp version requires updating the native package and rebuilding the application.

This creates a significant maintenance problem because yt-dlp's extractors can require frequent updates when websites change their APIs, signatures, or extraction mechanisms.

The current workflow is:

New yt-dlp release
       ↓
Update ytdlp-react-native
       ↓
Rebuild native package
       ↓
Rebuild application
       ↓
Release new APK/AAB
       ↓
Users install the new app

A runtime update mechanism could instead allow:

New yt-dlp release
       ↓
Application checks for update
       ↓
Download compatible yt-dlp package
       ↓
Store locally
       ↓
Use updated yt-dlp

This would allow applications to receive yt-dlp extractor fixes without requiring an application update.

Proposed Architecture

The embedded Python runtime and native dependencies should remain unchanged.

Only the yt-dlp package/code should be replaceable at runtime:

Native Application
│
├── Embedded Python Runtime
│   └── Fixed / bundled
│
├── yt-dlp
│   ├── Bundled version
│   │      └── Fallback
│   │
│   └── Runtime version
│          └── Preferred when installed
│
└── Other native dependencies
       └── Fixed / bundled

The runtime version should take precedence when available, while the bundled version remains available as a fallback.

Proposed API

The exact API can be discussed, but a possible design is:

const version = await YtDlp.getVersion();

Check for an available update:

const update = await YtDlp.checkForUpdate();

if (update.available) {
  console.log(update.currentVersion);
  console.log(update.latestVersion);
}

Install the update:

await YtDlp.update();

Optionally install a specific version:

await YtDlp.update({
  version: "2026.09.05",
});

Rollback to the bundled version:

await YtDlp.rollback();

Clear the runtime override:

await YtDlp.clearRuntimeVersion();

Runtime Update Configuration

Developers should be able to control whether runtime updates are enabled:

YtDlp.configure({
  runtimeUpdates: {
    enabled: true,
    autoUpdate: false,
    checkInterval: 86400000,
  },
});

Automatic updates should not be required. Applications should be able to check for updates and decide when to install them.

Requirements

• Allow yt-dlp to be updated without rebuilding the native application.
• Keep the embedded Python runtime unchanged.
• Keep native dependencies unchanged.
• Store the runtime yt-dlp version in application-private storage.
• Prefer the runtime version over the bundled version when it is valid and available.
• Fall back to the bundled yt-dlp version if the runtime version is unavailable or fails validation.
• Provide getVersion().
• Provide checkForUpdate().
• Provide update().
• Provide a way to rollback/remove the runtime version.
• Support installing a specific yt-dlp version where practical.
• Provide download/update progress where practical.
• Support cancellation of an update.
• Validate downloaded packages before activating them.
• Handle interrupted or corrupted updates safely.
• Do not replace the currently working version until the new version has been successfully downloaded and validated.
• Preserve backward compatibility for applications that do not enable runtime updates.
• Clearly document supported platforms and limitations.

Safe Update Strategy

The update should use an atomic-style installation process:

Current yt-dlp
      │
      ├── Download new version
      │
      ├── Validate package
      │
      ├── Install to temporary location
      │
      ├── Verify installation
      │
      └── Activate new version
              │
              ▼
       New yt-dlp version

If anything fails during the process:

Update failed
     ↓
Keep current version
     ↓
Continue using existing yt-dlp

This prevents a failed download or corrupted package from breaking yt-dlp completely.

Version Selection

The library should expose enough information for applications to make update decisions:

{
  currentVersion: string;
  latestVersion: string;
  available: boolean;
}

If practical, the update mechanism could also support:

• Stable releases only
• Specific version pinning
• Minimum supported version
• Rollback to bundled version

Security

Runtime packages should not be blindly executed after downloading.

Where practical, the update mechanism should verify:

• Download integrity
• Expected package/version
• Package metadata
• Checksum or signature

The implementation should also use a trusted source for obtaining yt-dlp releases.

Acceptance Criteria

• A developer can update yt-dlp without rebuilding the application.
• The application can detect the currently active yt-dlp version.
• The application can check whether a newer version is available.
• The application can download and activate a newer compatible yt-dlp version.
• The runtime version is preferred over the bundled version.
• A failed update does not break the existing installation.
• The application can return to the bundled yt-dlp version.
• Existing applications continue working without enabling runtime updates.
• Documentation explains the runtime update mechanism, storage behavior, security considerations, and fallback behavior.

Out of Scope

This issue should not attempt to update:

• The embedded Python runtime
• Native Android/iOS code
• Native FFmpeg binaries
• Other native dependencies
• The React Native/Expo package itself

The primary goal is to make the yt-dlp package independently updatable at runtime.

Benefits

This would significantly reduce the need for application releases when yt-dlp requires an extractor update.

Instead of:

Website change
    ↓
New yt-dlp
    ↓
New native package
    ↓
New application build

applications could use:

Website change
    ↓
New yt-dlp
    ↓
Runtime update
    ↓
Continue downloading

This would make ytdlp-react-native considerably more practical for production applications where extractor reliability is critical.