AVPlayerViewController: چیست، روش‌های یکپارچه‌سازی در iOS

AVPlayerViewController چیست؟

AVPlayerViewController یک کامپوننت از فریم‌ورک AVKit است که یک رابط آماده برای پخش ویدیو در برنامه‌های Apple فراهم می‌کند. این کامپوننت توسعه‌دهنده را از نیاز به ایجاد یک پخش‌کننده سفارشی از صفر بی‌نیاز می‌کند و عناصر کنترل استاندارد را ارائه می‌دهد: پخش/مکث، عقب‌کشیدن، تنظیم صدا و حالت تمام‌صفحه.

برخلاف AVPlayerLayer سطح پایین که نیاز به ساخت دستی UI دارد، AVPlayerViewController به طور کامل چرخه حیات پخش‌کننده را مدیریت می‌کند. کنترلر به طور خودکار چرخش صفحه را پردازش می‌کند، با Safe Area در iPhone دارای ناچ تطبیق می‌یابد و از چندوظیفه‌ای در iPad پشتیبانی می‌کند.

بر اساس Apple Documentation (2026)، AVPlayerViewController با AVPlayer و AVQueuePlayer سازگار است و امکان پخش هم فایل‌های تکی و هم لیست‌های پخش را فراهم می‌کند. URLهای ذخیره‌سازی محلی، جریان‌های شبکه HLS و محتوای رمزگذاری‌شده FairPlay پشتیبانی می‌شوند.

تاریخچه و نسخه‌های AVPlayerViewController

این کامپوننت در iOS 8 همراه با AVKit به عنوان جایگزینی برای MPMoviePlayerController منسوخ ظاهر شد. در iOS 11 پشتیبانی از Picture in Picture و نمایش زیرنویس‌ها اضافه شد. در iOS 14 کنترلر یک نوار کنترل قابل شخصی‌سازی از طریق دلیگیت AVPlayerViewControllerDelegate دریافت کرد. از iOS 16، پشتیبانی از جایگزینی دینامیک فایل رسانه بدون بازسازی پخش‌کننده فراهم شد.

AVPlayerViewController مدرن برای نمایشگرهای ProMotion بهینه شده است — نرخ فریم ویدیو به طور خودکار با نرخ تازه‌سازی صفحه همگام می‌شود. در tvOS کامپوننت با رابط فوکوس Siri Remote و در macOS با حالت پنجره‌ای QuickTime Player تطبیق می‌یابد.

AVPlayerViewController چگونه کار می‌کند

در قلب کنترلر، پیوند AVPlayer و AVPlayerItem قرار دارد. AVPlayer یک شیء پخش است که خط زمانی، سرعت و وضعیت را مدیریت می‌کند. AVPlayerItem یک پوشش بر روی فایل رسانه مشخص است که شامل فراداده‌ها، ترک‌ها و اطلاعات بارگذاری است.

در زمان مقداردهی اولیه، AVPlayerViewController یک ارجاع به AVPlayer دریافت می‌کند و به طور خودکار AVPlayerLayer را برای نمایش ویدیو ایجاد می‌کند. کنترلر در اعلان‌های KVO AVPlayer درباره تغییر وضعیت readyToPlay، خطاهای بارگذاری و پایان پخش مشترک می‌شود.

عناصر کنترل (نوار حمل‌ونقل) با ضربه زدن روی صفحه نمایش داده می‌شوند. در iOS 15+ آنها از سفارشی‌سازی از طریق AVPlayerViewControllerCustomizationDelegate پشتیبانی می‌کنند و امکان مخفی کردن یا جایگزینی دکمه‌های استاندارد را می‌دهند.

چرخه حیات کنترلر

پس از ایجاد کنترلر و اختصاص AVPlayer، متد viewDidLoad فراخوانی می‌شود که آماده‌سازی جریان ویدیو را آغاز می‌کند. وقتی AVPlayerItem به وضعیت AVPlayerItemStatusReadyToPlay می‌رود، پخش‌کننده برای نمایش فریم‌ها آماده است. با فراخوانی متد play()، رمزگشایی جریان ویدیو از طریق Video Toolbox آغاز می‌شود.

