تطبيق 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 وPlayActivity

يعرض التطبيق التجريبي قائمة بالنماذج (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. تعديل مواد العرض/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. 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",
        "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. 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",
            "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 (على سبيل المثال، في المتصفّح أو في برنامج البريد الإلكتروني) على جهاز تم تثبيت التطبيق التجريبي إليه إلى فتحه أيضًا في التطبيق التجريبي. وبالتالي، فإنّ استضافة ملف *.exolist.json JSON توفّر طريقة بسيطة لتوزيع المحتوى لتجربته الآخرين في التطبيق التجريبي.

3. تنشيط هدف

يمكن استخدام الأهداف لتجاوز قائمة النماذج وبدء التشغيل مباشرةً. لتشغيل عيّنة واحدة، اضبط إجراء الهدف على 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 [سلسلة] نموذج تلميح لنوع MIME. على سبيل المثال، application/dash+xml لمحتوى DASH.
    • clip_start_position_ms [طويل] نقطة بداية يجب اقتصاص العيّنة بها، بالمللي ثانية.
    • clip_end_position_ms [طويل] نقطة نهاية يجب قطع العيّنة منها، بالمللي ثانية.
    • drm_scheme [سلسلة] يتم استخدام نظام إدارة الحقوق الرقمية (DRM) في حال حمايتها. القيم الصالحة هي widevine وplayready وclearkey. يتم أيضًا قبول أرقام التعريف الفريدة العالمية (UUID) في نظام إدارة الحقوق الرقمية.
    • drm_license_uri [سلسلة] معرّف الموارد المنتظم (URI) لخادم الترخيص في حال حمايته
    • drm_force_default_license_uri [منطقي] تحديد ما إذا كان سيتم فرض استخدام drm_license_uri للطلبات الرئيسية التي تتضمن معرّف الموارد المنتظم (URI) للترخيص الخاص بها
    • drm_key_request_properties [مصفوفة سلسلة] عناوين طلبات المفاتيح معبأة على النحو name1 وvalue1 وname2 وvalue2 وما إلى ذلك إذا كانت محمية.
    • drm_session_for_clear_content [منطقي] لتحديد ما إذا كان سيتم إرفاق جلسة إدارة الحقوق الرقمية لمحو مقاطع الفيديو والصوت
    • drm_multi_session [منطقي] تفعيل تدوير المفاتيح في حال حمايتها
    • subtitle_uri [سلسلة] معرّف الموارد المنتظم (URI) لملف الترجمة الجانبية
    • subtitle_mime_type [سلسلة] نوع MIME لـ subtitle_uri (وهو مطلوب في حال ضبط subtitle_uri).
    • subtitle_language [سلسلة] رمز لغة BCP47 لملف الترجمة (ignored if subtitle_uri عدم تعيين).
    • ad_tag_uri [سلسلة] معرّف الموارد المنتظم (URI) لعلامة إعلان المطلوب تحميلها باستخدام [إضافة IMA][].
    • prefer_extension_decoders [منطقي] ما إذا كانت برامج فك ترميز الإضافات هي المفضّلة لبرامج فك ترميز الإضافات.

عند استخدام 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