AVPlayerViewController: ano ito, mga paraan ng integrasyon sa iOS

Ano ang AVPlayerViewController?

AVPlayerViewController ay isang component ng AVKit framework na nagbibigay ng handa nang interface para sa pag-playback ng video sa mga Apple app. Inililigtas nito ang developer mula sa pangangailangan na gumawa ng custom na player mula sa simula, nag-aalok ng mga standard na kontrol: play/pause, rewind, volume adjustment, at full-screen mode.

Hindi tulad ng low-level na AVPlayerLayer na nangangailangan ng manual na pagbuo ng UI, ang AVPlayerViewController ay ganap na namamahala sa lifecycle ng player. Ang controller ay awtomatikong humahawak ng screen rotation, umaangkop sa Safe Area sa iPhone na may notch, at sumusuporta sa multitasking sa iPad.

Ayon sa Apple Documentation (2026), ang AVPlayerViewController ay compatible sa AVPlayer at AVQueuePlayer, na nagpapahintulot sa pag-playback ng parehong indibidwal na file at playlist. Ang mga URL mula sa local storage, HLS network stream, at naka-encrypt na FairPlay content ay sinusuportahan.

Kasaysayan at mga bersyon ng AVPlayerViewController

Ang component ay lumitaw sa iOS 8 kasama ng AVKit bilang kapalit para sa lumang MPMoviePlayerController. Sa iOS 11 ay idinagdag ang suporta para sa Picture in Picture at pagpapakita ng mga subtitle. Sa iOS 14 ang controller ay nakakuha ng customizable na transport bar sa pamamagitan ng delegate na AVPlayerViewControllerDelegate. Simula sa iOS 16, lumitaw ang suporta para sa dynamic na pagpapalit ng media file nang hindi muling ginagawa ang player.

Ang modernong AVPlayerViewController ay na-optimize para sa ProMotion display — ang video frame rate ay awtomatikong nagsi-sync sa screen refresh rate. Sa tvOS ang component ay umaangkop sa focus interface ng Siri Remote, at sa macOS sa window mode ng QuickTime Player.

Paano gumagana ang AVPlayerViewController

Sa puso ng controller ay ang ugnayan ng AVPlayer at AVPlayerItem. Ang AVPlayer ay ang playback object na namamahala sa timeline, bilis, at estado. Ang AVPlayerItem ay isang wrapper sa paligid ng isang partikular na media file na naglalaman ng metadata, track, at impormasyon sa pag-load.

Sa pagsisimula, ang AVPlayerViewController ay tumatanggap ng reference sa AVPlayer at awtomatikong gumagawa ng AVPlayerLayer para sa pagpapakita ng video. Ang controller ay nag-subscribe sa KVO notification ng AVPlayer tungkol sa pagbabago ng status ng readyToPlay, mga error sa pag-load, at pagtatapos ng playback.

Ang mga kontrol (transport bar) ay ipinapakita sa pag-tap sa screen. Sa iOS 15+ sinusuportahan nila ang pag-customize sa pamamagitan ng AVPlayerViewControllerCustomizationDelegate, na nagpapahintulot sa pagtatago o pagpapalit ng mga standard na button.

Lifecycle ng controller

Pagkatapos gawin ang controller at italaga ang AVPlayer, ang method na viewDidLoad ay tinatawag na nagsisimula sa paghahanda ng video stream. Kapag ang AVPlayerItem ay pumasok sa status na AVPlayerItemStatusReadyToPlay, ang player ay handa nang magpakita ng mga frame. Kapag tinawag ang method na play(), magsisimula ang pag-decode ng video stream sa pamamagitan ng Video Toolbox.

Kapag umalis sa screen, ang controller ay awtomatikong nag-pause ng playback at naglalabas ng mga resource ng decoder. Sa iOS 13+ para mapanatili ang playback habang mini-minimize ang app, kinakailangan ang pag-configure ng Background Modes at Audio Session. Ayon sa WWDC 2024, inirerekomenda ang paggamit ng AVPlayerPlaybackCoordinator para sa pag-sync sa media center ng iOS.

