ממשק API של מצלמה

מסגרת Android כוללת תמיכה במצלמות ובתכונות מצלמה שונות שזמינות במכשירים, ומאפשרת לכם לצלם תמונות וסרטונים באפליקציות. במסמך הזה נסביר על גישה מהירה ופשוטה לצילום תמונות וסרטונים, ונציג גישה מתקדמת ליצירת חוויות מצלמה בהתאמה אישית למשתמשים.

הערה: בדף הזה מתוארת הכיתה Camera, שהוצאה משימוש. מומלץ להשתמש בספריית Jetpack‏ CameraX, או, במקרים ספציפיים, בכיתה camera2. גם CameraX וגם Camera2 פועלות ב-Android מגרסה 5.0 (רמת API‏ 21) ואילך.

שיקולים

לפני שמפעילים את האפשרות של האפליקציה להשתמש במצלמות במכשירי Android, כדאי לשקול כמה שאלות לגבי האופן שבו האפליקציה מתכוונת להשתמש בתכונה החומרה הזו.

• דרישה למצלמה – האם השימוש במצלמה חשוב לאפליקציה שלכם עד כדי כך שאתם לא רוצים שהאפליקציה תותקן במכשיר שאין בו מצלמה? אם כן, צריך להצהיר על דרישת המצלמה במניפסט.
• תמונה מהירה או מצלמה מותאמת אישית – איך האפליקציה שלכם תשתמש במצלמה? האם אתם רוצים רק לצלם תמונה או קליפ וידאו מהירים, או שהאפליקציה שלכם תספק דרך חדשה לשימוש במצלמות? כדי לצלם תמונה או סרטון במהירות, כדאי להשתמש באפליקציות מצלמה קיימות. כדי לפתח תכונה מותאמת אישית של מצלמה, כדאי לעיין בקטע פיתוח אפליקציית מצלמה.
• דרישה לשירותים שפועלים בחזית – מתי האפליקציה שלכם יוצרת אינטראקציה עם המצלמה? ב-Android 9 ואילך (API ברמה 28 ואילך), לאפליקציות שפועלות ברקע אין גישה למצלמה. לכן, צריך להשתמש במצלמה רק כשהאפליקציה בחזית או כחלק משירות שפועל בחזית.
• אחסון – האם התמונות או הסרטונים שהאפליקציה יוצרת נועדו להיות גלויים רק לאפליקציה או לשותף אותם כדי שאפליקציות אחרות, כמו 'גלריה' או אפליקציות מדיה ורשתות חברתיות אחרות, יוכלו להשתמש בהם? רוצים שהתמונות והסרטונים יהיו זמינים גם אם האפליקציה תוסר? בקטע שמירה של קובצי מדיה מוסבר איך מטמיעים את האפשרויות האלה.

העקרונות הבסיסיים

מסגרת Android תומכת בצילום תמונות וסרטונים באמצעות API‏ android.hardware.camera2 או המצלמה Intent. אלה הכיתות הרלוונטיות:

android.hardware.camera2

החבילה הזו היא ה-API הראשי לניהול המצלמות במכשיר. אפשר להשתמש בו כדי לצלם תמונות או סרטונים כשאתם מפתחים אפליקציית מצלמה.

Camera

הקלאס הזה הוא ממשק ה-API הקודם שהוצא משימוש לשליטה במצלמות של המכשיר.

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 (רמת API 29) וגרסאות ישנות יותר, ומציינת את הפרטים הבאים במניפסט.

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

• הרשאה להקלטת אודיו – כדי להקליט אודיו עם צילום וידאו, האפליקציה צריכה לבקש את ההרשאה להקלטת אודיו.

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

