Cloud Run、Video Intelligence API、Vertex AI を使用して、動画のシーン単位の画像説明サービスを作成する

1. はじめに

概要

この Codelab では、動画内のすべてのシーンの視覚的な説明を提供する Node.js で記述された Cloud Run サービスを作成します。まず、サービスは Video Intelligence API を使用して、シーンが変更されるたびにタイムスタンプを検出します。次に、サービスは ffmpeg というサードパーティのバイナリを使用して、シーン変更のタイムスタンプごとにスクリーンショットをキャプチャします。最後に、Vertex AI 画像キャプションを使用して、スクリーンショットの視覚的な説明を提供します。

この Codelab では、Cloud Run サービス内で ffmpeg を使用して、指定されたタイムスタンプで動画から画像をキャプチャする方法についても説明します。ffmpeg は個別にインストールする必要があるため、この Codelab では、Cloud Run サービスの一部として ffmpeg をインストールする Dockerfile を作成する方法について説明します。

Cloud Run サービスの仕組みを以下に示します。

学習内容

• Dockerfile を使用してコンテナ イメージを作成し、サードパーティのバイナリをインストールする方法
• Cloud Run サービス用のサービス アカウントを作成して他の Google Cloud サービスを呼び出すことで、最小権限の原則に従う方法
• Cloud Run サービスから Video Intelligence クライアント ライブラリを使用する方法
• Google API を呼び出して、Vertex AI から各シーンの視覚的な説明を取得する方法

2. 設定と要件

前提条件

• Cloud コンソールにログインしていること。
• Cloud Run サービスをすでにデプロイしていること。たとえば、ソースコードからウェブサービスをデプロイするクイックスタートに沿って作業を開始できます。

Cloud Shell をアクティブにする

1. Cloud Console で、[Cloud Shell をアクティブにする ] をクリックします。

Cloud Shell を初めて起動した場合は、その内容を説明する画面が表示されます。その場合は、[続行] をクリックしてください。

すぐにプロビジョニングが実行され、Cloud Shell に接続されます。

この仮想マシンには、必要な開発ツールがすべてロードされています。永続的な 5 GB のホーム ディレクトリが用意されており、Google Cloud で実行されるため、ネットワーク パフォーマンスと認証が大幅に向上します。 この Codelab で行う作業のほとんどはブラウザから実行できます。

Cloud Shell に接続すると、認証が完了し、プロジェクトがプロジェクト ID に設定されていることがわかります。

2. Cloud Shell で次のコマンドを実行して、認証されたことを確認します。

gcloud auth list

コマンド出力

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

注: gcloud コマンドライン ツールは、Google Cloud の強力な統合型コマンドライン ツールです。このツールは Cloud Shell にあらかじめインストールされています。タブ補完にも対応しています。コマンドを初めて実行したとき、認証を求めるプロンプトが表示されることがあります。詳細については、gcloud コマンドライン ツールの概要をご覧ください。

3. Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

コマンド出力

[core]
project = <PROJECT_ID>

上記のようになっていない場合は、次のコマンドで設定できます。

gcloud config set project <PROJECT_ID>

コマンド出力

Updated property [core/project].

注: Cloud Shell の外部でこのチュートリアルを完了する場合は、アプリケーションのデフォルト認証情報を設定するをご覧ください。

3. API を有効にして環境変数を設定する

この Codelab を開始する前に、いくつかの API を有効にする必要があります。この Codelab では、次の API を使用する必要があります。これらの API を有効にするには、次のコマンドを実行します。

gcloud services enable run.googleapis.com \
    storage.googleapis.com \
    cloudbuild.googleapis.com \
    videointelligence.googleapis.com \
    aiplatform.googleapis.com

次に、この Codelab 全体で使用する環境変数を設定します。

REGION=<YOUR-REGION>
PROJECT_ID=<YOUR-PROJECT-ID>

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
SERVICE_NAME=video-describer
export BUCKET_ID=$PROJECT_ID-video-describer

4. Cloud Storage バケットを作成する

次のコマンドを使用して、Cloud Run サービスで処理する動画をアップロードできる Cloud Storage バケットを作成します。

gsutil mb -l us-central1 gs://$BUCKET_ID/

（省略可）このサンプル動画をローカルにダウンロードして使用できます。

gsutil cp gs://cloud-samples-data/video/visionapi.mp4 testvideo.mp4

