Cómo enumerar y recuperar elementos multimedia

Una vez que el usuario haya configurado su dispositivo ambient y seleccionado fuentes de contenido multimedia en Google Fotos, tu aplicación podrá enumerar y recuperar esos elementos multimedia para mostrarlos.

Antes de comenzar

• Verifica la configuración del dispositivo: Asegúrate de haber creado y configurado correctamente un dispositivo para el usuario.
• Comprende el flujo de la API de Ambient: Revisa el flujo de la API de Ambient para comprender el proceso general, en especial el paso que implica sondear mediaSourcesSet.

Encuesta para mediaSourcesSet

Antes de que puedas mostrar los elementos multimedia de un dispositivo, el usuario debe haber seleccionado las fotos que quiere compartir con tu aplicación en la app de Google Fotos. Tu aplicación debe sondear el dispositivo para determinar cuándo se realizó esta selección.

Llama periódicamente al método devices.get para el deviceId específico. Supervisa el campo mediaSourcesSet en la respuesta de AmbientDevice. Inicialmente, será false. Una vez que el usuario haya seleccionado correctamente las fuentes de medios, este campo cambiará a true.

La respuesta AmbientDevice incluye un pollingConfig con un pollInterval que debes usar como guía para tu frecuencia de sondeo.

Enumera elementos multimedia

Una vez que mediaSourcesSet es true para un dispositivo, puedes comenzar a recuperar los elementos multimedia seleccionados por el usuario.

1. Usa el extremo mediaItems.list: Realiza una solicitud GET a https://photosambient.googleapis.com/v1/mediaItems y proporciona deviceId en la ruta.

2. Controla la paginación (si es necesario): Es posible que la respuesta esté paginada. Usa el parámetro pageSize para especificar la cantidad máxima de elementos que se devolverán y el pageToken de una respuesta anterior para recuperar las páginas posteriores de resultados.

3. Procesa los elementos multimedia: La respuesta contendrá un array de objetos AmbientMediaItem, cada uno de los cuales representa un elemento multimedia seleccionado. Estos objetos incluyen detalles esenciales, como los siguientes:

   • id: Es el identificador único del elemento multimedia.
   • creationTime: Es la marca de tiempo en la que se creó el elemento multimedia.
   • mediaFile: Es un objeto que contiene detalles para acceder al contenido real.

El campo mediaFile incluye el baseUrl. Este baseUrl es el que usarás para construir URLs que permitan acceder al contenido del elemento multimedia en varias resoluciones o formatos.

URL base

Las URLs base de las APIs de Google Fotos proporcionan acceso a los bytes sin procesar de los elementos multimedia, lo que permite que tu app los descargue o muestre. Estas URLs se incluyen en las respuestas cuando se enumeran álbumes (API de Library) o se accede a elementos multimedia (APIs de Library y Picker). Recuerda que las URLs base requieren parámetros adicionales para funcionar correctamente.

Para la API de Picker:

Todos los objetos PickedMediaItem.mediaFile incluyen un baseUrl.

Las URLs base permanecen activas durante 60 minutos, pero pueden vencer antes si el usuario revoca los permisos de tu app a través de la configuración de su Cuenta de Google.

Nota: Las solicitudes a una baseUrl de PickedMediaItem.mediaFile deben incluir un encabezado de autorización con un token del portador de OAuth 2.0 válido.

Para la API de Library:

Las URLs base permanecen activas durante 60 minutos.

Las diferentes URLs base son las siguientes:

• baseUrl: Accede directamente a fotos, miniaturas de videos o descarga bytes de videos.
• coverPhotoBaseUrl: Accede directamente a la foto de portada del álbum.
• profilePictureBaseUrl: Acceder directamente a la foto de perfil del propietario de un mediaItem

Advertencia: Si usas la URL base, debes especificar un parámetro de descarga o el ancho y la altura máximos.

URLs base de imágenes

A continuación, se muestra la lista de opciones que puedes usar con las URLs base de imágenes:

