CameraX: czym jest, CameraX API i jak działa kamera

Co to jest CameraX?

CameraX — to biblioteka z zestawu Android Jetpack, po raz pierwszy wydana przez Google w 2019 roku jako zamiennik przestarzałego Camera API i uproszczona alternatywa dla złożonego Camera2. Główna filozofia CameraX — „napisz raz, działa na wszystkich urządzeniach". Biblioteka automatycznie obsługuje różnice sprzętowe: położenie kamer, obsługiwane rozdzielczości, orientację sensora i dostępne formaty — programista nie musi pisać kodu specyficznego dla urządzenia.

Architektura CameraX opiera się na use cases: Preview (wyświetlanie obrazu z kamery w Viewfinder), ImageCapture (robienie zdjęć), ImageAnalysis (analiza strumienia klatek dla ML) i VideoCapture (nagrywanie wideo). Każdy use case to niezależny komponent, który można łączyć: jednocześnie uruchomić Preview dla wizjera i ImageAnalysis dla przetwarzania ML. Według Google (2026), CameraX jest obsługiwany na 99% urządzeń Android z API 21+.

Główne funkcje

CameraX zapewnia automatyczne przełączanie między przednią i tylną kamerą, obsługę obrotu ekranu bez odtwarzania sesji, wbudowaną obsługę cyklu życia przez LifecycleOwner, wiązanie use cases z jednym procesem Lifecycle, obsługę Camera2 Extensions dla portretu, HDR i trybu nocnego, a także TestableCameraX do testów jednostkowych bez rzeczywistego urządzenia.

Use cases CameraX

CameraX definiuje cztery standardowe use case, z których każdy rozwiązuje konkretne zadanie pracy z kamerą. Use cases można łączyć: najpopularniejsze zestawienia to Preview + ImageCapture dla aparatu i Preview + ImageAnalysis dla skanera ML.

Preview

Preview use case wyświetla strumień wideo z kamery w PreviewView — specjalnym View z biblioteki CameraX. PreviewView automatycznie dostosowuje się do proporcji kamery, obsługuje ScaleType (FillCenter, FitCenter) i obrót ekranu bez odtwarzania use case. Programista musi tylko powiązać Preview z Lifecycle przez ProcessCameraProvider.

ImageAnalysis

ImageAnalysis use case przekazuje każdą klatkę z kamery do handlera w celu analizy: rozpoznawanie tekstu, wykrywanie twarzy, skanowanie kodów QR. Analizator otrzymuje klatki w formacie YUV_420_888 — uniwersalnej przestrzeni kolorów Android. Tryb pracy (BLOCKING lub NON_BLOCKING) zarządza kolejką klatek: BLOCKING czeka na zakończenie poprzedniej analizy, NON_BLOCKING pomija klatki w przypadku opóźnienia.

ImageCapture

ImageCapture use case robi zdjęcia z kamery z ustawieniami lampy błyskowej, rozdzielczości i kompresji. Obsługiwane są formaty JPEG i RAW (na zgodnych urządzeniach). ImageCapture zapisuje zdjęcie asynchronicznie przez OnImageCapturedCallback lub bezpośrednio do pliku przez ImageCapture.OutputFileOptions.

VideoCapture — nagrywanie wideo

VideoCapture use case został dodany w CameraX 1.1.0 (beta) i pozwala nagrywać wideo w rozdzielczości do 4K przy 30 FPS. Use case automatycznie synchronizuje się z Preview: obraz w wizjerze odpowiada temu, co jest nagrywane do pliku. VideoCapture używa wewnętrznie MediaCodec i MediaMuxer, ukrywając złożoność konfiguracji kodeka wideo i kontenera MP4.

CameraX vs Camera2

CameraX i Camera2 — dwa podejścia do pracy z kamerą w Android. Camera2 — niskopoziomowy API, dający pełną kontrolę nad urządzeniem. CameraX — wysokopoziomowa abstrakcja, automatyzująca typowe scenariusze. Wybór między nimi zależy od wymagań projektu.

Używaj CameraX do standardowych zadań: aparat w aplikacji, skaner QR, przetwarzanie strumienia ML. Używaj Camera2, gdy wymagane jest ręczne sterowanie ekspozycją, RAW z pełną kontrolą parametrów, praca z wieloma kamerami jednocześnie.

Przykłady kodu w Kotlin

Rozważmy pełną konfigurację CameraX w aplikacji Android z użyciem wszystkich trzech głównych use cases: Preview, ImageCapture i ImageAnalysis.

Konfiguracja ProcessCameraProvider

Kod wiąże CameraX z Lifecycle Activity przez ProcessCameraProvider. Najpierw żądana jest instancja providera, następnie tworzone są use cases i wykonywane jest wiązanie.

val cameraProviderFuture =
    ProcessCameraProvider.getInstance(this)

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

    // Tworzenie Preview
    val preview = Preview.Builder()
        .build()
        .also {
            it.setSurfaceProvider(
                binding.viewFinder.surfaceProvider
            )
        }

    // Tworzenie ImageCapture
    val imageCapture = ImageCapture.Builder()
        .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
        .build()

    // Powiązanie z Lifecycle
    cameraProvider.unbindAll()
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}, ContextCompact.getMainExecutor(this))

