واجهة برمجة تطبيقات الكاميرا

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

ملاحظة: توضِّح هذه الصفحة فئة Camera التي تم إيقافها نهائيًا. ننصحك باستخدام مكتبة CameraX من Jetpack أو فئة camera2، في حالات استخدام معيّنة. يعمل كلّ من CameraX وCamera2 على الإصدار 5.0 من نظام التشغيل Android (المستوى 21 لواجهة برمجة التطبيقات) والإصدارات الأحدث.

الاعتبارات

قبل تفعيل تطبيقك لاستخدام الكاميرات على أجهزة Android، عليك مراعاة بعض الأسئلة حول كيفية استخدام تطبيقك لهذه الميزة في الجهاز.

• متطلبات الكاميرا: هل استخدام الكاميرا مهم جدًا لتطبيقك لدرجة أنّك لا تريد تثبيت تطبيقك على جهاز لا يحتوي على كاميرا؟ إذا كان الأمر كذلك، عليك الإفصاح عن متطلّبات الكاميرا في ملف البيان.
• صورة سريعة أو كاميرا مخصّصة: كيف سيستخدم تطبيقك الكاميرا؟ هل تريد فقط التقاط صورة سريعة أو مقطع فيديو، أم سيقدّم تطبيقك طريقة جديدة لاستخدام الكاميرات؟ لالتقاط صورة أو مقطع سريع، ننصحك باستخدام تطبيقات الكاميرا الحالية. لتطوير ميزة كاميرا مخصّصة، اطّلِع على القسم إنشاء تطبيق كاميرا.
• متطلّبات الخدمات التي تعمل في المقدّمة: متى يتفاعل تطبيقك مع الكاميرا؟ في الإصدار 9 من Android (المستوى 28 لواجهة برمجة التطبيقات) والإصدارات الأحدث، لا يمكن للتطبيقات التي تعمل في الخلفية الوصول إلى الكاميرا. لذلك، يجب استخدام الكاميرا إما عندما يكون تطبيقك في المقدّمة أو كجزء من خدمة تعمل في المقدّمة.
• مساحة التخزين: هل الصور أو الفيديوهات التي ينشئها تطبيقك مخصّصة ليتم عرضها فقط في تطبيقك أو مشاركتها كي تتمكّن تطبيقات أخرى، مثل "معرض الصور" أو تطبيقات الوسائط ووسائل التواصل الاجتماعي الأخرى، من استخدامها؟ هل تريد أن تظل الصور والفيديوهات متاحة حتى إذا تمت إزالة التطبيق؟ اطّلِع على قسم حفظ ملفات الوسائط لتحديد كيفية تنفيذ هذه الخيارات.

الأساسيات

يتيح إطار عمل Android التقاط الصور والفيديوهات من خلال واجهة برمجة التطبيقات android.hardware.camera2 أو الكاميرا Intent. في ما يلي klassen ذات الصلة:

android.hardware.camera2

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

Camera

هذه الفئة هي واجهة برمجة التطبيقات القديمة التي تم إيقافها نهائيًا للتحكّم في كاميرات الأجهزة.

SurfaceView

تُستخدَم هذه الفئة لتقديم معاينة كاميرا مباشرة للمستخدم.

MediaRecorder

تُستخدَم هذه الفئة لتسجيل فيديو من الكاميرا.

Intent

يمكن استخدام نوع إجراء النية MediaStore.ACTION_IMAGE_CAPTURE أو MediaStore.ACTION_VIDEO_CAPTURE لالتقاط صور أو فيديوهات بدون استخدام عنصر Camera مباشرةً.

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

قبل بدء تطوير تطبيقك باستخدام واجهة برمجة التطبيقات Camera API، يجب التأكّد من أنّ البيان يحتوي على التصاريح المناسبة للسماح باستخدام أجهزة الكاميرا وغيرها من الميزات ذات الصلة.

• إذن الوصول إلى الكاميرا: يجب أن يطلب تطبيقك إذنًا لاستخدام كاميرا الجهاز.

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

  ملاحظة: إذا كنت تستخدم الكاميرا من خلال تشغيل تطبيق كاميرا حالي، لا يحتاج تطبيقك إلى طلب هذا الإذن.

• ميزات الكاميرا: يجب أن يوضّح تطبيقك أيضًا استخدام ميزات الكاميرا، على سبيل المثال:

  <uses-feature android:name="android.hardware.camera" />

  للحصول على قائمة بميزات الكاميرا، يُرجى الاطّلاع على مرجع ميزات البيان.

  تؤدي إضافة ميزات الكاميرا إلى البيان إلى منع Google Play من تثبيت تطبيقك على الأجهزة التي لا تتضمّن كاميرا أو لا تتيح استخدام ميزات الكاميرا التي تحديدها. لمزيد من المعلومات حول استخدام الفلترة المستندة إلى الميزات مع Google Play، يُرجى الاطّلاع على مقالة Google Play والفلترة المستندة إلى الميزات.

  إذا كان تطبيقك يمكنه استخدام كاميرا أو ميزة كاميرا لعمله بشكل صحيح، ولكنه لا يتطلّب ذلك، عليك تحديد ذلك في ملف البيان عن طريق تضمين السمة android:required وضبطها على false:

  <uses-feature android:name="android.hardware.camera" android:required="false" />

• إذن الوصول إلى مساحة التخزين: يمكن لتطبيقك حفظ الصور أو الفيديوهات في مساحة التخزين الخارجية للجهاز (بطاقة SD) إذا كان يستهدف الإصدار Android 10 (المستوى 29 من واجهة برمجة التطبيقات) أو إصدارًا أقل، ويحدّد ما يلي في البيان:

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

• إذن تسجيل الصوت: لتسجيل الصوت أثناء تسجيل الفيديو، يجب أن يطلب تطبيقك إذن تسجيل الصوت.

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

• إذن تحديد الموقع الجغرافي: إذا كان تطبيقك يضع علامات على الصور باستخدام معلومات الموقع الجغرافي حسب نظام تحديد المواقع العالمي (GPS)، يجب طلب إذن ACCESS_FINE_LOCATION. يُرجى العلم أنّه إذا كان تطبيقك يستهدف الإصدار 5.0 من نظام التشغيل Android (المستوى 21 من واجهة برمجة التطبيقات) أو إصدارًا أحدث، عليك أيضًا الإفصاح عن أنّ تطبيقك يستخدم نظام تحديد المواقع العالمي (GPS) في الجهاز:

  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  ...
  <!-- Needed only if your app targets Android 5.0 (API level 21) or higher. -->
  <uses-feature android:name="android.hardware.location.gps" />

  لمزيد من المعلومات عن الحصول على الموقع الجغرافي للمستخدم، اطّلِع على استراتيجيات الموقع الجغرافي.

استخدام تطبيقات الكاميرا الحالية

هناك طريقة سريعة لتفعيل التقاط الصور أو الفيديوهات في تطبيقك بدون الكثير من الرموز البرمجية الإضافية، وهي استخدام Intent لتشغيل تطبيق كاميرا Android حالي. يمكنك الاطّلاع على التفاصيل في الدرسَين التدريبيَين التقاط الصور بسهولة و تسجيل الفيديوهات بسهولة.

إنشاء تطبيق كاميرا

قد يطلب بعض المطوّرين واجهة مستخدم للكاميرا مخصّصة لمظهر تطبيقهم أو توفّر ميزات خاصة. يمكن أن توفّر كتابة رمزك الخاص لالتقاط الصور تجربة أكثر إقناعًا للمستخدمين.

ملاحظة: يتناول الدليل التالي واجهة برمجة التطبيقات Camera القديمة التي تمّ إيقافها نهائيًا. بالنسبة إلى تطبيقات الكاميرا الجديدة أو المتقدّمة، يُنصح باستخدام واجهة برمجة التطبيقات android.hardware.camera2 الجديدة.

في ما يلي الخطوات العامة لإنشاء واجهة كاميرا مخصّصة لتطبيقك:

