تطبيق ExoPlayer التجريبي

يخدم تطبيق العرض التوضيحي الرئيسي في ExoPlayer غرضَين أساسيَّين:

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

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

الحصول على الرمز

يمكنك العثور على الرمز المصدر لتطبيق العرض التوضيحي الرئيسي في المجلد demos/main ضمن مشروع GitHub. إذا لم يسبق لك إجراء ذلك، استنسِخ المشروع إلى دليل محلي:

git clone https://github.com/androidx/media.git

بعد ذلك، افتح المشروع في "استوديو Android". من المفترض أن يظهر لك ما يلي في طريقة العرض "مشروع Android" (تم توسيع المجلدات ذات الصلة في التطبيق التجريبي):

المشروع في "استوديو Android"

التجميع والتنفيذ

لإنشاء تطبيق تجريبي وتشغيله، اختَر إعداد demo وشغِّله في "استوديو Android". سيتم تثبيت التطبيق التجريبي وتشغيله على جهاز Android متصل. ننصحك باستخدام جهاز فعلي إذا أمكن. إذا كنت تريد استخدام محاكي بدلاً من ذلك، يُرجى قراءة قسم المحاكيات في الأجهزة المتوافقة والتأكّد من أنّ جهازك الافتراضي يستخدم صورة نظام بمستوى واجهة برمجة تطبيقات 23 على الأقل.

SampleChooserActivity وPlayerActivity

يعرض التطبيق التجريبي قائمة بالعينات (SampleChooserActivity). سيؤدي اختيار عينة إلى فتح نشاط ثانٍ (PlayerActivity) لتشغيلها. يتضمّن العرض التوضيحي عناصر تحكّم في التشغيل ووظيفة اختيار المسار. ويستخدم أيضًا فئة الأداة المساعدة EventLogger في ExoPlayer لعرض معلومات تصحيح الأخطاء المفيدة في سجلّ النظام. يمكن الاطّلاع على هذا التسجيل (إلى جانب تسجيل مستوى الخطأ للعلامات الأخرى) باستخدام الأمر:

adb logcat EventLogger:V *:E

تفعيل برامج الترميز المجمّعة

يتضمّن ExoPlayer عددًا من الإضافات التي تتيح استخدام برامج الترميز المجمَّعة، بما في ذلك AV1 وVP9 وOpus وFLAC وFFmpeg (الصوت فقط). يمكن إنشاء التطبيق التجريبي ليتضمّن هذه الإضافات ويستخدمها على النحو التالي:

  1. أنشئ كل الإضافات التي تريد تضمينها. يُرجى العِلم أنّ هذه العملية تتم يدويًا. يُرجى الرجوع إلى ملف README.md في كل إضافة للاطّلاع على التعليمات.

  2. في عرض "تنويعات التصميم" في استوديو Android، اضبط تنويعة التصميم لوحدة التطبيق التجريبي على withDecoderExtensionsDebug أو withDecoderExtensionsRelease كما هو موضّح في الصورة التالية.

    اختيار تنويعة التصميم التجريبي `withDecoderExtensionsDebug`

  3. جمِّع إعدادات demo وثبِّتها وشغِّلها كالمعتاد.

بشكلٍ تلقائي، لن يتم استخدام برنامج فك ترميز الإضافة إلا إذا لم يتوفّر برنامج فك ترميز مناسب للنظام الأساسي. يمكن تحديد أنّه يجب تفضيل برامج فك ترميز الإضافات، كما هو موضّح في الأقسام التالية.

تشغيل المحتوى الخاص بك

هناك عدة طرق لتشغيل المحتوى الخاص بك في التطبيق التجريبي.

‫1. تعديل ملف assets/media.exolist.json