• הרשאת מיקום – אם האפליקציה שלכם מתייגת תמונות בפרטי מיקום לפי GPS, עליכם לבקש את ההרשאה ACCESS_FINE_LOCATION. הערה: אם האפליקציה שלכם מטרגטת ל-Android 5.0 (רמת API ‏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. הפרטים מפורטים בשיעורי ההדרכה צילום תמונות פשוט וצילום סרטונים פשוט.

פיתוח אפליקציית מצלמה

יכול להיות שמפתחים מסוימים יצטרכו ממשק משתמש של מצלמה מותאם אישית למראה של האפליקציה שלהם או שמציע תכונות מיוחדות. כתיבת קוד משלכם לצילום תמונות יכולה לספק למשתמשים חוויה מרתקת יותר.

הערה: המדריך הבא מיועד לממשק ה-API הישן יותר, Camera, שהוצא משימוש. לאפליקציות מצלמה חדשות או מתקדמות, מומלץ להשתמש ב-API החדש יותר של android.hardware.camera2.

השלבים הכלליים ליצירת ממשק מצלמה מותאם אישית לאפליקציה הם:

• זיהוי מצלמה וגישה אליה – יצירת קוד לבדיקה אם יש מצלמות ולבקשת גישה.
• יצירת מחלקת תצוגה מקדימה – יצירת מחלקה של תצוגה מקדימה של מצלמה שמרחיבה את SurfaceView ומטמיעה את הממשק SurfaceHolder. בכיתה הזו מוצגת תצוגה מקדימה של התמונות הפעילות מהמצלמה.
• יצירת פריסה של תצוגה מקדימה – אחרי שיוצרים את הכיתה של התצוגה המקדימה של המצלמה, יוצרים פריסה של תצוגה שמשלבת את התצוגה המקדימה ואת פקדי ממשק המשתמש הרצויים.
• הגדרת מאזינים לצילום – חיבור מאזינים לפקדים בממשק כדי להתחיל לצלם תמונות או סרטונים בתגובה לפעולות של משתמשים, כמו לחיצה על לחצן.
• צילום ושמירת קבצים – הגדרת הקוד לצילום תמונות או סרטונים ולשמירת הפלט.
• שחרור המצלמה – אחרי שמשתמשים במצלמה, האפליקציה צריכה לשחרר אותה בצורה תקינה לשימוש של אפליקציות אחרות.

חומרת המצלמה היא משאב משותף שצריך לנהל אותו בקפידה כדי שהאפליקציה שלכם לא תתנגש באפליקציות אחרות שרוצות להשתמש בו. בסעיפים הבאים מוסבר איך לזהות חומרה של מצלמה, איך לבקש גישה למצלמה, איך לצלם תמונות או סרטונים ואיך לשחרר את המצלמה כשהאפליקציה סיימה להשתמש בה.

זהירות: חשוב לזכור לשחרר את האובייקט 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 יכולות להיות כמה מצלמות, למשל מצלמה אחורית לצילום ומצלמה קדמית לשיחות וידאו. ב-Android מגרסה 2.3 ואילך (רמת API 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(). אם לא בודקים אם המצלמה בשימוש או לא קיימת, המערכת תסגור את האפליקציה.

במכשירים עם Android מגרסה 2.3 (רמת API‏ 9) ואילך, אפשר לגשת למצלמות ספציפיות באמצעות Camera.open(int). הקוד לדוגמה שלמעלה ייתן גישה למצלמה הראשונה, המצלמה הקדמית, במכשיר עם יותר ממצלמה אחת.

בדיקת התכונות של המצלמה

אחרי שמקבלים גישה למצלמה, אפשר לקבל מידע נוסף על היכולות שלה באמצעות השיטה Camera.getParameters() ולבדוק את היכולות הנתמכות באובייקט Camera.Parameters המוחזר. כשמשתמשים ב-API ברמה 9 ואילך, אפשר להשתמש ב-Camera.getCameraInfo() כדי לקבוע אם המצלמה ממוקמת בחלק הקדמי או האחורי של המכשיר ואת כיוון התמונה.

יצירת כיתה לתצוגה מקדימה

כדי שהמשתמשים יוכלו לצלם תמונות או סרטונים בצורה יעילה, הם צריכים לראות את מה שמצלמת המכשיר רואה. סיווג תצוגה מקדימה של מצלמה הוא SurfaceView שיכול להציג את נתוני התמונה החיים שמגיעים מהמצלמה, כדי שהמשתמשים יוכלו לכוון את התמונה או הסרטון ולצלם אותם.

הקוד לדוגמה הבא מראה איך ליצור סוג בסיסי של תצוגה מקדימה של מצלמה שאפשר לכלול בפריסה View. הכיתה הזו מיישמת את SurfaceHolder.Callback כדי לתעד את אירועי ה-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 (רמת API 24) ואילך, אי אפשר יותר להניח שיחס הגובה-רוחב של התצוגה המקדימה זהה לזה של הפעילות, גם אחרי קריאה ל-setDisplayOrientation(). בהתאם לגודל החלון וליחס הגובה-רוחב, יכול להיות שתצטרכו להתאים תצוגה מקדימה של מצלמה רחבה לפריסה בפורמט לאורך, או להפך, באמצעות פריסה בפורמט letterbox.

הצבת תצוגה מקדימה בפריסה

צריך למקם את הכיתה של תצוגה מקדימה של המצלמה, כמו הדוגמה שמוצגת בקטע הקודם, בפריסה של הפעילות, יחד עם רכיבי UI אחרים לצילום תמונה או סרטון. בקטע הזה נסביר איך ליצור פריסה ופעילות בסיסיות לתצוגה המקדימה.

קוד הפריסה הבא מספק תצוגה בסיסית מאוד שאפשר להשתמש בה כדי להציג תצוגה מקדימה של המצלמה. בדוגמה הזו, הרכיב 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‏ (רמת API 8), אפשר להשתמש ב-method‏ 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());
        }
    }
};