• رصد الكاميرا والوصول إليها: يمكنك إنشاء رمز للتحقّق من توفّر الكاميرات وطلب الوصول إليها.
• إنشاء فئة معاينة: يمكنك إنشاء فئة معاينة للكاميرا تُنشئ فئة SurfaceView وتنفِّذ واجهة SurfaceHolder. يعرِض هذا الصف معاينة للصور المباشرة من الكاميرا.
• إنشاء تنسيق معاينة: بعد الحصول على فئة معاينة الكاميرا، أنشئ تنسيق عرض يضمّ المعاينة وعناصر التحكّم في واجهة المستخدم التي تريدها.
• إعداد مستمعي عمليات الالتقاط: يمكنك ربط مستمعي عناصر التحكّم في الواجهة لبدء التقاط الصور أو الفيديوهات استجابةً لإجراءات المستخدم، مثل الضغط على أحد buttons.
• التقاط الملفات وحفظها: يمكنك إعداد الرمز البرمجي لالتقاط الصور أو الفيديوهات وحفظ النتيجة.
• إخلاء الكاميرا: بعد استخدام الكاميرا، يجب أن يُخلي تطبيقك سبيلها بشكل صحيح لاستخدامها من قِبل التطبيقات الأخرى.

إنّ جهاز الكاميرا هو مورد مشترَك يجب إدارته بعناية حتى لا يتعارض تطبيقك مع التطبيقات الأخرى التي قد تريد استخدامه أيضًا. تتناول الأقسام التالية كيفية رصد أجهزة الكاميرا وطلب الوصول إليها والتقاط الصور أو الفيديوهات وكيفية تحرير الكاميرا عند انتهاء تطبيقك من استخدامها.

تحذير: تذكَّر تحرير Camera العنصر من خلال استدعاء Camera.release() عند انتهاء تطبيقك من استخدامه. إذا لم يُغلق تطبيقك الكاميرا بشكلٍ صحيح، ستتعذّر كل المحاولات اللاحقة للوصول إلى الكاميرا، بما في ذلك المحاولات التي يجريها تطبيقك، وقد يؤدي ذلك إلى إغلاق تطبيقك أو التطبيقات الأخرى.

رصد أجهزة الكاميرا

إذا لم يكن تطبيقك يتطلّب استخدام كاميرا على وجه التحديد باستخدام بيان البيان، عليك التحقّق ممّا إذا كانت الكاميرا متاحة أثناء التشغيل. لإجراء هذا التحقّق، استخدِم الطريقة PackageManager.hasSystemFeature() كما هو موضّح في مثال الرمز البرمجي أدناه:

/** Check if this device has a camera */
private fun checkCameraHardware(context: Context): Boolean {
    if (context.packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
        // this device has a camera
        return true
    } else {
        // no camera on this device
        return false
    }
}

/** Check if this device has a camera */
private boolean checkCameraHardware(Context context) {
    if (context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA)){
        // this device has a camera
        return true;
    } else {
        // no camera on this device
        return false;
    }
}

يمكن أن تتضمّن أجهزة Android كاميرات متعددة، مثل كاميرا خلفية للتصوير وكاميرا أمامية لمكالمات الفيديو. يتيح لك الإصدار 2.3 من نظام التشغيل Android (المستوى 9 من واجهة برمجة التطبيقات) والإصدارات الأحدث التحقّق من عدد الكاميرات المتاحة على الجهاز باستخدام الطريقة Camera.getNumberOfCameras().

الوصول إلى الكاميرات

إذا تبيّن لك أنّ الجهاز الذي يعمل عليه تطبيقك يحتوي على كاميرا، يجب طلب الوصول إليها من خلال الحصول على مثيل من Camera (ما لم يكن يتم استخدام نية للوصول إلى الكاميرا).

للوصول إلى الكاميرا الأساسية، استخدِم الطريقة Camera.open() وتأكَّد من رصد أي استثناءات، كما هو موضّح في الرمز البرمجي أدناه:

/** A safe way to get an instance of the Camera object. */
fun getCameraInstance(): Camera? {
    return try {
        Camera.open() // attempt to get a Camera instance
    } catch (e: Exception) {
        // Camera is not available (in use or does not exist)
        null // returns null if camera is unavailable
    }
}

/** A safe way to get an instance of the Camera object. */
public static Camera getCameraInstance(){
    Camera c = null;
    try {
        c = Camera.open(); // attempt to get a Camera instance
    }
    catch (Exception e){
        // Camera is not available (in use or does not exist)
    }
    return c; // returns null if camera is unavailable
}

ملاحظة: تحقَّق دائمًا من الاستثناءات عند استخدام Camera.open(). في حال عدم التحقّق من الاستثناءات إذا كانت الكاميرا في استخدامٍ أو غير متوفّرة، سيؤدي ذلك إلى إغلاق النظام لتطبيقك.

على الأجهزة التي تعمل بالإصدار 2.3 من نظام التشغيل Android (المستوى 9 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث، يمكنك الوصول إلى كاميرات معيّنة باستخدام Camera.open(int). سيستخدم رمز المثال أعلاه الكاميرا الأولى الخلفية على جهاز يتضمّن أكثر من كاميرا واحدة.

التحقّق من ميزات الكاميرا

بعد الحصول على إذن الوصول إلى كاميرا، يمكنك الحصول على مزيد من المعلومات عن إمكاناتها باستخدام Camera.getParameters() وفحص Camera.Parameters الذي تم إرجاعه للاطّلاع على الإمكانات المتاحة. عند استخدام المستوى 9 من واجهة برمجة التطبيقات أو إصدار أحدث، استخدِم Camera.getCameraInfo() لتحديد ما إذا كانت الكاميرا في الجهة الأمامية أو الخلفية من الجهاز، واتجاه الصورة.

إنشاء فئة معاينة

لكي يتمكّن المستخدمون من التقاط الصور أو الفيديوهات بفعالية، يجب أن يتمكّنوا من رؤية ما ترصده كاميرا الجهاز. فئة معاينة الكاميرا هي SurfaceView يمكنها عرض بيانات الصورة المباشرة المُرسَلة من الكاميرا، حتى يتمكّن المستخدمون من وضع إطار لصورة أو فيديو والتقاطهما.

يوضّح مثال الرمز البرمجي التالي كيفية إنشاء فئة أساسية لمعاينة الكاميرا يمكن إدراجها في تنسيق View. تنفِّذ هذه الفئة SurfaceHolder.Callback لتسجيل أحداث الاستدعاء لإنشاء العرض وإزالته، وهي ضرورية لتحديد إدخال معاينة الكاميرا.

/** A basic Camera preview class */
class CameraPreview(
        context: Context,
        private val mCamera: Camera
) : SurfaceView(context), SurfaceHolder.Callback {

    private val mHolder: SurfaceHolder = holder.apply {
        // Install a SurfaceHolder.Callback so we get notified when the
        // underlying surface is created and destroyed.
        addCallback(this@CameraPreview)
        // deprecated setting, but required on Android versions prior to 3.0
        setType(SurfaceHolder.SURFACE_TYPE_PUSH_BUFFERS)
    }

    override fun surfaceCreated(holder: SurfaceHolder) {
        // The Surface has been created, now tell the camera where to draw the preview.
        mCamera.apply {
            try {
                setPreviewDisplay(holder)
                startPreview()
            } catch (e: IOException) {
                Log.d(TAG, "Error setting camera preview: ${e.message}")
            }
        }
    }

    override fun surfaceDestroyed(holder: SurfaceHolder) {
        // empty. Take care of releasing the Camera preview in your activity.
    }

    override fun surfaceChanged(holder: SurfaceHolder, format: Int, w: Int, h: Int) {
        // If your preview can change or rotate, take care of those events here.
        // Make sure to stop the preview before resizing or reformatting it.
        if (mHolder.surface == null) {
            // preview surface does not exist
            return
        }

        // stop preview before making changes
        try {
            mCamera.stopPreview()
        } catch (e: Exception) {
            // ignore: tried to stop a non-existent preview
        }

        // set preview size and make any resize, rotate or
        // reformatting changes here

        // start preview with new settings
        mCamera.apply {
            try {
                setPreviewDisplay(mHolder)
                startPreview()
            } catch (e: Exception) {
                Log.d(TAG, "Error starting camera preview: ${e.message}")
            }
        }
    }
}

/** A basic Camera preview class */
public class CameraPreview extends SurfaceView implements SurfaceHolder.Callback {
    private SurfaceHolder mHolder;
    private Camera mCamera;

    public CameraPreview(Context context, Camera camera) {
        super(context);
        mCamera = camera;

        // Install a SurfaceHolder.Callback so we get notified when the
        // underlying surface is created and destroyed.
        mHolder = getHolder();
        mHolder.addCallback(this);
        // deprecated setting, but required on Android versions prior to 3.0
        mHolder.setType(SurfaceHolder.SURFACE_TYPE_PUSH_BUFFERS);
    }

    public void surfaceCreated(SurfaceHolder holder) {
        // The Surface has been created, now tell the camera where to draw the preview.
        try {
            mCamera.setPreviewDisplay(holder);
            mCamera.startPreview();
        } catch (IOException e) {
            Log.d(TAG, "Error setting camera preview: " + e.getMessage());
        }
    }

    public void surfaceDestroyed(SurfaceHolder holder) {
        // empty. Take care of releasing the Camera preview in your activity.
    }

    public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) {
        // If your preview can change or rotate, take care of those events here.
        // Make sure to stop the preview before resizing or reformatting it.

        if (mHolder.getSurface() == null){
          // preview surface does not exist
          return;
        }

        // stop preview before making changes
        try {
            mCamera.stopPreview();
        } catch (Exception e){
          // ignore: tried to stop a non-existent preview
        }

        // set preview size and make any resize, rotate or
        // reformatting changes here

        // start preview with new settings
        try {
            mCamera.setPreviewDisplay(mHolder);
            mCamera.startPreview();

        } catch (Exception e){
            Log.d(TAG, "Error starting camera preview: " + e.getMessage());
        }
    }
}

