AVPlayerViewController: ما هو، طرق التكامل في iOS

ما هو AVPlayerViewController؟

AVPlayerViewController هو مكون من إطار عمل AVKit يوفر واجهة جاهزة لتشغيل الفيديو في تطبيقات Apple. يريح المطور من الحاجة إلى إنشاء مشغل مخصص من الصفر، حيث يقدم عناصر تحكم قياسية: تشغيل/إيقاف، تقديم سريع، ضبط الصوت ووضع ملء الشاشة.

على عكس AVPlayerLayer منخفض المستوى الذي يتطلب بناء واجهة مستخدم يدويًا، يدير AVPlayerViewController دورة حياة المشغل بالكامل. تتعامل وحدة التحكم تلقائيًا مع تدوير الشاشة، وتتكيف مع المنطقة الآمنة على أجهزة iPhone ذات النتوء، وتدعم تعدد المهام على iPad.

وفقًا لوثائق Apple (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+، للحفاظ على التشغيل عند تصغير التطبيق، يجب تكوين أوضاع الخلفية وجلسة الصوت. وفقًا لـ WWDC 2024، يوصى باستخدام AVPlayerPlaybackCoordinator للمزامنة مع مركز الوسائط في iOS.

الميزات الرئيسية لـ AVPlayerViewController

يوفر المكون مجموعة غنية من الميزات الجاهزة، مما يجعله جذابًا لمعظم المشاريع. فيما يلي القدرات الرئيسية التي لا تتطلب كودًا إضافيًا.

• شريط النقل مع تشغيل/إيقاف، تقدم 15 ثانية، التحكم في الصوت ومنزلق التقدم.
• دعم الترجمة — عرض تلقائي للترجمة المضمنة والخارجية بتنسيقات 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

شريط النقل هو الجزء السفلي من الواجهة الذي يحتوي على أزرار التحكم الرئيسية. افتراضيًا، يختفي الشريط بعد 3 ثوانٍ من عدم نشاط المستخدم ويظهر عند النقر. في iOS 16+، يمكن استخدام المفوض للتحكم في رؤية العناصر الفردية.

في وضع التصحيح، يمكن إجبار شريط النقل على الظهور باستخدام خاصية AVPlayerViewController.requiresLinearPlayback، والتي تمنع أيضًا إيقاف الفيديو مؤقتًا. هذا مفيد للإعلانات التجارية والمحتوى التعليمي.

دمج AVPlayerViewController في مشروعك

التكامل الأساسي لوحدة التحكم لا يستغرق أكثر من 10 أسطر من الكود. أولاً، قم بإنشاء مثيل 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:) قبل الدخول إلى وضع ملء الشاشة وتسمح بإعداد واجهة المستخدم.

لإخفاء الأزرار الفردية، استخدم خاصية AVPlayerViewController.showsPlaybackControls. إذا تم تعيينها على false، يختفي شريط النقل تمامًا، تاركًا فقط تدفق الفيديو. مفيد للعناصر المتراكبة المخصصة.

التخصيص باستخدام المفوض

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
    ) {
        // إضافة زر متراكب
    }

    func playerViewController(
        _ playerViewController: AVPlayerViewController,
        didUpdate legibleMediaSelection: AVMediaSelectionGroup
    ) {
        print("تم تحديد لغة ترجمة جديدة")
    }
}

يسمح المفوض باعتراض أحداث تغيير الترجمة، الدخول والخروج من وضع ملء الشاشة، وكذلك بدء وإنهاء Picture in Picture. في WWDC 2024، أوصت Apple باستخدام المفوض للتحليلات — تسجيل كل انتقال في غضون 100 مللي ثانية.

العمل مع الترجمة والمسارات الصوتية

يعرض 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 بين خيارات الصوت لمجموعة audible عن الخيار الذي يتوافق extendedLanguageTag مع رمز اللغة المطلوب. هذا يسمح بتنفيذ ميزة «الصوت الأصلي» في التطبيقات ذات المحتوى متعدد اللغات.

Picture in Picture على iPad

وضع Picture in Picture (PiP) يسمح بعرض الفيديو في نافذة عائمة فوق التطبيقات الأخرى. على iPad، هذه الميزة متاحة منذ iOS 9، على iPhone — منذ iOS 14. يضيف AVPlayerViewController تلقائيًا زر PiP إلى شريط النقل عند الاشتراك في UIBackgroundModes.

لتفعيل PiP، أضف مفتاح UIBackgroundModes بقيمتي audio و airplay إلى Info.plist. بعد ذلك، يظهر زر PiP في وحدة التحكم، والذي عند النقر عليه يقلص الفيديو إلى نافذة عائمة بحجم 192x108 نقطة.

تتم معالجة أحداث PiP من خلال المفوض: playerViewController(_:willStartPictureInPictureFromFullScreen:) و playerViewController(_:didStopPictureInPicture:). وفقًا لـ Apple HIG، يجب أن يكون الحد الأدنى لحجم نافذة PiP 120x68 نقطة على الأقل للحفاظ على إمكانية قراءة المحتوى.