بدء استخدام "مشغّل الوسائط"

تقدّم هذه المقالة المفاهيم الأساسية التي يجب أن تكون على دراية بها قبل استخدام "مشغّل الوسائط".

فئات الصوت والفيديو

تعرض الفئات التالية الصوت والفيديو في إطار عمل Android:

• MediaPlayer: هذه الفئة هي واجهة برمجة التطبيقات الأساسية لتشغيل الصوت والفيديو.
• AudioManager: تدير هذه الفئة مصادر الصوت ومصدر إخراج الصوت على الجهاز.

بيانات البيان

قبل البدء في تطوير تطبيقك باستخدام MediaPlayer، تأكَّد من أنّ البيان يتضمّن البيانات المناسبة للسماح باستخدام الميزات ذات الصلة.

• إذن الوصول إلى الإنترنت: إذا كنت تستخدم MediaPlayer لبث محتوى مستند إلى الشبكة، يجب أن يطلب تطبيقك الوصول إلى الشبكة.

  <uses-permission android:name="android.permission.INTERNET" />
  

• إذن قفل التنشيط: إذا كان تطبيق المشغّل بحاجة إلى منع الشاشة من التعتيم أو المعالج من الدخول في وضع السكون، أو إذا كان يستخدم الطريقتَين MediaPlayer.setScreenOnWhilePlaying(boolean) أو MediaPlayer.setWakeMode(android.content.Context, int)، يجب طلب هذا الإذن.

  <uses-permission android:name="android.permission.WAKE_LOCK" />
  

استخدام فئة MediaPlayer

تُعدّ فئة MediaPlayer مكوّنًا أساسيًا في إطار عمل الوسائط. يمكن لكائن من هذه الفئة جلب كل من الصوت والفيديو وفك ترميزهما وتشغيلهما بأقل إعداد ممكن. تتوافق MediaPlayer مع عدة مصادر وسائط، بما في ذلك:

• المراجع المحلية
• معرّفات الموارد المنتظمة الداخلية، مثل المعرّف الذي قد تحصل عليه من Content Resolver
• عناوين URL الخارجية (البث)

للاطّلاع على قائمة بتنسيقات الوسائط التي يتوافق معها Android، يُرجى الانتقال إلى صفحة تنسيقات الوسائط المتوافقة.

أمثلة على العمل مع مصادر الصوت

في ما يلي مثال على كيفية تشغيل الصوت المتاح كمورد أولي محلي (محفوظ في دليل res/raw/ الخاص بتطبيقك):

Kotlin

var mediaPlayer = MediaPlayer.create(context, R.raw.sound_file_1)
mediaPlayer.start() // no need to call prepare(); create() does that for you

Java

MediaPlayer mediaPlayer = MediaPlayer.create(context, R.raw.sound_file_1);
mediaPlayer.start(); // no need to call prepare(); create() does that for you

في هذه الحالة، يكون المورد "الأولي" ملفًا لا يحاول النظام تحليله بأي طريقة معيّنة. ومع ذلك، يجب ألا يكون محتوى هذا المورد صوتًا أوليًا. بل يجب أن يكون ملف وسائط تم ترميزه وتنسيقه بشكلٍ سليم بأحد التنسيقات المتوافقة.

في ما يلي كيفية التشغيل من معرّف موارد منتظم متاح محليًا في النظام (حصلت عليه من خلال Content Resolver، مثلاً):

Kotlin

val myUri: Uri = .... // initialize Uri here
val mediaPlayer = MediaPlayer().apply {
    setAudioAttributes(
        AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            .setUsage(AudioAttributes.USAGE_MEDIA)
            .build()
    )
    setDataSource(applicationContext, myUri)
    prepare()
    start()
}

Java

Uri myUri = ....; // initialize Uri here
MediaPlayer mediaPlayer = new MediaPlayer();
mediaPlayer.setAudioAttributes(
    new AudioAttributes.Builder()
        .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .build()
);
mediaPlayer.setDataSource(getApplicationContext(), myUri);
mediaPlayer.prepare();
mediaPlayer.start();

يبدو التشغيل من عنوان URL بعيد باستخدام بث HTTP على النحو التالي:

Kotlin

val url = "http://........" // your URL here
val mediaPlayer = MediaPlayer().apply {
    setAudioAttributes(
        AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            .setUsage(AudioAttributes.USAGE_MEDIA)
            .build()
    )
    setDataSource(url)
    prepare() // might take long! (for buffering, etc)
    start()
}

Java

String url = "http://........"; // your URL here
MediaPlayer mediaPlayer = new MediaPlayer();
mediaPlayer.setAudioAttributes(
    new AudioAttributes.Builder()
        .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .build()
);
mediaPlayer.setDataSource(url);
mediaPlayer.prepare(); // might take long! (for buffering, etc)
mediaPlayer.start();

ملاحظة: إذا كنت تمرِّر عنوان URL لبث ملف وسائط على الإنترنت، يجب أن يكون الملف قابلاً للتنزيل التدريجي.

تنبيه: يجب إما رصد IllegalArgumentException و IOException أو تمريرهما عند استخدام setDataSource() لأنّ الملف الذي تشير إليه قد لا يكون موجودًا.

استخدام الإعداد غير المتزامن لتحسين الأداء

ضَع الأداء في الاعتبار عند استخدام MediaPlayer. على سبيل المثال، قد يستغرق تنفيذ طلب prepare() وقتًا طويلاً، لأنّه قد يتضمّن جلب بيانات الوسائط وفك ترميزها. لذلك، على غرار أي طريقة قد يستغرق تنفيذها وقتًا طويلاً لتنفيذها، لا تستدعِها أبدًا من سلسلة واجهة المستخدم لتطبيقك. سيؤدي ذلك إلى توقّف واجهة المستخدم عن الاستجابة إلى أن تعرض الطريقة قيمة، ما يؤدي إلى تجربة سيئة للمستخدم ويمكن أن يتسبب في حدوث خطأ "التطبيق لا يستجيب" (ANR).

لتجنُّب تعليق سلسلة واجهة المستخدم، أنشئ سلسلة تعليمات أخرى لإعداد الـ MediaPlayer وإشعار سلسلة التعليمات الرئيسية عند الانتهاء. يوفر إطار العمل طريقة ملائمة لإنجاز طريقة prepareAsync() لتنفيذ هذه المهمة. تبدأ هذه الطريقة في إعداد الوسائط في الخلفية وتعرض قيمة على الفور. عند الانتهاء من إعداد الوسائط، يتم استدعاء طريقة onPrepared() في MediaPlayer.OnPreparedListener التي تم ضبطها من خلال setOnPreparedListener().

مزيد من المعلومات

‫Jetpack Media3 هو الحل المقترَح لتشغيل الوسائط في تطبيقك. مزيد من المعلومات حوله

تتناول هذه الصفحات مواضيع متعلقة بتسجيل الصوت والفيديو وتخزينهما وتشغيلهما:

• تنسيقات الوسائط المتوافقة
• MediaRecorder
• تخزين البيانات