إذا أردت ضبط حجم محدّد لمعاينة الكاميرا، يمكنك ضبطه في طريقة surfaceChanged() كما هو موضّح في التعليقات أعلاه. عند ضبط حجم المعاينة، عليك استخدام القيم من getSupportedPreviewSizes(). لا تضبط قيمًا عشوائية في طريقة setPreviewSize().

ملاحظة: مع طرح ميزة "وضع المتعدّد النوافذ" في نظام التشغيل Android 7.0 (المستوى 24 من واجهة برمجة التطبيقات) والإصدارات الأحدث، لن تتمكّن مجددًا من افتراض أنّ نسبة العرض إلى الارتفاع في المعاينة هي نفسها نسبة العرض إلى الارتفاع في نشاطك حتى بعد استدعاء setDisplayOrientation(). استنادًا إلى حجم النافذة ونسبة العرض إلى الارتفاع، قد تحتاج إلى ملاءمة معاينة الكاميرا المزوّدة بعدسة عريضة في تنسيق عمودي، أو العكس، باستخدام تنسيق إطار مُعدّ للعرض على شاشة عريضة أفقيًا.

وضع معاينة في تنسيق

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

يوفّر رمز التنسيق التالي عرضًا أساسيًا جدًا يمكن استخدامه لعرض ملف كاميرا معاينة. في هذا المثال، يُفترض أن يكون العنصر FrameLayout هو الحاوية لفئة معاينة الكاميرا. يُستخدَم هذا النوع من التنسيقات لكي تتمكّن من إضافة معلومات أو عناصر تحكّم إضافية على صور معاينة الكاميرا المباشرة.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="horizontal"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
  <FrameLayout
    android:id="@+id/camera_preview"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:layout_weight="1"
    />

  <Button
    android:id="@+id/button_capture"
    android:text="Capture"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_gravity="center"
    />
</LinearLayout>

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

<activity android:name=".CameraActivity"
          android:label="@string/app_name"

          android:screenOrientation="landscape">
          <!-- configure this activity to use landscape orientation -->

          <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

ملاحظة: لا يلزم أن تكون معاينة الكاميرا في الوضع الأفقي. بدءًا من الإصدار 2.2 من Android (المستوى 8 لواجهة برمجة التطبيقات)، يمكنك استخدام الطريقة setDisplayOrientation() لضبط درجة دوران صورة المعاينة. لتغيير اتجاه المعاينة عندما يعيد المستخدم توجيه الهاتف، ضمن طريقة surfaceChanged() لفئة المعاينة، أوقِف أولاً المعاينة باستخدام Camera.stopPreview() غيِّر الاتجاه ثم ابدأ المعاينة مرة أخرى باستخدام Camera.startPreview().

في نشاط عرض الكاميرا، أضِف فئة المعاينة إلى عنصر FrameLayout المعروض في المثال أعلاه. يجب أن يضمن نشاط الكاميرا أيضًا إغلاق الكاميرا عند إيقافها مؤقتًا أو إغلاقها. يوضّح المثال التالي كيفية تعديل نشاط الكاميرا لإرفاق فئة المعاينة الموضّحة في إنشاء فئة معاينة.

class CameraActivity : Activity() {

    private var mCamera: Camera? = null
    private var mPreview: CameraPreview? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Create an instance of Camera
        mCamera = getCameraInstance()

        mPreview = mCamera?.let {
            // Create our Preview view
            CameraPreview(this, it)
        }

        // Set the Preview view as the content of our activity.
        mPreview?.also {
            val preview: FrameLayout = findViewById(R.id.camera_preview)
            preview.addView(it)
        }
    }
}

public class CameraActivity extends Activity {

    private Camera mCamera;
    private CameraPreview mPreview;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        // Create an instance of Camera
        mCamera = getCameraInstance();

        // Create our Preview view and set it as the content of our activity.
        mPreview = new CameraPreview(this, mCamera);
        FrameLayout preview = (FrameLayout) findViewById(R.id.camera_preview);
        preview.addView(mPreview);
    }
}

ملاحظة: تشير طريقة getCameraInstance() في المثال أعلاه إلى مثال الطريقة الموضّح في الوصول إلى الكاميرات.

التقاط الصور

بعد إنشاء فئة معاينة وتنسيق عرض لعرضها، ستكون مستعدًا لبدء التقاط الصور باستخدام تطبيقك. في رمز تطبيقك، عليك إعداد مستمعين لعناصر التحكّم في واجهة المستخدم من أجل الاستجابة لإجراء المستخدِم من خلال التقاط صورة.

لاسترداد صورة، استخدِم الطريقة Camera.takePicture(). تأخذ هذه الطريقة ثلاث مَعلمات تتلقّى البيانات من الكاميرا. لتلقّي البيانات بتنسيق JPEG، يجب تنفيذ واجهة Camera.PictureCallback لتلقّي بيانات الصورة ونقلها إلى ملف. يعرض الرمز البرمجي التالي تنفيذًا أساسيًا لواجهة Camera.PictureCallback لحفظ صورة تم استلامها من الكاميرا.

private val mPicture = Camera.PictureCallback { data, _ ->
    val pictureFile: File = getOutputMediaFile(MEDIA_TYPE_IMAGE) ?: run {
        Log.d(TAG, ("Error creating media file, check storage permissions"))
        return@PictureCallback
    }

    try {
        val fos = FileOutputStream(pictureFile)
        fos.write(data)
        fos.close()
    } catch (e: FileNotFoundException) {
        Log.d(TAG, "File not found: ${e.message}")
    } catch (e: IOException) {
        Log.d(TAG, "Error accessing file: ${e.message}")
    }
}

private PictureCallback mPicture = new PictureCallback() {

    @Override
    public void onPictureTaken(byte[] data, Camera camera) {

        File pictureFile = getOutputMediaFile(MEDIA_TYPE_IMAGE);
        if (pictureFile == null){
            Log.d(TAG, "Error creating media file, check storage permissions");
            return;
        }

        try {
            FileOutputStream fos = new FileOutputStream(pictureFile);
            fos.write(data);
            fos.close();
        } catch (FileNotFoundException e) {
            Log.d(TAG, "File not found: " + e.getMessage());
        } catch (IOException e) {
            Log.d(TAG, "Error accessing file: " + e.getMessage());
        }
    }
};

يمكنك بدء التقاط صورة من خلال استدعاء الطريقة Camera.takePicture(). يعرض الرمز البرمجي التالي كيفية استدعاء هذه الطريقة من زر View.OnClickListener.

val captureButton: Button = findViewById(R.id.button_capture)
captureButton.setOnClickListener {
    // get an image from the camera
    mCamera?.takePicture(null, null, picture)
}

// Add a listener to the Capture button
Button captureButton = (Button) findViewById(R.id.button_capture);
captureButton.setOnClickListener(
    new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            // get an image from the camera
            mCamera.takePicture(null, null, picture);
        }
    }
);

ملاحظة: يشير العضو mPicture في المثال التالي إلى مثال الرمز أعلاه.

تحذير: تذكَّر تحرير Camera العنصر من خلال استدعاء Camera.release() عند انتهاء تطبيقك من استخدامه. للحصول على معلومات عن كيفية إزالة الكاميرا، يُرجى الاطّلاع على إزالة الكاميرا.

تسجيل الفيديوهات

