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