Mga pangunahing tampok ng AVPlayerViewController

Ang component ay nagbibigay ng mayamang hanay ng mga feature na handa na, ginagawa itong kaakit-akit para sa karamihan ng mga proyekto. Nasa ibaba ang mga pangunahing kakayahan na hindi nangangailangan ng karagdagang code.

• Transport bar na may play/pause, 15 segundong rewind, volume regulator, at progress slider.
• Suporta sa subtitle — awtomatikong pagpapakita ng mga naka-embed at external na subtitle sa VTT, SRT, at iTunes Timed Text format.
• AirPlay — kakayahang mag-stream ng video sa Apple TV at iba pang AirPlay-compatible na device.
• Picture in Picture — pag-playback sa isang lumulutang na window kapag pinindot ang isang espesyal na button (sa iPad at iPhone na may iOS 14+).
• Full-screen mode — awtomatikong paglipat kapag pinaikot ang device at kapag nag-tap sa zoom button.
• Pagbabago ng bilis — built-in na controller para sa pagpili ng playback speed (0.5x, 1.0x, 1.5x, 2.0x).
• Protektadong content — native na suporta para sa FairPlay Streaming para sa HLS content na may DRM.

Transport bar ng AVPlayerViewController

Ang transport bar ay ang ibabang bahagi ng interface na naglalaman ng mga pangunahing control button. Bilang default, ang bar ay nagtatago pagkatapos ng 3 segundo ng kawalan ng aktibidad ng user at lumilitaw kapag nag-tap. Sa iOS 16+ sa pamamagitan ng delegate, ang visibility ng mga indibidwal na elemento ay maaaring pamahalaan.

Sa debug mode, ang transport bar ay maaaring pilit na ipakita sa pamamagitan ng property na AVPlayerViewController.requiresLinearPlayback, na hinaharangan din ang kakayahang i-pause ang video. Ito ay kapaki-pakinabang para sa mga ad insert at pang-edukasyon na content.

Integrasyon ng AVPlayerViewController sa proyekto

Ang basic na integrasyon ng controller ay hindi tumatagal ng higit sa 10 linya ng code. Una, kailangan gumawa ng AVPlayer instance na may URL ng media file, pagkatapos ay ipasa ito sa AVPlayerViewController at ipakita ang controller sa screen.

Paggawa ng basic player sa Swift

import AVKit

let player = AVPlayer(url: URL(string: "https://example.com/video.mp4")!)
let playerVC = AVPlayerViewController()
playerVC.player = player

present(playerVC, animated: true) {
    player.play()
}

Pagkatapos tawagin ang present, ang controller ay ipinapakita sa buong screen. Ang video ay nagsisimulang mag-load mula sa network at sa sandaling maabot ng buffer ang readyToPlay threshold, awtomatikong magsisimula ang playback pagkatapos tawagin ang play().

Pag-configure ng AVPlayerItem para sa advanced na pamamahala

let asset = AVAsset(url: videoURL)
let item = AVPlayerItem(asset: asset)

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "Ang aking video"
item.addMetadata(metadata)

let player = AVPlayer(playerItem: item)
let playerVC = AVPlayerViewController()
playerVC.player = player

Ang paggamit ng AVPlayerItem ay nagbibigay ng kontrol sa metadata, time code, pagpili ng audio track at subtitle. Sa pamamagitan ng AVPlayerItem ay maaari ring subaybayan ang progress ng pag-load, buffering, at network error gamit ang KVO sa property na status.

Pag-configure ng mga kontrol

Simula sa iOS 11, ang developer ay maaaring mag-customize ng transport bar sa pamamagitan ng protocol na AVPlayerViewControllerDelegate. Ang method na playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) ay tinatawag bago pumasok sa full-screen mode at nagpapahintulot sa paghahanda ng UI.

