לאפליקציית הדגמה הראשית של ExoPlayer יש שתי מטרות עיקריות:
- כדי לספק דוגמה פשוטה יחסית עם כל התכונות לשימוש ב-ExoPlayer. אפשר להשתמש באפליקציית הדגמה כנקודת התחלה נוחה לפיתוח אפליקציה משלכם.
- כדי שתוכלו לנסות את ExoPlayer בקלות. אפשר להשתמש באפליקציית הדגמה כדי לבדוק את ההפעלה של התוכן שלכם, בנוסף לדוגמאות הכלולות.
בדף הזה נסביר איך מורידים, יוצרים ומריצים את אפליקציית הדגמה. בנוסף, נסביר איך להשתמש בה כדי להפעיל מדיה משלכם.
קבלת הקוד
קוד המקור של אפליקציית ההדגמה הראשית נמצא בתיקייה demos/main
בפרויקט שלנו ב-GitHub. אם עדיין לא עשיתם זאת, צריך להעתיק את הפרויקט לספרייה מקומית:
git clone https://github.com/androidx/media.git
לאחר מכן, פותחים את הפרויקט ב-Android Studio. בתצוגת הפרויקט ב-Android אמורים להופיע הפריטים הבאים (התיקיות הרלוונטיות של אפליקציית הדגמה הורחבו):
הידור והפעלה
כדי לקמפל ולהריץ את אפליקציית הדגמה, בוחרים את ההגדרה demo
ומפעילים אותה ב-Android Studio. אפליקציית ההדגמה תותקן ותפעל במכשיר Android מחובר.
אם אפשר, מומלץ להשתמש במכשיר פיזי. אם במקום זאת אתם רוצים להשתמש במהדר, כדאי לקרוא את הקטע על מכשירי אמולטור בקטע מכשירים נתמכים ולוודא שבמכשיר הווירטואלי שלכם מותקנת קובץ אימג' של מערכת עם רמת API של 23 לפחות.
באפליקציית הדגמה מוצגת רשימה של טעימות (SampleChooserActivity
). בחירה בטעימה תפתח פעילות שנייה (PlayerActivity
) להפעלה. הדמו כולל לחצני הפעלה ופונקציות לבחירת טראקים. הוא משתמש גם בכיתה השירות EventLogger
של ExoPlayer כדי להפיק מידע שימושי לניפוי באגים ביומן המערכת. אפשר לראות את הרישום ביומן הזה (יחד עם רישום ביומן ברמת השגיאה של תגים אחרים) באמצעות הפקודה:
adb logcat EventLogger:V *:E
הפעלת מקודדים בחבילה
ל-ExoPlayer יש כמה תוספים שמאפשרים להשתמש במקודדים של תוכנות בחבילה, כולל AV1, VP9, Opus, FLAC ו-FFmpeg (אודיו בלבד). אפשר ליצור את אפליקציית ההדגמה כדי לכלול את התוספים האלה ולהשתמש בהם באופן הבא:
- יוצרים את כל התוספים שרוצים לכלול. שימו לב שמדובר בתהליך ידני. להוראות, יש לעיין בקובץ
README.md
בכל סיומת. בתצוגה 'וריאציות של build' ב-Android Studio, מגדירים את וריאנט ה-build של המודול להדגמה ל-
withDecoderExtensionsDebug
או ל-withDecoderExtensionsRelease
כפי שמוצג בתמונה הבאה.עורכים קובץ 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