Questa pagina è stata tradotta dall'API Cloud Translation.

Transcodifica di contenuti multimediali compatibili

Su Android 12 (livello API 31) e versioni successive, il sistema può convertire automaticamente i video registrati in formati come HEVC (H.265) in AVC (H.264) quando vengono aperti da un'app che non supporta HEVC. Questa funzionalità consente alle app di acquisizione video di utilizzare una codifica più moderna ed efficiente per lo spazio di archiviazione per i video registrati sul dispositivo senza sacrificare la compatibilità con altre app.

I seguenti formati possono essere transcodificati automaticamente per i contenuti creati sul dispositivo:

Formato multimediale	Attributo XML	Tipo MIME MediaFormat
HEVC (H.265)	HEVC	MediaFormat.MIMETYPE_VIDEO_HEVC
HDR10	HDR10	MediaFeature.HdrType.HDR10
HDR10+	HDR10+	MediaFeature.HdrType.HDR10_PLUS

Android presuppone che le app possano supportare la riproduzione di tutti i formati multimediali, pertanto la transcodifica dei contenuti multimediali compatibili è disattivata per impostazione predefinita.

Quando utilizzare la transcodifica

La transcodifica è un'operazione di calcolo complessa e aggiunge un ritardo significativo all'apertura di un file video. Ad esempio, la transcodifica di un file video HEVC di un minuto in AVC su uno smartphone Pixel 3 richiede circa 20 secondi. Per questo motivo, devi transcodificare un file video solo quando lo invii dal dispositivo. Ad esempio, quando condividi un file video con altri utenti della stessa app o con un server cloud che non supporta i formati video moderni.

Non eseguire la transcodifica quando apri i file video per la riproduzione sul dispositivo o per la creazione di immagini in miniatura.

Configurazione della transcodifica

Le app possono controllare il proprio comportamento di transcodifica dichiarando le proprie funzionalità multimediali. Esistono due modi per dichiarare queste funzionalità: nel codice o in una risorsa.

Dichiarare le funzionalità nel codice

Puoi dichiarare le funzionalità multimediali nel codice creando un'istanza di un oggetto ApplicationMediaCapabilities utilizzando un generatore:

Kotlin

val mediaCapabilities = ApplicationMediaCapabilities.Builder()
    .addSupportedVideoMimeType(MediaFormat.MIMETYPE_VIDEO_HEVC)
    .addUnsupportedHdrType(MediaFeature.HdrType.HDR10)
    .addUnsupportedHdrType(MediaFeature.HdrType.HDR10_PLUS)
    .build()

Java

ApplicationMediaCapabilities mediaCapabilities = new ApplicationMediaCapabilities.Builder()
        .addSupportedVideoMimeType(MediaFormat.MIMETYPE_VIDEO_HEVC)
        .addUnsupportedHdrType(MediaFeature.HdrType.HDR10)
        .addUnsupportedHdrType(MediaFeature.HdrType.HDR10_PLUS)
        .build();

Utilizza questo oggetto quando accedi ai contenuti multimediali tramite metodi come ContentResolver#openTypedAssetFileDescriptor():

Kotlin

val providerOptions = Bundle().apply {
    putParcelable(MediaStore.EXTRA_MEDIA_CAPABILITIES, mediaCapabilities)
}
contentResolver.openTypedAssetFileDescriptor(mediaUri, mediaMimeType, providerOptions)
    .use { fileDescriptor ->
        // Content will be transcoded based on values defined in the
        // ApplicationMediaCapabilities provided.
    }

Java

Bundle providerOptions = new Bundle();
providerOptions.putParcelable(MediaStore.EXTRA_MEDIA_CAPABILITIES, mediaCapabilities);
try (AssetFileDescriptor fileDescriptor =  contentResolver.openTypedAssetFileDescriptor(mediaUri, mediaMimeType, providerOptions)) {
    // Content will be transcoded based on values defined in the
    // ApplicationMediaCapabilities provided.
}

Questo metodo consente un controllo granulare per percorsi di codice specifici, ad esempio l'attivazione della transcodifica solo quando si trasferisce un file video al di fuori del dispositivo. Ha la precedenza sul metodo descritto di seguito.

Dichiarare le funzionalità in una risorsa

La dichiarazione delle funzionalità in una risorsa consente un controllo generale sulla transcodifica. Questo metodo deve essere utilizzato solo in casi molto specifici. Ad esempio, se la tua app riceve file video solo da altre app (anziché aprirli direttamente) e li carica su un server che non supporta codec video moderni (vedi lo scenario di esempio 1 di seguito).

L'utilizzo di questo metodo quando non è assolutamente necessario potrebbe attivare la transcodifica in scenari involontari, ad esempio durante la creazione di miniature dei video, con conseguente peggioramento dell'esperienza utente.

Per utilizzare questo metodo, crea un file di risorse media_capabilities.xml:

<?xml version="1.0" encoding="utf-8"?>
<media-capabilities xmlns:android="http://schemas.android.com/apk/res/android">
    <format android:name="HEVC" supported="true"/>
    <format android:name="HDR10" supported="false"/>
    <format android:name="HDR10Plus" supported="false"/>
</media-capabilities>

