Instructivo de detección de cambio de plano

Público

Este instructivo está diseñado para que comiences a explorar y desarrollar aplicaciones rápidamente con la API de Video Intelligence. Está pensado para los usuarios familiarizados con la programación básica, aunque deberías poder entenderlo sin tener muchos conocimientos sobre programación. Una vez que completes este instructivo, debería poder usar la Documentación de referencia para crear tus propias aplicaciones básicas.

En este instructivo, se explica paso a paso una aplicación de la API de Video Intelligence que usa el código de Python. La finalidad no es explicar las bibliotecas cliente de Python, sino cómo hacer llamadas a la API de Video Intelligence. En esencia, las aplicaciones en Java y Node.js son similares.

Si buscas un ejemplo de código único o un ejemplo en otro lenguaje, consulta la guía práctica complementaria.

Requisitos previos

Este instructivo tiene varios requisitos previos:

Anota un video con la detección de cambio de toma

En este instructivo, se explica cómo es una aplicación básica de la API de video, mediante una solicitud SHOT_CHANGE_DETECTION. Una solicitud SHOT_CHANGE_DETECTION proporciona los resultados de la anotación:

  • Una lista de todas las tomas que ocurren en el video
  • En cada toma, proporciona la hora de inicio y finalización de la toma

Te mostraremos el código completo primero. (Ten en cuenta que quitamos la mayoría de los comentarios de este código para mostrarte lo breve que es. Proporcionaremos más comentarios a medida que repasemos el código).

import argparse

from google.cloud import videointelligence

def analyze_shots(path):
    """Detects camera shot changes."""
    video_client = videointelligence.VideoIntelligenceServiceClient()
    features = [videointelligence.Feature.SHOT_CHANGE_DETECTION]
    operation = video_client.annotate_video(
        request={"features": features, "input_uri": path}
    )
    print("\nProcessing video for shot change annotations:")

    result = operation.result(timeout=120)
    print("\nFinished processing.")

    for i, shot in enumerate(result.annotation_results[0].shot_annotations):
        start_time = (
            shot.start_time_offset.seconds + shot.start_time_offset.microseconds / 1e6
        )
        end_time = (
            shot.end_time_offset.seconds + shot.end_time_offset.microseconds / 1e6
        )
        print("\tShot {}: {} to {}".format(i, start_time, end_time))

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("path", help="GCS path for shot change detection.")
    args = parser.parse_args()

    analyze_shots(args.path)

Esta aplicación simple ejecuta las siguientes tareas:

  • Importa las bibliotecas necesarias para ejecutar la aplicación.
  • Toma un archivo de video almacenado en el URI de Cloud Storage como un argumento y lo pasa a la función main().
  • Obtiene las credenciales para ejecutar el servicio de la API de Video Intelligence.
  • Crea una solicitud de anotación de video para enviar al servicio de video.
  • Envía la solicitud y muestra una operación de larga duración.
  • Repite de forma indefinida la operación de larga duración hasta que el video se procese y muestre los valores disponibles.
  • Analiza la respuesta del servicio y muestra la respuesta al usuario.

Repasaremos estos pasos con más detalle a continuación.

Importa las bibliotecas

import argparse

from google.cloud import videointelligence

Importamos argparse para permitir que la aplicación acepte nombres de archivos de entrada como argumentos.

Para usar la API de Video Intelligence, también importamos la biblioteca google.cloud.videointelligence, que contiene el directorio de nuestras llamadas a la API y constantes de enumeración.

Ejecuta tu aplicación

parser = argparse.ArgumentParser(
    description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
)
parser.add_argument("path", help="GCS path for shot change detection.")
args = parser.parse_args()

analyze_shots(args.path)

Aquí, analizamos el argumento pasado para el URI de Google Cloud Storage del nombre de archivo del video y lo pasamos a la función main().

Autenticación en la API

