واجهة Player
هي أساس مكتبة ExoPlayer. تعرض السمة Player
وظائف تقليدية عالية المستوى لمشغّل الوسائط، مثل إمكانية التخزين المؤقت للوسائط والتشغيل والإيقاف المؤقت والترجيع. تم تصميم آلية التنفيذ التلقائية ExoPlayer
لوضع بعض الافتراضات حول (وبالتالي فرض بعض القيود على)
نوع الوسائط التي يتم تشغيلها وكيفية تخزينها ومكان تخزينها وكيفية
عرضها. وبدلاً من تنفيذ تحميل الوسائط وعرضها مباشرةً،
يفوّض ExoPlayer
تنفيذ هذا العمل إلى المكوّنات التي يتم إدخالها
عند إنشاء مشغّل أو عند نقل مصادر وسائط جديدة إلى المشغّل.
المكونات الشائعة لجميع عمليات تنفيذ ExoPlayer
هي:
MediaSource
التي تحدد الوسائط التي سيتم تشغيلها وتحمِّل الوسائط وتتمكن من قراءة الوسائط المحملة. يتم إنشاء مثيلMediaSource
منMediaItem
بواسطةMediaSource.Factory
داخل المشغّل. ويمكن أيضًا إرسالها مباشرةً إلى المشغّل باستخدام واجهة برمجة تطبيقات قائمة التشغيل المستندة إلى مصدر الوسائط.- تمثّل هذه السمة
MediaSource.Factory
التي تحوِّلMediaItem
إلىMediaSource
. يتم إدخالMediaSource.Factory
عند إنشاء المشغّل. Renderer
مثيل تعرض مكونات فردية من الوسائط. ويتم إدخالها عند إنشاء المشغّل.TrackSelector
الذي يختار المقاطع الصوتية المقدّمة منMediaSource
ليشاهدها كلRenderer
متاح. يتم إدخالTrackSelector
عند إنشاء المشغّل.LoadControl
يتحكّم في وقت التخزين المؤقت لمزيد من الوسائط فيMediaSource
، ومقدار التخزين المؤقت للوسائط. يتم إدخالLoadControl
عند إنشاء المشغّل.LivePlaybackSpeedControl
الذي يتحكم في سرعة التشغيل أثناء عمليات التشغيل المباشر للسماح للمشغّل بالاقتراب من إزاحة مباشرة تم ضبطها. يتم إدخالLivePlaybackSpeedControl
عند إنشاء المشغّل.
وينطبق مفهوم إدخال المكونات التي تنفّذ أجزاء من وظائف اللاعب في جميع أنحاء المكتبة. تعمل التطبيقات الافتراضية لبعض المكونات على تفويض العمل إلى المزيد من المكونات التي تم إدخالها. ويسمح هذا باستبدال العديد من المكونات الفرعية بشكل فردي بعمليات تنفيذ تمت تهيئتها بطريقة مخصصة.
تخصيص المشغّل
في ما يلي بعض الأمثلة الشائعة لتخصيص المشغل عن طريق إدخال المكونات.
إعداد حِزم الشبكة
لدينا صفحة حول تخصيص حزمة الشبكات التي يستخدمها ExoPlayer.
التخزين المؤقت للبيانات التي تم تحميلها من الشبكة
يمكنك الاطّلاع على الأدلّة المتعلّقة بالتخزين المؤقت المؤقت بشكل فوري وتنزيل الوسائط.
تخصيص تفاعلات الخادم
قد تريد بعض التطبيقات اعتراض طلبات HTTP واستجاباتها. قد تحتاج إلى إدخال عناوين طلبات مخصّصة وقراءة عناوين استجابة الخادم وتعديل معرّفات الموارد المنتظمة (URI) للطلبات وما إلى ذلك. على سبيل المثال، قد يجري تطبيقك مصادقة نفسه عن طريق إدخال رمز مميّز كعنوان عند طلب شرائح الوسائط.
يوضّح المثال التالي كيفية تنفيذ هذه السلوكيات من خلال
إدخال DataSource.Factory
مخصّص في DefaultMediaSourceFactory
:
Kotlin
val dataSourceFactory = DataSource.Factory { val dataSource = httpDataSourceFactory.createDataSource() // Set a custom authentication request header. dataSource.setRequestProperty("Header", "Value") dataSource } val player = ExoPlayer.Builder(context) .setMediaSourceFactory( DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory) ) .build()
Java
DataSource.Factory dataSourceFactory = () -> { HttpDataSource dataSource = httpDataSourceFactory.createDataSource(); // Set a custom authentication request header. dataSource.setRequestProperty("Header", "Value"); return dataSource; }; ExoPlayer player = new ExoPlayer.Builder(context) .setMediaSourceFactory( new DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory)) .build();
في مقتطف الرمز أعلاه، يشتمل HttpDataSource
الذي تم إدخاله على العنوان
"Header: Value"
في كل طلب HTTP. يكون هذا السلوك مثبّتًا لكل تفاعل مع مصدر HTTP.
ولتطبيق أسلوب أكثر دقة، يمكنك إدخال سلوك في الوقت المناسب باستخدام
ResolvingDataSource
. يعرض مقتطف الرمز التالي كيفية إدخال عناوين الطلبات قبل التفاعل مع مصدر HTTP مباشرةً:
Kotlin
val dataSourceFactory: DataSource.Factory = ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec -> // Provide just-in-time request headers. dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri)) }
Java
DataSource.Factory dataSourceFactory = new ResolvingDataSource.Factory( httpDataSourceFactory, // Provide just-in-time request headers. dataSpec -> dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri)));
يمكنك أيضًا استخدام ResolvingDataSource
لإجراء تعديلات في الوقت المناسب على معرّف الموارد المنتظم (URI)، كما هو موضّح في المقتطف التالي:
Kotlin
val dataSourceFactory: DataSource.Factory = ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec -> // Provide just-in-time URI resolution logic. dataSpec.withUri(resolveUri(dataSpec.uri)) }
Java
DataSource.Factory dataSourceFactory = new ResolvingDataSource.Factory( httpDataSourceFactory, // Provide just-in-time URI resolution logic. dataSpec -> dataSpec.withUri(resolveUri(dataSpec.uri)));
تخصيص معالجة الأخطاء
يسمح تنفيذ LoadErrorHandlingPolicy
مخصّص للتطبيقات بتخصيص طريقة تفاعل ExoPlayer مع أخطاء التحميل. على سبيل المثال، قد يرغب أحد التطبيقات في الفشل بسرعة بدلاً من إعادة المحاولة عدة مرات، أو قد يرغب في تخصيص منطق التراجع الذي يتحكّم في مدة انتظار اللاعب بين كل إعادة محاولة. يوضح المقتطف التالي كيفية
تنفيذ منطق تراجع مخصص:
Kotlin
val loadErrorHandlingPolicy: LoadErrorHandlingPolicy = object : DefaultLoadErrorHandlingPolicy() { override fun getRetryDelayMsFor(loadErrorInfo: LoadErrorInfo): Long { // Implement custom back-off logic here. return 0 } } val player = ExoPlayer.Builder(context) .setMediaSourceFactory( DefaultMediaSourceFactory(context).setLoadErrorHandlingPolicy(loadErrorHandlingPolicy) ) .build()
Java
LoadErrorHandlingPolicy loadErrorHandlingPolicy = new DefaultLoadErrorHandlingPolicy() { @Override public long getRetryDelayMsFor(LoadErrorInfo loadErrorInfo) { // Implement custom back-off logic here. return 0; } }; ExoPlayer player = new ExoPlayer.Builder(context) .setMediaSourceFactory( new DefaultMediaSourceFactory(context) .setLoadErrorHandlingPolicy(loadErrorHandlingPolicy)) .build();
تحتوي الوسيطة LoadErrorInfo
على مزيد من المعلومات حول تعذُّر التحميل
لتخصيص المنطق استنادًا إلى نوع الخطأ أو الطلب الذي تعذّر تنفيذه.
تخصيص علامات أداة استخراج البيانات
يمكن استخدام علامات أداة الاستخراج لتخصيص كيفية استخراج التنسيقات الفردية من الوسائط المتتالية. ويمكن ضبطها على "DefaultExtractorsFactory
"
التي يتم توفيرها لـ "DefaultMediaSourceFactory
". يمرر المثال التالي علامة تتيح البحث المستند إلى الفهرس لملفات بث MP3.
Kotlin
val extractorsFactory = DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING) val player = ExoPlayer.Builder(context) .setMediaSourceFactory(DefaultMediaSourceFactory(context, extractorsFactory)) .build()
Java
DefaultExtractorsFactory extractorsFactory = new DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING); ExoPlayer player = new ExoPlayer.Builder(context) .setMediaSourceFactory(new DefaultMediaSourceFactory(context, extractorsFactory)) .build();
تفعيل وضع التقديم/الترجيع باستمرار لمعدل نقل البيانات
في مجموعات البث بتنسيق MP3 وADTS وAMR، يمكنك تفعيل وضع التقديم/الترجيع بشكل تقريبي باستخدام افتراض معدّل نقل بيانات ثابت مع علامات FLAG_ENABLE_CONSTANT_BITRATE_SEEKING
.
يمكن إعداد هذه العلامات لأدوات استخراج البيانات الفردية باستخدام طرق DefaultExtractorsFactory.setXyzExtractorFlags
الفردية كما هو موضّح أعلاه. لتفعيل البحث عن معدل نقل البيانات المستمر في جميع أدوات استخراج البيانات المتوافقة معه، استخدِم
DefaultExtractorsFactory.setConstantBitrateSeekingEnabled
.
Kotlin
val extractorsFactory = DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true)
Java
DefaultExtractorsFactory extractorsFactory = new DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true);
ويمكن بعد ذلك إدخال ExtractorsFactory
من خلال DefaultMediaSourceFactory
على النحو الموضَّح لتخصيص علامات أداة الاستخراج أعلاه.
تفعيل قائمة انتظار التخزين المؤقت غير المتزامنة
إنّ وضع المخزن المؤقت غير المتزامن هو تحسين في مسار عرض ExoPlayer، والذي يشغّل مثيلات MediaCodec
في وضع غير متزامن ويستخدم سلاسل محادثات إضافية لجدولة عملية فك ترميز البيانات وعرضها. يمكن أن يؤدي تفعيل هذه الميزة إلى
الحدّ من اللقطات التي تم إسقاطها وعمليات تشغيل الصوت.
يتم تفعيل "قائمة المحتوى التالي في التخزين المؤقت غير المتزامن" تلقائيًا على الأجهزة التي تعمل بالإصدار 12 من نظام التشغيل Android (المستوى 31 من واجهة برمجة التطبيقات) والإصدارات الأحدث، ويمكن تفعيلها يدويًا بدءًا من الإصدار Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات). جرِّب تفعيل هذه الميزة لأجهزة معينة لاحظت أن إطاراتها مفقودة أو انخفضت عمليات تشغيل الصوت، خاصةً عند تشغيل محتوى محمي بموجب إدارة الحقوق الرقمية أو محتوى عالي السرعة.
في أبسط الحالات، ستحتاج إلى إدخال DefaultRenderersFactory
في المشغّل على النحو التالي:
Kotlin
val renderersFactory = DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing() val exoPlayer = ExoPlayer.Builder(context, renderersFactory).build()
Java
DefaultRenderersFactory renderersFactory = new DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing(); ExoPlayer exoPlayer = new ExoPlayer.Builder(context, renderersFactory).build();
إذا كنت تنشئ مثيلاً لعارضي العروض مباشرةً، مرِّر AsynchronousMediaCodecAdapter.Factory
إلى الدالتين الإنشائية MediaCodecVideoRenderer
وMediaCodecAudioRenderer
.
اعتراض طلبات البيانات باستخدام ForwardingPlayer
يمكنك تخصيص بعض سلوك المثيل Player
من خلال إحاطته بفئة فرعية من ForwardingPlayer
وتجاوز الطرق لتنفيذ أي مما يلي:
- يمكنك الوصول إلى المَعلمات قبل تمريرها إلى المفوَّض
Player
. - عليك الوصول إلى القيمة المعروضة من المستخدم المفوَّض
Player
قبل عرضها. - أعِد تنفيذ الطريقة بالكامل.
عند إلغاء طرق ForwardingPlayer
، من المهم التأكّد من أنّ عملية التنفيذ تحافظ على الاتساق الذاتي والتوافق مع واجهة Player
، خاصةً عند التعامل مع الأساليب التي تهدف إلى الحصول على سلوك متطابق أو ذي صلة. مثلاً:
- إذا أردت إلغاء كل عملية من عمليات "التشغيل"، يجب إلغاء كلاً من
ForwardingPlayer.play
وForwardingPlayer.setPlayWhenReady
، لأنّ المتصل سيتوقع أن يكون سلوك هاتين الطريقتَين متطابقتَين عندplayWhenReady = true
. - إذا كنت تريد تغيير زيادة التقديم/الترجيع، يجب إلغاء كلاً من
ForwardingPlayer.seekForward
لتقديم طلب بالزيادة المخصّصة وForwardingPlayer.getSeekForwardIncrement
حتى يتم إبلاغ المتصل بالزيادة المخصّصة الصحيحة. - إذا أردت التحكّم في ما يتم الإعلان عنه من خلال مثيل
Player.Commands
للمشغّل، عليك إلغاء كل منPlayer.getAvailableCommands()
وPlayer.isCommandAvailable()
، والاستماع أيضًا إلى رد الاتصال فيPlayer.Listener.onAvailableCommandsChanged()
ليتم إعلامك بالتغييرات القادمة من المشغّل الأساسي.
تخصيص MediaSource
تؤدي الأمثلة الواردة أعلاه إلى إدخال مكونات مخصّصة لاستخدامها أثناء تشغيل جميع عناصر MediaItem
التي يتم تمريرها إلى المشغّل. وعندما يكون إجراء التخصيص بالغ الدقة مطلوبًا، من الممكن أيضًا إدخال مكوِّنات مخصّصة في مثيلات MediaSource
فردية والتي يمكن تمريرها إلى المشغّل مباشرةً. ويوضّح المثال أدناه كيفية تخصيص ProgressiveMediaSource
لاستخدام سمات DataSource.Factory
وExtractorsFactory
وLoadErrorHandlingPolicy
مخصّصة:
Kotlin
val mediaSource = ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory) .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy) .createMediaSource(MediaItem.fromUri(streamUri))
Java
ProgressiveMediaSource mediaSource = new ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory) .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy) .createMediaSource(MediaItem.fromUri(streamUri));
إنشاء مكونات مخصصة
توفر المكتبة تطبيقات افتراضية للمكونات المدرجة أعلى هذه الصفحة لحالات الاستخدام الشائعة. يمكن أن يستخدم ExoPlayer
هذه المكوّنات، ولكن قد يتم إنشاؤه أيضًا لاستخدام عمليات تنفيذ مخصّصة إذا لزم الأمر سلوكيات غير عادية. في ما يلي بعض حالات الاستخدام المخصّصة لعمليات التنفيذ المخصّصة:
Renderer
– يمكنك استخدامRenderer
مخصّص لمعالجة نوع وسائط غير متوافق مع عمليات التنفيذ التلقائية التي توفّرها المكتبة.TrackSelector
: يتيح تنفيذTrackSelector
مخصّص لمطوّر التطبيقات تغيير طريقة اختيار المقاطع الصوتية التي تم الكشف عنها من خلالMediaSource
ليتم استخدامها في كل منRenderer
المتاحة.LoadControl
– يتيح تنفيذLoadControl
مخصّص لمطوّر التطبيق تغيير سياسة التخزين المؤقت للمشغّل.Extractor
– إذا كنت تريد إتاحة تنسيق حاوية غير متوافق مع المكتبة حاليًا، ننصحك بتنفيذ فئةExtractor
مخصّصة.MediaSource
– قد يكون من المناسب تنفيذ فئةMediaSource
مخصّصة إذا كنت تريد الحصول على عيّنات من الوسائط لإضافتها إلى خلاصة العارضين بطريقة مخصّصة، أو إذا كنت تريد تطبيق سلوكMediaSource
مخصّص.MediaSource.Factory
– يتيح تنفيذMediaSource.Factory
مخصّص للتطبيق تخصيص طريقة إنشاءMediaSource
منMediaItem
.DataSource
– تحتوي حزمة ExoPlayer على عدد من عمليات تنفيذDataSource
لحالات الاستخدام المختلفة. قد يكون من الأفضل استخدام فئةDataSource
لتحميل البيانات بطريقة أخرى، مثلاً عبر بروتوكول مخصّص أو من خلال حزمة HTTP مخصصة أو من ذاكرة تخزين مؤقت دائمة مخصَّصة.
عند إنشاء مكونات مخصصة، ننصحك بما يلي:
- إذا كان أحد المكوّنات المخصّصة يحتاج إلى إرسال تقارير إلى التطبيق مرة أخرى عن الأحداث، ننصحك
بإجراء ذلك باستخدام النموذج نفسه المستخدَم في مكوّنات ExoPlayer الحالية،
على سبيل المثال، باستخدام فئات
EventDispatcher
أو تمريرHandler
مع أداة إنشاء للمكوِّن. - ننصح بأن تستخدم المكوّنات المخصّصة النموذج نفسه المستخدَم في مكوّنات ExoPlayer الحالية
للسماح بإعادة ضبط التطبيق أثناء التشغيل. لإجراء ذلك، يجب أن تنفّذ المكونات المخصّصة
PlayerMessage.Target
وأن تتلقّى تغييرات الإعدادات في طريقةhandleMessage
. ينبغي أن يجتاز رمز التطبيق تغييرات الإعدادات من خلال استدعاء طريقةcreateMessage
في ExoPlayer، وإعداد الرسالة، وإرسالها إلى المكوِّن باستخدامPlayerMessage.send
. يضمن إرسال الرسائل ليتم تسليمها في سلسلة التشغيل أن يتم تنفيذها بالترتيب مع أي عمليات أخرى يتم تنفيذها على المشغّل.