Add playerItem() with automatic video and audio combination - #143
alexeichhorn wants to merge 25 commits into
Conversation
…erating player items
alexeichhorn
changed the title
![codex-pr-bot[bot]](https://avatars.githubusercontent.com/in/4238751?s=60&v=4){kind=small}
| throw YouTubeKitError.extractError | ||
| } | ||
|
|
||
| let metadataDuration = try await metadata?.duration |
There was a problem hiding this comment.
This unconditional metadata lookup can throw after streams were retrieved successfully, preventing both the HLS attempt and the composition fallback even though compositionPlayerItem explicitly supports a nil duration. In particular, metadata always uses local extraction regardless of methods, so a .remote stream fallback can still fail whenever local metadata extraction is broken—the exact condition remote extraction is intended to survive.
| if let bestCombinedStream { | ||
| if videoStream == nil || (bestCombinedStream.videoResolution ?? 0) >= (videoStream?.videoResolution ?? 0) { |
There was a problem hiding this comment.
A lower-resolution combined stream is rejected whenever a higher-resolution video-only stream exists, without considering whether audioStream is nil. If audio-only variants are absent or filtered as non-native, execution then reaches the guard and throws even though bestCombinedStream was directly playable. This can occur when a platform supports the combined stream's audio codec but not the available standalone audio variant.
| try videoTrack.insertTimeRange(CMTimeRange(start: .zero, duration: videoTimeRange), of: videoAssetTrack, at: .zero) | ||
|
|
||
| // add audio track | ||
| try audioTrack.insertTimeRange(CMTimeRange(start: .zero, duration: videoTimeRange), of: audioAssetTrack, at: .zero) |
There was a problem hiding this comment.
The same video-derived time range is inserted from the independent audio asset. Separate YouTube audio and video tracks can have slightly different durations, so when the audio track is shorter, insertTimeRange requests media outside its time range and the promised composition fallback throws instead of producing a player item. This also affects every watchOS call, where the HLS path is excluded.
| public func playerItem(maxResolution: Int? = nil) async throws -> AVPlayerItem { | ||
| // For livestreams: use the direct url | ||
| let isLiveContent = (try? await isLiveContent) ?? false | ||
| if isLiveContent, let livestream = try await livestreams.first { |
There was a problem hiding this comment.
When content is identified as live but livestreams returns an empty array because its streaming data has no HLS manifest, this condition falls through to ordinary stream selection. The PR also removed checkAvailability()'s prior liveStreamError guard, so a currently live stream—where only HLS is supported—can now be sent through MP4/HLS-index or composition assembly instead of reporting that no supported live stream exists.
There was a problem hiding this comment.
Intentionally not changing this: falling through can recover a video misclassified as live, while a genuine livestream without HLS will still fail in the existing stream path.
| if isLiveContent, let livestream = try await livestreams.first { | ||
| return AVPlayerItem(url: livestream.url) |
There was a problem hiding this comment.
The livestream branch returns the native adaptive HLS manifest without applying maxResolution or recording any maximum resolution on the player item. A call such as playerItem(maxResolution: 720) can therefore select a 1080p or 4K HLS variant, violating the public parameter contract and potentially exceeding the caller's bandwidth or device constraint.
| let isLiveContent = (try? await isLiveContent) ?? false | ||
| if isLiveContent, let livestream = try await livestreams.first { |
There was a problem hiding this comment.
This branch calls livestreams, whose implementation is documented to always use local streamingData and ignore methods. Consequently, YouTube(methods: [.remote]).playerItem() can still fail for a livestream when local extraction is broken, even if remote extraction can provide the stream; the parameterized remote test exercises the same local path rather than remote extraction.
There was a problem hiding this comment.
Not changing this in this PR: livestreams already documents that it uses local extraction regardless of methods. Remote livestream extraction can be added separately in the future.
1 participant
AVPlayercurrently means selecting an already-combined stream, which is often lower quality, or manually pairing separate video and audio streams.playerItem(maxResolution:)to select the best natively playable streams and automatically return one ready-to-useAVPlayerItem. It reuses a suitable combined stream when available, otherwise combines separate high-quality video and audio through the faster HLS-backed path with a composition fallback.Note
Overview Adds
playerItem(maxResolution:), a high-level API that returns anAVPlayerItemusing the highest-resolution natively playable media within the requested resolution limit.Automatic stream combination Prefers an existing combined video-and-audio stream when suitable; otherwise, it pairs the best video-only stream with the highest-bitrate audio stream.
Playback paths Uses native HLS directly for livestreams. For MP4/M4A on-demand media, it builds byte-range HLS playlists from MP4 segment indexes, with
AVMutableCompositionas the alternate combination path.Supporting metadata Adds video duration to
YouTubeMetadataand carries stream dimensions through local and remote extraction to describe generated playlists and bound playback length. The README now demonstrates the simplifiedplayerItem()workflow.