CameraX: چیست، CameraX API و نحوه کار دوربین

CameraX چیست؟

CameraX — کتابخانه‌ای از مجموعه Android Jetpack است که اولین بار توسط Google در سال 2019 به عنوان جایگزینی برای Camera API قدیمی و جایگزینی ساده‌شده برای Camera2 پیچیده منتشر شد. فلسفه اصلی CameraX — «یک بار بنویس، روی همه دستگاه‌ها کار کن». کتابخانه به طور خودکار تفاوت‌های سخت‌افزاری را مدیریت می‌کند: موقعیت دوربین‌ها، وضوح‌های پشتیبانی‌شده، جهت سنسور و فرمت‌های موجود — توسعه‌دهنده نیازی به نوشتن کد خاص دستگاه ندارد.

معماری CameraX بر اساس use cases ساخته شده است: Preview (نمایش تصویر دوربین در Viewfinder)، ImageCapture (عکاسی)، ImageAnalysis (تحلیل جریان فریم برای ML) و VideoCapture (ضبط ویدیو). هر use case یک مؤلفه مستقل است که می‌تواند ترکیب شود: همزمان Preview برای منظره‌یاب و ImageAnalysis برای پردازش ML اجرا شود. بر اساس Google (2026)، CameraX روی 99% دستگاه‌های Android با API 21+ پشتیبانی می‌شود.

قابلیت‌های اصلی

CameraX تعویض خودکار بین دوربین جلو و عقب، پشتیبانی از چرخش صفحه بدون بازآفرینی جلسه، مدیریت داخلی چرخه حیات از طریق LifecycleOwner، اتصال use cases به یک فرآیند Lifecycle، پشتیبانی از Camera2 Extensions برای پرتره، HDR و حالت شب، و همچنین TestableCameraX برای تست واحد بدون دستگاه واقعی را فراهم می‌کند.

use casesهای CameraX

CameraX چهار use case استاندارد تعریف می‌کند که هر کدام یک وظیفه خاص کار با دوربین را حل می‌کند. use casesها قابل ترکیب هستند: محبوب‌ترین ترکیب‌ها Preview + ImageCapture برای دوربین و Preview + ImageAnalysis برای اسکنر ML است.

Preview

Preview use case جریان ویدیو از دوربین را در PreviewView نمایش می‌دهد — View ویژه از کتابخانه CameraX. PreviewView به طور خودکار با نسبت تصویر دوربین تنظیم می‌شود، از ScaleType (FillCenter, FitCenter) و چرخش صفحه بدون بازآفرینی use case پشتیبانی می‌کند. توسعه‌دهنده فقط باید Preview را از طریق ProcessCameraProvider به Lifecycle متصل کند.

ImageAnalysis

ImageAnalysis use case هر فریم از دوربین را برای تحلیل به پردازشگر منتقل می‌کند: تشخیص متن، تشخیص چهره، اسکن کد QR. تحلیلگر فریم‌ها را در قالب YUV_420_888 دریافت می‌کند — فضای رنگی جهانی Android. حالت کار (BLOCKING یا NON_BLOCKING) صف فریم‌ها را مدیریت می‌کند: BLOCKING منتظر پایان تحلیل قبلی می‌ماند، NON_BLOCKING در صورت تأخیر فریم‌ها را رد می‌کند.

ImageCapture

ImageCapture use case با تنظیمات فلش، وضوح و فشرده‌سازی از دوربین عکس می‌گیرد. فرمت‌های JPEG و RAW پشتیبانی می‌شوند (در دستگاه‌های سازگار). ImageCapture عکس را به صورت ناهمگام از طریق OnImageCapturedCallback یا مستقیماً در فایل از طریق ImageCapture.OutputFileOptions ذخیره می‌کند.

VideoCapture — ضبط ویدیو

