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

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

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

يمكن إنشاء ملف وسائط يتألف من عنوان URL للبث فقط باستخدام 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();

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

صور

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

Kotlin

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

Java

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

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

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

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) مطلوبة، تكون جميع الخصائص الأخرى اختيارية.

مثال على الإعداد لتشغيل عنصر محمي بأدوات إدارة الحقوق الرقمية (DRM) من Widevine حيث لا يتوفّر معرّف الموارد المنتظم للترخيص مباشرةً في الوسائط (مثلاً في قائمة تشغيل 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 لمزيد من التفاصيل.

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

إدراج إعلان

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

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.