In questo esempio, i video HDR registrati sul dispositivo vengono transcodificati senza problemi in video AVC SDR (Standard Dynamic Range), mentre i video HEVC no.

Utilizza un tag property all'interno del tag application per aggiungere un riferimento al file media capabilities. Aggiungi queste proprietà al file AndroidManifest.xml:

<property
    android:name="android.media.PROPERTY_MEDIA_CAPABILITIES"
    android:resource="@xml/media_capabilities" />

Utilizzare le funzionalità multimediali di un'altra app per aprire un file video

Se la tua app condivide un file video con un'altra app, il file video potrebbe dover essere transcodificato prima che l'app di destinazione possa aprirlo.

Puoi gestire questa richiesta aprendo un file video utilizzando openTypedAssetFileDescriptor e specificando l'UID dell'app di destinazione, che può essere ottenuto utilizzando Binder.getCallingUid. La piattaforma utilizza quindi le funzionalità multimediali dell'app di destinazione per determinare se il file video deve essere transcodificato.

Kotlin

val providerOptions = Bundle().apply {
    putParcelable(MediaStore.EXTRA_MEDIA_CAPABILITIES_UID, Binder.getCallingUid())
}
contentResolver.openTypedAssetFileDescriptor(mediaUri, mediaMimeType, providerOptions)
    .use { fileDescriptor ->
        // Content will be transcoded based on the media capabilities of the
        // calling app.
    }

Java

Bundle providerOptions = new Bundle();
providerOptions.putParcelable(MediaStore.EXTRA_MEDIA_CAPABILITIES_UID, Binder.getCallingUid());
try (AssetFileDescriptor fileDescriptor =  contentResolver.openTypedAssetFileDescriptor(mediaUri, mediaMimeType, providerOptions)) {
    // Content will be transcoded based on the media capabilities of the
    // calling app.
}

Scenari di esempio

I seguenti diagrammi mostrano i due casi d'uso comuni. In entrambi i casi, il video originale è archiviato in formato HEVC e l'app di condivisione video non supporta HEVC.

Esempio 1. La transcodifica viene avviata dall'app di acquisizione video. L'app di condivisione video dichiara di non supportare HEVC nel suo file di risorse delle funzionalità multimediali. Poi richiede un video all'app di acquisizione video. L'app di acquisizione video gestisce la richiesta e apre il file utilizzando openTypedAssetFileDescriptor, specificando l'UID dell'app di condivisione. Viene avviata la procedura di transcodifica. Una volta ricevuto, il video transcodificato viene fornito all'app di condivisione, che lo carica su un server nel cloud.

Esempio 2. La transcodifica viene avviata dall'app di condivisione video. L'app di acquisizione video condivide un video con l'app di condivisione video utilizzando un URI MediaStore. L'app di condivisione video apre il file video utilizzando openTypedAssetFileDescriptor, specificando che non supporta HEVC nelle sue funzionalità multimediali. Viene avviata la procedura di transcodifica e, al termine, il file viene caricato su un server nel cloud.

Formati non dichiarati

La transcodificazione dei contenuti multimediali compatibili è attivata per tutti i formati dichiarati non supportati ed è disattivata per tutti i formati dichiarati supportati. Per gli altri formati non dichiarati, la piattaforma decide se eseguire o meno la transcodifica. In Android 12 la transcodifica è disattivata per tutti i formati non dichiarati. Questo comportamento potrebbe cambiare per i nuovi formati in futuro.

Opzioni sviluppatore

Puoi utilizzare le seguenti opzioni per sviluppatori per ignorare il comportamento di transcodifica predefinito di Android:

Sostituisci impostazioni predefinite transcodifica. Questa impostazione determina se la piattaforma controlla o meno la transcodifica automatica. Quando l'override è attivo, le impostazioni predefinite della piattaforma vengono ignorate e l'impostazione enable transcoding controlla la transcodifica automatica. Questa opzione è disattivata per impostazione predefinita.
Attiva la transcodifica. Questa impostazione specifica se i formati non dichiarati devono essere transcodificati automaticamente o meno. È attivata per impostazione predefinita, ma ha effetto solo se è attivata anche l'opzione Sostituisci i valori predefiniti della transcodifica.
Presupponi che le app supportino i formati moderni. Questa impostazione controlla cosa succede quando l'app tenta di riprodurre un formato non dichiarato. Questo accade quando il file manifest non dichiara se l'app supporta o meno un determinato formato oppure se Google non ha aggiunto l'app all'elenco di transcodifica forzata lato server. Quando l'impostazione è attivata, l'app non esegue la transcodifica, mentre se è disattivata, l'app esegue la transcodifica. Questa opzione è attiva per impostazione predefinita.
Mostra notifiche relative alla transcodifica Se questa opzione è attivata, l'app mostra una notifica relativa all'avanzamento della transcodifica quando questa viene attivata dalla lettura di un file multimediale non supportato. Questa opzione è attiva per impostazione predefinita.
Disattiva memorizzazione nella cache per la transcodifica Se questa opzione è attivata, le app che richiedono la transcodifica non useranno la memorizzazione nella cache per la transcodifica. Questa opzione può essere utile durante lo sviluppo per attivare facilmente la transcodifica su un file multimediale non supportato, ma può causare scarse prestazioni del dispositivo. Questa opzione è disattivata per impostazione predefinita.