VideoCapture use case در CameraX 1.1.0 (بتا) اضافه شده است و امکان ضبط ویدیو با وضوح تا 4K در 30 FPS را فراهم می‌کند. use case به طور خودکار با Preview همگام‌سازی می‌شود: تصویر در منظره‌یاب با آنچه در فایل ضبط می‌شود مطابقت دارد. VideoCapture در داخل از MediaCodec و MediaMuxer استفاده می‌کند و پیچیدگی تنظیم کدک ویدیو و کانتینر MP4 را پنهان می‌کند.

CameraX در مقابل Camera2

CameraX و Camera2 — دو رویکرد برای کار با دوربین در Android. Camera2 — API سطح پایین که کنترل کامل روی دستگاه می‌دهد. CameraX — انتزاع سطح بالا که سناریوهای معمولی را خودکار می‌کند. انتخاب بین آنها به نیازهای پروژه بستگی دارد.

از CameraX برای وظایف استاندارد استفاده کنید: دوربین در برنامه، اسکنر QR، پردازش جریان ML. از Camera2 زمانی استفاده کنید که کنترل دستی نوردهی، عکاسی RAW با کنترل کامل پارامترها، کار با چند دوربین همزمان مورد نیاز است.

نمونه کد در Kotlin

تنظیمات کامل CameraX در برنامه Android با استفاده از هر سه use case اصلی را بررسی می‌کنیم: Preview، ImageCapture و ImageAnalysis.

تنظیم ProcessCameraProvider

کد CameraX را از طریق ProcessCameraProvider به Lifecycle Activity متصل می‌کند. ابتدا یک نمونه از provider درخواست می‌شود، سپس use cases ایجاد و اتصال انجام می‌شود.

val cameraProviderFuture =
    ProcessCameraProvider.getInstance(this)

cameraProviderFuture.addListener({
    val cameraProvider = cameraProviderFuture.get()

    // ایجاد Preview
    val preview = Preview.Builder()
        .build()
        .also {
            it.setSurfaceProvider(
                binding.viewFinder.surfaceProvider
            )
        }

    // ایجاد ImageCapture
    val imageCapture = ImageCapture.Builder()
        .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
        .build()

    // اتصال به Lifecycle
    cameraProvider.unbindAll()
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}, ContextCompact.getMainExecutor(this))

کد Kotlin ProcessCameraProvider را از طریق future دریافت می‌کند، use cases Preview و ImageCapture را ایجاد می‌کند و آنها را به Lifecycle Activity جاری متصل می‌کند. CameraX به طور خودکار چرخش صفحه، تعویض دوربین‌ها و آزادسازی منابع هنگام بسته شدن Activity را مدیریت می‌کند.

ImageAnalysis برای پردازش ML

ImageAnalysis use case را برای پردازش فریم به فریم جریان دوربین اضافه می‌کنیم، مثلاً برای ادغام با ML Kit.

val imageAnalysis = ImageAnalysis.Builder()
    .setBackpressureStrategy(
        ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
    )
    .build()

imageAnalysis.setAnalyzer(
    ContextCompact.getMainExecutor(this)
) { imageProxy ->
    // تبدیل YUV به Bitmap برای ML Kit
    val bitmap = ImageUtils.yuvToBitmap(imageProxy)
    val inputImage = InputImage.fromBitmap(bitmap)

    // اجرای تشخیص متن ML Kit
    recognizer.process(inputImage)
        .addOnSuccessListener { result ->
            // پردازش نتیجه
            processTextResult(result)
        }
        .addOnCompleteListener {
            imageProxy.close()
        }
}

ImageAnalysis با استراتژی KEEP_ONLY_LATEST فقط آخرین فریم موجود را پردازش می‌کند و فریم‌های قدیمی را در صورت عدم سرعت تحلیلگر رد می‌کند. هر فریم از YUV به Bitmap برای ML Kit تبدیل می‌شود، سپس تشخیص متن اجرا می‌شود. فراخوانی imageProxy.close() اجباری است — در غیر این صورت CameraX ارائه فریم‌های جدید را متوقف می‌کند.

CameraX Extensions

