HLS

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

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

استخدام MediaItem

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

Kotlin

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

Groovy

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

يمكنك بعد ذلك إنشاء MediaItem لمعرّف الموارد المنتظم (URI) الخاص بقائمة تشغيل 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();

إذا لم ينتهِ معرّف URI الخاص بك باللاحقة .m3u8، يمكنك تمرير MimeTypes.APPLICATION_M3U8 إلى setMimeType من MediaItem.Builder للإشارة بوضوح إلى نوع المحتوى.

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

أسهل طريقة لتشغيل بث مباشر وفق بروتوكول 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);

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

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

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

اطّلِع على JavaDoc الخاص بـ HlsInterstitialsAdsLoader.Listener للحصول على المستندات التفصيلية الخاصة بجميع عمليات معاودة الاتصال المتاحة.

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

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