iOS使用AVPlayer播放HLS直播流报错：媒体格式样本描述无效

Hey there, let's break down the error you're seeing when trying to play an HLS live stream with AVPlayer on iOS. The AVFoundationErrorDomain Code=-11800 is a general media playback failure, but the underlying NSOSStatusErrorDomain Code=-12714 (which maps to kMediaFormatErr_SampleDescriptionInvalid) tells us the core issue: the stream's media sample description is invalid—most commonly due to an invalid video size or malformed encoding parameters.

Here are actionable steps to diagnose and fix this:

1. Validate Video Resolution & Encoding Compatibility #

• Check if your stream uses non-standard or unsupported resolution: iOS devices struggle with odd-numbered dimensions (e.g., 1921×1080) or resolutions exceeding the device's hardware limits (like 4K on older iPhones). Stick to even-width/height values (1920×1080, 1280×720, etc.).
• Confirm the codec is iOS-friendly: Use H.264 (Baseline/Main/High profile) for broad compatibility, or H.265 (HEVC) if targeting iOS 11+. Avoid custom or niche codecs that AVFoundation doesn't natively support.

2. Inspect HLS Playlist (M3U8) & TS Slice Integrity #

• Open your stream's M3U8 file and check the EXT-X-STREAM-INF tags. Ensure the RESOLUTION field has valid, non-zero values (no 0x0 or impossible dimensions).
• Use ffprobe to analyze individual TS slices for corruption:

  ffprobe -show_streams path/to/your/stream_slice.ts
  

  Look for red flags in the output—like invalid width/height values or malformed codec metadata. If slices have broken sample description boxes, the stream is corrupted at the source.

3. Rule Out App-Specific Code Issues #

• Test the stream with Apple's native AVPlayerViewController (no custom code). If the native player also throws the same error, the problem is definitely with the stream itself. If it works, double-check your code for any custom media processing (like modifying AVAsset properties or using non-standard AVPlayerItem configurations) that might be breaking playback.
• Clear your app's cache and restart the device—sometimes stale media data can cause unexpected format errors.

4. Fix Server-Side Transcoding Configuration #

If you control the streaming server (e.g., using FFmpeg to generate HLS):

• Ensure your transcoding command specifies valid, even dimensions and supported codecs. Example of a valid FFmpeg command:

  ffmpeg -i input_source -c:v libx264 -profile:v main -level:v 4.1 -s 1920x1080 -c:a aac -f hls -hls_time 10 -hls_list_size 6 output.m3u8
  

• Update your transcoding tool to the latest stable version (e.g., FFmpeg 6.x)—older versions sometimes generate malformed sample descriptions for live streams.
• For adaptive bitrate (ABR) streams, make sure all resolution tiers use valid dimensions and consistent encoding parameters. Sudden resolution switches with invalid metadata can trigger this error mid-playback.

内容的提问来源于stack exchange，提问作者mike bob