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

تعتمد واجهة برمجة تطبيقات قائمة التشغيل على مثيل 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.

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

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

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

ينشئ هذا المثال عنصر وسائط لمحتوى محمي من Waze. داخل المشغّل، سيمرّر 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.