動画ファイルをストレージ バケットにアップロードします。

FILENAME=<YOUR-VIDEO-FILENAME>
gsutil cp $FILENAME gs://$BUCKET_ID

5. Node.js アプリを作成する

まず、ソースコードのディレクトリを作成し、そのディレクトリに移動します。

mkdir video-describer && cd $_

次の内容で package.json ファイルを作成します。

{
  "name": "video-describer",
  "version": "1.0.0",
  "private": true,
  "description": "describes the image in every scene for a given video",
  "main": "index.js",
  "author": "Google LLC",
  "license": "Apache-2.0",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/storage": "^7.7.0",
    "@google-cloud/video-intelligence": "^5.0.1",
    "axios": "^1.6.2",
    "express": "^4.18.2",
    "fluent-ffmpeg": "^2.1.2",
    "google-auth-library": "^9.4.1"
  }
}

このアプリは、読みやすさを向上させるために複数のソースファイルで構成されています。まず、次の内容で index.js ソースファイルを作成します。このファイルには、サービスのエントリ ポイントとアプリのメインロジックが含まれています。

const { captureImages } = require('./imageCapture.js');
const { detectSceneChanges } = require('./sceneDetector.js');
const transcribeScene = require('./imageDescriber.js');
const { Storage } = require('@google-cloud/storage');
const fs = require('fs').promises;
const path = require('path');
const express = require('express');
const app = express();

const bucketName = process.env.BUCKET_ID;

const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
  console.log(`video describer service ready: listening on port ${port}`);
});

// entry point for the service
app.get('/', async (req, res) => {

  try {

    // download the requested video from Cloud Storage
    let videoFilename =  req.query.filename; 
    console.log("processing file: " + videoFilename);

    // download the file to locally to the Cloud Run instance
    let localFilename = await downloadVideoFile(videoFilename);

    // detect all the scenes in the video & save timestamps to an array
    let timestamps = await detectSceneChanges(localFilename);
    console.log("Detected scene changes at the following timestamps: ", timestamps);

    // create an image of each scene change
    // and save to a local directory called "output"
    await captureImages(localFilename, timestamps);

    // get an access token for the Service Account to call the Google APIs 
    let accessToken = await transcribeScene.getAccessToken();
    console.log("got an access token");

    let imageBaseName = path.parse(localFilename).name;

    // the data structure for storing the scene description and timestamp
    // e.g. an array of json objects {timestamp: 1, description: "..."}, etc.    
    let scenes = []

    // for each timestamp, send the image to Vertex AI
    console.log("getting Vertex AI description all the timestamps");
    scenes = await Promise.all(
      timestamps.map(async (timestamp) => {

        let filepath = path.join("./output", imageBaseName + "-" + timestamp + ".png");

        // get the base64 encoded image
        const encodedFile = await fs.readFile(filepath, 'base64');

        // send each screenshot to Vertex AI for description
        let description = await transcribeScene.transcribeScene(accessToken, encodedFile)

        return { timestamp: timestamp, description: description };
      }));

    console.log("finished collecting all the scenes");
    //console.log(scenes);

    return res.json(scenes);

  } catch (error) {

    //return an error
    console.log("received error: ", error);
    return res.status(500).json("an internal error occurred");
  }

});

async function downloadVideoFile(videoFilename) {
  // Creates a client
  const storage = new Storage();

  // keep same name locally
  let localFilename = videoFilename;

  const options = {
    destination: localFilename
  };

  // Download the file
  await storage.bucket(bucketName).file(videoFilename).download(options);

  console.log(
    `gs://${bucketName}/${videoFilename} downloaded locally to ${localFilename}.`
  );

  return localFilename;
}

次に、次の内容で sceneDetector.js ファイルを作成します。このファイルは Video Intelligence API を使用して、動画内のシーンが変更されたタイミングを検出します。

const fs = require('fs');
const util = require('util');
const readFile = util.promisify(fs.readFile);
const ffmpeg = require('fluent-ffmpeg');

const Video = require('@google-cloud/video-intelligence');
const client = new Video.VideoIntelligenceServiceClient();