מפעילים את הצילום של התמונה על ידי קריאה ל-method‏ 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 (רמת API‏ 14), הקריאות Camera.lock() ו-Camera.unlock() מנוהלות באופן אוטומטי.

בניגוד לצילום תמונות במצלמת המכשיר, כדי לצלם סרטון צריך להשתמש בסדר קריאה ספציפי מאוד. כדי להכין את האפליקציה לצילומי וידאו ולצלם אותם, צריך לפעול לפי סדר ספציפי של פעולות, כפי שמפורט בהמשך.

1. פתיחת המצלמה – משתמשים ב-Camera.open() כדי לקבל מופע של אובייקט המצלמה.
2. Connect Preview (חיבור לתצוגה מקדימה) – כדי להכין תצוגה מקדימה של תמונה מהמצלמה בשידור חי, מחברים 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. מגדירים את הפורמט והקידוד של פלט הווידאו. ב-Android 2.2 (רמת API 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 לאפליקציה. משתמשים באותו אובייקט שציינתם ב-Connect Preview.

      זהירות: צריך להפעיל את שיטות ההגדרה MediaRecorder בסדר הזה, אחרת יהיו באפליקציה שגיאות וההקלטה תיכשל.

   3. Prepare MediaRecorder – מפעילים את MediaRecorder.prepare() כדי להכין את MediaRecorder עם הגדרות התצורה שסופקו.
   4. התחלת MediaRecorder – התחלת הקלטת וידאו באמצעות קריאה ל-MediaRecorder.start().
5. עצירת ההקלטה של הסרטון – כדי להשלים את ההקלטה של הסרטון, צריך להפעיל את השיטות הבאות בסדר:
   1. Stop MediaRecorder – כדי להפסיק את הקלטת הסרטון, קוראים ל-MediaRecorder.stop().
   2. איפוס MediaRecorder – אפשר גם להסיר את הגדרות ההגדרה מהמכשיר באמצעות קריאה ל-MediaRecorder.reset().
   3. שחרור MediaRecorder – משחררים את MediaRecorder על ידי קריאה ל-MediaRecorder.release().
   4. נעילת המצלמה – כדי לנעול את המצלמה כך שאפשר יהיה להשתמש בה בסשנים עתידיים של MediaRecorder, צריך להפעיל את הפקודה Camera.lock(). החל מגרסה Android 4.0‏ (רמת API 14), הקריאה הזו לא נדרשת אלא אם קריאת MediaRecorder.prepare() נכשלת.
6. הפסקת התצוגה המקדימה – כשהפעילות עם המצלמה מסתיימת, מפסיקים את התצוגה המקדימה באמצעות Camera.stopPreview().
7. שחרור המצלמה – שחרור המצלמה כדי שאפליקציות אחרות יוכלו להשתמש בה, באמצעות קריאה ל-Camera.release().

הערה: אפשר להשתמש ב-MediaRecorder בלי ליצור תצוגה מקדימה במצלמה ולדלג על השלבים הראשונים בתהליך. עם זאת, בדרך כלל משתמשים מעדיפים לראות תצוגה מקדימה לפני שהם מתחילים להקליט, ולכן לא נדון בתהליך הזה כאן.

טיפ: אם האפליקציה משמשת בדרך כלל להקלטת וידאו, צריך להגדיר את setRecordingHint(boolean) ל-true לפני שמתחילים את התצוגה המקדימה. ההגדרה הזו יכולה לעזור לקצר את הזמן הנדרש להתחלת ההקלטה.

הגדרת MediaRecorder

כשמשתמשים בכיתה MediaRecorder כדי לצלם סרטון, צריך לבצע את שלבי ההגדרה בסדר ספציפי ואז לבצע קריאה ל-method‏ 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;
}