يتطلّب تسجيل الفيديو باستخدام إطار عمل Android إدارةً دقيقةً لعنصر Camera والتنسيق مع فئة MediaRecorder. عند تسجيل فيديو باستخدام Camera، عليك إدارة مكالمات Camera.lock() وCamera.unlock() للسماح لتطبيق MediaRecorder بالوصول إلى أجهزة الكاميرا، بالإضافة إلى مكالمات Camera.open() وCamera.release().

ملاحظة: اعتبارًا من الإصدار 4.0 من Android (المستوى 14 من واجهة برمجة التطبيقات)، تتم إدارة المكالمات الواردة من Camera.lock() وCamera.unlock() تلقائيًا.

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

1. فتح الكاميرا: استخدِم Camera.open() للحصول على مثيل لعنصر الكاميرا.
2. معاينة الاتصال: يمكنك إعداد معاينة لصورة الكاميرا المباشرة من خلال توصيل SurfaceView بالكاميرا باستخدام Camera.setPreviewDisplay().
3. بدء المعاينة: اتصل برقم Camera.startPreview() لبدء عرض صور الكاميرا المباشرة.
4. بدء تسجيل الفيديو: يجب إكمال الخطوات التالية بترتيبٍ معيّن لتسجيل الفيديو بنجاح:
   1. فتح قفل الكاميرا: يمكنك فتح قفل الكاميرا لاستخدامها من قِبل MediaRecorder من خلال الاتصال برقم Camera.unlock().
   2. ضبط MediaRecorder: استخدِم MediaRecorder طريقة من الطرق التالية بالترتيب التالي. لمزيد من المعلومات، يُرجى الاطّلاع على المستندات المرجعية MediaRecorder.
      1. ‫setCamera() - اضبط الكاميرا لاستخدامها في تسجيل الفيديو، واستخدِم الإصدار الحالي من Camera في تطبيقك.
      2. setAudioSource() - اضبط مصدر الصوت، واستخدِم MediaRecorder.AudioSource.CAMCORDER.
      3. setVideoSource() - لضبط مصدر الفيديو، استخدِم MediaRecorder.VideoSource.CAMERA.
      4. اضبط تنسيق إخراج الفيديو وتشفيره. بالنسبة إلى الإصدار 2.2 من نظام التشغيل Android (المستوى 8 من واجهة برمجة التطبيقات) والإصدارات الأحدث، استخدِم الطريقة MediaRecorder.setProfile، واحصل على مثيل ملف شخصي باستخدام CamcorderProfile.get(). بالنسبة إلى إصدارات Android الأقدم من 2.2، عليك ضبط تنسيق إخراج الفيديو ومَعلمات التشفير:
         1. setOutputFormat() - اضبط تنسيق الإخراج، أو حدِّد الإعداد التلقائي، أو انقر على MediaRecorder.OutputFormat.MPEG_4.
         2. setAudioEncoder() - اضبط نوع ترميز الصوت، أو حدِّد الإعداد التلقائي أو MediaRecorder.AudioEncoder.AMR_NB.
         3. setVideoEncoder() - اضبط نوع ترميز الفيديو، وحدِّد الإعداد التلقائي أو MediaRecorder.VideoEncoder.MPEG_4_SP.
      5. setOutputFile() - حدِّد ملف الإخراج، واستخدِم getOutputMediaFile(MEDIA_TYPE_VIDEO).toString() من المثال على الطريقة في قسم حفظ ملفات الوسائط.
      6. setPreviewDisplay() - حدِّد عنصر SurfaceView تنسيق المعاينة لتطبيقك. استخدِم العنصر نفسه الذي حدّدته في معاينة "الاتصال".

      ملاحظة: يجب استدعاء طرق ضبط MediaRecorder هذه بالترتيب التالي، وإلا سيواجه تطبيقك أخطاء ولن يتم التسجيل.

   3. إعداد MediaRecorder: حضِّر MediaRecorder باستخدام إعدادات الضبط المقدَّمة من خلال استدعاء MediaRecorder.prepare().
   4. بدء MediaRecorder: ابدأ تسجيل الفيديو من خلال الاتصال بالرقم MediaRecorder.start().
5. إيقاف تسجيل الفيديو: اتّبِع الطرق التالية بالترتيب لإكمال تسجيل الفيديو بنجاح:
   1. إيقاف MediaRecorder: يمكنك إيقاف تسجيل الفيديو من خلال الاتصال بالرقم MediaRecorder.stop().
   2. إعادة ضبط MediaRecorder: يمكنك اختياريًا إزالة إعدادات الضبط من الجهاز المسجِّل من خلال الاتصال بالرقم MediaRecorder.reset().
   3. إلغاء حجز MediaRecorder: يمكنك إلغاء حجز MediaRecorder من خلال الاتصال بالرقم MediaRecorder.release().
   4. قفل الكاميرا: يمكنك قفل الكاميرا لكي تتمكّن جلسات MediaRecorder المستقبلية من استخدامها من خلال الاتصال بالرقم Camera.lock(). بدءًا من الإصدار 4.0 من Android (المستوى 14 لواجهة برمجة التطبيقات)، لم يعُد هذا الطلب مطلوبًا ما لم يتعذّر تنفيذ طلب MediaRecorder.prepare().
6. إيقاف المعاينة: عند الانتهاء من استخدام الكاميرا، يمكنك إيقاف المعاينة باستخدام Camera.stopPreview().
7. إلغاء حجز الكاميرا: يمكنك إلغاء حجز الكاميرا حتى تتمكّن التطبيقات الأخرى من استخدامها من خلال الاتصال بالرقم Camera.release().

ملاحظة: يمكنك استخدام MediaRecorder بدون إنشاء معاينة للكاميرا أولاً وتخطّي الخطوات القليلة الأولى من هذه العملية. ومع ذلك، بما أنّ المستخدمين يفضّلون عادةً الاطّلاع على معاينة قبل بدء التسجيل، لن تتم مناقشة هذه العملية هنا.

ملاحظة: إذا كان تطبيقك يُستخدَم عادةً لتسجيل الفيديو، اضبط setRecordingHint(boolean) على true قبل بدء المعاينة. يمكن أن يساعد هذا الإعداد في تقليل الوقت المستغرَق لبدء التسجيل.

ضبط MediaRecorder

عند استخدام فئة MediaRecorder لتسجيل الفيديو، عليك تنفيذ خطوات الإعداد بترتيب معيّن ثم استدعاء طريقة MediaRecorder.prepare() للتحقّق من الإعداد وتنفيذه. يوضّح مثال الرمز البرمجي التالي كيفية ضبط فئة MediaRecorder وإعدادها بشكلٍ سليم لتسجيل الفيديو.

private fun prepareVideoRecorder(): Boolean {
    mediaRecorder = MediaRecorder()

    mCamera?.let { camera ->
        // Step 1: Unlock and set camera to MediaRecorder
        camera?.unlock()

        mediaRecorder?.run {
            setCamera(camera)

            // Step 2: Set sources
            setAudioSource(MediaRecorder.AudioSource.CAMCORDER)
            setVideoSource(MediaRecorder.VideoSource.CAMERA)

            // Step 3: Set a CamcorderProfile (requires API Level 8 or higher)
            setProfile(CamcorderProfile.get(CamcorderProfile.QUALITY_HIGH))

            // Step 4: Set output file
            setOutputFile(getOutputMediaFile(MEDIA_TYPE_VIDEO).toString())

            // Step 5: Set the preview output
            setPreviewDisplay(mPreview?.holder?.surface)

            setOutputFormat(MediaRecorder.OutputFormat.MPEG_4)
            setAudioEncoder(MediaRecorder.AudioEncoder.DEFAULT)
            setVideoEncoder(MediaRecorder.VideoEncoder.DEFAULT)


            // Step 6: Prepare configured MediaRecorder
            return try {
                prepare()
                true
            } catch (e: IllegalStateException) {
                Log.d(TAG, "IllegalStateException preparing MediaRecorder: ${e.message}")
                releaseMediaRecorder()
                false
            } catch (e: IOException) {
                Log.d(TAG, "IOException preparing MediaRecorder: ${e.message}")
                releaseMediaRecorder()
                false
            }
        }

    }
    return false
}