Kod Kotlin otrzymuje ProcessCameraProvider przez future, tworzy use cases Preview i ImageCapture, i wiąże je z Lifecycle bieżącej Activity. CameraX automatycznie obsługuje obrót ekranu, przełączanie kamer i zwalnianie zasobów przy zamykaniu Activity.

ImageAnalysis do przetwarzania ML

Dodajmy ImageAnalysis use case do przetwarzania klatka po klatce strumienia z kamery, na przykład do integracji z ML Kit.

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

imageAnalysis.setAnalyzer(
    ContextCompact.getMainExecutor(this)
) { imageProxy ->
    // Konwersja YUV na Bitmap dla ML Kit
    val bitmap = ImageUtils.yuvToBitmap(imageProxy)
    val inputImage = InputImage.fromBitmap(bitmap)

    // Uruchomienie rozpoznawania tekstu ML Kit
    recognizer.process(inputImage)
        .addOnSuccessListener { result ->
            // Przetwarzanie wyniku
            processTextResult(result)
        }
        .addOnCompleteListener {
            imageProxy.close()
        }
}

ImageAnalysis z strategią KEEP_ONLY_LATEST przetwarza tylko ostatnią dostępną klatkę, pomijając nieaktualne, jeśli analizator nie nadąża. Każda klatka jest konwertowana z YUV do Bitmap dla ML Kit, po czym uruchamiane jest rozpoznawanie tekstu. Wywołanie imageProxy.close() jest obowiązkowe — w przeciwnym razie CameraX przestanie dostarczać nowe klatki.

CameraX Extensions

CameraX Extensions — moduł dodający zaawansowane tryby fotografowania: portretowy (rozmycie tła), HDR (rozszerzony zakres dynamiczny), tryb nocny (fotografowanie przy słabym oświetleniu), autoretusz (korekcja skóry) i tryb „piękna twarz" (beauty). Rozszerzenia aktywują się tylko na urządzeniach, gdzie producent kamery dostarczył implementację OEM.

Sprawdzanie i włączanie rozszerzeń

Przed użyciem CameraX Extensions należy sprawdzić, czy rozszerzenie jest dostępne na bieżącym urządzeniu. Google zaleca sprawdzanie przez ExtensionsManager.isExtensionAvailable.

val extensionsManager =
    ExtensionsManager.getInstance(this)

if (extensionsManager.isExtensionAvailable(
    cameraProvider,
    CameraSelector.DEFAULT_BACK_CAMERA,
    ExtensionMode.BOKEH
)) {
    // Włączenie trybu portretowego
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}

Kod sprawdza obsługę rozszerzenia BOKEH (portretowego) przez ExtensionsManager i włącza je, jeśli dostępna jest implementacja OEM. CameraX automatycznie przełącza ustawienia kamery dla trybu portretowego. Jeśli rozszerzenie jest niedostępne, aplikacja kontynuuje działanie w standardowym trybie bez awarii.

CameraX Extensions rozwiązują jeden z głównych problemów programowania Android: fragmentację kamer. Na różnych urządzeniach tryb portretowy jest realizowany inaczej — niektóre używają dwóch obiektywów, inne — programowego rozmycia. CameraX abstrahuje tę różnicę: programista włącza tryb BOKEH, a biblioteka sama określa, jak go zaimplementować na konkretnym urządzeniu. Google utrzymuje listę sprawdzonych partnerów OEM: Samsung, Xiaomi, OPPO, vivo, Google Pixel.

Podczas pracy z CameraX należy uwzględnić ograniczenia dotyczące liczby jednoczesnych use cases: na większości urządzeń można jednocześnie uruchomić maksymalnie 3 use case. Na przykład Preview + ImageCapture + ImageAnalysis działają na wszystkich nowoczesnych urządzeniach, ale Preview + ImageCapture + VideoCapture mogą nie być obsługiwane na budżetowych modelach. CameraX udostępnia metodę ProcessCameraProvider.checkAvailability(), która sprawdza zgodność kombinacji use cases przed wiązaniem, co pozwala uniknąć crash w runtime.

CameraX integruje się z Jetpack Navigation przez CameraXFragment lub zgodny z Compose PreviewView. Dla Compose używany jest element AndroidView, w który osadza się PreviewView. CameraX poprawnie obsługuje obrót ekranu i zmianę konfiguracji bez utraty stanu sesji kamery — wystarczy wskazać LifecycleOwner, a biblioteka automatycznie odtworzy wiązanie use cases przy obrocie urządzenia.

Do testowania CameraX bez rzeczywistego urządzenia Google udostępnia TestableCameraX — bibliotekę emulującą zachowanie kamery w testach jednostkowych. TestableCameraX pozwala symulować klatki z kamery, sprawdzać działanie ImageAnalysis i poprawność przetwarzania ImageCapture bez fizycznego urządzenia. To znacznie przyspiesza pipeline CI/CD dla projektów pracujących z kamerą.