CameraX Extensions — ماژولی که حالت‌های پیشرفته عکاسی را اضافه می‌کند: پرتره (محو کردن پس‌زمینه)، HDR (محدوده دینامیکی گسترده)، حالت شب (عکاسی در نور کم)، رتوش خودکار (تصحیح پوست) و حالت «چهره زیبا» (beauty). افزونه‌ها فقط در دستگاه‌هایی فعال می‌شوند که تولیدکننده دوربین پیاده‌سازی OEM را ارائه کرده است.

بررسی و فعال‌سازی افزونه‌ها

قبل از استفاده از CameraX Extensions باید بررسی کنید که آیا افزونه در دستگاه فعلی در دسترس است یا خیر. Google بررسی از طریق ExtensionsManager.isExtensionAvailable را توصیه می‌کند.

val extensionsManager =
    ExtensionsManager.getInstance(this)

if (extensionsManager.isExtensionAvailable(
    cameraProvider,
    CameraSelector.DEFAULT_BACK_CAMERA,
    ExtensionMode.BOKEH
)) {
    // فعال‌سازی حالت پرتره
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}

کد پشتیبانی از افزونه BOKEH (پرتره) را از طریق ExtensionsManager بررسی می‌کند و در صورت وجود پیاده‌سازی OEM آن را فعال می‌کند. CameraX به طور خودکار تنظیمات دوربین را برای حالت پرتره تغییر می‌دهد. اگر افزونه در دسترس نباشد، برنامه در حالت استاندارد بدون مشکل به کار ادامه می‌دهد.

CameraX Extensions یکی از مشکلات اصلی توسعه Android را حل می‌کند: تکه‌تکه شدن دوربین‌ها. در دستگاه‌های مختلف، حالت پرتره به طور متفاوت پیاده‌سازی می‌شود — برخی از دو لنز استفاده می‌کنند، برخی دیگر از محو کردن نرم‌افزاری. CameraX این تفاوت را انتزاع می‌کند: توسعه‌دهنده حالت BOKEH را فعال می‌کند و کتابخانه خود تعیین می‌کند که چگونه آن را در دستگاه خاص پیاده‌سازی کند. Google فهرستی از شرکای OEM تأیید شده را نگهداری می‌کند: Samsung, Xiaomi, OPPO, vivo, Google Pixel.

هنگام کار با CameraX مهم است که محدودیت‌های مربوط به تعداد use cases همزمان را در نظر بگیرید: در اکثر دستگاه‌ها حداکثر 3 use case می‌توانند همزمان اجرا شوند. به عنوان مثال، Preview + ImageCapture + ImageAnalysis در همه دستگاه‌های مدرن کار می‌کند، اما Preview + ImageCapture + VideoCapture ممکن است در مدل‌های اقتصادی پشتیبانی نشود. CameraX متد ProcessCameraProvider.checkAvailability() را ارائه می‌کند که سازگاری ترکیب use cases را قبل از اتصال بررسی می‌کند و از crash در زمان اجرا جلوگیری می‌کند.

CameraX با Jetpack Navigation از طریق CameraXFragment یا PreviewView سازگار با Compose ادغام می‌شود. برای Compose از عنصر AndroidView استفاده می‌شود که PreviewView در آن قرار می‌گیرد. CameraX به درستی چرخش صفحه و تغییر پیکربندی را بدون از دست دادن وضعیت جلسه دوربین مدیریت می‌کند — کافی است LifecycleOwner را مشخص کنید و کتابخانه به طور خودکار اتصال use cases را هنگام چرخش دستگاه بازآفرینی می‌کند.

برای آزمایش CameraX بدون دستگاه واقعی، Google TestableCameraX را ارائه می‌کند — کتابخانه‌ای که رفتار دوربین را در تست‌های واحد شبیه‌سازی می‌کند. TestableCameraX امکان شبیه‌سازی فریم‌های دوربین، بررسی عملکرد ImageAnalysis و صحت پردازش ImageCapture بدون دستگاه فیزیکی را فراهم می‌کند. این به طور قابل توجهی pipeline CI/CD را برای پروژه‌های کار با دوربین تسریع می‌کند.