CameraX: cos'è, API CameraX e come funziona la fotocamera

Cos'è CameraX?

CameraX è una libreria della suite Android Jetpack, rilasciata per la prima volta da Google nel 2019 come sostituto della obsoleta Camera API e alternativa semplificata alla complessa Camera2. La filosofia principale di CameraX è “scrivi una volta, funziona su tutti i dispositivi”. La libreria gestisce automaticamente le differenze hardware: posizione delle fotocamere, risoluzioni supportate, orientamento del sensore e formati disponibili — lo sviluppatore non deve scrivere codice specifico del dispositivo.

L'architettura di CameraX è basata sui casi d'uso: Preview (visualizzazione del flusso della fotocamera in Viewfinder), ImageCapture (scatto di foto), ImageAnalysis (analisi del flusso di frame per ML) e VideoCapture (registrazione video). Ogni caso d'uso è un componente indipendente che può essere combinato: eseguire Preview per il mirino e ImageAnalysis per l'elaborazione ML simultaneamente. Secondo Google (2026), CameraX è supportato sul 99% dei dispositivi Android con API 21+.

Funzionalità principali

CameraX fornisce commutazione automatica tra fotocamera anteriore e posteriore, supporto per la rotazione dello schermo senza ricreare la sessione, gestione integrata del ciclo di vita tramite LifecycleOwner, binding dei casi d'uso a un singolo processo Lifecycle, supporto per Camera2 Extensions per ritratto, HDR e modalità notturna, e TestableCameraX per test unitari senza dispositivo reale.

Casi d'uso di CameraX

CameraX definisce quattro casi d'uso standard, ciascuno dei quali risolve un compito specifico della fotocamera. I casi d'uso possono essere combinati: le combinazioni più popolari sono Preview + ImageCapture per un'app fotocamera e Preview + ImageAnalysis per uno scanner ML.

Preview

Il caso d'uso Preview mostra il flusso video della fotocamera in PreviewView — una View speciale della libreria CameraX. PreviewView si adatta automaticamente alle proporzioni della fotocamera, supporta ScaleType (FillCenter, FitCenter) e la rotazione dello schermo senza ricreare il caso d'uso. Lo sviluppatore deve solo associare Preview a un Lifecycle tramite ProcessCameraProvider.

ImageAnalysis

Il caso d'uso ImageAnalysis invia ogni frame della fotocamera a un gestore per l'analisi: riconoscimento testo, rilevamento volti, scansione QR code. L'analizzatore riceve i frame in formato YUV_420_888 — lo spazio colore universale di Android. Modalità operativa (BLOCKING o NON_BLOCKING) controlla la coda dei frame: BLOCKING attende il completamento dell'analisi precedente, NON_BLOCKING salta i frame in caso di ritardo.

ImageCapture

Il caso d'uso ImageCapture scatta foto dalla fotocamera con impostazioni di flash, risoluzione e compressione. I formati JPEG e RAW sono supportati (su dispositivi compatibili). ImageCapture salva lo scatto in modo asincrono tramite OnImageCapturedCallback o direttamente in un file tramite ImageCapture.OutputFileOptions.

VideoCapture — Registrazione video

Il caso d'uso VideoCapture è stato aggiunto in CameraX 1.1.0 (beta) e consente di registrare video fino a 4K a 30 FPS. Il caso d'uso si sincronizza automaticamente con Preview: l'immagine nel mirino corrisponde a ciò che viene registrato nel file. VideoCapture utilizza internamente MediaCodec e MediaMuxer, nascondendo la complessità della configurazione del codec video e del contenitore MP4.

CameraX vs Camera2

CameraX e Camera2 sono due approcci per lavorare con la fotocamera in Android. Camera2 è un'API di basso livello che offre il controllo completo del dispositivo. CameraX è un'astrazione di alto livello che automatizza scenari tipici. La scelta tra essi dipende dai requisiti del progetto.

Usa CameraX per attività standard: fotocamera nell'app, scanner QR, elaborazione flusso ML. Usa Camera2 quando è richiesto il controllo manuale dell'esposizione, lo scatto RAW con controllo completo dei parametri o il lavoro con più fotocamere contemporaneamente.

Esempi di codice in Kotlin

Esaminiamo una configurazione completa di CameraX in un'applicazione Android utilizzando i tre casi d'uso principali: Preview, ImageCapture e ImageAnalysis.

Configurazione di ProcessCameraProvider

Il codice associa CameraX al ciclo di vita dell'Activity tramite ProcessCameraProvider. Prima viene richiesta un'istanza del provider, poi vengono creati i casi d'uso e viene eseguito il binding.

