⚠ Created by AI πŸ€–

I ran into an interesting HLS streaming problem:

  • curl could download the playlist.
  • VLC could play an individual segment.
  • FFmpeg could identify the problem.
  • But VLC could not play the HLS stream directly.

The eventual solution was a small Python proxy that rewrites the HLS segment URLs.

The original request

The stream was accessed through an URL that returned an HLS playlist.

A request with the appropriate browser-like headers worked:

curl -v \
  -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:152.0) Gecko/20100101 Firefox/152.0' \
  -e 'https://abc.xyz/' \
  'YOUR_M3U8_URL'

The important part was that the server returned:

HTTP/2 200
content-type: application/vnd.apple.mpegurl
server: cloudflare

So the URL itself wasn’t a media file. It was an HLS playlist.

VLC initially got HTTP 403

When VLC tried the same URL, the request looked roughly like:

vlc \
  --http-user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:152.0) Gecko/20100101 Firefox/152.0" \
  --http-host "abc.xyz" \
  --http-referrer "https://abc.xyz/" \
    "YOUR_M3U8_URL"
GET /... HTTP/1.1
Host: abc.xyz
User-Agent: VLC/3.0.21 LibVLC/3.0.21
Referer: https://abc.xyz/
Range: bytes=0-

The server returned:

HTTP/1.1 403 Forbidden
Server: cloudflare

This initially suggested that Cloudflare was rejecting VLC’s request based on its HTTP fingerprint, particularly the VLC User-Agent and request characteristics.

Using browser-like headers helped confirm that the URL itself was accessible.

But that wasn’t the whole problem.

The playlist revealed the real problem

Downloading the playlist with curl showed a normal M3U8 file:

#EXTM3U
#EXT-X-...
...
https://example.com/.../0000.png
#EXTINF:5.000000,
https://example.com/.../0001.png
#EXTINF:5.000000,
...

The important detail was the segment extension:

.png

At first glance these looked like image files.

They weren’t.

The .png files were actually MPEG-TS

I downloaded one of the segments:

curl -v \
  -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:152.0) Gecko/20100101 Firefox/152.0' \
  -e 'https://abc.xyz/' \
  'https://example.com/.../0000.png' \
  -o /tmp/segment

file reported only:

/tmp/segment: data

But VLC could play the downloaded file directly.

Looking at the first bytes showed:

xxd -l 32 /tmp/segment

# 47 40 11 10 ...

0x47 is the MPEG transport-stream sync byte.

VLC’s demuxer confirmed it:

vlc -vvv /tmp/segment 2>&1 | grep -Ei 'demux|codec|format|mpeg|h264|h265|avc|hevc'
ts demux
pid=256 type=0x1b AVC video stream
pid=257 type=0xf ISO/IEC 13818-7 Audio with ADTS transport

In other words, the .png URL was actually returning:

  • MPEG-TS
  • H.264 video
  • AAC/ADTS audio

So the URL extension was deliberately or accidentally misleading.

Why VLC could play the file but not the HLS stream

This was the key distinction.

If I downloaded:

0000.png

and opened the resulting file directly in VLC, VLC could inspect the bytes and recognize MPEG-TS.

But when VLC’s HLS/adaptive demuxer encountered:

https://.../0000.png

it failed with:

adaptive demux error: Failed to create demuxer 0x0 Unknown

The HLS layer was having trouble determining which demuxer to use for the segment.

So:

Downloaded file
    ↓
VLC inspects bytes
    ↓
MPEG-TS detected
    ↓
Works

while:

M3U8
    ↓
HLS adaptive demuxer
    ↓
segment ends in .png
    ↓
cannot create appropriate demuxer
    ↓
fails

This explains the seemingly contradictory behavior.

FFmpeg confirmed it

FFmpeg produced an even more useful error:

URL https://.../0000.png is not in allowed_segment_extensions

That made the problem much clearer.

FFmpeg’s HLS demuxer has restrictions on which segment extensions it will accept. A .png segment URL isn’t treated like a normal MPEG-TS segment.

The media bytes were fine.

The URL naming was the problem.

Why a browser player may behave differently

A web player such as JW Player may handle the stream differently depending on:

  • browser
  • native HLS vs MSE
  • MIME type
  • segment response headers
  • browser security policies
  • the server’s User-Agent/Referer requirements

The solution: rewrite the playlist

The clean solution was to put a small HTTP proxy between the player and the upstream server.

Instead of:

VLC
 ↓
original.m3u8
 ↓
0000.png
 ↓