هنگام خروج از صفحه، کنترلر به طور خودکار پخش را متوقف می‌کند و منابع رمزگشا را آزاد می‌کند. در iOS 13+ برای حفظ پخش هنگام کوچک‌سازی برنامه، پیکربندی Background Modes و Audio Session مورد نیاز است. به گفته WWDC 2024، توصیه می‌شود از AVPlayerPlaybackCoordinator برای همگام‌سازی با مرکز رسانه iOS استفاده کنید.

قابلیت‌های اصلی AVPlayerViewController

این کامپوننت مجموعه غنی از قابلیت‌ها را به صورت آماده فراهم می‌کند که آن را برای اکثر پروژه‌ها جذاب می‌سازد. در زیر قابلیت‌های کلیدی که به کد اضافی نیاز ندارند آورده شده است.

• نوار حمل‌ونقل با پخش/مکث، عقب‌کشیدن ۱۵ ثانیه، تنظیم صدا و لغزنده پیشرفت.
• پشتیبانی از زیرنویس — نمایش خودکار زیرنویس‌های داخلی و خارجی در فرمت‌های VTT، SRT و iTunes Timed Text.
• AirPlay — امکان پخش ویدیو در Apple TV و سایر دستگاه‌های سازگار با AirPlay.
• Picture in Picture — پخش در پنجره شناور با فشار دادن دکمه مخصوص (در iPad و iPhone با iOS 14+).
• حالت تمام‌صفحه — تغییر خودکار هنگام چرخش دستگاه و ضربه زدن روی دکمه بزرگنمایی.
• تغییر سرعت — کنترل داخلی انتخاب سرعت پخش (0.5x، 1.0x، 1.5x، 2.0x).
• محتوای محافظت‌شده — پشتیبانی بومی از FairPlay Streaming برای محتوای HLS با DRM.

نوار حمل‌ونقل AVPlayerViewController

نوار حمل‌ونقل بخش پایینی رابط است که دکمه‌های اصلی کنترل را شامل می‌شود. به طور پیش‌فرض، نوار پس از ۳ ثانیه عدم فعالیت کاربر مخفی می‌شود و با ضربه ظاهر می‌شود. در iOS 16+ از طریق دلیگیت می‌توان visibility عناصر جداگانه را مدیریت کرد.

در حالت اشکال‌زدایی، نوار حمل‌ونقل را می‌توان از طریق ویژگی AVPlayerViewController.requiresLinearPlayback به طور اجباری نمایش داد که همچنین امکان مکث ویدیو را مسدود می‌کند. این برای درج تبلیغات و محتوای آموزشی مفید است.

یکپارچه‌سازی AVPlayerViewController در پروژه

یکپارچه‌سازی پایه کنترلر بیش از ۱۰ خط کد نمی‌گیرد. ابتدا باید یک نمونه AVPlayer با URL فایل رسانه ایجاد کنید، سپس آن را به AVPlayerViewController منتقل کنید و کنترلر را روی صفحه نمایش دهید.

ایجاد پخش‌کننده پایه در 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()
}

پس از فراخوانی present، کنترلر در تمام‌صفحه نمایش داده می‌شود. ویدیو شروع به بارگذاری از شبکه می‌کند و به محض اینکه بافر به آستانه readyToPlay رسید، پس از فراخوانی play() به طور خودکار پخش آغاز می‌شود.

پیکربندی AVPlayerItem برای مدیریت پیشرفته

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

let metadata = AVMutableMetadataItem()
metadata.key = AVMetadataKey.commonKeyTitle
metadata.value = "ویدیوی من"
item.addMetadata(metadata)

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

استفاده از AVPlayerItem کنترل بر فراداده‌ها، کدهای زمانی، انتخاب ترک‌های صوتی و زیرنویس‌ها را فراهم می‌کند. از طریق AVPlayerItem می‌توان پیشرفت بارگذاری، بافر کردن و خطاهای شبکه را با KVO روی ویژگی status مشاهده کرد.