يتم تحميل النماذج المُدرَجة في التطبيق التجريبي من assets/media.exolist.json. من خلال تعديل ملف JSON هذا، يمكن إضافة عيّنات وإزالتها من تطبيق العرض التوضيحي. وفي ما يلي المخطط، حيث يشير [O] إلى سمة اختيارية.

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of sample",
        "uri": "The URI of the sample",
        "extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8",
        "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
        "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
        "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
        "drm_license_uri": "[O] URI of the license server if protected",
        "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
        "drm_key_request_properties": "[O] Key request headers if protected",
        "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks"
        "drm_multi_session": "[O] Enables key rotation if protected",
        "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
        "subtitle_uri": "[O] The URI of a subtitle sidecar file",
        "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
        "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)",
        "ad_tag_uri": "[O] The URI of an ad tag to load via the IMA extension"
      },
      ...etc
    ]
  },
  ...etc
]

يمكن تحديد قوائم تشغيل العيّنات باستخدام المخطط التالي:

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of playlist sample",
        "playlist": [
          {
            "uri": "The URI of the first sample in the playlist",
            "extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8"
            "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
            "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
            "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
            "drm_license_uri": "[O] URI of the license server if protected",
            "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
            "drm_key_request_properties": "[O] Key request headers if protected",
            "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
            "drm_multi_session": "[O] Enables key rotation if protected",
            "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
            "subtitle_uri": "[O] The URI of a subtitle sidecar file",
            "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
            "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)"
          },
          {
            "uri": "The URI of the second sample in the playlist",
            ...etc
          },
          ...etc
        ]
      },
      ...etc
    ]
  },
  ...etc
]

في حال الحاجة إلى ذلك، يتم تحديد عناوين طلب المفتاح كعنصر يحتوي على سمة سلسلة لكل عنوان:

"drm_key_request_properties": {
  "name1": "value1",
  "name2": "value2",
  ...etc
}

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

معرّفات موارد منتظمة (URI) للملفات المحلية وقيود التخزين الفرعي

عند تحديد معرّفات الموارد المنتظمة (URI) للملفات المحلية، يطلب التطبيق التجريبي أذونات الوصول إلى مساحة التخزين اللازمة لقراءة هذه الملفات. ومع ذلك، بدءًا من Android 13، لا يمكن تحميل أي ملفات عشوائية لا تنتهي بامتداد ملف وسائط نموذجي (مثل .mp4). إذا كنت بحاجة إلى تحميل مثل هذا الملف، يمكنك وضعه في دليل التخزين الخاص بالتطبيق التجريبي الذي لا يتضمّن أي قيود على الوصول. يمكن العثور على هذا المعرّف عادةً في /sdcard/Android/data/androidx.media3.demo.main/files.

‫2- تحميل ملف exolist.json خارجي

يمكن للتطبيق التجريبي تحميل ملفات JSON خارجية باستخدام المخطط أعلاه وتسميتها وفقًا لاتفاقية *.exolist.json. على سبيل المثال، إذا كنت تستضيف ملفًا من هذا النوع على https://yourdomain.com/samples.exolist.json، يمكنك فتحه في التطبيق التجريبي باستخدام:

adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com/samples.exolist.json

سيؤدي النقر على رابط *.exolist.json (على سبيل المثال، في المتصفح أو برنامج البريد الإلكتروني) على جهاز مثبَّت عليه التطبيق التجريبي إلى فتح التطبيق التجريبي أيضًا. وبالتالي، فإنّ استضافة ملف JSON *.exolist.json توفّر طريقة بسيطة لتوزيع المحتوى ليجرّبه الآخرون في التطبيق التجريبي.

3- إطلاق نية

يمكن استخدام النوايا لتخطّي قائمة العيّنات وبدء التشغيل مباشرةً. لتشغيل عيّنة واحدة، اضبط إجراء الغرض على androidx.media3.demo.main.action.VIEW وضبط معرّف الموارد المنتظم (URI) للبيانات على معرّف الموارد المنتظم (URI) الخاص بالعيّنة المطلوب تشغيلها. يمكن إطلاق مثل هذه النية من الوحدة الطرفية باستخدام:

adb shell am start -a androidx.media3.demo.main.action.VIEW \
    -d https://yourdomain.com/sample.mp4

