Add optional munim-ffmpeg post-processing adapter

[fazi-gondal]

Hi @devusimple Add an optional integration path for using munim-ffmpeg for native media post-processing after yt-dlp downloads the required streams.

This should complement the existing ffmpeg.location support rather than replace it.

Motivation

The current ffmpeg.location option is useful when yt-dlp itself needs to invoke a real FFmpeg executable for merging or post-processing. However, munim-ffmpeg provides an in-process native FFmpeg API for React Native/Expo and therefore should not be treated as an ffmpeg.location executable.

A useful integration would allow applications to use yt-dlp purely for extraction/download and delegate the final media processing to munim-ffmpeg.

Proposed Architecture

ytdlp-react-native
        │
        │ download separate streams
        ▼
 video file + audio file
        │
        ▼
 optional post-processing
        │
        ▼
   munim-ffmpeg
        │
        ▼
   final media file

The important distinction is:

• yt-dlp → extraction and downloading
• munim-ffmpeg → optional native muxing/transcoding/post-processing
• ffmpeg.location → remains available when yt-dlp itself needs a real FFmpeg executable

Proposed API

The exact API can be discussed, but one possible design is to expose a way to download video and audio separately without asking yt-dlp to merge them:

const streams = await YtDlp.downloadStreams({
  url,
  videoFormat: "bestvideo",
  audioFormat: "bestaudio",
});

Returning something similar to:

{
  videoPath: string;
  audioPath: string;
}

The application could then pass those files to munim-ffmpeg:

await FFmpegSession.execute(
  `-i "${videoPath}" -i "${audioPath}" -c copy "${outputPath}"`
);

For compatible streams, -c copy should allow muxing without re-encoding.

The API could later be extended for other post-processing operations such as:

• Transcoding
• Subtitle burning
• Metadata manipulation
• Thumbnail embedding
• Audio/video stream selection

Requirements

• Keep munim-ffmpeg an optional dependency; it must not become a required dependency of the core package.
• Provide a supported way to download separate video/audio streams without requiring yt-dlp to invoke an FFmpeg executable for the merge step.
• Return the downloaded stream paths so applications can process them with munim-ffmpeg.
• Document that munim-ffmpeg is an in-process post-processing integration and cannot be supplied directly as ffmpeg.location.
• Preserve the existing ffmpeg.location behavior for users who want yt-dlp to perform its own FFmpeg processing.
• Support efficient stream copying/muxing where possible to avoid unnecessary re-encoding.
• Make errors from the download and post-processing stages distinguishable and actionable.
• Keep cancellation/progress handling compatible with the existing download task API where practical.
• Ensure the feature remains compatible with Expo development builds and the existing Android architecture.

Acceptance Criteria

• Applications can download separate video and audio streams without requiring a real FFmpeg executable for the download stage.
• The returned stream paths can be passed to munim-ffmpeg to produce a final media file.
• Compatible streams can be muxed with stream copy without re-encoding.
• Existing users who configure ffmpeg.location continue to work without changes.
• The core package does not require munim-ffmpeg to be installed.
• Documentation clearly explains when to use ffmpeg.location versus the optional munim-ffmpeg integration.

Related

This builds on the existing FFmpeg guidance in the README while providing a native post-processing path for applications that prefer munim-ffmpeg over spawning an FFmpeg executable.