الصور
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يتوافق ExoPlayer مع تنسيقات الصور التالية. اطّلِع على مكتبات تحميل الصور للتعرّف على كيفية الدمج مع المكتبات الخارجية التي قد توفّر دعمًا لمجموعة مختلفة من التنسيقات.
تنسيق الصورة |
معلومات معتمَدة |
ملاحظات |
BMP |
نعم |
|
ملف GIF |
لا |
لا تتوفّر أداة استخراج |
JPEG |
نعم |
|
صورة متحركة بتنسيق JPEG |
نعم |
الصور الثابتة والفيديوهات المتوافقة |
دقة HDR فائقة بتنسيق JPEG
|
نعم
|
يتم الرجوع إلى SDR قبل Android 14 أو على
الشاشات غير المزوّدة بتقنية النطاق العالي الديناميكية |
PNG |
نعم |
|
WebP |
نعم |
|
HEIF/HEIC |
نعم |
|
صورة حيّة بتنسيق HEIC |
جزئيًا |
تتوفّر الصور الثابتة فقط* |
AVIF (الأساسي) |
نعم |
يتم فك ترميزها على الإصدار 14 من نظام التشغيل Android والإصدارات الأحدث فقط. |
* يمكن الحصول على جزء الفيديو من الصور المتحركة بتنسيق HEIC باستخدام مكتبة MetadataRetriever وتشغيله كملف مستقل.
لتشغيل صورة كجزء من قائمة تشغيل، أنشئ MediaItem
باستخدام عنوان URL للصورة
وقدِّمه إلى المشغّل. يجب أن يتضمّن MediaItem
imageDurationMs
لتحديد مدّة عرض الصورة.
Kotlin
// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the media item to be played with the desired duration.
player.setMediaItem(
MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build())
// Prepare the player.
player.prepare()
Java
// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the media item to be played with the desired duration.
player.setMediaItem(
new MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build());
// Prepare the player.
player.prepare();
الصور الحيّة
الصور الحيّة هي ملفات تجمع بين صورة ثابتة وفيديو قصير.
- إذا تم تحديد مدة الصورة باستخدام
setImageDuration
، يتم عرض الصورة الحيّة
كصورة ثابتة خلال المدة المحدّدة.
- إذا لم يتم تحديد مدة الصورة، يتم تشغيل الصورة الحيّة كفيديو.
لمزيد من خيارات التخصيص، يمكنك إنشاء ProgressiveMediaSource
ونقله مباشرةً إلى المشغّل بدلاً من MediaItem
.
Kotlin
// Create a data source factory.
val dataSourceFactory = DefaultHttpDataSource.Factory()
// Create a media item with the image URI and the desired duration.
val mediaItem =
MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build()
// Create a progressive media source for this media item.
val mediaSource =
ProgressiveMediaSource.Factory(dataSourceFactory)
.createMediaSource(mediaItem)
// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the media source to be played.
player.setMediaSource(mediaSource)
// Prepare the player.
player.prepare()
Java
// Create a data source factory.
DataSource.Factory dataSourceFactory = new DefaultHttpDataSource.Factory();
// Create a media item with the image URI and the desired duration.
MediaItem mediaItem =
new MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build();
// Create a progressive media source for this media item.
MediaSource mediaSource =
new ProgressiveMediaSource.Factory(dataSourceFactory)
.createMediaSource(mediaItem);
// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the media source to be played.
player.setMediaSource(mediaSource);
// Prepare the player.
player.prepare();
تخصيص عملية التشغيل
يقدّم ExoPlayer طرقًا متعدّدة لتخصيص تجربة التشغيل وفقًا لاحتياجات
تطبيقك. اطّلِع على صفحة التخصيص للحصول على أمثلة.
مكتبات تحميل الصور
غالبًا ما تتم إدارة الصور من خلال مكتبات تحميل صور خارجية، مثل
Glide أو
Coil.
يتطلب دمج هذه المكتبات في مسار التشغيل 3 خطوات:
- حدِّد
MediaItem
بنوع MIME APPLICATION_EXTERNALLY_LOADED_IMAGE
.
- قدِّم وحدة فك ترميز الصور لاسترداد
Bitmap
من مكتبة تحميل
الصور.
- قدِّم أداة تحميل خارجية لبدء ميزة التخزين المؤقت وميزة التحميل المُسبَق.
عنصر MediaItem بنوع MIME لصورة تم تحميلها خارجيًا
يجب أن تحدِّد القيمة MediaItem
المُضافة إلى القيمة Player
نوع APPLICATION_EXTERNALLY_LOADED_IMAGE
MIME بشكل صريح لاستخدام مسارات رمز مكتبة تحميل
الصور:
Kotlin
val mediaItem =
MediaItem.Builder()
.setUri(imageUri)
.setMimeType(MimeTypes.APPLICATION_EXTERNALLY_LOADED_IMAGE)
.build()
Java
MediaItem mediaItem =
new MediaItem.Builder()
.setUri(imageUri)
.setMimeType(MimeTypes.APPLICATION_EXTERNALLY_LOADED_IMAGE)
.build();
أداة فك ترميز الصور باستخدام مكتبة لتحميل الصور
يحتاج مشغّل العرض إلى ExternallyLoadedImageDecoder
لاسترداد
Bitmap
من Uri
. يمكن توفير هذا الترميز من خلال إلغاء
DefaultRenderersFactory.getImageDecoderFactory
.
يستخدم المثال التالي Glide لتحميل صورة:
Kotlin
val glideImageDecoderFactory: ImageDecoder.Factory =
ExternallyLoadedImageDecoder.Factory { request: ExternalImageRequest ->
GlideFutures.submit(Glide.with(context).asBitmap().load(request.uri))
}
val player: Player =
ExoPlayer.Builder(context)
.setRenderersFactory(
object : DefaultRenderersFactory(context) {
override fun getImageDecoderFactory(): ImageDecoder.Factory {
return glideImageDecoderFactory
}
}
)
.build()
Java
ImageDecoder.Factory glideImageDecoderFactory =
new ExternallyLoadedImageDecoder.Factory(
request -> GlideFutures.submit(
Glide.with(context).asBitmap().load(request.uri)));
Player player =
new ExoPlayer.Builder(context)
.setRenderersFactory(
new DefaultRenderersFactory(context) {
@Override
protected ImageDecoder.Factory getImageDecoderFactory() {
return glideImageDecoderFactory;
}
})
.build();
تحميل الصور مسبقًا باستخدام مكتبة لتحميل الصور
أثناء التشغيل، يطلب المشغّل تحميل الصورة التالية مسبقًا بعد تحميل العنصر السابق
في قائمة التشغيل بالكامل. عند استخدام مكتبة loading
خارجية لتحميل الصور، يجب تحديد ExternalLoader
لبدء عملية التحميل المُسبَق هذه. إذا لم يكن التمهيد المُسبَق ممكنًا أو مطلوبًا، يجب توفير أداة التحميل هذه، ولكن لن تتمكّن من تنفيذ أي إجراء.
يستخدم المثال التالي Glide لضمان تحميل الصورة المطلوبة مسبقًا
إلى القرص:
Kotlin
val glidePreloader = ExternalLoader { request: LoadRequest ->
GlideFutures.submit(
Glide.with(context)
.asFile()
.apply(
RequestOptions.diskCacheStrategyOf(DiskCacheStrategy.DATA)
.priority(Priority.HIGH)
.skipMemoryCache(true)
)
.load(request.uri)
)
}
val player =
ExoPlayer.Builder(context)
.setMediaSourceFactory(DefaultMediaSourceFactory(context)
.setExternalImageLoader(glidePreloader))
.build()
Java
ExternalLoader glidePreloader =
request ->
GlideFutures.submit(
Glide.with(context)
.asFile()
.apply(
diskCacheStrategyOf(DiskCacheStrategy.DATA)
.priority(Priority.HIGH)
.skipMemoryCache(true))
.load(request.uri));
Player player =
new ExoPlayer.Builder(context)
.setMediaSourceFactory(new DefaultMediaSourceFactory(context)
.setExternalImageLoader(glidePreloader))
.build();
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Images\n\nExoPlayer supports the following image formats. See\n[Image Loading Libraries](/media/media3/exoplayer/images#image-loading-libraries)\nfor how to integrate with external libraries that may provide support for a\ndifferent set of formats.\n\n| Image format | Supported | Notes |\n|-------------------|-----------|------------------------------------------------------------|\n| BMP | YES | |\n| GIF | NO | No Extractor support |\n| JPEG | YES | |\n| JPEG Motion Photo | YES | Still image and video supported |\n| JPEG Ultra HDR | YES | Falls back to SDR before Android 14 or on non-HDR displays |\n| PNG | YES | |\n| WebP | YES | |\n| HEIF/HEIC | YES | |\n| HEIC Motion Photo | Partially | Only still image supported\\* |\n| AVIF (baseline) | YES | Decoded on Android 14+ only |\n\n\\* The video part of HEIC motion photos can be obtained with\n[MetadataRetriever](/media/media3/exoplayer/retrieving-metadata#motion-photos)\nand played as a standalone file.\n\nUsing MediaItem\n---------------\n\nTo play an image as part of a playlist, create a `MediaItem` with the image URI\nand pass it to the player. The `MediaItem` must have a `imageDurationMs` to\nspecify for how long the image should be displayed. \n\n### Kotlin\n\n```kotlin\n// Create a player instance.\nval player = ExoPlayer.Builder(context).build()\n// Set the media item to be played with the desired duration.\nplayer.setMediaItem(\n MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build())\n// Prepare the player.\nplayer.prepare()\n```\n\n### Java\n\n```java\n// Create a player instance.\nExoPlayer player = new ExoPlayer.Builder(context).build();\n// Set the media item to be played with the desired duration.\nplayer.setMediaItem(\n new MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build());\n// Prepare the player.\nplayer.prepare();\n```\n\n\u003cbr /\u003e\n\n### Motion Photos\n\nMotion photos are files combining a still image with a short video.\n\n- If the image duration is defined with `setImageDuration`, the motion photo is displayed for the declared duration as a still image.\n- If the image duration is undefined, the motion photo is played as a video.\n\nUsing ProgressiveMediaSource\n----------------------------\n\nFor more customization options, you can create a `ProgressiveMediaSource` and\npass it directly to the player instead of a `MediaItem`. \n\n### Kotlin\n\n```kotlin\n// Create a data source factory.\nval dataSourceFactory = DefaultHttpDataSource.Factory()\n// Create a media item with the image URI and the desired duration.\nval mediaItem =\n MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build()\n// Create a progressive media source for this media item.\nval mediaSource =\n ProgressiveMediaSource.Factory(dataSourceFactory)\n .createMediaSource(mediaItem)\n// Create a player instance.\nval player = ExoPlayer.Builder(context).build()\n// Set the media source to be played.\nplayer.setMediaSource(mediaSource)\n// Prepare the player.\nplayer.prepare()\n```\n\n### Java\n\n```java\n// Create a data source factory.\nDataSource.Factory dataSourceFactory = new DefaultHttpDataSource.Factory();\n// Create a media item with the image URI and the desired duration.\nMediaItem mediaItem =\n new MediaItem.Builder().setUri(imageUri).setImageDurationMs(2000).build();\n// Create a progressive media source for this media item.\nMediaSource mediaSource =\n new ProgressiveMediaSource.Factory(dataSourceFactory)\n .createMediaSource(mediaItem);\n// Create a player instance.\nExoPlayer player = new ExoPlayer.Builder(context).build();\n// Set the media source to be played.\nplayer.setMediaSource(mediaSource);\n// Prepare the player.\nplayer.prepare();\n```\n\n\u003cbr /\u003e\n\nCustomizing playback\n--------------------\n\nExoPlayer provides multiple ways for you to tailor playback experience to your\napp's needs. See the [Customization page](/guide/topics/media/exoplayer/customization) for examples.\n\nImage Loading Libraries\n-----------------------\n\nImages are often managed by external image loading libraries, for example\n[Glide](https://bumptech.github.io/glide/) or\n[Coil](https://coil-kt.github.io/coil/).\n\nIntegrating these libraries into the playback pipeline requires 3 steps:\n\n1. Define a `MediaItem` with `APPLICATION_EXTERNALLY_LOADED_IMAGE` MIME type.\n2. Provide an image decoder to retrieve a `Bitmap` from the image loading library.\n3. Provide an external loader to trigger caching and preloading.\n\n### MediaItem with externally loaded image MIME type\n\nThe `MediaItem` added to the `Player` must define the\n`APPLICATION_EXTERNALLY_LOADED_IMAGE` MIME type explicitly to use the image\nloading library code paths: \n\n### Kotlin\n\n```kotlin\nval mediaItem =\n MediaItem.Builder()\n .setUri(imageUri)\n .setMimeType(MimeTypes.APPLICATION_EXTERNALLY_LOADED_IMAGE)\n .build()\n```\n\n### Java\n\n```java\nMediaItem mediaItem =\n new MediaItem.Builder()\n .setUri(imageUri)\n .setMimeType(MimeTypes.APPLICATION_EXTERNALLY_LOADED_IMAGE)\n .build();\n```\n\n\u003cbr /\u003e\n\n### Image decoder using an image loading library\n\nThe image renderer needs an `ExternallyLoadedImageDecoder` to retrieve the\n`Bitmap` from the `Uri`. This decoder can be provided by overriding\n`DefaultRenderersFactory.getImageDecoderFactory`.\n\nThe following example uses Glide to load an image: \n\n### Kotlin\n\n```kotlin\nval glideImageDecoderFactory: ImageDecoder.Factory =\n ExternallyLoadedImageDecoder.Factory { request: ExternalImageRequest -\u003e\n GlideFutures.submit(Glide.with(context).asBitmap().load(request.uri))\n }\nval player: Player =\n ExoPlayer.Builder(context)\n .setRenderersFactory(\n object : DefaultRenderersFactory(context) {\n override fun getImageDecoderFactory(): ImageDecoder.Factory {\n return glideImageDecoderFactory\n }\n }\n )\n .build()\n```\n\n### Java\n\n```java\nImageDecoder.Factory glideImageDecoderFactory =\n new ExternallyLoadedImageDecoder.Factory(\n request -\u003e GlideFutures.submit(\n Glide.with(context).asBitmap().load(request.uri)));\nPlayer player =\n new ExoPlayer.Builder(context)\n .setRenderersFactory(\n new DefaultRenderersFactory(context) {\n @Override\n protected ImageDecoder.Factory getImageDecoderFactory() {\n return glideImageDecoderFactory;\n }\n })\n .build();\n```\n\n\u003cbr /\u003e\n\n### Image preloading with an image loading library\n\nDuring playback, the player requests to preload the next image once the previous\nitem in the playlist has fully loaded. When using an external image loading\nlibrary, you must specify an `ExternalLoader` to trigger this preloading. If no\npreloading is possible or required, this loader still needs to be provided, but\ncan do nothing.\n\nThe following example uses Glide to ensure that the requested image is preloaded\nto disk: \n\n### Kotlin\n\n```kotlin\nval glidePreloader = ExternalLoader { request: LoadRequest -\u003e\n GlideFutures.submit(\n Glide.with(context)\n .asFile()\n .apply(\n RequestOptions.diskCacheStrategyOf(DiskCacheStrategy.DATA)\n .priority(Priority.HIGH)\n .skipMemoryCache(true)\n )\n .load(request.uri)\n )\n}\nval player =\n ExoPlayer.Builder(context)\n .setMediaSourceFactory(DefaultMediaSourceFactory(context)\n .setExternalImageLoader(glidePreloader))\n .build()\n```\n\n### Java\n\n```java\nExternalLoader glidePreloader =\n request -\u003e\n GlideFutures.submit(\n Glide.with(context)\n .asFile()\n .apply(\n diskCacheStrategyOf(DiskCacheStrategy.DATA)\n .priority(Priority.HIGH)\n .skipMemoryCache(true))\n .load(request.uri));\nPlayer player =\n new ExoPlayer.Builder(context)\n .setMediaSourceFactory(new DefaultMediaSourceFactory(context)\n .setExternalImageLoader(glidePreloader))\n .build();\n```\n\n\u003cbr /\u003e"]]