Prompt
How do I troubleshoot failed HLS playlist generation?
Latest observation
Here’s a practical checklist for troubleshooting failed HLS playlist generation.
1) Confirm the source media is valid
Problems often start with the input, not HLS itself.
- Verify the file/container is readable:
ffprobe input.mp4
- Check for:
- Corrupt file
- Missing audio/video tracks
- Variable frame rate issues
- Unsupported codecs
- Broken timestamps
Useful command:
ffprobe -v error -show_streams -show_format input.mp4
2) Inspect the encoder/transcoder logs
Look for messages about:
- Missing keyframes
- Timestamp discontinuities
- Audio/video sync problems
- Segment writing errors
- Permission issues
- Disk space issues
If using FFmpeg, increase verbosity:
ffmpeg -loglevel verbose ...
or
ffmpeg -loglevel debug ...
3) Verify HLS output settings
Common playlist-generation failures come from bad HLS parameters.
Check these:
-f hlsis set- Output directory exists and is writable
- Segment filename pattern is valid
- Playlist path is writable
- Segment duration is reasonable
- Encryption settings are correct if enabled
Example:
ffmpeg -i input.mp4 \
-c:v h264 -c:a aac \
-f hls \
-hls_time 6 \
-hls_playlist_type vod \
-hls_segment_filename "segments/seg_%03d.ts" \
playlist.m3u8
4) Ensure keyframe alignment
HLS segments generally work best when segments start on keyframes. If the encoder doesn’t place keyframes correctly, playlist generation or playback can fail.
Consider forcing keyframes:
-g 48 -keyint_min 48 -sc_threshold 0
Or with timestamp-based forcing:
-force_key_frames "expr:gte(t,n_forced*6)"
5) Check timestamp issues
Bad timestamps can break segmentation.
Signs:
- Non-monotonic DTS/PTS
- “Invalid DTS”
- “Past duration too large”
- Playlist generated, but segments are missing or unplayable
Possible fixes:
-fflags +genpts
or
-copyts
depending on your workflow.
Sometimes re-encoding is more reliable than stream copying.
6) Test stream copy vs re-encode
If playlist generation fails with -c copy, the source may not be HLS-friendly.
Try re-encoding:
ffmpeg -i input.mp4 -c:v libx264 -c:a aac -f hls playlist.m3u8
If that works, the issue is likely in the source codec/timestamps/keyframes.
7) Check filesystem and permissions
HLS needs to create:
- playlist file
- segment files
- sometimes temp files
Make sure:
- The output directory exists
- The process has write permission
- There’s enough disk space
- The path isn’t read-only or mounted with restrictions
8) Validate the generated playlist
If the playlist is created but fails later, inspect it.
A valid .m3u8 should have:
#EXTM3U#EXT-X-VERSION#EXT-X-TARGETDURATION#EXTINFentries- Segment URLs/paths that actually exist
Example:
cat playlist.m3u8
Look for:
- Missing segment names
- Wrong relative paths
- Bad encoding of special characters
- Inconsistent target duration
9) Check segment naming and path rules
Some HLS generators fail if:
- Segment pattern is malformed
- Directory doesn’t exist
- Playlist points to a different base path than expected
Example:
-hls_segment_filename "/var/hls/seg_%03d.ts"
If using relative paths, make sure your server serves them correctly.
10) Verify web server delivery
Sometimes playlist generation is fine, but serving fails.
Check:
- MIME types:
.m3u8→application/vnd.apple.mpegurlorapplication/x-mpegURL.ts→video/mp2t
- CORS headers if playback is from another origin
- Cache settings
- HTTPS mixed-content issues
11) Confirm segment duration and list size
If segments are too short or too long, some players behave poorly.
Typical values:
- Segment length: 2–10 seconds
- Playlist window for live: enough entries for buffering
FFmpeg live example:
ffmpeg -i input.mp4 \
-c:v libx264 -c:a aac \
-f hls \
-hls_time 6 \
-hls_list_size 5 \
-hls_flags delete_segments \
live.m3u8
12) Try a minimal reproducible test
Reduce variables:
- Use a known-good input file
- Encode to a local directory
- Use default HLS options
- Remove encryption, filters, and copy modes
If the minimal test works, add options back one at a time until it breaks.
13) Common FFmpeg-specific fixes
If you’re using FFmpeg, these often help:
Re-encode with aligned keyframes
ffmpeg -i input.mp4 \
-c:v libx264 -preset veryfast -c:a aac \
-force_key_frames "expr:gte(t,n_forced*6)" \
-f hls -hls_time 6 playlist.m3u8
Handle timestamp issues
ffmpeg -fflags +genpts -i input.mp4 -f hls playlist.m3u8
Ensure compatible audio
-c:a aac -ar 48000 -b:a 128k
14) If encryption is enabled
Playlist generation can fail if key info is wrong.
Check:
- Key file exists
- Key URI is reachable
- IV/key info format is correct
- Permissions allow reading the key
15) Look at player-side symptoms
If the playlist generates but playback fails, the issue may be:
- Wrong segment URLs
- CORS
- Codec incompatibility
- Missing audio
- Nonstandard tags
- Incorrect live playlist updates
Quick diagnostic flow
- Run
ffprobeon the source - Generate HLS with verbose logs
- Test with re-encoding instead of copy
- Check keyframes and timestamps
- Inspect playlist and segment files
- Verify web server delivery
If you want, I can also give you:
- a step-by-step FFmpeg troubleshooting script
- a checklist for live HLS
- or help diagnose a specific error log if you paste it here.
Brands