Apple PlatformIssue Guide
#011 AVFoundation Open

AVPlayerItemSampleBufferOutput returns no decoded audio for HLS on iOS 27 beta

AvfoundationHlsPlaybackApple forumInferredIosInvestigatingKnown issueApple docs
GitHub source

Inferred. This page is generated from GitHub Issue #11; GitHub remains the canonical authoring and discussion source.

Source#

Apple Developer Forums, AVFoundation tag — recent posts titled “AVPlayerItemSampleBufferOutput” and “fail to get HLS realtime stream via AVPlayerItemSampleBufferOutputDelegate”:
https://developer.apple.com/forums/tags/avfoundation

Apple documentation:
https://developer.apple.com/documentation/avfoundation/avplayeritemsamplebufferoutput

Problem#

Developers testing the new iOS 27 beta AVPlayerItemSampleBufferOutput API report that ordinary HLS playback succeeds, but decoded PCM cannot be obtained from the attached output. In the reported cases:

  • the AVPlayerItem reaches .readyToPlay;
  • HLS playback itself proceeds;
  • AVPlayerItemSampleBufferOutput is created with an audio configuration;
  • the requested format is PCM;
  • the output is attached with AVPlayerItem.addOutput(_:);
  • delegate callbacks do not provide usable sample data, or pull methods return no sample buffers.

This is particularly important because the API is new and currently documented as beta.

Public API contract#

Apple documents AVPlayerItemSampleBufferOutput as delivering CMSampleBuffers for AVPlayerItem playback. For audio, create it with AVPlayerItemSampleBufferOutputAudioConfiguration, specify a PCM requestedAudioFormat, and attach the output to the player item using addOutput(_:).

The documentation also states that the output can be pulled ahead of current playback time, so the application must coordinate pulling with the item timebase.

The requested PCM description is a preference: the resulting output format may differ in LPCM numeric type, interleaving, or sample size while still matching the described AudioStreamBasicDescription fields.

Investigation model#

Do not collapse this into “HLS cannot expose PCM” or “the PCM format is wrong” without locating the first failing state transition.

Use this pipeline:

HLS resource acquisition
        ↓
demux / audio track selection
        ↓
decode pipeline instantiated
        ↓
AVPlayerItem becomes current item
        ↓
SampleBufferOutput attached and accepted
        ↓
audio output configuration negotiated
        ↓
decoded sample becomes available
        ↓
delegate notification / pull readiness
        ↓
next sample buffer returned

The important distinction is:

AVPlayerItem.readyToPlay
        ≠
SampleBufferOutput is producing samples

readyToPlay describes the player item's playback readiness. It is not evidence that a newly attached auxiliary output has already been connected to the active decode graph.

Key A/B tests#

1. Attachment timing#

Compare:

A. create output → addOutput → make item current → play
B. wait for readyToPlay → create output → addOutput → play
C. start playback → add output after playback has advanced

If A works while B/C fail, output-graph construction timing becomes the primary boundary.

2. HLS versus file-backed media#

Use the same encoded audio where possible:

A. local/progressive MP4 or M4A
B. VOD HLS
C. live HLS
D. LL-HLS

This separates generic sample-output configuration from HLS-specific pipeline behavior.

3. Requested PCM format#

Start with the simplest supported PCM description rather than requiring one exact downstream representation. Record the actual CMFormatDescription from every returned sample.

Do not reject a sample solely because interleaving, numeric type, or sample size differs from the requested format; Apple's beta documentation explicitly allows these differences.

4. Pull versus delegate path#

Instrument both concepts independently:

delegate callback observed?
nextAvailableSampleBuffer reports data?
nextSampleBuffer returns data?
item timebase advancing?
player rate > 0?
current item identity unchanged?

A missing delegate callback and a pull API returning no data are not necessarily the same failure. Determine whether the decode/output queue is empty or only notification delivery is missing.

5. Current-item requirement#

Apple documents that playback occurs only while the AVPlayerItem is the player's current item. Log:

output owner item
player.currentItem identity
currentItem status
timebase time
player rate

when every sample request occurs.

Evidence versus inference#

Evidence#

  • Apple documents the API as able to deliver decoded audio CMSampleBuffers from AVPlayerItem playback.
  • Audio configuration currently requires a PCM requested format.
  • The output is explicitly documented as a beta API.
  • Multiple recent forum reports describe no PCM delivery for HLS during iOS 27 beta testing while AVPlayer playback itself works.

Inference to test#

  • Attaching the output only after .readyToPlay may leave it outside, or require reconfiguration of, an already-established HLS decode/output graph.
  • The current beta may contain an HLS-specific output-path defect.
  • Delegate notification and pull readiness may have separate failure modes.

None of these should be presented as an Apple contract until reproduced or confirmed by Apple.

Verification matrix#

For each run capture:

OS build
asset type: file / VOD HLS / live HLS / LL-HLS
audio codec
output creation timestamp
addOutput timestamp
readyToPlay timestamp
play timestamp
player.currentItem identity
player rate
item timebase
requested PCM ASBD
delegate callback timestamps
nextAvailableSampleBuffer result
nextSampleBuffer result
returned sample format description
AVPlayerItem access/error logs
relevant Media Playback system logs

Minimum matrix:

                    output before current   output after readyToPlay
file-backed                A                         B
VOD HLS                    C                         D
live HLS                   E                         F

The first cell where behavior changes is a stronger root-cause boundary than the final symptom “no PCM”.

Guideline#

For new AVFoundation output APIs, debug pipeline participation before debugging media bytes.

Use this invariant:

resource is playable
        ≠
auxiliary output is attached to active decode graph
        ≠
sample is available to client
        ≠
notification was delivered

Treat each as a separate state and instrument the transition between them.

Until iOS 27 and this API leave beta, keep production architecture behind an availability/feature gate and validate each beta build independently.

Reusable engineering rule#

When playback succeeds but a data-output API returns nothing, locate the boundary between decode success, output-graph attachment, sample availability, and callback delivery before changing the media source or format.

References#