אפליקציית הדגמה של ExoPlayer

אפליקציית ההדגמה הראשית של ExoPlayer מיועדת לשתי מטרות עיקריות:

  1. כדי לספק דוגמה פשוטה יחסית לשימוש ב-ExoPlayer, אבל עם כל התכונות. אפשר להשתמש באפליקציית ההדגמה כנקודת התחלה נוחה לפיתוח אפליקציה משלכם.
  2. כדי שיהיה קל לנסות את ExoPlayer. אפשר להשתמש באפליקציית ההדגמה כדי לבדוק את ההפעלה של התוכן שלכם, בנוסף לדוגמאות שכלולות בה.

בדף הזה מוסבר איך להוריד, לקמפל ולהפעיל את אפליקציית ההדגמה. מוסבר גם איך להשתמש בה כדי להפעיל מדיה משלכם.

קבלת הקוד

קוד המקור של אפליקציית ההדגמה הראשית נמצא בתיקייה demos/main של פרויקט GitHub שלנו. אם עדיין לא עשיתם זאת, משכפלים את הפרויקט לספרייה מקומית:

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

לאחר מכן, פותחים את הפרויקט ב-Android Studio. אתם אמורים לראות את הדברים הבאים בתצוגת הפרויקט ב-Android (התיקיות הרלוונטיות של אפליקציית ההדגמה מורחבות):

הפרויקט ב-Android Studio

הידור והפעלה

כדי לקמפל ולהפעיל את אפליקציית ההדגמה, בוחרים את ההגדרה demo ומפעילים אותה ב-Android Studio. אפליקציית ההדגמה תותקן ותפעל במכשיר Android מחובר. מומלץ להשתמש במכשיר פיזי אם אפשר. אם רוצים להשתמש במקום זאת באמולטור, צריך לקרוא את הקטע בנושא אמולטורים במכשירים נתמכים ולוודא שהמכשיר הווירטואלי משתמש בקובץ אימג' של המערכת עם רמת API של 23 לפחות.

‫SampleChooserActivity ו-PlayerActivity

באפליקציית ההדגמה מוצגת רשימה של דוגמאות (SampleChooserActivity). כשבוחרים דוגמה, נפתח מסך פעילות שני (PlayerActivity) להפעלה. הדמו כולל אמצעי בקרה להפעלה ופונקציונליות לבחירת רצועות. הוא גם משתמש במחלקה EventLogger של ExoPlayer כדי להפיק מידע שימושי לניפוי באגים ביומן המערכת. אפשר לראות את הרישום ביומן (יחד עם רישום ביומן של רמת השגיאה עבור תגים אחרים) באמצעות הפקודה:

adb logcat EventLogger:V *:E

הפעלת מפענחים מאוגדים

ל-ExoPlayer יש מספר תוספים שמאפשרים שימוש במפענחי תוכנה בחבילה, כולל AV1,‏ VP9,‏ Opus,‏ FLAC ו-FFmpeg (אודיו בלבד). אפשר ליצור את אפליקציית ההדגמה כך שתכלול את התוספים האלה ותשתמש בהם באופן הבא:

  1. יוצרים כל אחד מהתוספים שרוצים לכלול. שימו לב, זהו תהליך ידני. הוראות מפורטות אפשר למצוא בקובץ README.md בכל תוסף.

  2. בתצוגה Build Variants (וריאנט build) ב-Android Studio, מגדירים את וריאנט build של מודול ההדגמה ל-withDecoderExtensionsDebug או ל-withDecoderExtensionsRelease, כמו שמוצג בתמונה הבאה.

    בחירת וריאציית ה-build של ההדגמה `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. 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. הפעלת כוונה

אפשר להשתמש בכוונות כדי לעקוף את רשימת הדוגמאות ולהפעיל את ההשמעה ישירות. כדי להפעיל דגימה אחת, מגדירים את הפעולה של ה-Intent ל-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 [ארוך] נקודת התחלה שאליה צריך לחתוך את הדגימה, באלפיות שנייה.
    • ‫clip_end_position_ms [Long] נקודת סיום שממנה צריך לחתוך את הדגימה, באלפיות השנייה.
    • ‫drm_scheme [String] תוכנית DRM אם התוכן מוגן. הערכים החוקיים הם widevine,‏ playready ו-clearkey. אפשר להשתמש גם ב-UUID של סכימת DRM.
    • ‫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 לרצועות וידאו ואודיו לא מוצפנות.
    • ‫drm_multi_session [בוליאני] הפעלת רוטציית מפתחות אם הם מוגנים.
    • ‫subtitle_uri [String] ה-URI של קובץ כתוביות נלווה.
    • ‫subtitle_mime_type [String] סוג ה-MIME של subtitle_uri (חובה אם מוגדר subtitle_uri).
    • ‫subtitle_language [String] קוד השפה מסוג BCP47 של קובץ הכתוביות (המערכת מתעלמת מהערך אם לא מוגדר subtitle_uri).
    • ad_tag_uri [מחרוזת] ה-URI של תג מודעה לטעינה באמצעות [התוסף IMA][].
    • prefer_extension_decoders [Boolean] האם עדיף להשתמש במפענחי תוספים במקום במפענחי פלטפורמה.

כשמשתמשים ב-adb shell am start כדי להפעיל intent, אפשר להגדיר מחרוזת אופציונלית נוספת באמצעות --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