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

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

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

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

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

في ما يلي كيفية تشغيل المحتوى من عنوان URI متاح محليًا في النظام (الذي حصلت عليه من خلال 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();

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

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

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

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

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

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