YouTube downloads: M3U/HLS saved as .mp4, and proposal for a Kotlin downloader rewrite

[Priveetee]

Hi @InfinityLoop1308,

Following up on our discussion in PipePipeExtractor#62, where you mentioned that the legacy NewPipe YouTube downloader is hard to maintain and that an FFmpeg-like direction may be the correct way, I started investigating the YouTube download issue reported in PipePipe#2288.

I would like your opinion before implementing something large.

What I found

I reproduced one real bad output in PipePipe Debug:

• YouTube video: Rick Astley - Never Gonna Give You Up
• The output filename ended with .mp4
• The file was only 57053 bytes
• file identified it as M3U playlist, ASCII text
• ffprobe failed with moov atom not found
• So PipePipe saved playlist/manifest text as an MP4 file

I also added local debug instrumentation to the client downloader and captured a successful control run for the same video.

In the successful control run:

• The selected video stream was itag 136, avc1.4d401f, 720p
• The selected audio stream was itag 140, mp4a.40.2
• Both streams were exposed as direct URLs
• HTTP returned Content-Type: video/mp4 and Content-Type: audio/mp4
• Range requests returned 206
• Mp4FromDashMuxer completed successfully
• The final MP4 was valid

So the current evidence does not point to a universal MP4 muxer failure. It looks more like some YouTube response/session variant can expose a playlist/manifest resource where the client expects direct media.

Current hypothesis

There are probably two separate problems:

• The Extractor/client boundary does not make the stream type strict enough for downloads.
• The client downloader does not have a strong preflight layer to reject M3U/HLS/text before saving/postprocessing as .mp4.

A minimal fix would be to detect Content-Type or #EXTM3U and fail cleanly instead of saving a corrupt MP4.

But since the legacy YouTube downloader path is hard to maintain anyway, I would prefer to use this as a starting point for a more structured rewrite.

Proposed rewrite direction

I am thinking about a progressive Kotlin rewrite of the download stack, not a big-bang replacement.

The idea would be:

• Keep the current UI and service entry points at first
• Introduce typed models like DownloadRequest, DownloadPlan, PlannedResource, and ProbeResult
• Add a real probe layer for redirects, cookies, headers, Content-Type, range support, length, and manifest detection
• Replace the current range downloader with a stricter resumable block downloader
• Use temporary files and atomic finalization instead of writing directly to the final output when possible
• Make muxing explicit through a Muxer abstraction
• Decide per format whether to use existing internal muxers, FFmpeg/libavformat, or another backend
• Add proper HLS/M3U support instead of accidentally treating playlists as direct media

In TypeType-Downloader I used a different design: direct media streams are downloaded separately with strict parallel range validation, then audio/video are remuxed through libavformat using stream copy. That is server-side Go, so it cannot be copied directly to Android, but I think the architecture idea may apply.

Questions

Would you prefer a small targeted fix first, or are you open to starting a larger downloader rewrite?

If a rewrite is acceptable, what muxing direction would you prefer for PipePipe?

• Keep existing internal muxers
• Move toward FFmpeg/libavformat-style remuxing
• Use a hybrid/pluggable muxer abstraction
• Something else

For the Extractor/client boundary, how should HLS/M3U-like streams be exposed?

• Explicitly mark them as HLS/manifest delivery
• Hide them from normal download choices until the client supports HLS downloads
• Expose them only if the client declares support
• Another approach

I am fully open to your guidance here. If you are interested in this direction, I can split the work into small PRs and do my best to maintain it.

[InfinityLoop1308]

Well things are not that complex. The issue: we use hls stream if logged in, but the downloader doesn't support it.

Direct solution: use the same way as in NicoNicoMuxer - that means skip the whole download part and directly download the stream with ffmpegkit. Easy. No need to touch the core downloader code, just need to make sure the progress shows properly. Drawback: can't pause or stop. (but may be acceptable since not many user use PipePipe with YT logged in)

Full solution: introduce a hls download mechanism and embed it to the existed downloader. mux can be written manually or use ffmpegkit. You also need to take care about the recover.
Not sure if this is possible since I never fully understand the downloading procedure.

[Priveetee]

Ok got it, i'm experimenting something since I will keep u updated ;)

Thx for the answer

[Priveetee]

quick proper update after reading your answer and digging a bit more locally.

I think I understand the issue better now.

What changed in my understanding

At first I was looking at this as a broader downloader/client boundary problem:

• sometimes PipePipe expects direct media
• but the selected resource can actually be HLS/M3U
• then the current path may end up saving playlist text as .mp4

Your answer makes the root cause clearer:

• YouTube logged-in path can expose/use HLS streams
• the current downloader path was designed around direct HTTP/range downloads
• so the real missing piece is not "MP4 muxer is broken"
• it is "HLS is not a real supported download type yet"

So yes, the NicoNico/ffmpegkit bypass is the fastest practical fix.

But I'm personally more interested in investigating the full solution.

What I found in the code

The Extractor side already has the concept we need:

• Stream#getDeliveryMethod()
• DeliveryMethod.HLS
• Stream#getManifestUrl()

YouTube HLS streams are also already marked as HLS when they are parsed.

But on the client/download side, this information is mostly lost.

The download dialog currently passes only selectedStream.getContent() into the mission URLs.
So by the time the downloader starts, it mostly sees a String[] urls, not a typed resource saying:

• this is direct HTTP
• this is HLS manifest
• this came from a master playlist
• this needs segment download/remux
• this recovery should preserve HLS behavior

I also noticed that recovery info stores format/quality/bitrate/kind, but not the delivery method or manifest information.
So even if the first run knows it was HLS, recovery/resume does not really have enough typed state yet.

[Priveetee]

Why I don't want to start with only the bypass

The direct solution is useful and probably acceptable short-term.

But if we only use ffmpegkit to download the remote HLS URL directly, we skip the normal downloader behavior:

• pause/stop is not clean
• recovery is not really integrated
• progress is approximate unless we add special handling
• the downloader still does not "understand" HLS

For a small user-facing fix, that may be fine.

But for the real solution, I think HLS should become a first-class download resource.

Direction I want to investigate

My current idea is not a big rewrite PR in one shot.

I want to investigate a staged solution:

1. Keep HLS information from Extractor to Client
2. Add real HLS planning instead of treating it like a normal range-downloadable file
3. Add segment-level download state for pause/resume/recovery
4. Download segments locally, then remux/finalize after that
5. Add proper recovery when YouTube URLs expire

For HLS checkpointing, we probably need more than current resource + byte count.

We may need to store things like:

• manifest URL
• selected media playlist URL
• current segment index
• current segment byte offset if possible
• downloaded temp segment files
• media sequence
• playlist fingerprint/version
• whether the playlist changed too much and requires restart

For the final output, I think the pragmatic first step may be:

• app downloader handles network/progress/recovery
• ffmpegkit or libavformat only remuxes local downloaded files with stream copy

The important difference from the NicoNico-style bypass is that ffmpegkit would not be responsible for downloading the remote HLS stream.

Current conclusion

So my current understanding is:

• direct ffmpegkit bypass = easiest short-term solution
• real HLS downloader support = more correct long-term solution
• the main missing part is not muxing only
• the main missing part is typed HLS planning + segment checkpoint/recovery

I'm going to keep investigating this locally before proposing code.

If it turns out to be too invasive or not maintainable, I'll say it clearly instead of sending a huge messy PR.

But I think this is worth exploring because it would make the downloader behavior much more explicit and avoid this class of "manifest saved as media file" bugs in the future.

[Priveetee]

This is mainly for me this comment lmao to not get losted and document a little bit my work :}

[Priveetee]

I'm cooking something up. I think if I pull it off, we could completely drop FFmpegKit and use only Media3, but it's still cooking...

[Priveetee]

NicoNico is harder because it exposes HLS playlists, so it needs the HLS segment downloader first...

[Priveetee]

BiliBili is the easy case here: in my tests it exposes video-only MP4/HEVC streams and M4A audio streams as direct HTTP URLs, not HLS playlists. That makes it suitable for a native Android remux path: download both resources, then mux locally without FFmpegKit.

[Priveetee]

Hi again @InfinityLoop1308 Small update/question before I go too far in this direction :P

I managed to get a working local prototype where the problematic core media download paths are handled by a new native downloader path, currently called download2 in my local branch, instead of FFmpegKit (We can change the name, yes the name sucks, I suck to choose name)

By "core media download paths", I mean the central media download path for the problematic services we discussed here, not the whole app UI/service/queue layer.

In short, this local download2 path keeps typed download resources, probes direct media vs manifests before writing output, downloads direct media with HTTP/range requests, downloads HLS segment-by-segment when needed, decrypts HLS AES-128 locally, and then remuxes local media with Android native MediaExtractor/MediaMuxer.

So far locally:

• YouTube DASH downloads use direct video/audio media streams and the existing internal muxing path.
• BiliBili video/audio direct media downloads are muxed natively.
• NicoNico HLS, including AES-128 encrypted segments, downloads and remuxes natively.
• FFmpegKit can be removed from the app build in this prototype.

