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

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

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

تعمل الفئات التالية على تشغيل الصوت والفيديو في إطار عمل 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/ في تطبيقك):

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

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

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

في ما يلي كيفية تشغيل المحتوى من عنوان URI متاح على الجهاز (مثل العنوان الذي حصلت عليه من خلال Content Resolver):

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()
}

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:

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()
}

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();

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

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

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

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

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

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

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