HLS

يتوافق ExoPlayer مع HLS باستخدام تنسيقات حاويات متعددة. يجب أيضًا أن تكون تنسيقات عيّنات الصوت والفيديو المضمّنة متوافقة (اطّلِع على قسم تنسيقات العيّنات لمعرفة التفاصيل). ننصحك بشدة بصنّاع المحتوى الذين يستخدمون بروتوكول HLS بإنشاء عمليات بث HLS عالية الجودة، كما هو موضّح في هذا المنشور على المدوّنة.

الميزة معلومات معتمَدة التعليقات
الحاويات
‫MPEG-TS نعم
‫FMP4/CMAF نعم
ADTS (AAC) نعم
MP3 نعم
الترجمة والشرح / الترجمة
‫CEA-608 نعم
‫CEA-708 نعم
WebVTT نعم
البيانات الوصفية
رقم التعريف 3 نعم
SCTE-35 لا
حماية المحتوى
‫AES-128 نعم
نموذج AES-128 لا
Widevine نعم الإصدار 19 من واجهة برمجة التطبيقات والإصدارات الأحدث ("مخطط cenc") و الإصدار 25 من واجهة برمجة التطبيقات والإصدارات الأحدث ("مخطط cbcs")
‫PlayReady SL2000 نعم Android TV فقط
التحكّم في الخادم
تعديلات دلتا نعم
حظر إعادة تحميل قائمة التشغيل نعم
حظر تحميل إشارات التحميل المُسبَق نعم باستثناء نطاقات البايت التي تتضمن أطوالًا غير محدّدة
إدراج الإعلانات
إدراج الإعلانات بتوجيه من الخادم (الإعلانات البينية) جزئيًا الفيديوهات عند الطلب فقط مع X-ASSET-URI ستتم إضافة أحداث البث المباشر وX-ASSET-LIST لاحقًا.
إعلانات IMA من جهة العميل وخادم نعم دليل إدراج الإعلانات
التشغيل المباشر
التشغيل المباشر العادي نعم
البث المباشر وفق بروتوكول HTTP (HLS) بوقت استجابة منخفض (Apple) نعم
البث المباشر وفق بروتوكول HTTP (HLS) بوقت استجابة منخفض (المنتدى) لا
بيانات العميل المشترك في الوسائط CMCD نعم دليل دمج CMCD

استخدام MediaItem

لتشغيل بث مباشر وفق بروتوكول HLS، عليك الاعتماد على وحدة HLS.

Kotlin

implementation("androidx.media3:media3-exoplayer-hls:1.6.0")

رائع

implementation "androidx.media3:media3-exoplayer-hls:1.6.0"

يمكنك بعد ذلك إنشاء MediaItem لمعرّف الموارد المنتظم لقائمة تشغيل HLS ونقله إلى المشغّل.

Kotlin

// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri(hlsUri))
// Prepare the player.
player.prepare()

Java

// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri(hlsUri));
// Prepare the player.
player.prepare();

إذا لم ينتهِ عنوان URL بـ .m3u8، يمكنك تمرير MimeTypes.APPLICATION_M3U8 إلى setMimeType من MediaItem.Builder للإشارة صراحةً إلى نوع المحتوى.

قد يشير معرّف الموارد المنتظم لملف الوسائط إلى قائمة تشغيل وسائط أو قائمة تشغيل متعددة الأشكال. إذا كان معرّف الموارد المطلق يشير إلى قائمة تشغيل متعددة الصيغ تُعرِض علامات #EXT-X-STREAM-INF متعددة، سيتكيّف ExoPlayer تلقائيًا بين الصيغ، مع الأخذ في الاعتبار كلاً من معدل نقل البيانات المتاح وإمكانات الجهاز.

استخدام HlsMediaSource

لمزيد من خيارات التخصيص، يمكنك إنشاء HlsMediaSource ونقله مباشرةً إلى المشغّل بدلاً من MediaItem.

Kotlin

// Create a data source factory.
val dataSourceFactory: DataSource.Factory = DefaultHttpDataSource.Factory()
// Create a HLS media source pointing to a playlist uri.
val hlsMediaSource =
  HlsMediaSource.Factory(dataSourceFactory).createMediaSource(MediaItem.fromUri(hlsUri))
// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the HLS media source as the playlist with a single media item.
player.setMediaSource(hlsMediaSource)
// Prepare the player.
player.prepare()

Java

// Create a data source factory.
DataSource.Factory dataSourceFactory = new DefaultHttpDataSource.Factory();
// Create a HLS media source pointing to a playlist uri.
HlsMediaSource hlsMediaSource =
    new HlsMediaSource.Factory(dataSourceFactory).createMediaSource(MediaItem.fromUri(hlsUri));
// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the HLS media source as the playlist with a single media item.
player.setMediaSource(hlsMediaSource);
// Prepare the player.
player.prepare();

الوصول إلى البيان

يمكنك استرداد البيان الحالي من خلال الاتصال برقم Player.getCurrentManifest. بالنسبة إلى HLS، يجب تحويل العنصر المعروض إلى HlsManifest. يتم أيضًا استدعاء دالّة ردّ الاتصال onTimelineChanged لـ Player.Listener عند تحميل البيان. سيتم إجراء ذلك مرة واحدة للمحتوى المسجّل و قد يتم إجراء ذلك عدة مرات للمحتوى المباشر. يوضّح المقتطف التالي من الرمز البرمجي كيف يمكن للتطبيق تنفيذ إجراء معيّن عند تحميل البيان.

Kotlin

player.addListener(
  object : Player.Listener {
    override fun onTimelineChanged(timeline: Timeline, @TimelineChangeReason reason: Int) {
      val manifest = player.currentManifest
      if (manifest is HlsManifest) {
        // Do something with the manifest.
      }
    }
  }
)

Java

player.addListener(
    new Player.Listener() {
      @Override
      public void onTimelineChanged(
          Timeline timeline, @Player.TimelineChangeReason int reason) {
        Object manifest = player.getCurrentManifest();
        if (manifest != null) {
          HlsManifest hlsManifest = (HlsManifest) manifest;
          // Do something with the manifest.
        }
      }
    });

تشغيل أحداث البث المباشر وفق بروتوكول HTTP ‏(HLS) مع الإعلانات البينية

تحدِّد مواصفات HLS إعلانات HLS البينية التي يمكن استخدامها لتضمين معلومات الإعلانات البينية في قائمة تشغيل وسائط. يتجاهل ExoPlayer تلقائيًا الإعلانات البينية هذه. يمكن إضافة الدعم باستخدام HlsInterstitialsAdsLoader. لن تتمكّن من استخدام كل ميزات المواصفات من البداية. إذا لم يكن بثك متوافقًا مع الميزة، يُرجى إعلامنا بذلك من خلال الإبلاغ عن مشكلة على GitHub وإرسال عنوان URI لبثك كي نتمكّن من إضافة البث إلى الميزة.

استخدام MediaItem مع واجهة برمجة التطبيقات playlist API

إنّ الطريقة الأنسب لتشغيل أحداث البث المباشر وفق بروتوكول HTTP (HLS) مع إعلانات بينية هي إنشاء مثيل ExoPlayer باستخدام HlsInterstitialsAdsLoader.AdsMediaSourceFactory. يتيح ذلك استخدام واجهة برمجة التطبيقات لقوائم التشغيل المستندة إلى MediaItem في واجهة Player لتشغيل الإعلانات البينية بتنسيق HLS.

يمكن إدخال MediaSource.Factory من ExoPlayer في أداة الإنشاء عند إنشاء مثيل المشغّل:

Kotlin

hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context)
// Create a MediaSource.Factory for HLS streams with interstitials.
var hlsMediaSourceFactory =
  HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
    hlsInterstitialsAdsLoader,
    playerView,
    DefaultMediaSourceFactory(context),
  )

// Build player with interstitials media source factory
player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(hlsMediaSourceFactory)
    .build()

// Set the player on the ads loader.
hlsInterstitialsAdsLoader.setPlayer(player)
playerView.setPlayer(player)

Java

hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);
// Create a MediaSource.Factory for HLS streams with interstitials.
MediaSource.Factory hlsMediaSourceFactory =
      new HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
          hlsInterstitialsAdsLoader, playerView, new DefaultMediaSourceFactory(context));

// Build player with interstitials media source factory
player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(hlsMediaSourceFactory)
        .build();

// Set the player on the ads loader.
hlsInterstitialsAdsLoader.setPlayer(player);
playerView.setPlayer(player);

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

Kotlin

player.setMediaItem(
  MediaItem.Builder()
    .setUri("https://www.example.com/media.m3u8")
    .setAdsConfiguration(
      AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
        .setAdsId("ad-tag-0") // must be unique within playlist
        .build())
    .build())

player.prepare();
player.play();

Java

player.setMediaItem(
    new MediaItem.Builder()
        .setUri("https://www.example.com/media.m3u8")
        .setAdsConfiguration(
            new AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
                .setAdsId("ad-tag-0") // must be unique within playlist
                .build())
        .build());
player.prepare();
player.play();

استخدام واجهة برمجة التطبيقات المستندة إلى مصدر الوسائط