I know this direction is more radical than the direct FFmpegKit bypass, so I wanted to ask first: would you be okay with this approach, or would you prefer not to go this far?

If you are open to it, I would not send one huge PR. Once I am satisfied with my work, I can split it into multiple small PRs so each step is easier to review.

I can also document the design/tradeoffs properly and answer any questions you have. I'm also willing to take responsibility for maintaining this download backend myself if this direction is accepted :)

For SoundCloud, PeerTube, Bandcamp and MediaCCC, I would keep the current legacy behavior untouched for now unless you want otherwise.

[InfinityLoop1308]

I don't think using MediaExtractor/MediaMuxer is a good idea. The critical issue: it doesn't guarantee the same result on every device.

[InfinityLoop1308]

IMO we should rely on ffmpeg for media operations and we take care of downloading logic.

[Priveetee]

Yes I understand the concern about MediaExtractor/MediaMuxer.

If the result can change depending on the device, then I agree it should not replace the current ffmpeg-based path by default.

I was maybe a bit too optimistic in my previous wording about dropping FFmpegKit/use Media3 everywhere :P

So maybe the better direction is this:

First, I can make a smaller PR for the current downloader path only. The goal would be to fix the safe parts there, like not saving manifest/HLS playlist text as media, while still keeping ffmpeg for media operations.

Then separately, download2 can stay as an experimental/beta backend only, not the default. Also yes, download2 is still a bad temporary name :P

I still think it is worth testing locally because the results are good, and devices will only get newer over time. Also FFmpegKit is now archived/officially retired, so long term I think it is useful to at least experiment with alternatives, even if ffmpeg stays the stable/default path for now.

For reference, my local results so far:

• YouTube DASH 720p 136+140: current path ~4.04s, experimental ~1.66s
• BiliBili: current path ~34.67s, experimental ~7.5s
• NicoNico HLS/AES: current path ~34.30s, experimental ~6.3s

I also tested ffprobe output, pause/resume, cancel, network interruption recovery, process kill/restart recovery, and expired URL recovery.

So I think I will focus first on the small safe PR for the current ffmpeg-based path, and keep the experimental backend only as a beta idea for later.

Would this be okay for you?

[InfinityLoop1308]

my thoughts:

• perf is important for app, but not that important in downloading. T(download process) >>> T(post-process / mux)
• not maintained is not a strong reason for replacing a component, especially in a mobile app. ffmpegkit uses ffmpeg 6.0 which is enough for working reliably for a really long period of time.
• for my understanding downloader2 only takes care of hls downloading? if yes, there is no need for being a beta option or fallback, it becomes the hlsdownloader; if no, I must say there is no reason to replace the existed downloading route for YT dash or other legacy services.
• i'm not sure if my previous comment in the pr confuse you, but let's be clear: things are "hard to maintain" doesn't mean we need to replace them. actually from my sight almost the whole app built on NewPipe is hard to maintain - but we don't need and should not rewrite it. We coexists with it.

[Priveetee]

Ok yes, I think I understand better now.

I was probably mixing two things in my head: the HLS download problem, and my local experiment where I also tried to replace other download routes. After your clarification, I agree it should not be presented like that.

So I will refocus this as an HLS downloader only:

• keep the current downloader route for YT DASH/direct and existing services
• keep FFmpegKit for media operations/remux
• app downloader only handles HLS segment download/checkpoint/recovery
• no beta backend/fallback thing, just HlsDownloader for HLS resources

I already started cleaning my local branch in this direction. The goal is not to rewrite the downloader or replace NewPipe logic, but only to add the missing HLS download path so we don't save manifests as media and can still have pause/resume/recovery.

I will still keep working on performance too, but more as normal optimization after the design is correct, not as the main reason to replace existing routes.

Thanks for the clarification, it helps me avoid going too far in the wrong direction :)

[Priveetee]

I think the client-side work is basically ready now.

I tested it quite a bit:

• YouTube HLS downloads finish correctly
• YouTube non-HLS/direct downloads still use the old path
• NicoNico HLS works
• BiliBili direct download still works
• pause/resume works
• force-stop/restart recovery works

I'll open the client PR so the current direction is easier to review.

While checking the diff before opening it, I noticed 2 possible cleanup ideas:

• maybe replace my small custom HLS playlist parser with ExoPlayer's existing HlsPlaylistParser, since the app already uses it for playback
• deduplicate some HLS helper/routing code between the dialog/direct downloader/service/mission classes

Not sure if u prefer I try these before review, or if it's better to open the PR first and adjust from review comments. Just let me know what sounds better :)