تشمل الإضافات الاختيارية المتاحة لنموذج واحد من نية المستخدم ما يلي:

  • إضافات نموذج الإعداد:
    • mime_type [String] عيّنة من تلميح نوع MIME. على سبيل المثال، application/dash+xml لمحتوى DASH.
    • clip_start_position_ms [Long] نقطة بداية يجب اقتطاع العيّنة منها، بالملي ثانية.
    • clip_end_position_ms [Long] نقطة نهاية يجب اقتطاع العينة منها، بالمللي ثانية.
    • ‫drm_scheme [String] نظام إدارة الحقوق الرقمية إذا كان المحتوى محميًا. القيم الصالحة هي widevine وplayready وclearkey. يتم قبول معرّفات UUID الخاصة بمخطط إدارة الحقوق الرقمية أيضًا.
    • drm_license_uri [String] معرّف الموارد المنتظم (URI) لخادم الترخيص إذا كان محميًا.
    • drm_force_default_license_uri [Boolean] ما إذا كان سيتم فرض استخدام drm_license_uri لطلبات المفاتيح التي تتضمّن معرّف الموارد المنتظم (URI) الخاص بالترخيص.
    • drm_key_request_properties [مصفوفة السلاسل النصية] عناوين طلب المفتاح التي تم تجميعها على النحو التالي: name1, value1, name2, value2 وما إلى ذلك، إذا كانت محمية.
    • drm_session_for_clear_content [Boolean] ما إذا كان سيتم إرفاق جلسة إدارة حقوق رقمية بمقاطع الفيديو والصوت غير المشفرة.
    • drm_multi_session [Boolean] تفعيل عملية تغيير المفتاح إذا كان محميًا
    • subtitle_uri [String] معرّف الموارد المنتظم (URI) لملف الترجمة المصاحبة
    • subtitle_mime_type [String] نوع MIME الخاص بـ subtitle_uri (مطلوب إذا تم ضبط subtitle_uri).
    • ‫subtitle_language [String] رمز اللغة المستخدَمة في ملف الترجمة والشرح وفق المعيار BCP47 (يتم تجاهله إذا لم يتم ضبط subtitle_uri).
    • ‫ad_tag_uri [String] معرّف الموارد المنتظم (URI) لعلامة إعلان سيتم تحميلها باستخدام [إضافة IMA][].
    • ‫prefer_extension_decoders [Boolean]: تحدّد ما إذا كان سيتم تفضيل برامج فك الترميز الخاصة بالإضافات على تلك الخاصة بالمنصة.

عند استخدام adb shell am start لتفعيل هدف، يمكن ضبط سلسلة اختيارية إضافية باستخدام --es (مثلاً، --es extension mpd). ويمكن ضبط قيمة منطقية اختيارية إضافية باستخدام --ez (مثلاً، --ez prefer_extension_decoders TRUE). ويمكن ضبط قيمة طويلة اختيارية إضافية باستخدام --el (مثلاً، --el clip_start_position_ms 5000). ويمكن ضبط مصفوفة سلاسل اختيارية إضافية باستخدام --esa (مثلاً، --esa drm_key_request_properties name1,value1).

لتشغيل قائمة تشغيل تتضمّن عيّنات، اضبط إجراء الغرض على androidx.media3.demo.main.action.VIEW_LIST. تبقى الإضافات في نموذج الإعداد كما هي بالنسبة إلى androidx.media3.demo.main.action.VIEW، باستثناء اختلافَين:

  • يجب أن تتضمّن مفاتيح البيانات الإضافية شرطة سفلية وفهرس العيّنة المستند إلى الرقم 0 كلاحقة. على سبيل المثال، سيشير extension_0 إلى نوع العيّنة الأولى. سيؤدي drm_scheme_1 إلى ضبط نظام إدارة الحقوق الرقمية (DRM) للعيّنة الثانية.
  • يتم تمرير معرّف الموارد المنتظم (URI) الخاص بالعينة كعنصر إضافي باستخدام المفتاح uri_<sample-index>.

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

adb shell am start -a androidx.media3.demo.main.action.VIEW_LIST \
    --es uri_0 https://a.com/sample1.mp4 \
    --es uri_1 https://b.com/sample2.fake_mpd \
    --es extension_1 mpd