بدلاً من ذلك، يمكن إنشاء مثيل ExoPlayer بدون إلغاء منشأ مصدر الوسائط التلقائي. لإتاحة عرض الإعلانات البينية، يمكن للتطبيق استخدام HlsInterstitialsAdsLoader.AdsMediaSourceFactory مباشرةً لإنشاء MediaSource وتقديمه إلى ExoPlayer باستخدام واجهة برمجة التطبيقات للقائمة الموسيقية المستندة إلى مصدر الوسائط:

Kotlin

hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context)
// Create a MediaSource.Factory for HLS streams with interstitials.
var hlsMediaSourceFactory =
  HlsInterstitialsAdsLoader.AdsMediaSourceFactory(hlsInterstitialsAdsLoader, playerView, context)

// Build player with default media source factory.
player = new ExoPlayer.Builder(context).build();

// Create an media source from an HLS media item with ads configuration.
val mediaSource =
  hlsMediaSourceFactory.createMediaSource(
    MediaItem.Builder()
      .setUri("https://www.example.com/media.m3u8")
      .setAdsConfiguration(
        MediaItem.AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
          .setAdsId("ad-tag-0")
          .build()
      )
      .build()
  )

// Set the media source on the player.
player.setMediaSource(mediaSource)
player.prepare()
player.play()

Java

HlsInterstitialsAdsLoader hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);
// Create a MediaSource.Factory for HLS streams with interstitials.
MediaSource.Factory hlsMediaSourceFactory =
    new HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
      hlsInterstitialsAdsLoader, playerView, context);

// Build player with default media source factory.
player = new ExoPlayer.Builder(context).build();

// Create an media source from an HLS media item with ads configuration.
MediaSource mediaSource =
    hlsMediaSourceFactory.createMediaSource(
      new MediaItem.Builder()
        .setUri("https://www.example.com/media.m3u8")
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
                .setAdsId("ad-tag-0")
                .build())
        .build());

// Set the media source on the player.
exoPlayer.setMediaSource(mediaSource);
exoPlayer.prepare();
exoPlayer.play();

الاستماع إلى أحداث الإعلانات

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

Kotlin

class AdsLoaderListener : HlsInterstitialsAdsLoader.Listener {

  override fun onStart(mediaItem: MediaItem, adsId: Any, adViewProvider: AdViewProvider) {
    // Do something when HLS media item with interstitials is started.
  }

  override fun onMetadata(
    mediaItem: MediaItem,
    adsId: Any,
    adGroupIndex: Int,
    adIndexInAdGroup: Int,
    metadata: Metadata,
  ) {
    // Do something with metadata that is emitted by the ad media source of the given ad.
  }

  override fun onAdCompleted(
    mediaItem: MediaItem,
    adsId: Any,
    adGroupIndex: Int,
    adIndexInAdGroup: Int,
  ) {
    // Do something when ad completed playback.
  }

  // ... See JavaDoc for further callbacks of HlsInterstitialsAdsLoader.Listener.

  override fun onStop(mediaItem: MediaItem, adsId: Any, adPlaybackState: AdPlaybackState) {
    // Do something with the resulting ad playback state when stopped.
  }
}

Java

private class AdsLoaderListener
    implements HlsInterstitialsAdsLoader.Listener {

  // implement HlsInterstitialsAdsLoader.Listener

  @Override
  public void onStart(MediaItem mediaItem, Object adsId, AdViewProvider adViewProvider) {
    // Do something when HLS media item with interstitials is started.
  }

  @Override
  public void onMetadata(
      MediaItem mediaItem,
      Object adsId,
      int adGroupIndex,
      int adIndexInAdGroup,
      Metadata metadata) {
    // Do something with metadata that is emitted by the ad media source of the given ad.
  }

  @Override
  public void onAdCompleted(
      MediaItem mediaItem, Object adsId, int adGroupIndex, int adIndexInAdGroup) {
    // Do something when ad completed playback.
  }

  // ... See JavaDoc for further callbacks of HlsInterstitialsAdsLoader.Listener.

  @Override
  public void onStop(MediaItem mediaItem, Object adsId, AdPlaybackState adPlaybackState) {
    // Do something with the resulting ad playback state when stopped.
  }
}

يمكن بعد ذلك إضافة المستمع إلى أداة تحميل الإعلانات:

Kotlin

var listener  = AdsLoaderListener();
// Add the listener to the ads loader to receive ad loader events.
hlsInterstitialsAdsLoader.addListener(listener);

Java

AdsLoaderListener listener = new AdsLoaderListener();
// Add the listener to the ads loader to receive ad loader events.
hlsInterstitialsAdsLoader.addListener(listener);

مراحل HlsInterstitialsAdsLoader

يمكن إعادة استخدام مثيل HlsInterstitialsAdsLoader أو HlsInterstitialsAdsLoader.AdsMediaSourceFactory لعدة مثيلات مشغّل وسائط تُنشئ مصادر وسائط متعددة يجب تحميل الإعلانات لها.