Antes de comunicarte con el servicio de la API de Video Intelligence, debes autenticar tu servicio con las credenciales ya adquiridas. Dentro de una aplicación, la manera más simple de obtener credenciales es usar las Credenciales predeterminadas de la aplicación (ADC). De forma predeterminada, las ADC intentarán obtener credenciales del archivo de entorno GOOGLE_APPLICATION_CREDENTIALS, el cual debe configurarse para que apunte al archivo de claves JSON de tu cuenta de servicio. (Debes haber configurado tu cuenta de servicio y tu entorno para usar las ADC en la Guía de inicio rápido. Consulta Configurar una cuenta de servicio para obtener más información).

Crea la solicitud

video_client = videointelligence.VideoIntelligenceServiceClient()
features = [videointelligence.Feature.SHOT_CHANGE_DETECTION]
operation = video_client.annotate_video(
    request={"features": features, "input_uri": path}
)

Ahora que nuestro servicio de la API de Video Intelligence está listo, podemos generar una solicitud para ese servicio. Las solicitudes a la API de Video Intelligence se proporcionan como objetos JSON. Consulta la referencia de la API de Video Intelligence para obtener información completa sobre la estructura específica de esta solicitud.

Este fragmento de código realiza las siguientes tareas:

  1. Construye el JSON para una solicitud POST al método annotate_video().
  2. Inserta la ubicación de Google Cloud Storage de nuestro nombre de archivo de video pasado en la solicitud.
  3. Indica que el método annotate debe realizar una SHOT_CHANGE_DETECTION.

Crea la operación de larga duración

Cuando ejecutamos una solicitud en la API de Video Intelligence por primera vez, no obtenemos un resultado inmediato. En su lugar, obtenemos un nombre de operación, almacenado dentro del campo name de la respuesta, que luego podemos usar para verificar los resultados más adelante.

Pasar el nombre de esa operación (que es una string numérica) al método Servicio de operaciones operations de la API de Video Intelligence muestra el estado actual de la operación. A continuación se muestra una respuesta de ejemplo:

{
   "response":{
      "@type":"type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoResponse"
   },
   "name":"us-west1.17159971042783089144",
   "metadata":{
      "annotationProgress":[
         {
            "inputUri":"/video/gbikes_dinosaur.mp4",
            "updateTime":"2017-01-27T19:45:54.297807Z",
            "startTime":"2017-01-27T19:45:54.275023Z"
         }
      ],
      "@type":"type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress"
   }
}

Ten en cuenta que el campo response en este momento solo contiene un campo @type, que denota el tipo de esa respuesta. Una vez que los resultados están disponibles, el campo de respuesta contendrá los resultados de ese tipo.

Verifica la operación

result = operation.result(timeout=120)
print("\nFinished processing.")

Con la solicitud de operación existente para nuestra operación existente, construimos un bucle while a fin de verificar el estado de esa operación de forma periódica. Una vez que nuestra operación indica que la operación está done, desglosamos el bucle y podemos analizar la respuesta.

Analiza la respuesta

for i, shot in enumerate(result.annotation_results[0].shot_annotations):
    start_time = (
        shot.start_time_offset.seconds + shot.start_time_offset.microseconds / 1e6
    )
    end_time = (
        shot.end_time_offset.seconds + shot.end_time_offset.microseconds / 1e6
    )
    print("\tShot {}: {} to {}".format(i, start_time, end_time))

Una vez que se haya completado la operación, la respuesta contendrá una AnnotateVideoResponse, que consiste en una lista de annotationResults, uno para cada video enviado en la solicitud. Como enviamos solo un video en la solicitud, tomamos la primera shotAnnotations del resultado. Repasamos todos los "segmentos" del video.

Ejecuta nuestra aplicación

Para ejecutar nuestra aplicación, simplemente pasa el URI de Cloud Storage de un video:

$ python shotchange.py gs://cloud-samples-data/video/gbikes_dinosaur.mp4
operationId=us-west1.12468772851081463748
Operation us-west1.12468772851081463748 started: 2017-01-30T01:53:45.981043Z
Processing video for shot change annotations:
Finished processing.
  Shot 0: 0.0 to 5.166666
  Shot 1: 5.233333 to 10.066666
  Shot 2: 10.1 to 28.133333
  Shot 3: 28.166666 to 42.766666

¡Felicitaciones! Realizaste una tarea de anotación con la API de Video Intelligence.