Para sa pagtatago ng mga indibidwal na button, ginagamit ang property na AVPlayerViewController.showsPlaybackControls. Kung itatakda sa false, ang transport bar ay ganap na nawawala, naiiwan lamang ang video stream. Kapaki-pakinabang para sa mga custom na overlay element.

Pag-customize gamit ang delegate

class CustomPlayerViewController: UIViewController {
    private let playerVC = AVPlayerViewController()

    override func viewDidLoad() {
        super.viewDidLoad()
        playerVC.delegate = self
        playerVC.showsPlaybackControls = true
        playerVC.entersFullScreenWhenPlaybackBegins = true
    }
}

extension CustomPlayerViewController: AVPlayerViewControllerDelegate {
    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        willBeginFullScreenPresentationWithAnimationCoordinator coordinator: UIViewControllerTransitionCoordinator
    ) {
        // Magdagdag ng overlay button
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("Napili ang bagong wika ng subtitle")
    }
}

Ang delegate ay nagpapahintulot sa pag-intercept ng mga event ng pagbabago ng subtitle, pagpasok at paglabas ng full-screen mode, pati na rin pagsisimula at pagtatapos ng Picture in Picture. Sa WWDC 2024, inirekomenda ng Apple ang paggamit ng delegate para sa analytics — pag-log ng bawat transition hanggang 100 ms.

Paggawa gamit ang mga subtitle at audio track

Ang AVPlayerViewController ay awtomatikong nagpapakita ng lahat ng available na subtitle at audio track, kung naka-embed ang mga ito sa media file o tinukoy sa HLS manifest. Ang user ay maaaring lumipat sa mga ito sa pamamagitan ng menu na lumilitaw kapag nag-tap sa subtitle icon sa transport bar.

Para sa HLS stream, ang M3U8 manifest ay naglalaman ng listahan ng mga available na language variant. Ang AVPlayer ay naglo-load ng kaukulang subtitle segment sa WebVTT format at ipinapasa ang mga ito para sa rendering sa pamamagitan ng AVPlayerLayer. Sa iOS 16+ lumitaw ang suporta para sa styling ng subtitle sa pamamagitan ng AVTextStyleRule.

Programmatic na pagpili ng audio track

func selectAudioTrack(languageCode: String) {
    guard let group = player.currentItem?
        .asset.mediaSelectionGroup(forMediaCharacteristic: AVMediaCharacteristic.audible)
    else { return }

    for option in group.options {
        if option.extendedLanguageTag?.hasPrefix(languageCode) == true {
            player.currentItem?.select(option, in: group)
        }
    }
}

Ang method na selectAudioTrack ay naghahanap sa mga audio option ng audiable group ng variant na ang extendedLanguageTag ay tumutugma sa nais na language code. Ito ay nagpapahintulot sa pagpapatupad ng feature na “Original audio” sa mga app na may multilinggwal na content.

Picture in Picture sa iPad

Ang mode na Picture in Picture (PiP) ay nagpapahintulot sa pagpapakita ng video sa isang lumulutang na window sa ibabaw ng iba pang apps. Sa iPad, ang feature na ito ay available mula sa iOS 9, sa iPhone mula sa iOS 14. Ang AVPlayerViewController ay awtomatikong nagdaragdag ng PiP button sa transport bar kapag may subscription sa UIBackgroundModes.

Para i-activate ang PiP, sa Info.plist kailangang magdagdag ng key na UIBackgroundModes na may value na audio at airplay. Pagkatapos nito, lilitaw ang PiP button sa controller, kapag pinindot ang video ay lumiliit sa isang lumulutang na window na may sukat na 192x108 puntos.

Ang mga event ng PiP ay pinoproseso sa pamamagitan ng delegate: playerViewController(_:willStartPictureInPictureFromFullScreen:) at playerViewController(_:didStopPictureInPicture:). Ayon sa Apple HIG, ang minimum na sukat ng PiP window ay dapat na hindi bababa sa 120x68 puntos upang mapanatili ang pagiging nababasa ng content.