يمكن إنشاء مثيل مثلاً في طريقة onCreate من Activity ثم إعادة استخدامه لمثيلّات متعددة من اللاعبين. ويعمل هذا الإجراء طالما أنّه قيد الاستخدام من خلال مثيل مشغّل واحد في الوقت نفسه. يكون ذلك مفيدًا في حالة الاستخدام المشترَكة عند نقل التطبيق إلى الخلفية، ويتم إتلاف مثيل المشغّل ثم يتم إنشاء مثيل جديد عند نقل التطبيق إلى المقدّمة مجددًا.

Kotlin

// Create the ads loader instance (for example onCreate).
hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context);

// Build a player and set it on the ads loader (for example onStart).
player = ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Build another player and set it on the ads loader (for example onStart).
player = ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Release the ads loader when not used anymore  (for example onDestroy).
hlsInterstitialsAdsLoader.release();

Java

// Create the ads loader instance (for example onCreate).
hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);

// Build a player and set it on the ads loader (for example onStart).
player = new ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Build another player and set it on the ads loader (for example onStart).
player = new ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Release the ads loader when not used anymore  (for example onDestroy).
hlsInterstitialsAdsLoader.release();

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

تخصيص عملية التشغيل

يقدّم ExoPlayer طرقًا متعدّدة لتخصيص تجربة التشغيل وفقًا لاحتياجات تطبيقك. اطّلِع على صفحة التخصيص للحصول على أمثلة.

إيقاف ميزة "الإعداد بدون أجزاء"

سيستخدم ExoPlayer الإعداد بدون أجزاء تلقائيًا. وهذا يعني أنّ ExoPlayer لن يستخدم سوى المعلومات الواردة في قائمة التشغيل التي تتضمّن صيغًا متعددة لإعداد البث، وذلك إذا كانت علامات #EXT-X-STREAM-INF تحتوي على السمة CODECS.

قد تحتاج إلى إيقاف هذه الميزة إذا كانت مقاطع الوسائط تحتوي على مقاطع ملف ملتحم لترجمة الشاشة لم يتم الإعلان عنها في قائمة التشغيل المتعدّدة الصيغ باستخدام علامة #EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS. بخلاف ذلك، لن يتم رصد مقاطع الترجمة والشرح هذه وتشغيلها. يمكنك إيقاف ميزة "الإعداد بدون أجزاء" في HlsMediaSource.Factory كما هو موضّح في المقتطف التالي. يُرجى العِلم أنّه سيزيد ذلك من وقت بدء التشغيل لأنّ ExoPlayer يحتاج إلى تنزيل مقطع وسائط لتحديد هذه المقاطع الصوتية الإضافية، ومن الأفضل الإفصاح عن المقاطع الصوتية التي تتضمّن ترجمة وشرحًا في قائمة التشغيل المتعدّدة الصيغ بدلاً من ذلك.

Kotlin

val hlsMediaSource =
  HlsMediaSource.Factory(dataSourceFactory)
    .setAllowChunklessPreparation(false)
    .createMediaSource(MediaItem.fromUri(hlsUri))

Java

HlsMediaSource hlsMediaSource =
    new HlsMediaSource.Factory(dataSourceFactory)
        .setAllowChunklessPreparation(false)
        .createMediaSource(MediaItem.fromUri(hlsUri));

إنشاء محتوى HLS عالي الجودة

للاستفادة إلى أقصى حد من ExoPlayer، هناك إرشادات معيّنة يمكنك اتّباعها لتحسين محتوى HLS. يمكنك الاطّلاع على المشاركة على Medium حول تشغيل HLS في ExoPlayer للحصول على شرح كامل. في ما يلي النقاط الرئيسية:

  • استخدِم مدّات دقيقة للمقاطع.
  • استخدِم بثًا متّصلاً للوسائط، وتجنَّب التغييرات في بنية الوسائط على مستوى المقاطع.
  • استخدِم العلامة #EXT-X-INDEPENDENT-SEGMENTS.
  • يُفضَّل استخدام أحداث البث التي تم فك ترميزها، بدلاً من الملفات التي تتضمّن الفيديو والصوت معًا.
  • أدرِج كل المعلومات التي يمكنك تضمينها في قائمة التشغيل التي تتضمّن خيارات متعددة.

تنطبق الإرشادات التالية على أحداث البث المباشر تحديدًا:

  • استخدِم العلامة #EXT-X-PROGRAM-DATE-TIME.
  • استخدِم العلامة #EXT-X-DISCONTINUITY-SEQUENCE.
  • يجب توفير فترة طويلة للبث المباشر. من الجيد أن تبلغ مدّة المراجعة دقيقة واحدة أو أكثر.