private boolean prepareVideoRecorder(){

    mCamera = getCameraInstance();
    mediaRecorder = new MediaRecorder();

    // Step 1: Unlock and set camera to MediaRecorder
    mCamera.unlock();
    mediaRecorder.setCamera(mCamera);

    // Step 2: Set sources
    mediaRecorder.setAudioSource(MediaRecorder.AudioSource.CAMCORDER);
    mediaRecorder.setVideoSource(MediaRecorder.VideoSource.CAMERA);

    // Step 3: Set a CamcorderProfile (requires API Level 8 or higher)
    mediaRecorder.setProfile(CamcorderProfile.get(CamcorderProfile.QUALITY_HIGH));

    // Step 4: Set output file
    mediaRecorder.setOutputFile(getOutputMediaFile(MEDIA_TYPE_VIDEO).toString());

    // Step 5: Set the preview output
    mediaRecorder.setPreviewDisplay(mPreview.getHolder().getSurface());

    // Step 6: Prepare configured MediaRecorder
    try {
        mediaRecorder.prepare();
    } catch (IllegalStateException e) {
        Log.d(TAG, "IllegalStateException preparing MediaRecorder: " + e.getMessage());
        releaseMediaRecorder();
        return false;
    } catch (IOException e) {
        Log.d(TAG, "IOException preparing MediaRecorder: " + e.getMessage());
        releaseMediaRecorder();
        return false;
    }
    return true;
}

قبل الإصدار 2.2 من Android (المستوى 8 لواجهة برمجة التطبيقات)، يجب ضبط مَعلمتَي تنسيق الإخراج وتنسيقات الترميز مباشرةً، بدلاً من استخدام CamcorderProfile. يمكن الاطّلاع على هذا الأسلوب في التعليمة البرمجية التالية:

    // Step 3: Set output format and encoding (for versions prior to API Level 8)
    mediaRecorder?.apply {
        setOutputFormat(MediaRecorder.OutputFormat.MPEG_4)
        setAudioEncoder(MediaRecorder.AudioEncoder.DEFAULT)
        setVideoEncoder(MediaRecorder.VideoEncoder.DEFAULT)
    }

    // Step 3: Set output format and encoding (for versions prior to API Level 8)
    mediaRecorder.setOutputFormat(MediaRecorder.OutputFormat.MPEG_4);
    mediaRecorder.setAudioEncoder(MediaRecorder.AudioEncoder.DEFAULT);
    mediaRecorder.setVideoEncoder(MediaRecorder.VideoEncoder.DEFAULT);

في ما يلي مَعلمات تسجيل الفيديو التالية لجهاز MediaRecorder، وهي تمثل الإعدادات default (تلقائية)، ولكن قد تحتاج إلى تعديل هذه الإعدادات لتطبيقك:

• setVideoEncodingBitRate()
• setVideoSize()
• setVideoFrameRate()
• setAudioEncodingBitRate()
• setAudioChannels()
• setAudioSamplingRate()

بدء MediaRecorder وإيقافه

عند بدء تسجيل الفيديو وإيقافه باستخدام فئة MediaRecorder، يجب اتّباع ترتيب معيّن كما هو موضّح أدناه.

1. فتح قفل الكاميرا باستخدام Camera.unlock()
2. اضبط MediaRecorder كما هو موضّح في مثال الرمز البرمجي أعلاه.
3. بدء التسجيل باستخدام MediaRecorder.start()
4. تسجيل الفيديو
5. إيقاف التسجيل باستخدام MediaRecorder.stop()
6. إزالة "مسجّلة الوسائط" باستخدام MediaRecorder.release()
7. قفل الكاميرا باستخدام Camera.lock()

يوضّح مثال الرمز البرمجي التالي كيفية ربط زر لبدء تسجيل الفيديو وإيقافه بشكلٍ سليم باستخدام الكاميرا وفئته MediaRecorder.

ملاحظة: عند إكمال تسجيل فيديو، لا ترفع إصبعك عن الكاميرا وإلا سيتم إيقاف المعاينة.

var isRecording = false
val captureButton: Button = findViewById(R.id.button_capture)
captureButton.setOnClickListener {
    if (isRecording) {
        // stop recording and release camera
        mediaRecorder?.stop() // stop the recording
        releaseMediaRecorder() // release the MediaRecorder object
        mCamera?.lock() // take camera access back from MediaRecorder

        // inform the user that recording has stopped
        setCaptureButtonText("Capture")
        isRecording = false
    } else {
        // initialize video camera
        if (prepareVideoRecorder()) {
            // Camera is available and unlocked, MediaRecorder is prepared,
            // now you can start recording
            mediaRecorder?.start()

            // inform the user that recording has started
            setCaptureButtonText("Stop")
            isRecording = true
        } else {
            // prepare didn't work, release the camera
            releaseMediaRecorder()
            // inform user
        }
    }
}

private boolean isRecording = false;

// Add a listener to the Capture button
Button captureButton = (Button) findViewById(id.button_capture);
captureButton.setOnClickListener(
    new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            if (isRecording) {
                // stop recording and release camera
                mediaRecorder.stop();  // stop the recording
                releaseMediaRecorder(); // release the MediaRecorder object
                mCamera.lock();         // take camera access back from MediaRecorder

                // inform the user that recording has stopped
                setCaptureButtonText("Capture");
                isRecording = false;
            } else {
                // initialize video camera
                if (prepareVideoRecorder()) {
                    // Camera is available and unlocked, MediaRecorder is prepared,
                    // now you can start recording
                    mediaRecorder.start();

                    // inform the user that recording has started
                    setCaptureButtonText("Stop");
                    isRecording = true;
                } else {
                    // prepare didn't work, release the camera
                    releaseMediaRecorder();
                    // inform user
                }
            }
        }
    }
);

ملاحظة: في المثال أعلاه، تشير الطريقة prepareVideoRecorder() إلى مثال الرمز المعروض في ضبط MediaRecorder. تتولى هذه الطريقة قفل الكاميرا وضبط مثيل MediaRecorder وإعداده.

إزالة الكاميرا

الكاميرات هي مورد تشترك فيه التطبيقات على الجهاز. يمكن لتطبيقك استخدام الكاميرا بعد الحصول على مثيل من Camera، ويجب أن تحرص بشدة على تحرير عنصر الكاميرا عندما يتوقف تطبيقك عن استخدامه، وفور إيقاف تطبيقك مؤقتًا (Activity.onPause()). إذا لم يُحرِّر تطبيقك الكاميرا بشكلٍ صحيح، ستتعذّر كل المحاولات اللاحقة للوصول إلى الكاميرا، بما في ذلك المحاولات التي يجريها تطبيقك، وقد تؤدي إلى إيقاف تطبيقك أو التطبيقات الأخرى.

لتحرير مثيل من عنصر Camera، استخدِم الطريقة Camera.release()، كما هو موضّح في مثال الرمز البرمجي أدناه.

class CameraActivity : Activity() {
    private var mCamera: Camera?
    private var preview: SurfaceView?
    private var mediaRecorder: MediaRecorder?

    override fun onPause() {
        super.onPause()
        releaseMediaRecorder() // if you are using MediaRecorder, release it first
        releaseCamera() // release the camera immediately on pause event
    }

    private fun releaseMediaRecorder() {
        mediaRecorder?.reset() // clear recorder configuration
        mediaRecorder?.release() // release the recorder object
        mediaRecorder = null
        mCamera?.lock() // lock camera for later use
    }

    private fun releaseCamera() {
        mCamera?.release() // release the camera for other applications
        mCamera = null
    }
}

public class CameraActivity extends Activity {
    private Camera mCamera;
    private SurfaceView preview;
    private MediaRecorder mediaRecorder;

    ...

    @Override
    protected void onPause() {
        super.onPause();
        releaseMediaRecorder();       // if you are using MediaRecorder, release it first
        releaseCamera();              // release the camera immediately on pause event
    }

    private void releaseMediaRecorder(){
        if (mediaRecorder != null) {
            mediaRecorder.reset();   // clear recorder configuration
            mediaRecorder.release(); // release the recorder object
            mediaRecorder = null;
            mCamera.lock();           // lock camera for later use
        }
    }

    private void releaseCamera(){
        if (mCamera != null){
            mCamera.release();        // release the camera for other applications
            mCamera = null;
        }
    }
}

تحذير: إذا لم يُغلق تطبيقك الكاميرا بشكلٍ صحيح، ستتعذّر كل المحاولات اللاحقة للوصول إلى الكاميرا، بما في ذلك المحاولات التي يجريها تطبيقك، وقد يؤدي ذلك إلى إغلاق تطبيقك أو التطبيقات الأخرى.

