تتناول هذه الأدلة واجهات برمجة التطبيقات MediaCompat API التي لم تعد يتم تحديثها. ننصحك بشدة باستخدام مكتبة
Jetpack Media3 بدلاً من ذلك.
إنشاء نشاط لمشغّل فيديو
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
عندما يتلقّى النشاط طريقة معاودة الاتصال بمراحل نشاط onCreate()
، يجب تنفيذ الخطوات التالية:
- إنشاء جلسة الوسائط وإعدادها
- ضبط معاودة الاتصال لجلسة الوسائط
- اضبط مستقبل زر الوسائط لجلسة الوسائط على "خالٍ" بحيث لا يؤدي حدث زر الوسائط إلى إعادة تشغيل المشغّل عندما لا يكون مرئيًا. ولا يؤثِّر ذلك إلا في الأجهزة التي تعمل بالإصدار 5.0 من نظام التشغيل Android (المستوى 21 من واجهة برمجة التطبيقات) والإصدارات الأحدث.
- إنشاء وحدة التحكُّم في الوسائط وتهيئتها
يوضح رمز onCreate()
أدناه هذه الخطوات:
Kotlin
private lateinit var mediaSession: MediaSessionCompat
public override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Create a MediaSessionCompat
mediaSession = MediaSessionCompat(this, LOG_TAG).apply {
// Enable callbacks from MediaButtons and TransportControls
setFlags(MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS or
MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS)
// Do not let MediaButtons restart the player when the app is not visible
setMediaButtonReceiver(null)
// Set an initial PlaybackState with ACTION_PLAY, so media buttons can start the player
val stateBuilder = PlaybackStateCompat.Builder()
.setActions(PlaybackStateCompat.ACTION_PLAY or PlaybackStateCompat.ACTION_PLAY_PAUSE)
setPlaybackState(stateBuilder.build())
// MySessionCallback has methods that handle callbacks from a media controller
setCallback(MySessionCallback())
}
// Create a MediaControllerCompat
MediaControllerCompat(this, mediaSession).also { mediaController ->
MediaControllerCompat.setMediaController(this, mediaController)
}
}
Java
MediaSessionCompat mediaSession;
PlaybackStateCompat.Builder stateBuilder;
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Create a MediaSessionCompat
mediaSession = new MediaSessionCompat(this, LOG_TAG);
// Enable callbacks from MediaButtons and TransportControls
mediaSession.setFlags(
MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS |
MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS);
// Do not let MediaButtons restart the player when the app is not visible
mediaSession.setMediaButtonReceiver(null);
// Set an initial PlaybackState with ACTION_PLAY, so media buttons can start the player
stateBuilder = new PlaybackStateCompat.Builder()
.setActions(
PlaybackStateCompat.ACTION_PLAY |
PlaybackStateCompat.ACTION_PLAY_PAUSE);
mediaSession.setState(stateBuilder.build());
// MySessionCallback has methods that handle callbacks from a media controller
mediaSession.setCallback(new MySessionCallback());
// Create a MediaControllerCompat
MediaControllerCompat mediaController =
new MediaControllerCompat(this, mediaSession);
MediaControllerCompat.setMediaController(this, mediaController);
}
عند إغلاق أحد التطبيقات، يتلقّى النشاط استدعاءَي onPause()
وonStop()
على التوالي. إذا كان اللاعب قيد التشغيل، يجب إيقافه قبل أن ينتهي النشاط. يعتمد اختيار معاودة الاتصال التي سيتم استخدامها على إصدار Android الذي تستخدمه.
في الإصدار Android 6.0 (المستوى 23 لواجهة برمجة التطبيقات) والإصدارات الأقدم، ليس هناك ما يضمن استدعاء onStop()
. يمكن أن يتم استدعاؤه بعد 5 ثوانٍ من اختفاء نشاطك. لذلك، في إصدارات Android الأقدم من 7.0، يجب أن يتوقّف تشغيل تطبيقك في onPause()
. في الإصدار Android 7.0 والإصدارات الأحدث، يتصل النظام بـ onStop()
فور عدم ظهور النشاط، لذلك لا مشكلة في ذلك.
في ما يلي ملخّص:
- في الإصدار 6.0 من نظام التشغيل Android والإصدارات الأقدم، أوقِف المشغّل في معاودة الاتصال على جهاز
onPause()
.
- في الإصدار 7.0 من Android والإصدارات الأحدث، أوقِف المشغّل عند معاودة الاتصال على "
onStop()
".
عندما يتلقّى النشاط معاودة الاتصال "onDestroy()
"، يجب رفع إصبعك عن المشغّل ومحوه.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Building a video player activity\n\nWhen the activity receives the `onCreate()` lifecycle callback method it should perform these steps:\n\n- Create and [initialize the media session](/guide/topics/media-apps/working-with-a-media-session#init-session)\n- Set the media session callback\n- Set the media session's media button receiver to null so that a [media button event](/guide/topics/media-apps/mediabuttons#restarting-inactive-mediasessions) won't restart the player when it is not visible. This only affects Android 5.0 (API level 21) and higher devices.\n- Create and initialize the media controller\n\nThe `onCreate()` code below demonstrates these steps: \n\n### Kotlin\n\n```kotlin\nprivate lateinit var mediaSession: MediaSessionCompat\n\npublic override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n\n // Create a MediaSessionCompat\n mediaSession = MediaSessionCompat(this, LOG_TAG).apply {\n\n // Enable callbacks from MediaButtons and TransportControls\n setFlags(MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS or\n MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS)\n\n // Do not let MediaButtons restart the player when the app is not visible\n setMediaButtonReceiver(null)\n\n // Set an initial PlaybackState with ACTION_PLAY, so media buttons can start the player\n val stateBuilder = PlaybackStateCompat.Builder()\n .setActions(PlaybackStateCompat.ACTION_PLAY or PlaybackStateCompat.ACTION_PLAY_PAUSE)\n setPlaybackState(stateBuilder.build())\n\n // MySessionCallback has methods that handle callbacks from a media controller\n setCallback(MySessionCallback())\n }\n\n // Create a MediaControllerCompat\n MediaControllerCompat(this, mediaSession).also { mediaController -\u003e\n MediaControllerCompat.setMediaController(this, mediaController)\n }\n}\n```\n\n### Java\n\n```java\nMediaSessionCompat mediaSession;\nPlaybackStateCompat.Builder stateBuilder;\n\n@Override\npublic void onCreate(Bundle savedInstanceState) {\n super.onCreate(savedInstanceState);\n\n // Create a MediaSessionCompat\n mediaSession = new MediaSessionCompat(this, LOG_TAG);\n\n // Enable callbacks from MediaButtons and TransportControls\n mediaSession.setFlags(\n MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS |\n MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS);\n\n // Do not let MediaButtons restart the player when the app is not visible\n mediaSession.setMediaButtonReceiver(null);\n\n // Set an initial PlaybackState with ACTION_PLAY, so media buttons can start the player\n stateBuilder = new PlaybackStateCompat.Builder()\n .setActions(\n PlaybackStateCompat.ACTION_PLAY |\n PlaybackStateCompat.ACTION_PLAY_PAUSE);\n mediaSession.setState(stateBuilder.build());\n\n // MySessionCallback has methods that handle callbacks from a media controller\n mediaSession.setCallback(new MySessionCallback());\n\n // Create a MediaControllerCompat\n MediaControllerCompat mediaController =\n new MediaControllerCompat(this, mediaSession);\n\n MediaControllerCompat.setMediaController(this, mediaController);\n}\n```\n\nWhen an app is closed, the activity receives the `onPause()` and `onStop()` callbacks in succession. If the player is playing, you must stop it before its activity goes away. The choice of which callback to use depends on what Android version you're running.\n\nIn Android 6.0 (API level 23) and earlier there is no guarantee of when `onStop()` is called; it could get called 5 seconds after your activity disappears. Therefore, in Android versions earlier than 7.0, your app should stop playback in `onPause()`. In Android 7.0 and beyond, the system calls `onStop()` as soon as the activity becomes not visible, so this is not a problem.\n\nTo summarize:\n\n- In Android version 6.0 and earlier, stop the player in the `onPause()` callback.\n- In Android version 7.0 and later, stop the player in the `onStop()` callback.\n\nWhen the activity receives the `onDestroy()` callback, it should release and clean up your player."]]