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

يخدم تطبيق ExoPlayer التجريبي الرئيسي غرضَين أساسيَين:

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

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

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

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

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

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

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

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

لتجميع التطبيق التجريبي وتشغيله، اختَر إعداد demo وشغِّله في IDE Android Studio. سيتم تثبيت التطبيق التجريبي وتشغيله على جهاز 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. 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) للملفات المحلية، يطلب التطبيق التجريبي أذونات الوصول إلى مساحة التخزين اللازمة لقراءة هذه الملفات. ومع ذلك، اعتبارًا من الإصدار 13 من Android، ليس بإمكانك تحميل ملفات عشوائية لا تنتهي بامتداد ملف وسائط عادي (مثل .mp4). إذا كنت بحاجة إلى تحميل ملف من هذا النوع، يمكنك وضعه في directoryملف التخزين المحدد للتطبيق التجريبي والذي ليس له قيود وصول. يمكن العثور على هذا الرمز عادةً في /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- رمي الكرة

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

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 [سلسلة] مخطّط إدارة الحقوق الرقمية في حال كان المحتوى محميًا القيم الصالحة هي widevine وplayready وclearkey. يتم أيضًا قبول معرّفات UUID الخاصة بمخطط إدارة الحقوق الرقمية.
    • ‫drm_license_uri [سلسلة] عنوان URL لخادم الترخيص إذا كان محميًا
    • 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 لملف الترجمة (يتم تجاهله في حال عدم ضبط سمة subtitle_uri).
    • ad_tag_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 مخطّط إدارة الحقوق الرقمية للعينة الثانية.
  • يتم تمرير عنوان URL للعيّنة كقيمة إضافية باستخدام المفتاح 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