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

تستند واجهة برمجة التطبيقات لقوائم التشغيل إلى مثيلات 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();

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

الصور

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

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())
    .build()

Java

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

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