MediaSession — المفاهيم الأساسية والتكامل وآلية العمل في Android

ما هو MediaSession؟

MediaSession هو مكون نظام في Android يسمح للتطبيق بالإعلان عن نشاطه الوسائطي واستقبال أوامر التحكم من مصادر خارجية. عندما يضغط المستخدم على زر التشغيل في سماعة Bluetooth، يقوم النظام بتمرير هذا الحدث إلى MediaSession النشطة، ويستجيب التطبيق من خلال Callback الخاص به.

قبل Android 5.0، كان يُستخدم RemoteControlClient لهذا الغرض، لكنه لم يوفر المرونة الكافية ولم يدعم السيناريوهات الحديثة — Android Auto والساعات الذكية ومكبرات الصوت الذكية. تم تقديم MediaSession في API 21 وأصبح المعيار الفعلي لجميع تطبيقات Android التي تحتوي على تشغيل صوتي وفيديو.

وفقًا لوثائق مطوري Android (2026)، يجب على التطبيق إنشاء MediaSession واحدة لكل مصدر تشغيل مستقل. في أي لحظة، يمكن أن تكون جلسة واحدة فقط نشطة — أي جلسة جديدة تقوم تلقائيًا بإلغاء تنشيط الجلسة السابقة.

MediaSession وMediaBrowserService

يوفر الجمع بين MediaSession وMediaBrowserService دورة كاملة لإدارة الوسائط: يقدم الخدمة شجرة محتوى (قوائم تشغيل، كتالوجات)، وتقبل الجلسة أوامر التنقل والتشغيل. هذه هي البنية الموصى بها من Google لمشغلات الموسيقى والبودكاست والكتب الصوتية.

يعمل MediaBrowserService كخدمة أمامية مع إشعار، مما يضمن استمرار عمل التطبيق حتى عند إتلاف النشاط. هذا أمر بالغ الأهمية لمشغلات الصوت التي يجب أن تستمر في التشغيل عند تصغير التطبيق.

كيف يعمل MediaSession

تدعم الجلسة نوعين من التفاعل: تستقبل الأوامر من MediaController (الجانب العميل) وتبث الحالة من خلال PlaybackState. يمكن أن يكون MediaController في نفس العملية أو في تطبيق منفصل — يقوم النظام بتوجيه الطلبات عبر SessionToken.

عندما يستدعي المستخدم المساعد الصوتي لـ Android ويقول “شغل المسار التالي”، يجد النظام MediaSession النشطة من خلال اتصالها بـ MediaBrowserService ويرسل الأمر ACTION_SKIP_TO_NEXT. يتلقى Callback التطبيق استدعاء onSkipToNext() ويقوم بتحديث PlaybackState.

يؤدي تحديث PlaybackState عبر setPlaybackState() إلى إعلام جميع مثيلات MediaController المتصلة فورًا. يتلقى مركز الوسائط النظامي وجهاز Bluetooth وAndroid Auto التحديث في وقت واحد — لا يتجاوز التأخير 50 مللي ثانية في الظروف العادية.

PlaybackState وبياناته الوصفية

يحتوي PlaybackState على علامات الحالة الرئيسية: isPlaying والموضع والسرعة والإجراءات المتاحة (تشغيل، إيقاف مؤقت، بحث، إيقاف). بدون PlaybackState مملوء بشكل صحيح، لا يعرف النظام الأوامر التي يدعمها التطبيق ولا يرسل الأحداث المقابلة.

تكمل البيانات الوصفية (MediaMetadata) الحالة بمعلومات حول المسار الحالي — العنوان والفنان وURI غلاف الألبوم. يستخدم Android Auto والساعات الذكية MediaMetadata لعرض المعلومات على الشاشة. وفقًا لـ Google I/O 2024، فإن الملء الصحيح لـ MediaMetadata يزيد من ظهور التطبيق في مشغلات الطرف الثالث بنسبة 40%.

المكونات الأساسية لـ MediaSession

تتكون بنية MediaSession من أربعة مكونات مترابطة، كل منها يؤدي وظيفته الخاصة. يحتاج المطور إلى تنفيذ الأربعة جميعًا للتكامل الكامل مع النظام.