Parámetro
w, h	Descripción Los parámetros de ancho, w, y alto, h. Para acceder a un elemento multimedia de imagen, como una foto o una miniatura de un video, debes especificar las dimensiones en las que planeas mostrarlo en tu aplicación (para que la imagen se pueda ajustar a esas dimensiones y, al mismo tiempo, conservar la relación de aspecto). Para ello, concatena la URL base con las dimensiones requeridas, como se muestra en los ejemplos. Ejemplos: base-url=wmax-width-hmax-height A continuación, se muestra un ejemplo para mostrar un elemento multimedia que no supere los 2,048 px de ancho ni los 1,024 px de alto: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c	Descripción El parámetro de recorte, c. Si deseas recortar la imagen según las dimensiones exactas de ancho y alto que especificaste, concatena la URL base con el parámetro opcional -c junto con los parámetros obligatorios w y h. El tamaño (en píxeles) debe estar en el rango [1, 16383]. Si el ancho o la altura de la imagen superan el tamaño solicitado, la imagen se reduce y se recorta (manteniendo la relación de aspecto). Ejemplos: base-url=wmax-width-hmax-height-c En este ejemplo, la aplicación muestra un elemento multimedia que tiene exactamente 256 px de ancho por 256 px de alto, como una miniatura: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d	Descripción Parámetro de descarga, d Si deseas descargar la imagen y conservar todos los metadatos Exif, excepto los de ubicación, concatena la URL base con el parámetro d. Ejemplos: base-url=d En este ejemplo, la aplicación descarga una imagen con todos los metadatos, excepto los de ubicación: https://lh3.googleusercontent.com/p/Az....XabC=d

URLs base de los videos

A continuación, se muestra la lista de opciones que puedes usar con las URLs base de los videos:

Parámetro
dv	Descripción Para acceder a los bytes de un video mediaItem, concatena el parámetro baseUrl con el parámetro de descarga de video, dv. El parámetro dv solicita una versión transcodificada de alta calidad del video original. El parámetro no es compatible con los parámetros w y h. Las URLs base para las descargas de videos pueden tardar hasta unos segundos en devolver bytes. Antes de usar este parámetro, verifica que el campo mediaMetadata.status de los elementos multimedia sea READY. De lo contrario, si tu elemento multimedia no terminó de procesarse, es posible que recibas un error. Ejemplos: base-url=dv En el siguiente ejemplo, se muestra cómo descargar los bytes de un video: https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c y d	Descripción Para acceder a la miniatura del video, usa cualquiera de los parámetros de URL base de la imagen. De forma predeterminada, todas las miniaturas de video incluyen una superposición de un botón de reproducción. Consulta el parámetro -no para quitar esta superposición. Ejemplos: Consulta la tabla de URLs de imágenes base para ver ejemplos.
no	Descripción Es el parámetro no de la superposición para quitar la miniatura. Si quieres recuperar la miniatura de un video sin la superposición de un botón de reproducción, concatena la URL base con el parámetro no. El parámetro no se debe usar con al menos uno de los parámetros de URL base de la imagen. Ejemplos: base-url=wmax-width-hmax-height-no En el siguiente ejemplo, se muestra una miniatura de video de 1,280 px de ancho y 720 px de alto exactamente, que no incluye una superposición de botón de reproducción: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URLs base de fotos en movimiento

Las fotos en movimiento contienen elementos de foto y video. Puedes usar parámetros de URLs base de imágenes o URLs base de videos para las solicitudes de fotos en movimiento baseUrl.

Parámetro
dv	Descripción Para recuperar el elemento de video de un elemento multimedia de foto en movimiento, usa el parámetro dv como lo harías para descargar desde URLs base de video.
w, h, c y d	Descripción Para recuperar el elemento de foto de un elemento multimedia de foto en movimiento, usa el formato de las URLs base de imágenes.

Política de contenido y filtrado

De forma predeterminada, Google Fotos aplica un filtro de contenido estándar a las imágenes y los videos que se muestran en un dispositivo compartido, como una TV o una pantalla digital. Este filtro se diseñó para optimizar la experiencia de visualización, ya que excluye contenido como el siguiente:

• Imágenes funcionales (p. ej., capturas de pantalla, documentos, recibos)
• Imágenes que pueden renderizarse de forma deficiente en una pantalla grande (p. ej., resolución muy baja, desenfoque, grano excesivo)
• Contenido identificado como altamente personal o sensible, que puede no estar destinado a mostrarse de forma general en un entorno compartido.

Todo el filtrado de contenido es automático. Para darles a los usuarios más control sobre el contenido que se muestra, puedes permitirles seleccionar y actualizar manualmente las fuentes de medios que se usan para la pantalla ambiente.

Próximos pasos

• Aplicación de ejemplo: Nuestra aplicación de ejemplo incluye un ejemplo de cómo enumerar y recuperar elementos multimedia. Consulta las funciones checkMediaSourcesSet y fetch_media_item_list para obtener más información.
• Documentación de referencia: Consulta la documentación de referencia integral sobre elementos multimedia para obtener información detallada sobre todos los métodos disponibles, los parámetros de solicitud y respuesta, y los códigos de error.