حفظ ملفات الوسائط

يجب حفظ ملفات الوسائط التي أنشأها المستخدمون، مثل الصور والفيديوهات، في دليل التخزين الخارجي (بطاقة SD) للجهاز للحفاظ على مساحة النظام والسماح للمستخدمين بالوصول إلى هذه الملفات بدون استخدام أجهزتهم. هناك العديد من أماكن الدليل المحتملة لحفظ ملفات الوسائط على الجهاز، ولكن هناك مكانان عاديَّان فقط يجب أن تأخذهما في الاعتبار بصفتك مطوّرًا:

• ‫Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES): تعرض هذه الطريقة الموقع الجغرافي العادي والمشترَك والمُقترَح لحفظ الصور والفيديوهات. هذا الدليل مشترَك (عام)، لذا يمكن للتطبيقات الأخرى اكتشاف الملفات المحفوظة في هذا الموقع الجغرافي وقراءتها وتغييرها وحذفها بسهولة. إذا أزال المستخدم تطبيقك، لن تتم إزالة ملفات الوسائط المحفوظة في هذا الموقع. لتجنُّب التدخل في الصور والفيديوهات الحالية للمستخدمين، عليك إنشاء دليل فرعي لملفّات وسائط تطبيقك ضمن هذا الدليل، كما هو موضّح في نموذج الرمز البرمجي أدناه. تتوفّر هذه الطريقة في Android 2.2 (المستوى 8 من واجهة برمجة التطبيقات). للحصول على طلبات البيانات المماثلة في إصدارات واجهة برمجة التطبيقات الأقدم، يُرجى الاطّلاع على مقالة حفظ الملفات المشتركة.
• ‫Context.getExternalFilesDir(Environment.DIRECTORY_PICTURES): تعرض هذه الطريقة موقعًا جغرافيًا عاديًا لحفظ الصور والفيديوهات المرتبطة بتطبيقك. في حال إلغاء تثبيت تطبيقك، تتم إزالة أي ملفات محفوظة في هذا الموقع. لا يتم فرض الأمان على الملفات في هذا الموقع، وقد تقرأ التطبيقات الأخرى هذه الملفات وتغيرها وتحذفها.

يوضّح مثال الرمز البرمجي التالي كيفية إنشاء موقع File أو Uri لملف وسائط يمكن استخدامه عند استدعاء كاميرا الجهاز باستخدام Intent أو كجزء من إنشاء تطبيق كاميرا.

val MEDIA_TYPE_IMAGE = 1
val MEDIA_TYPE_VIDEO = 2

/** Create a file Uri for saving an image or video */
private fun getOutputMediaFileUri(type: Int): Uri {
    return Uri.fromFile(getOutputMediaFile(type))
}

/** Create a File for saving an image or video */
private fun getOutputMediaFile(type: Int): File? {
    // To be safe, you should check that the SDCard is mounted
    // using Environment.getExternalStorageState() before doing this.

    val mediaStorageDir = File(
            Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES),
            "MyCameraApp"
    )
    // This location works best if you want the created images to be shared
    // between applications and persist after your app has been uninstalled.

    // Create the storage directory if it does not exist
    mediaStorageDir.apply {
        if (!exists()) {
            if (!mkdirs()) {
                Log.d("MyCameraApp", "failed to create directory")
                return null
            }
        }
    }

    // Create a media file name
    val timeStamp = SimpleDateFormat("yyyyMMdd_HHmmss").format(Date())
    return when (type) {
        MEDIA_TYPE_IMAGE -> {
            File("${mediaStorageDir.path}${File.separator}IMG_$timeStamp.jpg")
        }
        MEDIA_TYPE_VIDEO -> {
            File("${mediaStorageDir.path}${File.separator}VID_$timeStamp.mp4")
        }
        else -> null
    }
}

public static final int MEDIA_TYPE_IMAGE = 1;
public static final int MEDIA_TYPE_VIDEO = 2;

/** Create a file Uri for saving an image or video */
private static Uri getOutputMediaFileUri(int type){
      return Uri.fromFile(getOutputMediaFile(type));
}

/** Create a File for saving an image or video */
private static File getOutputMediaFile(int type){
    // To be safe, you should check that the SDCard is mounted
    // using Environment.getExternalStorageState() before doing this.

    File mediaStorageDir = new File(Environment.getExternalStoragePublicDirectory(
              Environment.DIRECTORY_PICTURES), "MyCameraApp");
    // This location works best if you want the created images to be shared
    // between applications and persist after your app has been uninstalled.

    // Create the storage directory if it does not exist
    if (! mediaStorageDir.exists()){
        if (! mediaStorageDir.mkdirs()){
            Log.d("MyCameraApp", "failed to create directory");
            return null;
        }
    }

    // Create a media file name
    String timeStamp = new SimpleDateFormat("yyyyMMdd_HHmmss").format(new Date());
    File mediaFile;
    if (type == MEDIA_TYPE_IMAGE){
        mediaFile = new File(mediaStorageDir.getPath() + File.separator +
        "IMG_"+ timeStamp + ".jpg");
    } else if(type == MEDIA_TYPE_VIDEO) {
        mediaFile = new File(mediaStorageDir.getPath() + File.separator +
        "VID_"+ timeStamp + ".mp4");
    } else {
        return null;
    }

    return mediaFile;
}

