Tutorial de detección de cambio de plano

Audiencia

Este tutorial se ha diseñado para que puedas empezar a explorar y desarrollar aplicaciones con la API Video Intelligence rápidamente. Está diseñada para personas que tengan conocimientos básicos de programación, aunque, incluso si no tienes muchos conocimientos de programación, deberías poder seguir el curso. Después de haber seguido este tutorial, podrás utilizar la documentación de referencia para crear tus propias aplicaciones básicas.

Este tutorial avanza a través de una aplicación de la API Video Intelligence que usa el código de Python. El objetivo de este artículo no es explicar las bibliotecas de cliente de Python, sino cómo hacer llamadas a la API Video Intelligence. Las aplicaciones en Java y Node.js son esencialmente similares.

Si buscas un ejemplo que solo incluya código o un ejemplo en otro idioma, consulta la guía práctica complementaria.

Requisitos previos

Este tutorial tiene varios requisitos previos:

Anotar un vídeo mediante la detección de cambios de plano

Este tutorial te guía a través de una aplicación básica de API de vídeo mediante una petición SHOT_CHANGE_DETECTION. Las peticiones SHOT_CHANGE_DETECTION proporcionan los resultados de la anotación:

  • Una lista de todos los planos que ocurren dentro del vídeo
  • Proporciona el tiempo de inicio y finalización de cada plano

Primero mostraremos todo el código. Ten en cuenta que hemos eliminado la mayoría de los comentarios de este código para mostrarte lo breve que es. Incluiremos más comentarios a medida que analicemos 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 sencilla aplicación realiza las siguientes tareas:

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

A continuación, repasaremos estos pasos con más detalle.

Importar bibliotecas

import argparse

from google.cloud import videointelligence

Importamos argparse para que la aplicación pueda aceptar nombres de archivo de entrada como argumentos.

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

Ejecutar la 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 transferido para obtener el URI de Google Cloud Storage del nombre de archivo de vídeo y lo transferimos a la función main().

Autenticar en la API

Antes de comunicarte con el servicio de API Video Intelligence, debes autenticar tu servicio mediante las credenciales adquiridas previamente. Dentro de una aplicación, la forma más sencilla de obtener credenciales es usar Credenciales de aplicación predeterminadas (ADC). De forma predeterminada, ADC intentará obtener las credenciales del archivo de entorno GOOGLE_APPLICATION_CREDENTIALS, que debe configurarse para que apunte al archivo JSON de la clave de tu cuenta de servicio. (Deberías haber configurado tu cuenta de servicio y tu entorno para usar ADC en la guía de inicio rápido. Para obtener más información, consulta Configurar una cuenta de servicio.

Construir 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 está listo nuestro servicio de API Video Intelligence, podemos crear una petición para ese servicio. Las solicitudes a la API Video Intelligence se envían como objetos JSON. Consulta la referencia de la API Video Intelligence para obtener información completa sobre la estructura específica de dicha petición.

Este fragmento de código realiza las siguientes tareas:

  1. Crea el JSON de una solicitud POST al método annotate_video().
  2. Inserta la ubicación de Google Cloud Storage del nombre de archivo de vídeo que hemos enviado en la solicitud.
  3. Indica que el método annotate debe realizar una SHOT_CHANGE_DETECTION.

Construir la operación de larga duración

Cuando ejecutamos por primera vez una solicitud en la API Video Intelligence, no obtenemos un resultado inmediato, sino un nombre de operación, que se almacena en el campo name de la respuesta. Después, podemos usarlo para comprobar los resultados más adelante.

Si se pasa el nombre de esa operación (que es una cadena numérica) al método Operations Service operations de la API Video Intelligence, se devuelve 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, por el momento, el campo response solo contiene un campo @type, que indica el tipo de respuesta. Una vez que los resultados estén realmente disponibles, el campo de respuesta contendrá resultados de ese tipo.

Comprobar la operación

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

Con la solicitud de operación de nuestra operación, creamos un bucle while para comprobar periódicamente el estado de esa operación. Una vez que nuestra operación haya indicado que la operación es done, saldremos del bucle y podremos analizar la respuesta.

Analizar 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á un AnnotateVideoResponse, que consta de una lista de annotationResults, uno por cada vídeo enviado en la solicitud. Como solo hemos enviado un vídeo en la solicitud, tomamos el primer shotAnnotations del resultado. Pasamos por todos los "segmentos" del vídeo.

Ejecutar nuestra aplicación

Para ejecutar nuestra aplicación, solo tienes que pasarle el URI de Cloud Storage de un vídeo:

$ 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

¡Enhorabuena! Has realizado una tarea de anotación con la API Video Intelligence.