• MediaSessionCompat — الفئة الرئيسية للجلسة، يتم إنشاؤها مع علامة التطبيق وتقبل PendingIntent لأزرار الوسائط.
• MediaSession.Callback — معالج الأوامر. ينفذ onPlay وonPause وonSkipToNext وonSeekTo وطرق أخرى.
• PlaybackStateCompat — حالة المشغل الحالية. يحتوي على علامات وموضع وسرعة وقائمة الإجراءات المتاحة.
• MediaMetadataCompat — البيانات الوصفية للوسائط الحالية: العنوان والفنان والألبوم والغلاف والمدة.

دورة حياة MediaSession

يتم إنشاء الجلسة في طريقة onCreate لخدمة أو نشاط عن طريق استدعاء MediaSessionCompat(context, tag). بعد الإنشاء، يجب استدعاء setFlags(FLAG_HANDLES_MEDIA_BUTTONS | FLAG_HANDLES_TRANSPORT_CONTROLS). في onDestroy، يتم استدعاء release() لتحرير موارد النظام.

الإدارة غير الصحيحة لدورة الحياة هي أحد الأخطاء الشائعة. إذا لم يتم استدعاء release()، تبقى الجلسة في النظام، وقد يتلقى التطبيق التالي حالة قديمة. يُظهر Android 13+ تحذيرًا في Logcat عند تسرب الجلسات.

دمج MediaSession في التطبيق

يبدأ التكامل الأساسي بإنشاء جلسة وتنفيذ Callback. يُوصى باستخدام MediaSessionCompat من مكتبة AndroidX media، التي توفر API موحدة لجميع إصدارات Android — من API 14 إلى 35.

إنشاء MediaSession وCallback

class MusicService : Service() {

    private lateinit var mediaSession: MediaSessionCompat
    private lateinit var stateBuilder: PlaybackStateCompat.Builder

    override fun onCreate() {
        super.onCreate()

        mediaSession = MediaSessionCompat(this, "MusicService")
        mediaSession.setFlags(
            MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS
                or MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS
        )
        mediaSession.setCallback(MediaSessionCallback())
        updatePlaybackState(false)
    }

    private inner class MediaSessionCallback : MediaSessionCompat.Callback() {
        override fun onPlay() {
            updatePlaybackState(true)
        }

        override fun onPause() {
            updatePlaybackState(false)
        }
    }

    private fun updatePlaybackState(isPlaying: Boolean) {
        stateBuilder = PlaybackStateCompat.Builder()
            .setState(
                if (isPlaying) PlaybackStateCompat.STATE_PLAYING
                else PlaybackStateCompat.STATE_PAUSED,
                AudioTrackCompat.CURRENT_POSITION_NOT_SET,
                1.0f
            )
            .setActions(
                PlaybackStateCompat.ACTION_PLAY
                    or PlaybackStateCompat.ACTION_PAUSE
                    or PlaybackStateCompat.ACTION_SKIP_TO_NEXT
                    or PlaybackStateCompat.ACTION_SKIP_TO_PREVIOUS
            )
        mediaSession.setPlaybackState(stateBuilder.build())
    }

    override fun onDestroy() {
        mediaSession.release()
        super.onDestroy()
    }
}

في هذا المثال، يتم إنشاء MediaSession بعلامة MusicService وعلامات لمعالجة أزرار الوسائط. يقوم Callback بتنفيذ onPlay وonPause، وتحديث PlaybackState. تعلن طريقة setActions عن الإجراءات المتاحة التي يعرضها النظام على شاشة القفل وفي مركز الوسائط.

إعداد MediaMetadata

private fun setMetadata(title: String, artist: String) {
    val metadata = MediaMetadataCompat.Builder()
        .putString(MediaMetadataCompat.METADATA_KEY_TITLE, title)
        .putString(MediaMetadataCompat.METADATA_KEY_ARTIST, artist)
        .putLong(MediaMetadataCompat.METADATA_KEY_DURATION, 300000L)
        .putString(MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI, albumArtUrl)
        .build()
    mediaSession.setMetadata(metadata)
}