ملاحظة: تتوفّر Environment.getExternalStoragePublicDirectory() في الإصدار 2.2 من نظام التشغيل Android (المستوى 8 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث. إذا كنت تستهدِف الأجهزة التي تعمل بإصدارات أقدم من Android، استخدِم Environment.getExternalStorageDirectory() بدلاً من ذلك. لمزيد من المعلومات، يُرجى الاطّلاع على حفظ الملفات المشترَكة.

لجعل معرّف الموارد المنتظم متوافقًا مع الملفات الشخصية للعمل، عليك أولاً تحويل معرّف الموارد المنتظم للملف إلى معرّف موارد منتظم للمحتوى. بعد ذلك، أضِف معرّف الموارد المنتظم للمحتوى إلى EXTRA_OUTPUT Intent.

لمزيد من المعلومات حول حفظ الملفات على جهاز Android، يُرجى الاطّلاع على تخزين البيانات.

ميزات الكاميرا

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

• قياس الأداء ومناطق التركيز
• التعرّف على الوجوه
• فيديو بوضع "التسريع الزمني"

للحصول على معلومات عامة عن كيفية استخدام الميزات التي يتم التحكّم فيها من خلال Camera.Parameters، راجِع قسم استخدام ميزات الكاميرا. للحصول على معلومات أكثر تفصيلاً حول كيفية استخدام الميزات التي يتم التحكّم فيها من خلال ملف تعريف مَعلمات الكاميرا، اتّبِع الروابط في قائمة الميزات أدناه للوصول إلى مستندات مرجع واجهة برمجة التطبيقات.

الجدول 1: ميزات الكاميرا الشائعة مُرتَّبة حسب مستوى واجهة برمجة التطبيقات لنظام التشغيل Android الذي تم طرحها فيه

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

التحقّق من توفّر الميزات

عند استخدام ميزات الكاميرا على أجهزة Android، عليك أولاً معرفة أنّه لا تتوفّر بعض ميزات الكاميرا على بعض الأجهزة. بالإضافة إلى ذلك، قد تتيح الأجهزة التي تتيح استخدام ميزة معيّنة استخدامها بمستويات مختلفة أو مع خيارات مختلفة. لذلك، يُعدّ تحديد ميزات الكاميرا التي تريد إتاحة استخدامها ومستوى توفّرها جزءًا من عملية اتخاذك للقرارات أثناء تطوير تطبيق كاميرا. بعد اتخاذ هذا القرار، عليك تضمين رمز برمجي في تطبيق الكاميرا للتحقّق مما إذا كانت أجهزة الجهاز متوافقة مع هذه الميزات، ويجب أن يتوقف التطبيق عن العمل بشكل سلس في حال عدم توفّر إحدى الميزات.

يمكنك التحقّق من توفّر ميزات الكاميرا من خلال الحصول على مثيل لمَعلمات كاميرا، والتحقّق من الطرق ذات الصلة. يوضّح لك نموذج الرمز البرمجي التالي كيفية الحصول على كائن Camera.Parameters والتحقّق مما إذا كانت الكاميرا تتيح ميزة التركيز التلقائي:

val params: Camera.Parameters? = camera?.parameters
val focusModes: List<String>? = params?.supportedFocusModes
if (focusModes?.contains(Camera.Parameters.FOCUS_MODE_AUTO) == true) {
    // Autofocus mode is supported
}

// get Camera parameters
Camera.Parameters params = camera.getParameters();

List<String> focusModes = params.getSupportedFocusModes();
if (focusModes.contains(Camera.Parameters.FOCUS_MODE_AUTO)) {
  // Autofocus mode is supported
}

يمكنك استخدام الأسلوب الموضَّح أعلاه لمعظم ميزات الكاميرا. يقدّم كائن Camera.Parameters طريقة getSupported...() أو is...Supported() أو getMax...() لتحديد ما إذا كانت الميزة متاحة (وإلى أي مدى).

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

استخدام ميزات الكاميرا

يتم تفعيل معظم ميزات الكاميرا والتحكّم فيها باستخدام عنصر Camera.Parameters. يمكنك الحصول على هذا الكائن من خلال الحصول أولاً على مثيل لعنصر Camera، واستدعاء الطريقة getParameters()، وتغيير عنصر المَعلمة المعروض، ثمّ إعادته إلى عنصر الكاميرا، كما هو موضّح في المثال التالي للرمز البرمجي:

val params: Camera.Parameters? = camera?.parameters
params?.focusMode = Camera.Parameters.FOCUS_MODE_AUTO
camera?.parameters = params

// get Camera parameters
Camera.Parameters params = camera.getParameters();
// set the focus mode
params.setFocusMode(Camera.Parameters.FOCUS_MODE_AUTO);
// set Camera parameters
camera.setParameters(params);

تعمل هذه التقنية مع جميع ميزات الكاميرا تقريبًا، ويمكن تغيير معظم المَعلمات في أي وقت بعد الحصول على مثيل لعنصر Camera. تظهر التغييرات التي تطرأ علىparametrs عادةً للمستخدم على الفور في معاينة الكاميرا للتطبيق. من ناحية البرامج، قد تستغرق تغييرات المَعلمات عدة لقطات لتسريدها فعليًا لأنّه يتم معالجة التعليمات الجديدة في برمجيات الكاميرا ثم إرسال بيانات الصورة المعدَّلة.

ملاحظة مهمة: لا يمكن تغيير بعض ميزات الكاميرا متى شئت. على سبيل المثال، يتطلّب تغيير حجم معاينة الكاميرا أو اتجاهها إيقاف المعاينة أولاً وتغيير حجمها ثم إعادة تشغيلها. بدءًا من Android 4.0 (IDE المستوى 14)، يمكن تغيير اتجاه المعاينة بدون إعادة تشغيلها.

تتطلّب ميزات الكاميرا الأخرى مزيدًا من الرموز البرمجية لتنفيذها، بما في ذلك:

• القياس ومناطق التركيز
• التعرّف على الوجوه
• فيديو بوضع التسريع الزمني

في الأقسام التالية، يمكنك الاطّلاع على مخطّط سريع لكيفية تنفيذ هذه الميزات.

القياس ومناطق التركيز

في بعض سيناريوهات التصوير، قد لا تؤدي ميزة التركيز التلقائي وقياس الإضاءة إلى تحقيق النتائج المطلوبة. بدءًا من الإصدار Android 4.0 (المستوى 14 من واجهة برمجة التطبيقات)، يمكن لتطبيق الكاميرا توفير عناصر تحكّم إضافية للسماح لتطبيقك أو للمستخدمين بتحديد مناطق في الصورة لاستخدامها في تحديد إعدادات التركيز أو مستوى الإضاءة ونقل هذه القيم إلى جهاز الكاميرا لاستخدامها في التقاط الصور أو الفيديو.

تعمل مناطق القياس والتركيز بشكل مشابه جدًا لميزات الكاميرا الأخرى، حيث يمكنك التحكّم فيها من خلال الطرق في عنصر Camera.Parameters. يوضِّح الرمز البرمجي التالي كيفية ضبط منطقتَي قياس الإضاءة لنسخة من Camera:

// Create an instance of Camera
camera = getCameraInstance()

// set Camera parameters
val params: Camera.Parameters? = camera?.parameters

params?.apply {
    if (maxNumMeteringAreas > 0) { // check that metering areas are supported
        meteringAreas = ArrayList<Camera.Area>().apply {
            val areaRect1 = Rect(-100, -100, 100, 100) // specify an area in center of image
            add(Camera.Area(areaRect1, 600)) // set weight to 60%
            val areaRect2 = Rect(800, -1000, 1000, -800) // specify an area in upper right of image
            add(Camera.Area(areaRect2, 400)) // set weight to 40%
        }
    }
    camera?.parameters = this
}

// Create an instance of Camera
camera = getCameraInstance();

// set Camera parameters
Camera.Parameters params = camera.getParameters();

if (params.getMaxNumMeteringAreas() > 0){ // check that metering areas are supported
    List<Camera.Area> meteringAreas = new ArrayList<Camera.Area>();

    Rect areaRect1 = new Rect(-100, -100, 100, 100);    // specify an area in center of image
    meteringAreas.add(new Camera.Area(areaRect1, 600)); // set weight to 60%
    Rect areaRect2 = new Rect(800, -1000, 1000, -800);  // specify an area in upper right of image
    meteringAreas.add(new Camera.Area(areaRect2, 400)); // set weight to 40%
    params.setMeteringAreas(meteringAreas);
}

camera.setParameters(params);

يحتوي عنصر Camera.Area على مَعلمتَي بيانات: عنصر Rect لتحديد منطقة ضمن مجال رؤية الكاميرا وقيمة قياس الوزن، التي تُعلم الكاميرا بمستوى الأهمية الذي يجب أن تحظى به هذه المنطقة في عمليات قياس الإضاءة أو عمليات حساب التركيز.

يصف الحقل Rect في عنصر Camera.Area شكلًا مستطيلاً تمّ ربطه بشبكة من وحدات بحجم 2000 x ‏2000. تمثل الإحداثيات -1000، -1000 الزاوية العلوية اليمنى لصورة الكاميرا، بينما تمثل الإحداثيات 1000، 1000 الزاوية السفلية اليمنى لصورة الكاميرا، كما هو موضّح في الرسم التوضيحي أدناه.

الشكل 1: توضِّح الخطوط الحمراء نظام الإحداثيات لتحديد Camera.Area ضمن معاينة الكاميرا. يعرض المربّع الأزرق الموقع الجغرافي وشكل منطقة الكاميرا التي تحتوي على قيم Rect‏ 333,333,667,667.

تتوافق حدود نظام الإحداثيات هذا دائمًا مع الحافة الخارجية للصورة الظاهرة في معاينة الكاميرا، ولا تتقلّص أو تتوسّع مع مستوى التكبير/التصغير. وبالمثل، لا يؤدي تدوير معاينة الصورة باستخدام Camera.setDisplayOrientation() إلى إعادة ربط نظام الإحداثيات.

التعرّف على الوجوه

بالنسبة إلى الصور التي تتضمّن أشخاصًا، تكون الوجوه عادةً الجزء الأكثر أهمية في الصورة، ويجب استخدامها لتحديد كل من التركيز والتوازن الأبيض عند التقاط صورة. يقدّم إطار عمل Android 4.0 (المستوى 14 لواجهة برمجة التطبيقات) واجهات برمجة تطبيقات لتحديد الوجوه وحساب إعدادات الصور باستخدام تكنولوجيا التعرّف على الوجوه.

ملاحظة: أثناء تفعيل ميزة "التعرّف على الوجه"، لن يكون لإعدادات setWhiteBalance(String) و setFocusAreas(List<Camera.Area>) و setMeteringAreas(List<Camera.Area>) أي تأثير.

يتطلب استخدام ميزة "التعرّف على الوجوه" في تطبيق الكاميرا اتّباع بعض الخطوات العامة:

• التأكّد من توفّر ميزة "التعرّف على الوجوه" على الجهاز
• إنشاء مستمع لميزة "التعرّف على الوجوه"
• إضافة مستمع ميزة "التعرّف على الوجوه" إلى عنصر الكاميرا
• بدء ميزة "اكتشاف الوجه" بعد المعاينة (وبعد كل إعادة تشغيل للمعاينة)

لا تتوفّر ميزة "اكتشاف الوجه" على بعض الأجهزة. يمكنك التحقق من توفّر هذه الميزة من خلال الاتصال بالرقم getMaxNumDetectedFaces(). يظهر مثال على هذا التحقّق في startFaceDetection() نموذج الطريقة أدناه.

لتلقّي إشعارات بشأن رصد الوجه والردّ عليه، يجب أن يضبط تطبيق الكاميرا معالجًا لأحداث رصد الوجه. لإجراء ذلك، عليك إنشاء فئة مستمع تُنفِّذ واجهة Camera.FaceDetectionListener كما هو موضَّح في مثال التعليمات البرمجية أدناه.

internal class MyFaceDetectionListener : Camera.FaceDetectionListener {

    override fun onFaceDetection(faces: Array<Camera.Face>, camera: Camera) {
        if (faces.isNotEmpty()) {
            Log.d("FaceDetection", ("face detected: ${faces.size}" +
                    " Face 1 Location X: ${faces[0].rect.centerX()}" +
                    "Y: ${faces[0].rect.centerY()}"))
        }
    }
}

class MyFaceDetectionListener implements Camera.FaceDetectionListener {

    @Override
    public void onFaceDetection(Face[] faces, Camera camera) {
        if (faces.length > 0){
            Log.d("FaceDetection", "face detected: "+ faces.length +
                    " Face 1 Location X: " + faces[0].rect.centerX() +
                    "Y: " + faces[0].rect.centerY() );
        }
    }
}

بعد إنشاء هذه الفئة، يمكنك ضبطها في عنصر Camera الخاص بتطبيقك، كما هو موضّح في مثال التعليمات البرمجية أدناه:

camera?.setFaceDetectionListener(MyFaceDetectionListener())

camera.setFaceDetectionListener(new MyFaceDetectionListener());

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

fun startFaceDetection() {
    // Try starting Face Detection
    val params = mCamera?.parameters
    // start face detection only *after* preview has started

    params?.apply {
        if (maxNumDetectedFaces > 0) {
            // camera supports face detection, so can start it:
            mCamera?.startFaceDetection()
        }
    }
}

public void startFaceDetection(){
    // Try starting Face Detection
    Camera.Parameters params = mCamera.getParameters();

    // start face detection only *after* preview has started
    if (params.getMaxNumDetectedFaces() > 0){
        // camera supports face detection, so can start it:
        mCamera.startFaceDetection();
    }
}

يجب تفعيل ميزة "اكتشاف الوجوه" في كل مرة تبدأ فيها (أو تعيد فيها تشغيل) معاينة الكاميرا. إذا كنت تستخدِم فئة المعاينة الموضّحة في إنشاء فئة معاينة، أضِف startFaceDetection() إلى كلٍّ منsurfaceCreated() وsurfaceChanged() في فئة المعاينة، كما هو موضّح في نموذج الرمز البرمجي أدناه.

override fun surfaceCreated(holder: SurfaceHolder) {
    try {
        mCamera.setPreviewDisplay(holder)
        mCamera.startPreview()

        startFaceDetection() // start face detection feature
    } catch (e: IOException) {
        Log.d(TAG, "Error setting camera preview: ${e.message}")
    }
}

override fun surfaceChanged(holder: SurfaceHolder, format: Int, w: Int, h: Int) {
    if (holder.surface == null) {
        // preview surface does not exist
        Log.d(TAG, "holder.getSurface() == null")
        return
    }
    try {
        mCamera.stopPreview()
    } catch (e: Exception) {
        // ignore: tried to stop a non-existent preview
        Log.d(TAG, "Error stopping camera preview: ${e.message}")
    }
    try {
        mCamera.setPreviewDisplay(holder)
        mCamera.startPreview()

        startFaceDetection() // re-start face detection feature
    } catch (e: Exception) {
        // ignore: tried to stop a non-existent preview
        Log.d(TAG, "Error starting camera preview: ${e.message}")
    }
}

public void surfaceCreated(SurfaceHolder holder) {
    try {
        mCamera.setPreviewDisplay(holder);
        mCamera.startPreview();

        startFaceDetection(); // start face detection feature

    } catch (IOException e) {
        Log.d(TAG, "Error setting camera preview: " + e.getMessage());
    }
}

public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) {

    if (holder.getSurface() == null){
        // preview surface does not exist
        Log.d(TAG, "holder.getSurface() == null");
        return;
    }

    try {
        mCamera.stopPreview();

    } catch (Exception e){
        // ignore: tried to stop a non-existent preview
        Log.d(TAG, "Error stopping camera preview: " + e.getMessage());
    }

    try {
        mCamera.setPreviewDisplay(holder);
        mCamera.startPreview();

        startFaceDetection(); // re-start face detection feature

    } catch (Exception e){
        // ignore: tried to stop a non-existent preview
        Log.d(TAG, "Error starting camera preview: " + e.getMessage());
    }
}

