عناصر الوسائط

تستند واجهة برمجة التطبيقات لقوائم التشغيل إلى MediaItem مثيل، ويمكن إنشاؤها بسهولة باستخدام MediaItem.Builder. داخل المشغّل، يتم تحويل MediaItem إلى MediaSource قابل للتشغيل بواسطة MediaSource.Factory. بدون إعدادات مخصّصة، يتم إجراء عملية التحويل هذه بواسطة DefaultMediaSourceFactory، وهو قادر على إنشاء مصادر وسائط معقّدة تتوافق مع خصائص عنصر الوسائط. في ما يلي بعض الخصائص التي يمكن ضبطها على عناصر الوسائط.

ملفات الوسائط البسيطة

يمكن إنشاء عنصر وسائط يتألف فقط من معرّف الموارد المنتظم (URI) للبث باستخدام طريقة fromUri المريحة:

Kotlin

val mediaItem = MediaItem.fromUri(videoUri)
MediaItems.kt

Java

MediaItem mediaItem = MediaItem.fromUri(videoUri);
MediaItems.java

في جميع الحالات الأخرى، يمكن استخدام MediaItem.Builder. في المثال التالي، تم إنشاء عنصر وسائط باستخدام معرّف وبعض البيانات الوصفية المرفقة:

Kotlin

val mediaItem =
  MediaItem.Builder().setMediaId(mediaId).setTag(myAppData).setUri(videoUri).build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder().setMediaId(mediaId).setTag(myAppData).setUri(videoUri).build();
MediaItems.java

يمكن أن يكون إرفاق البيانات الوصفية مفيدًا في تعديل واجهة المستخدم في تطبيقك عند حدوث انتقالات في قائمة التشغيل.

صور

يتطلّب تشغيل الصور تحديد مدة في عنصر الوسائط لتحديد المدة التي يجب أن تظهر فيها الصورة أثناء التشغيل. يمكنك الاطّلاع على صفحة دليل الصور للحصول على مزيد من المعلومات حول الصور المتحركة ومكتبات تحميل الصور (مثل Glide).

Kotlin

val mediaItem = MediaItem.Builder().setUri(imageUri).setImageDurationMs(3000).build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder().setUri(imageUri).setImageDurationMs(3_000).build();
MediaItems.java

امتدادات الملفات غير العادية للوسائط التكيّفية

يوفّر ExoPlayer مصادر وسائط متكيّفة لبروتوكولات DASH وHLS وSmoothStreaming. إذا كان معرّف الموارد الموحّد (URI) لعنصر وسائط متكيّفة ينتهي بامتداد ملف عادي، يتم إنشاء مصدر الوسائط المقابل تلقائيًا. إذا كان معرّف الموارد الموحّد (URI) يتضمّن امتدادًا غير عادي أو لا يتضمّن أي امتداد، يمكن ضبط نوع MIME بشكل صريح للإشارة إلى نوع عنصر الوسائط:

Kotlin

val mediaItem =
  MediaItem.Builder().setUri(hlsUri).setMimeType(MimeTypes.APPLICATION_M3U8).build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder().setUri(hlsUri).setMimeType(MimeTypes.APPLICATION_M3U8).build();
MediaItems.java

بالنسبة إلى بث الوسائط التقدّمي، لا يُشترط توفّر نوع MIME.

المحتوى المحمي

بالنسبة إلى المحتوى المحمي، يجب ضبط خصائص إدارة الحقوق الرقمية لعنصر الوسائط. يجب توفير المعرّف الفريد العالمي (UUID)، وجميع الخصائص الأخرى اختيارية.

في ما يلي مثال على إعدادات تشغيل محتوى محمي باستخدام Widevine DRM حيث لا يتوفّر معرّف الموارد المنتظم للترخيص مباشرةً في الوسائط (مثل قائمة تشغيل DASH) وتكون هناك حاجة إلى جلسات متعددة (مثل بسبب تدوير المفاتيح):

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setDrmConfiguration(
      MediaItem.DrmConfiguration.Builder(C.WIDEVINE_UUID)
        .setLicenseUri(licenseUri)
        .setMultiSession(true)
        .setLicenseRequestHeaders(httpRequestHeaders)
        .build()
    )
    .build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setDrmConfiguration(
            new MediaItem.DrmConfiguration.Builder(C.WIDEVINE_UUID)
                .setLicenseUri(licenseUri)
                .setMultiSession(true)
                .setLicenseRequestHeaders(httpRequestHeaders)
                .build())
        .build();