בגרסאות Android שקדמו ל-2.2 (רמת API‏ 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 הם הגדרות ברירת מחדל, אבל מומלץ לשנות את ההגדרות האלה בהתאם לאפליקציה שלכם:

• 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 (רמת API‏ 8). לקריאות מקבילות בגרסאות API קודמות, ראו שמירה של קבצים משותפים.
• 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() זמין ב-Android מגרסה 2.2 (רמת API 8) ואילך. אם אתם מטרגטים מכשירים עם גרסאות קודמות של Android, השתמשו ב-Environment.getExternalStorageDirectory() במקום זאת. מידע נוסף זמין במאמר שמירה של קבצים משותפים.

כדי שמזהה ה-URI יתמוך בפרופילים של עבודה, קודם צריך להמיר את מזהה ה-URI של הקובץ למזהה URI של תוכן. לאחר מכן מוסיפים את ה-URI של התוכן ל-EXTRA_OUTPUT של Intent.

מידע נוסף על שמירת קבצים במכשיר Android זמין במאמר אחסון נתונים.

תכונות מצלמה

מערכת Android תומכת במגוון רחב של תכונות מצלמה שאפשר לשלוט בהן דרך אפליקציית המצלמה, כמו פורמט התמונה, מצב הפלאש, הגדרות המיקוד ועוד. בקטע הזה מפורטות התכונות הנפוצות של המצלמה, ומוסבר בקצרה איך משתמשים בהן. אפשר לגשת לרוב התכונות של המצלמה ולהגדיר אותן באמצעות האובייקט Camera.Parameters. עם זאת, יש כמה תכונות חשובות שדורשות יותר מהגדרות פשוטות ב-Camera.Parameters. התכונות האלה מפורטות בקטעים הבאים:

• מדידה ואזורי התמקדות
• זיהוי פנים
• סרטון Time Lapse

מידע כללי על השימוש בתכונות ששולטות בהן באמצעות Camera.Parameters זמין בקטע שימוש בתכונות המצלמה. למידע מפורט יותר על השימוש בתכונות ששולטות באמצעות אובייקט הפרמטרים של המצלמה, אפשר ללחוץ על הקישורים ברשימת התכונות שבהמשך כדי לעבור למסמכי העזרה של ה-API.

טבלה 1. תכונות מצלמה נפוצות שממוינות לפי רמת ה-API של 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, קוראים ל-method‏ 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. בדרך כלל, שינויים בפרמטרים גלויים למשתמש באופן מיידי בתצוגה המקדימה של המצלמה באפליקציה. בצד התוכנה, יכול להיות שיחלפו כמה פריימים עד ששינויים בפרמטר ייכנסו לתוקף, כי חומרת המצלמה מעבדת את ההוראות החדשות ואז שולחת נתוני תמונה מעודכנים.

חשוב: אי אפשר לשנות חלק מתכונות המצלמה לפי רצונכם. באופן ספציפי, כדי לשנות את הגודל או הכיוון של התצוגה המקדימה במצלמה, קודם צריך להפסיק את התצוגה המקדימה, לשנות את גודל התצוגה המקדימה ואז להפעיל מחדש את התצוגה המקדימה. החל מגרסה 4.0 של Android‏ (רמה 14 של API), אפשר לשנות את כיוון התצוגה המקדימה בלי להפעיל מחדש את התצוגה המקדימה.

כדי להטמיע תכונות מצלמה אחרות, צריך יותר קוד, כולל:

• מדידה ואזורי התמקדות
• זיהוי פנים
• סרטון בהילוך מהיר

בחלקים הבאים מוסבר בקצרה איך מטמיעים את התכונות האלה.

מדידה ואזורי התמקדות

בתרחישים מסוימים של צילום, יכול להיות שהמיקוד האוטומטי והמדידה האוטומטית של התאורה לא יניבו את התוצאות הרצויות. החל מ-Android 4.0 (רמת API 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 על 2000. הקואורדינטות -1000,‏ -1000 מייצגות את הפינה השמאלית העליונה של התמונה מהמצלמה, והקואורדינטות 1000,‏ 1000 מייצגות את הפינה השמאלית התחתונה של התמונה מהמצלמה, כפי שמוצג באיור שבהמשך.

איור 1. הקווים האדומים מייצגים את מערכת הקואורדינטות של Camera.Area בתצוגה המקדימה של המצלמה. התיבה הכחולה מציגה את המיקום והצורה של אזור המצלמה עם הערכים של Rect‏ 333,333,667,667.

גבולות מערכת הקואורדינטות הזו תואמים תמיד לקצה החיצוני של התמונה שמוצגת בתצוגה המקדימה במצלמה, והם לא מתכווצים או מתרחבים בהתאם לרמת הזום. באופן דומה, סיבוב התצוגה המקדימה של התמונה באמצעות Camera.setDisplayOrientation() לא משנה את המיפוי של מערכת הקואורדינטות.

זיהוי פנים

בתמונות שכוללות אנשים, הפנים הם בדרך כלל החלק החשוב ביותר בתמונה, ועל סמך הפנים צריך לקבוע גם את המיקוד וגם את איזון הלבן כשמצלמים תמונה. המסגרת של Android 4.0‏ (רמת API 14) מספקת ממשקי API לזיהוי פנים ולחישוב הגדרות התמונה באמצעות טכנולוגיית זיהוי פנים.

הערה: כשהתכונה 'זיהוי פנים' פועלת, לא מתבצעת פעולה לפי ההגדרות של 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 כדי לצלם את התמונות ליצירת סרטון הזמן.

כדי לצלם סרטון Time Lapse באמצעות MediaRecorder, צריך להגדיר את אובייקט התיעוד כאילו רוצים לצלם סרטון רגיל, להגדיר מספר נמוך של פריימים שרוצים לצלם בשנייה ולהשתמש באחת מההגדרות של איכות ה-Time Lapse, כפי שמתואר בדוגמת הקוד שבהמשך.

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 אפשר לראות עוד דוגמאות לשימוש בממשקי ה-API שמפורטים בדף הזה.

שדות של מצלמה שדורשים הרשאה

כדי שאפליקציות שפועלות ב-Android 10 ואילך (רמת API 29 ואילך) יוכלו לגשת לערכי השדות הבאים שמוחזרים על ידי השיטה getCameraCharacteristics(), הן צריכות את ההרשאה CAMERA:

• 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.