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

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

عناصر الوسائط البسيطة

يمكنك إنشاء عنصر وسائط يتكون من عنوان URI للبث باستخدام طريقة ملائمة fromUri:

Kotlin

val mediaItem = MediaItem.fromUri(videoUri)

Java

MediaItem mediaItem = MediaItem.fromUri(videoUri);

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

Kotlin

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

Java

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

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

التعامل مع امتدادات الملفات غير العادية

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

Kotlin

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

Java

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

بالنسبة إلى مجموعات بث الوسائط التقدّمية، لا يجب استخدام نوع MIME.

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

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

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

Kotlin

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

Java

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

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

تحميل مقاطع الترجمة والشرح من مصدر غير معروف

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

Kotlin

val subtitle =
  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()

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();

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

اقتصاص بث وسائط

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

Kotlin

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

Java

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

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

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

إدراج إعلان

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

Kotlin

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

Java

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

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

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