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

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

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

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

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

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

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

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

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

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

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

SampleChooserActivity وPlayerActivity في تطبيق ExoPlayer التجريبي
الشكل 2. ‫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) للملفات المحلية، يطلب التطبيق التجريبي أذونات الوصول إلى مساحة التخزين اللازمة لقراءة هذه الملفات. ومع ذلك، بدءًا من 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- إطلاق intent

يمكن استخدام النوايا لتخطّي قائمة العيّنات وبدء التشغيل مباشرةً. لتشغيل عيّنة واحدة، اضبط إجراء الغرض على androidx.media3.demo.main.action.VIEW وضبط معرّف الموارد المنتظم (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 [سلسلة] معرّف الموارد المنتظم (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