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

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

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

يمكن إنشاء عنصر وسائط يتألف فقط من معرّف الموارد المنتظم للبث باستخدام 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. إذا كان عنوان URL لعنصر الوسائط التكيُّفية هذا ينتهي بإضافةملف عادية، يتم إنشاء مصدر الوسائط المقابل تلقائيًا. إذا كان ملف تعريف الارتباط يحتوي على إضافة غير عادية أو لم يكن يحتوي على أي إضافة على الإطلاق، يمكن ضبط نوع 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 ، وجميع السمات الأخرى اختيارية.

مثال على الإعداد لتشغيل عنصر محمي بأدوات إدارة الحقوق الرقمية (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 مُعدًّا وفقًا لذلك في المشغّل.