module.exports = {
    detectSceneChanges: async function (downloadedFile) {

        // Reads a local video file and converts it to base64       
        const file = await readFile(downloadedFile);
        const inputContent = file.toString('base64');

        // setup request for shot change detection
        const videoContext = {
            speechTranscriptionConfig: {
                languageCode: 'en-US',
                enableAutomaticPunctuation: true,
            },
        };

        const request = {
            inputContent: inputContent,
            features: ['SHOT_CHANGE_DETECTION'],
        };

        // Detects camera shot changes
        const [operation] = await client.annotateVideo(request);
        console.log('Shot (scene) detection in progress...');
        const [operationResult] = await operation.promise();

        // Gets shot changes
        const shotChanges = operationResult.annotationResults[0].shotAnnotations;

        console.log("Shot (scene) changes detected: " + shotChanges.length);

        // data structure to be returned 
        let sceneChanges = [];

        // for the initial scene
        sceneChanges.push(1);

        // if only one scene, keep at 1 second
        if (shotChanges.length === 1) {
            return sceneChanges;
        }

        // get length of video
        const videoLength = await getVideoLength(downloadedFile);

        shotChanges.forEach((shot, shotIndex) => {
            if (shot.endTimeOffset === undefined) {
                shot.endTimeOffset = {};
            }
            if (shot.endTimeOffset.seconds === undefined) {
                shot.endTimeOffset.seconds = 0;
            }
            if (shot.endTimeOffset.nanos === undefined) {
                shot.endTimeOffset.nanos = 0;
            }

            // convert to a number
            let currentTimestampSecond = Number(shot.endTimeOffset.seconds);                  

            let sceneChangeTime = 0;
            // double-check no scenes were detected within the last second
            if (currentTimestampSecond + 1 > videoLength) {
                sceneChangeTime = currentTimestampSecond;                
            } else {
                // otherwise, for simplicity, just round up to the next second 
                sceneChangeTime = currentTimestampSecond + 1;
            }

            sceneChanges.push(sceneChangeTime);
        });

        return sceneChanges;
    }
}

async function getVideoLength(localFile) {
    let getLength = util.promisify(ffmpeg.ffprobe);
    let length = await getLength(localFile);

    console.log("video length: ", length.format.duration);
    return length.format.duration;
}

次の内容で imageCapture.js というファイルを作成します。このファイルは、node パッケージ fluent-ffmpeg を使用して、node アプリ内から ffmpeg コマンドを実行します。

const ffmpeg = require('fluent-ffmpeg');
const path = require('path');
const util = require('util');


module.exports = {
    captureImages: async function (localFile, scenes) {


        let imageBaseName = path.parse(localFile).name;


        try {
            for (scene of scenes) {
                console.log("creating screenshot for scene: ", + scene);
                await createScreenshot(localFile, imageBaseName, scene);
            }


        } catch (error) {
            console.log("error gathering screenshots: ", error);
        }


        console.log("finished gathering the screenshots");
    }
}


async function createScreenshot(localFile, imageBaseName, scene) {
    return new Promise((resolve, reject) => {
        ffmpeg(localFile)
            .screenshots({
                timestamps: [scene],
                filename: `${imageBaseName}-${scene}.png`,
                folder: 'output',
                size: '320x240'
            }).on("error", () => {
                console.log("Failed to create scene for timestamp: " + scene);
                return reject('Failed to create scene for timestamp: ' + scene);
            })
            .on("end", () => {
                return resolve();
            });
    })
}