MediaItems.java

داخل مشغّل الفيديو، ستنقل السمة DefaultMediaSourceFactory هذه السمات إلى السمة DrmSessionManagerProvider للحصول على DrmSessionManager، ثم يتم إدخالها في السمة MediaSource التي تم إنشاؤها. يمكنك تخصيص سلوك إدارة الحقوق الرقمية (DRM) بشكل أكبر ليناسب احتياجاتك.

تحميل مسارات الترجمة

لتحميل مسارات الترجمة والشرح بشكل جانبي، يمكن إضافة مثيلات MediaItem.Subtitle عند إنشاء عنصر وسائط:

Kotlin

val subtitle =
  MediaItem.SubtitleConfiguration.Builder(subtitleUri)
    .setMimeType(mimeType) // The correct MIME type (required).
    .setLanguage(language) // The subtitle language (optional).
    .setSelectionFlags(selectionFlags) // Selection flags for the track (optional).
    .build()
val mediaItem =
  MediaItem.Builder().setUri(videoUri).setSubtitleConfigurations(listOf(subtitle)).build()
MediaItems.kt

Java

MediaItem.SubtitleConfiguration subtitle =
    new MediaItem.SubtitleConfiguration.Builder(subtitleUri)
        .setMimeType(mimeType) // The correct MIME type (required).
        .setLanguage(language) // The subtitle language (optional).
        .setSelectionFlags(selectionFlags) // Selection flags for the track (optional).
        .build();
MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setSubtitleConfigurations(ImmutableList.of(subtitle))
        .build();
MediaItems.java

داخليًا، سيستخدم DefaultMediaSourceFactory MergingMediaSource لدمج مصدر وسائط المحتوى مع SingleSampleMediaSource لكل مسار ترجمة وشرح. لا يتيح DefaultMediaSourceFactory تحميل ملفات الترجمة والشرح بشكل جانبي لبرنامج DASH المتعدد الفترات.

اقتطاع مقطع من بث وسائط

لقص المحتوى المشار إليه بواسطة عنصر وسائط، اضبط مواضع البدء والانتهاء المخصّصة:

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setClippingConfiguration(
      MediaItem.ClippingConfiguration.Builder()
        .setStartPositionMs(startPositionMs)
        .setEndPositionMs(endPositionMs)
        .build()
    )
    .build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setClippingConfiguration(
            new ClippingConfiguration.Builder()
                .setStartPositionMs(startPositionMs)
                .setEndPositionMs(endPositionMs)
                .build())
        .build();
MediaItems.java

داخليًا، ستستخدم DefaultMediaSourceFactory ClippingMediaSource لتضمين مصدر وسائط المحتوى. تتوفّر خصائص إضافية للقص. لمزيد من التفاصيل، يُرجى الاطّلاع على MediaItem.Builder Javadoc.

ملاحظة: عند اقتصاص بداية ملف فيديو، حاوِل محاذاة موضع البداية مع إطار رئيسي إذا أمكن ذلك. إذا لم يتطابق موضع البدء مع إطار رئيسي، سيحتاج المشغّل إلى فك ترميز البيانات من الإطار الرئيسي السابق إلى موضع البدء ثم تجاهلها قبل أن يتمكّن من بدء التشغيل. سيؤدي ذلك إلى حدوث تأخير قصير في بداية التشغيل، بما في ذلك عند انتقال المشغّل إلى تشغيل مصدر وسائط مقتطع كجزء من قائمة تشغيل أو بسبب التكرار.

إدراج الإعلانات

لإدراج الإعلانات، يجب ضبط السمة URI لعلامة الإعلان الخاصة بعنصر الوسائط:

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setAdsConfiguration(MediaItem.AdsConfiguration.Builder(adTagUri).build())
    .build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
        .build();
MediaItems.java

داخليًا، سيغلّف DefaultMediaSourceFactory مصدر وسائط المحتوى في AdsMediaSource لإدراج الإعلانات على النحو المحدّد في علامة الإعلان. ولكي ينجح ذلك، يجب أن يكون DefaultMediaSourceFactory الخاص باللاعب مضبوطًا بشكل صحيح.

المشكلة المعروفة رقم 185: لا تتوفّر الترجمة والشرح واقتصاص المحتوى وإدراج الإعلانات إلا إذا كنت تستخدم DefaultMediaSourceFactory.