تنظیم عناصر کنترل

از iOS 11، توسعه‌دهنده می‌تواند نوار حمل‌ونقل را از طریق پروتکل AVPlayerViewControllerDelegate سفارشی کند. متد playerViewController(_:willBeginFullScreenPresentationWithAnimationCoordinator:) قبل از ورود به حالت تمام‌صفحه فراخوانی می‌شود و امکان آماده‌سازی UI را فراهم می‌کند.

برای مخفی کردن دکمه‌های جداگانه از ویژگی AVPlayerViewController.showsPlaybackControls استفاده می‌شود. اگر آن را روی false تنظیم کنید، نوار حمل‌ونقل کاملاً ناپدید می‌شود و فقط جریان ویدیو باقی می‌ماند. برای عناصر overlay سفارشی مفید است.

سفارشی‌سازی با استفاده از دلیگیت

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
    ) {
        // دکمه overlay اضافه کن
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("زبان زیرنویس جدید انتخاب شد")
    }
}

دلیگیت امکان رهگیری رویدادهای تغییر زیرنویس، ورود و خروج از حالت تمام‌صفحه و همچنین شروع و پایان Picture in Picture را فراهم می‌کند. در WWDC 2024، Apple استفاده از دلیگیت را برای تحلیل توصیه کرد — ثبت هر انتقال تا ۱۰۰ میلی‌ثانیه.

کار با زیرنویس‌ها و ترک‌های صوتی

AVPlayerViewController به طور خودکار تمام زیرنویس‌های موجود و ترک‌های صوتی را که در فایل رسانه جاسازی شده یا در مانیفست HLS مشخص شده‌اند نمایش می‌دهد. کاربر می‌تواند آنها را از طریق منویی که با ضربه روی آیکون زیرنویس در نوار حمل‌ونقل ظاهر می‌شود تغییر دهد.

برای جریان‌های HLS، مانیفست M3U8 شامل فهرست گزینه‌های زبانی موجود است. AVPlayer بخش‌های زیرنویس مربوطه را در قالب WebVTT بارگذاری می‌کند و آنها را برای رندر از طریق AVPlayerLayer منتقل می‌کند. در iOS 16+ پشتیبانی از سبک‌دهی زیرنویس از طریق AVTextStyleRule اضافه شد.

انتخاب برنامه‌ریزی شده ترک صوتی

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)
        }
    }
}

متد selectAudioTrack در میان گزینه‌های صوتی گروه audiable به دنبال گزینه‌ای می‌گردد که extendedLanguageTag آن با کد زبان مورد نظر مطابقت دارد. این امکان پیاده‌سازی قابلیت «صداگذاری اصلی» را در برنامه‌های با محتوای چندزبانه فراهم می‌کند.

Picture in Picture در iPad

حالت Picture in Picture (PiP) امکان نمایش ویدیو در یک پنجره شناور روی سایر برنامه‌ها را فراهم می‌کند. در iPad این قابلیت از iOS 9 و در iPhone از iOS 14 در دسترس است. AVPlayerViewController با اشتراک UIBackgroundModes به طور خودکار دکمه PiP را به نوار حمل‌ونقل اضافه می‌کند.

برای فعال‌سازی PiP باید در Info.plist کلید UIBackgroundModes با مقدار audio و airplay اضافه شود. پس از آن، دکمه PiP در کنترلر ظاهر می‌شود که با فشار دادن آن، ویدیو به یک پنجره شناور به اندازه 192x108 نقطه جمع می‌شود.

رویدادهای PiP از طریق دلیگیت پردازش می‌شوند: playerViewController(_:willStartPictureInPictureFromFullScreen:) و playerViewController(_:didStopPictureInPicture:). بر اساس Apple HIG، حداقل اندازه پنجره PiP باید حداقل 120x68 نقطه برای حفظ خوانایی محتوا باشد.