MPEG-TS

the proxy changes it to:

VLC
 ↓
http://127.0.0.1:8080/stream.m3u8
 ↓
http://127.0.0.1:8080/segment.ts
 ↓
upstream 0000.png
 ↓
MPEG-TS

The player sees .ts.

The upstream server still receives the original .png URL.

Small Python proxy

I used Flask and requests:

pip3 install flask requests

Then:

from flask import Flask, Response, request
import requests
from urllib.parse import quote, unquote

app = Flask(__name__)

UPSTREAM_M3U8 = "YOUR_M3U8_URL"

HEADERS = {
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:152.0) Gecko/20100101 Firefox/152.0",
    "Referer": "https://abc.xyz/",
}

session = requests.Session()
session.headers.update(HEADERS)


@app.route("/stream.m3u8")
def playlist():
    r = session.get(UPSTREAM_M3U8)
    r.raise_for_status()

    lines = r.text.splitlines()
    output = []

    for line in lines:
        if line.startswith("http"):
            output.append(
                "/segment.ts?url=" + quote(line, safe="")
            )
        else:
            output.append(line)

    return Response(
        "\n".join(output) + "\n",
        content_type="application/vnd.apple.mpegurl"
    )


@app.route("/segment.ts")
def segment():
    url = request.args.get("url")

    if not url:
        return "Missing URL", 400

    url = unquote(url)

    r = session.get(url, stream=True)
    r.raise_for_status()

    return Response(
        r.iter_content(chunk_size=64 * 1024),
        content_type="video/mp2t"
    )


if __name__ == "__main__":
    app.run(
        host="127.0.0.1",
        port=8080,
        threaded=True
    )

Start it with:

python3 proxy.py

Then open this in VLC:

http://127.0.0.1:8080/stream.m3u8

And the stream plays.

What the proxy actually changes

The original playlist contains:

#EXTINF:5.000000,
https://example.com/.../0000.png

The proxy turns it into something like:

#EXTINF:5.000000,
/segment.ts?url=https%3A%2F%2Fexample.com%2F...%2F0000.png

VLC requests:

GET /segment.ts?url=...

The proxy requests the original .png URL.

The proxy then returns the raw bytes with:

Content-Type: video/mp2t

So VLC sees a normal MPEG-TS segment.

Nothing is transcoded.

The proxy simply:

  1. downloads bytes
  2. changes the URL
  3. changes the response MIME type
  4. passes the media through

That makes it very lightweight.

The important lesson

The stream wasn’t fundamentally broken.

The chain looked like this:

             β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
             β”‚   Original M3U8      β”‚
             β”‚ abc.xyz   β”‚
             β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                        β”‚
                        β–Ό
             β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
             β”‚ HLS segment URL      β”‚
             β”‚ 0000.png   β”‚
             β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                        β”‚
                        β–Ό
             β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
             β”‚ Actual content       β”‚
             β”‚ MPEG-TS              β”‚
             β”‚ H.264 + AAC          β”‚
             β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

The confusing part was that the URL said:

.png

while the contents were:

MPEG-TS

Different software makes different decisions about whether to trust the extension, MIME type, or actual content.

Final diagnosis

ComponentResult
Original URLHLS playlist
PlaylistValid M3U8
Segment extension.png
Segment contentsMPEG-TS
VideoH.264
AudioAAC/ADTS
curlWorks
VLC individual segmentWorks
VLC HLS directlyFails
FFmpeg HLSRejects .png segment
Python proxyWorks

The proxy effectively normalizes the unusual HLS stream without modifying the underlying media.

A useful debugging strategy

When an HLS URL doesn’t play, don’t stop at the .m3u8.

Work through the layers:

1. Can I download the M3U8?
        ↓
2. Is the playlist valid?
        ↓
3. What are the segment URLs?
        ↓
4. Can I download one segment?
        ↓
5. What are the actual bytes?
        ↓
6. Can VLC/FFmpeg play the segment directly?
        ↓
7. Does the HLS demuxer fail specifically?

That distinction between “the media is invalid” and “the HLS client doesn’t like how the media is addressed” turned out to be the crucial clue.

In this case, the media was perfectly playable. The problem was that MPEG-TS data was being served behind URLs ending in .png, and the HLS clients were not consistently willing to treat those URLs as MPEG-TS segments.

If you want, I can also turn this into a more polished Hugo/Stack-style post with a diagram, β€œProblem β†’ Investigation β†’ Root Cause β†’ Fix” structure, and a collapsible troubleshooting section.