Tutorial sul rilevamento del cambio di inquadratura

Pubblico

Questo tutorial è progettato per consentirti di iniziare rapidamente a esplorare e sviluppare applicazioni con l'API Video Intelligence. È progettato per chi ha familiarità con la programmazione di base, anche se non hai molta conoscenza di programmazione, quindi dovresti essere in grado di seguirlo. Una volta seguito questo tutorial, dovresti essere in grado di utilizzare la documentazione di riferimento per creare le tue applicazioni di base.

Questo tutorial illustra un'applicazione API Video Intelligence che utilizza il codice Python. Lo scopo non è spiegare le librerie client Python, ma spiegare come effettuare chiamate all'API Video Intelligence. Le applicazioni in Java e Node.js sono essenzialmente simili.

Se stai cercando un esempio di solo codice o un esempio in un'altra lingua, consulta la guida illustrativa complementare.

Prerequisiti

Questo tutorial ha diversi prerequisiti:

Hai configurato un progetto API Video Intelligence in Google Cloud Console.
Hai configurato l'ambiente utilizzando un account di servizio e le credenziali predefinite dell'applicazione.
Hai familiarità con la programmazione di Python.
Configurare l'ambiente di sviluppo Python. Si consiglia di avere installato sul sistema la versione più recente di Python, pip e virtualenv. Per istruzioni, consulta la guida alla configurazione dell'ambiente di sviluppo di Python per Google Cloud Platform.
Hai installato la libreria client di Google Cloud.

Annota un video utilizzando il rilevamento del cambio di inquadratura

Questo tutorial illustra un'applicazione API di base, utilizzando una richiesta SHOT_CHANGE_DETECTION. Una richiesta SHOT_CHANGE_DETECTION fornisce i risultati dell'annotazione:

Elenco di tutti gli scatti che avvengono all'interno del video
Per ogni scatto, fornisci l'ora di inizio e quella di fine

Innanzitutto, mostriamo l'intero codice. Tieni presente che abbiamo rimosso la maggior parte dei commenti da questo codice per mostrare quanto è breve il codice. Forniremo altri commenti man mano che analizziamo il codice.

samples/shotchange/shotchange.py

Visualizza su GitHub

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)

Questa semplice applicazione esegue le attività seguenti:

Importa le librerie necessarie per eseguire l'applicazione.
Recupera un file video archiviato nell'URI di Cloud Storage come argomento e passalo alla funzione main().
Recupera le credenziali per eseguire il servizio API Video Intelligence.
Crea una richiesta di annotazione video da inviare al servizio video.
Invia la richiesta e restituisce un'operazione a lunga esecuzione.
Esegue il loop dell'operazione a lunga esecuzione fino a quando il video non viene elaborato e restituisce i valori disponibili.
Analizza la risposta per il servizio e mostra la risposta per l'utente.

Esamineremo questi passaggi più in dettaglio di seguito.

Importa librerie

samples/shotchange/shotchange.py

Visualizza su GitHub

import argparse

from google.cloud import videointelligence

Importiamo argparse per consentire all'applicazione di accettare nomi di file di input come argomenti.

Per utilizzare l'API Video Intelligence, viene importata anche la libreria google.cloud.videointelligence, che contiene la directory delle chiamate API e delle costanti di enumerazione.

Esegui la tua applicazione

samples/shotchange/shotchange.py

Visualizza su GitHub

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)

In questo caso, analizziamo l'argomento passato per l'URI Google Cloud Storage del nome file video e lo trasmettiamo alla funzione main().

Autenticazione nell'API

Prima di comunicare con il servizio API Video Intelligence, devi autenticare il servizio utilizzando credenziali acquisite in precedenza. All'interno di un'applicazione, il modo più semplice per ottenere le credenziali è utilizzare Credenziali predefinite dell'applicazione (ADC). Per impostazione predefinita, ADC tenterà di ottenere credenziali dal file di ambiente GOOGLE_APPLICATION_CREDENTIALS, che deve essere impostato in modo che punti al file chiave JSON dell'account di servizio. Dovresti aver configurato il tuo account di servizio e l'ambiente in modo da utilizzare ADC nella Guida rapida. Per ulteriori informazioni, consulta la sezione Configurazione di un account di servizio.

Crea la richiesta

samples/shotchange/shotchange.py

Visualizza su GitHub

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

Ora che il nostro servizio API Video Intelligence è pronto, possiamo creare una richiesta per quel servizio. Le richieste all'API Video Intelligence vengono fornite come oggetti JSON. Consulta la documentazione di riferimento dell'API Video Intelligence per informazioni complete sulla struttura specifica di questa richiesta.

Questo snippet di codice esegue le attività seguenti:

Crea il JSON per una richiesta POST al metodo annotate_video().
Aggiunge nella richiesta la posizione di Google Cloud Storage del nostro nome file video passato.
Indica che il metodo annotate deve eseguire un SHOT_CHANGE_DETECTION.

Crea l'operazione a lunga esecuzione

Quando eseguiamo per la prima volta una richiesta contro l'API Video Intelligence, non riceviamo un risultato immediato, ma riceviamo un nome dell'operazione memorizzato nel campo name della risposta, che possiamo utilizzare per verificare i risultati in un secondo momento.

Passando il nome dell'operazione (che è una stringa numerica) al metodo Service Operations operations dell'API Video Intelligence viene restituito lo stato attuale dell'operazione. Di seguito è riportato un esempio di risposta:

{
   "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"
   }
}

Tieni presente che al momento il campo response contiene solo un campo @type, che indica il tipo di risposta. Una volta che i risultati saranno effettivamente disponibili, il campo di risposta conterrà i risultati di quel tipo.

Controlla l'operazione

samples/shotchange/shotchange.py

Visualizza su GitHub

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

Utilizzando la richiesta di operazione esistente per la nostra operazione esistente, creiamo un loop while per controllare periodicamente lo stato di tale operazione. Una volta che la nostra operazione ha indicato che l'operazione è done, usciamo dal loop e possiamo analizzare la risposta.

Analizza la risposta

samples/shotchange/shotchange.py

Visualizza su GitHub

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 volta completata l'operazione, la risposta conterrà un AnnotateVideoResponse, che consiste in un elenco di annotationResults, uno per ogni video inviato nella richiesta. Poiché abbiamo inviato un solo video nella richiesta, prendiamo la prima shotAnnotations del risultato. Esaminiamo tutti i segmenti ' del video.

Esegui la nostra applicazione

Per eseguire la nostra applicazione, passa semplicemente l'URI Cloud Storage di 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

Complimenti! Hai eseguito un'attività di annotazione utilizzando l'API Video Intelligence.