最後に、次の内容で `imageDescriber.js`` というファイルを作成します。このファイルは Vertex AI を使用して、各シーン画像の視覚的な説明を取得します。

const axios = require("axios");
const { GoogleAuth } = require('google-auth-library');

const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform'
});

module.exports = {
    getAccessToken: async function () {

        return await auth.getAccessToken();
    }, 

    transcribeScene: async function(token, encodedFile) {

        let projectId = await auth.getProjectId();
    
        let config = {
            headers: {
                'Authorization': 'Bearer ' + token,
                'Content-Type': 'application/json; charset=utf-8'
            }
        }

        const json = {
            "instances": [
                {
                    "image": {
                        "bytesBase64Encoded": encodedFile
                    }
                }
            ],
            "parameters": {
                "sampleCount": 1,
                "language": "en"
            }
        }

        let response = await axios.post('https://us-central1-aiplatform.googleapis.com/v1/projects/' + projectId + '/locations/us-central1/publishers/google/models/imagetext:predict', json, config);

        return response.data.predictions[0];
    }
}

Dockerfile と .dockerignore ファイルを作成する

このサービスでは ffmpeg を使用するため、ffmpeg をインストールする Dockerfile を作成する必要があります。

次の内容の Dockerfile というファイルを作成します。

# Copyright 2020 Google, LLC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Use the official lightweight Node.js image.
# https://hub.docker.com/_/node
FROM node:20.10.0-slim

# Create and change to the app directory.
WORKDIR /usr/src/app

RUN apt-get update && apt-get install -y ffmpeg

# Copy application dependency manifests to the container image.
# A wildcard is used to ensure both package.json AND package-lock.json are copied.
# Copying this separately prevents re-running npm install on every code change.
COPY package*.json ./

# Install dependencies.
# If you add a package-lock.json speed your build by switching to 'npm ci'.
# RUN npm ci --only=production
RUN npm install --production

# Copy local code to the container image.
COPY . .

# Run the web service on container startup.
CMD [ "npm", "start" ]

また、特定のファイルのコンテナ化を無視する .dockerignore というファイルを作成します。

Dockerfile
.dockerignore
node_modules
npm-debug.log

6. サービス アカウントを作成する

Cloud Run サービスが Cloud Storage、Vertex AI、Video Intelligence API にアクセスするために使用するサービス アカウントを作成します。

SERVICE_ACCOUNT="cloud-run-video-description"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run Video Scene Image Describer service account"
 
# to view & download storage bucket objects
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/storage.objectViewer

# to call the Vertex AI imagetext model
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/aiplatform.user

7. Cloud Run サービスをデプロイする

ソースベースのデプロイを使用して、Cloud Run サービスを自動的にコンテナ化できるようになりました。

注: Cloud Run サービスのデフォルトの処理時間は 60 秒です。この Codelab では、推奨されるテスト動画の長さが 2 分であるため、5 分のタイムアウトを使用します。再生時間が長い動画を使用する場合は、時間を変更する必要があります。

gcloud run deploy $SERVICE_NAME \
  --region=$REGION \
  --set-env-vars BUCKET_ID=$BUCKET_ID \
  --no-allow-unauthenticated \
  --service-account $SERVICE_ACCOUNT_ADDRESS \
  --timeout=5m \
  --source=.

デプロイしたら、サービス URL を環境変数に保存します。

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --platform managed --region $REGION --format 'value(status.url)')

8. Cloud Run サービスを呼び出す

Cloud Storage にアップロードした動画の名前を指定して、サービスを呼び出すことができます。

curl -X GET -H "Authorization: Bearer $(gcloud auth print-identity-token)" ${SERVICE_URL}?filename=${FILENAME}

結果は、次の出力例のようになります。

[{"timestamp":1,"description":"an aerial view of a city with a bridge in the background"},{"timestamp":7,"description":"a man in a blue shirt sits in front of shelves of donuts"},{"timestamp":11,"description":"a black and white photo of people working in a bakery"},{"timestamp":12,"description":"a black and white photo of a man and woman working in a bakery"}]

9. 完了

以上で、この Codelab は完了です。

Video Intelligence API、Cloud Run、Vertex AI 画像キャプション のドキュメントを確認することをおすすめします。

学習した内容

• Dockerfile を使用してコンテナ イメージを作成し、サードパーティのバイナリをインストールする方法
• Cloud Run サービス用のサービス アカウントを作成して他の Google Cloud サービスを呼び出すことで、最小権限の原則に従う方法
• Cloud Run サービスから Video Intelligence クライアント ライブラリを使用する方法
• Google API を呼び出して、Vertex AI から各シーンの視覚的な説明を取得する方法

10. クリーンアップ

意図しない料金が発生しないようにするには（たとえば、この Cloud Run サービスが、無料枠の月間 Cloud Run 呼び出し割り当てよりも多く呼び出された場合など）、Cloud Run サービスを削除するか、ステップ 2 で作成したプロジェクトを削除します。

Cloud Run サービスを削除するには、Cloud Run Cloud Console（https://console.cloud.google.com/run/）に移動し、video-describer 関数（別の名前を使用した場合は $SERVICE_NAME）を削除します。

プロジェクト全体を削除する場合は、https://console.cloud.google.com/cloud-resource-manager に移動し、ステップ 2 で作成したプロジェクトを選択して [削除] を選択します。プロジェクトを削除する場合は、Cloud SDK でプロジェクトを変更する必要があります。gcloud projects list を実行すると、使用可能なすべてのプロジェクトのリストが表示されます。