ملاحظة: تذكَّر استدعاء هذه الطريقة بعد استدعاء startPreview(). لا تحاول بدء ميزة "اكتشاف الوجه" في طريقة onCreate() من النشاط الرئيسي لتطبيق الكاميرا، لأنّ المعاينة لا تكون متاحة في هذه المرحلة من تنفيذ تطبيقك.

فيديو بوضع التسريع الزمني

تتيح ميزة "التسريع الزمني" للمستخدمين إنشاء مقاطع فيديو تجمع صورًا تم التقاطها بفواصل زمنية تبلغ بضع ثوانٍ أو دقائق. تستخدِم هذه الميزة MediaRecorder لتسجيل الصور لإنشاء تسلسل متغيّر ببطء.

لتسجيل فيديو في وضع التسريع الزمني باستخدام MediaRecorder، عليك ضبط ملف تعريف المسجّل كما لو كنت تسجّل فيديو عاديًا، مع ضبط عدد اللقطات التي يتم التقاطها في الثانية على عدد منخفض واستخدام أحد إعدادات جودة وضع التسريع الزمني، كما هو موضّح في مثال الرمز البرمجي أدناه.

mediaRecorder.setProfile(CamcorderProfile.get(CamcorderProfile.QUALITY_TIME_LAPSE_HIGH))
mediaRecorder.setCaptureRate(0.1) // capture a frame every 10 seconds

// Step 3: Set a CamcorderProfile (requires API Level 8 or higher)
mediaRecorder.setProfile(CamcorderProfile.get(CamcorderProfile.QUALITY_TIME_LAPSE_HIGH));
...
// Step 5.5: Set the video capture rate to a low number
mediaRecorder.setCaptureRate(0.1); // capture a frame every 10 seconds

يجب إجراء هذه الإعدادات كجزء من إجراء إعداد أكبر لـ MediaRecorder. للحصول على مثال على رمز الضبط الكامل، يُرجى الاطّلاع على ضبط MediaRecorder. بعد اكتمال عملية الضبط، ابدأ تسجيل الفيديو كما لو كنت تسجل مقطع فيديو عاديًا. لمزيد من المعلومات حول ضبط إعدادات MediaRecorder وتشغيله، يُرجى الاطّلاع على مقالة تسجيل الفيديوهات.

يوضّح نموذجا Camera2Video وHdrViewfinder استخدام واجهات برمجة التطبيقات التي تتناولها هذه الصفحة.

حقول الكاميرا التي تتطلّب إذنًا

يجب أن يكون لدى التطبيقات التي تعمل بنظام التشغيل Android 10 (المستوى 29 لواجهة برمجة التطبيقات) أو إصدار أحدث إذن CAMERA لكي تتمكّن من الوصول إلى قيم الحقول التالية التي تعرضها الوسيطة getCameraCharacteristics():

• LENS_POSE_ROTATION
• LENS_POSE_TRANSLATION
• LENS_INTRINSIC_CALIBRATION
• LENS_RADIAL_DISTORTION
• LENS_POSE_REFERENCE
• LENS_DISTORTION
• LENS_INFO_HYPERFOCAL_DISTANCE
• LENS_INFO_MINIMUM_FOCUS_DISTANCE
• SENSOR_REFERENCE_ILLUMINANT1
• SENSOR_REFERENCE_ILLUMINANT2
• SENSOR_CALIBRATION_TRANSFORM1
• SENSOR_CALIBRATION_TRANSFORM2
• SENSOR_COLOR_TRANSFORM1
• SENSOR_COLOR_TRANSFORM2
• SENSOR_FORWARD_MATRIX1
• SENSOR_FORWARD_MATRIX2

نموذج رمز إضافي

لتنزيل نماذج التطبيقات، اطّلِع على نموذج Camera2Basic ونموذج تطبيق CameraX الرسمي.