אפליקציית הדגמה של 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' ב-Android Studio, מגדירים את וריאנט ה-build של המודול להדגמה ל-withDecoderExtensionsDebug או ל-withDecoderExtensionsRelease כפי שמוצג בתמונה הבאה.

    בחירת וריאנט ה-build של ההדגמה 'withDecoderExtensionDebug'

  3. עורכים קובץ build, מתקינים ומפעילים את קובץ התצורה של 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 של קבצים מקומיים, אפליקציית הדגמה מבקשת את הרשאות הגישה הנדרשות לאחסון כדי לקרוא את הקבצים האלה. עם זאת, החל מ-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

התוספות האופציונליות שנתמכות ב-Intent לדוגמה אחת הן:

  • דוגמאות להגדרות נוספות:
    • mime_type [מחרוזת] רמז לדוגמה לסוג MIME. לדוגמה, application/dash+xml לתוכן DASH.
    • clip_start_position_ms [ארוך] נקודת ההתחלה שבה צריך לחתוך את הדגימה, באלפיות שנייה.
    • clip_end_position_ms [Long] נקודת סיום שממנה צריך לחתוך את הדגימה, באלפיות שנייה.
    • drm_scheme [מחרוזת] הסכימה של DRM אם התוכן מוגן. הערכים המותרים הם widevine, playready ו-clearkey. אפשר להשתמש גם במזהי UUID של סכימת DRM.
    • 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 [בוליאני] אם לצרף סשן DRM לטראקים של וידאו ואודיו ללא הצפנה.
    • drm_multi_session [בוליאני] הפעלת רוטציית מפתחות אם המפתח מוגן.
    • subtitle_uri [מחרוזת] ה-URI של קובץ צדדי של כתוביות.
    • subtitle_mime_type [מחרוזת] סוג MIME של Caption_uri (חובה אם מוגדר caption_uri).
    • subtitle_language [מחרוזת] קוד השפה מסוג 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