يجب تحديث البيانات الوصفية عند كل تغيير للمسار. يستخدم النظام METADATA_KEY_TITLE وMETADATA_KEY_ARTIST لعرض المعلومات على شاشات Bluetooth في السيارات والأجهزة القابلة للارتداء. إذا لم يتم تعيين URI الغلاف، سيعرض المشغل عنصرًا نائبًا رماديًا.

معالجة أوامر الوسائط من Bluetooth وسماعات الرأس

ترسل سماعات Bluetooth الأوامر من خلال ملف التعريف AVRCP 1.6+. يقوم Android ببث هذه الأوامر كنوايا ACTION_MEDIA_BUTTON، التي يتم اعتراضها بواسطة MediaSession عند تعيين علم FLAG_HANDLES_MEDIA_BUTTONS.

عندما يضغط المستخدم على زر التشغيل في سماعات Bluetooth، يقوم النظام بإنشاء KeyEvent بالرمز KEYCODE_MEDIA_PLAY، الذي يتم إرساله إلى طريقة onMediaButtonEvent في Callback. إذا تم تنفيذ onPlay() في Callback، يقوم النظام باستدعائه مباشرة. ضغطة واحدة على زر سماعة الرأس ترسل KEYCODE_MEDIA_PLAY_PAUSE — يجب على المشغل تبديل الحالة.

معالجة السيناريوهات المعقدة بأزرار متعددة

يمكن أن تحتوي سماعات Bluetooth الحديثة على ما يصل إلى 5 أزرار: رفع/خفض الصوت، تشغيل/إيقاف مؤقت، التالي، السابق. يولد كل زر KeyEvent الخاص به، الذي يجب معالجته بشكل صحيح بواسطة Callback. عادةً ما يتم تفسير الضغط المزدوج على زر التشغيل/الإيقاف المؤقت على أنه انتقال إلى المسار التالي (ACTION_SKIP_TO_NEXT) في العديد من سماعات الرأس.

وفقًا لوثيقة تعريف توافق Android (2026)، يجب على جميع التطبيقات التي تحتوي على محتوى وسائط معالجة KEYCODE_MEDIA_PLAY_PAUSE بشكل صحيح. يؤدي تجاهل هذا المطلب إلى انخفاض تلقائي في تصنيف التطبيق في Google Play لفئة الموسيقى والصوت.

المزامنة مع مركز الوسائط النظامي

بدءًا من Android 11، يعرض مركز الوسائط النظامي (لوحة التحكم في الوسائط) ما يصل إلى 5 جلسات حديثة من MediaSession في لوحة الإشعارات. يمكن للمستخدم التحكم في المشغل دون فتح التطبيق. للعرض الصحيح، يجب تنفيذ MediaBrowserService وملء PlaybackState بشكل صحيح.

تعرض لوحة التحكم في الوسائط: عنوان المسار والفنان والغلاف (من MediaMetadata) وأزرار التحكم (من إجراءات PlaybackState المتاحة). إذا لم يقم التطبيق بتحديث PlaybackState مرة واحدة على الأقل كل 10 ثوانٍ أثناء التشغيل النشط، يخفي مركز الوسائط الجلسة من اللوحة.

الخدمة الأمامية مع إشعار

private fun startForegroundService() {
    val notification = NotificationCompat.Builder(this, "media_channel")
        .setSmallIcon(R.drawable.ic_play)
        .setContentTitle("جارٍ التشغيل الآن")
        .setContentText(currentTrackTitle)
        .setPriority(NotificationCompat.PRIORITY_LOW)
        .setStyle(
            androidx.media.app.NotificationCompat.MediaStyle()
                .setMediaSession(mediaSession.sessionToken)
        )
        .build()
    startForeground(1001, notification)
}

يرتبط إشعار MediaStyle بـ MediaSession عبر sessionToken ويعرض أزرار الوسائط القياسية. بدون MediaStyle، سيظهر الإشعار كتنبيه عادي بدون أزرار تحكم. يتطلب Android 13+ إذنًا صريحًا POST_NOTIFICATIONS للعرض.