val cameraProviderFuture =
    ProcessCameraProvider.getInstance(this)

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

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

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

    // Binding al Lifecycle
    cameraProvider.unbindAll()
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}, ContextCompact.getMainExecutor(this))

Il codice Kotlin ottiene ProcessCameraProvider tramite un future, crea i casi d'uso Preview e ImageCapture e li associa al ciclo di vita dell'Activity corrente. CameraX gestisce automaticamente la rotazione dello schermo, il cambio di fotocamera e il rilascio delle risorse alla chiusura dell'Activity.

ImageAnalysis per l'elaborazione ML

Aggiungiamo un caso d'uso ImageAnalysis per l'elaborazione frame per frame del flusso della fotocamera, ad esempio per l'integrazione con ML Kit.

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

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

    // Avvio riconoscimento testo ML Kit
    recognizer.process(inputImage)
        .addOnSuccessListener { result ->
            // Elaborazione del risultato
            processTextResult(result)
        }
        .addOnCompleteListener {
            imageProxy.close()
        }
}

ImageAnalysis con strategia KEEP_ONLY_LATEST elabora solo l'ultimo frame disponibile, saltando quelli obsoleti se l'analizzatore non riesce a tenere il passo. Ogni frame viene convertito da YUV a Bitmap per ML Kit, dopodiché viene avviato il riconoscimento del testo. La chiamata a imageProxy.close() è obbligatoria — altrimenti CameraX smetterà di fornire nuovi frame.

CameraX Extensions

CameraX Extensions è un modulo che aggiunge modalità di scatto avanzate: ritratto (sfocatura dello sfondo), HDR (gamma dinamica estesa), modalità notturna (scatto in condizioni di scarsa illuminazione), ritocco automatico (correzione della pelle) e modalità bellezza. Le estensioni vengono attivate solo sui dispositivi in cui il produttore della fotocamera ha fornito un'implementazione OEM.

Verifica e attivazione delle estensioni

Prima di utilizzare CameraX Extensions, è necessario verificare se l'estensione è disponibile sul dispositivo corrente. Google consiglia di verificare tramite ExtensionsManager.isExtensionAvailable.

val extensionsManager =
    ExtensionsManager.getInstance(this)

if (extensionsManager.isExtensionAvailable(
    cameraProvider,
    CameraSelector.DEFAULT_BACK_CAMERA,
    ExtensionMode.BOKEH
)) {
    // Attivazione modalità ritratto
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}

Il codice verifica il supporto per l'estensione BOKEH (ritratto) tramite ExtensionsManager e la attiva se è disponibile un'implementazione OEM. CameraX commuta automaticamente le impostazioni della fotocamera per la modalità ritratto. Se l'estensione non è disponibile, l'app continua a funzionare in modalità standard senza crash.

CameraX Extensions risolve uno dei principali problemi dello sviluppo Android: la frammentazione delle fotocamere. Su dispositivi diversi, la modalità ritratto è implementata in modo diverso — alcuni usano doppie lenti, altri usano la sfocatura software. CameraX astrae questa differenza: lo sviluppatore attiva la modalità BOKEH, e la libreria stessa determina come implementarla su un dispositivo specifico. Google mantiene un elenco di partner OEM verificati: Samsung, Xiaomi, OPPO, vivo, Google Pixel.

Quando si lavora con CameraX, è importante considerare le limitazioni sul numero di casi d'uso simultanei: sulla maggior parte dei dispositivi, è possibile eseguire al massimo 3 casi d'uso contemporaneamente. Ad esempio, Preview + ImageCapture + ImageAnalysis funziona su tutti i dispositivi moderni, ma Preview + ImageCapture + VideoCapture potrebbe non essere supportato sui modelli economici. CameraX fornisce il metodo ProcessCameraProvider.checkAvailability(), che verifica la compatibilità della combinazione di casi d'uso prima del binding, aiutando a evitare crash in fase di esecuzione.

CameraX si integra con Jetpack Navigation tramite CameraXFragment o PreviewView compatibile con Compose. Per Compose, viene utilizzato l'elemento AndroidView, in cui viene incorporato PreviewView. CameraX gestisce correttamente la rotazione dello schermo e i cambiamenti di configurazione senza perdere lo stato della sessione della fotocamera — basta specificare il LifecycleOwner, e la libreria ricreerà automaticamente i binding dei casi d'uso quando il dispositivo ruota.

Per testare CameraX senza un dispositivo reale, Google fornisce TestableCameraX — una libreria che emula il comportamento della fotocamera nei test unitari. TestableCameraX consente di simulare i frame della fotocamera, testare il funzionamento di ImageAnalysis e la correttezza di ImageCapture senza un dispositivo fisico. Questo accelera significativamente la pipeline CI/CD per i progetti che lavorano con la fotocamera.