キャプションを追加する

動画ライブラリへキャプションと字幕を追加します。

キャプションを追加または変更する

動画へキャプションを追加する方法は 2 つあります。AI で生成するか、キャプションファイルをアップロードします。

動画のキャプションを作成または変更するには、Cloudflare API Token ↗ が必要です。

<LANGUAGE_TAG> は BCP 47 形式 ↗ に従う必要があります。よく使う言語コードは、便宜上このドキュメントの末尾にあります。表にない言語を追加する場合は、言語コード一覧を管理している IANA レジストリ ↗ で値を探せます。送信する値を見つけるには、言語名で検索します。トルコ語の字幕向けに送る値を IANA で調べた例は次のとおりです。

%%

Subtag: tr
Description: Turkish
Added: 2005-10-16
Suppress-Script: Latn
%%

Subtag コードは tr です。HTTP リクエスト末尾の language として送る値です。

指定した言語からラベルが生成されます。ラベルはプレーヤーでのユーザー選択に表示されます。たとえば tr を送るとラベル Türkçe が作られ、de を送るとラベル Deutsch が作られます。

キャプションを生成する

生成キャプションは、音声認識（speech-to-text）の人工知能を使い、動画のクローズドキャプションを作ります。

キャプションを生成する前に、動画をアップロードし、ready 状態になっている必要があります。以降の URL 例では、動画の UID を <VIDEO_UID> として示します。アップロード後に動画が ready へ遷移したときに webhook を受け取るには、webhook を使うの手順に従います。

キャプションを生成できる言語は次のとおりです。

cs - チェコ語
nl - オランダ語
en - 英語
fr - フランス語
de - ドイツ語
it - イタリア語
ja - 日本語
ko - 韓国語
pl - ポーランド語
pt - ポルトガル語
ru - ロシア語
es - スペイン語

キャプションを生成するときは、音声で話されている言語向けに生成します。

1 本の動画に複数言語のキャプションを付けられますが、各言語は一意である必要があります。たとえば英語、フランス語、ドイツ語のキャプションは共存できますが、英語のキャプションを 2 つ持つことはできません。すでに英語のキャプションをアップロードしている場合は、英語の生成キャプションを作る前に、先に削除する必要があります。削除手順は後述します。

<LANGUAGE_TAG> は BCP 47 形式に従う必要があります。英語のタグは en です。 en-GB のように地域を指定すると、キャプションのラベルは British English と表示されます。

curl -X POST \
-H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/generate

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const caption = await client.stream.captions.language.create("<VIDEO_UID>", "en", {
	account_id: '<ACCOUNT_ID>',
});

外部アプリケーションから REST API を使う方法と、TypeScript、Python、Go 向けの事前生成 SDK の詳細は、Stream の REST API と SDK リファレンスを参照してください。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		const caption = await env.STREAM.video(videoId).captions.generate("en");
		return new Response(JSON.stringify({ caption }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true
	},
	"stream": {
		"binding": "STREAM"
	}
}

Workers Stream バインディング API リファレンスを参照してください。

レスポンスの例:

{
  "result": {
    "language": "en",
    "label": "English (auto-generated)",
    "generated": true,
    "status": "inprogress"
  },
  "success": true,
  "errors": [],
  "messages": []
}

結果の status は、キャプション生成の進捗を示します。
状態は inprogress、ready、error の 3 つです。ラベルには (auto-generated) が付きます。

生成キャプションが ready になると、動画プレーヤーと動画マニフェストに自動で表示されます。

キャプションが error 状態になった場合は、先に削除してから上記のエンドポイントを使い、再生成できます。削除手順は後述します。

ファイルをアップロードする

生成キャプションを編集すると、次の 2 点が変わります。generated フィールドは false になり、ラベルの (auto-generated) 部分は消えます。

キャプションファイルを作成または置き換えるには:

curl -X PUT \
 -H 'Authorization: Bearer <API_TOKEN>' \
 -F file=@/Users/mickie/Desktop/example_caption.vtt \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const caption = await client.stream.captions.language.update("<VIDEO_UID>", "en", {
	account_id: '<ACCOUNT_ID>',
	file: '@/path/to/caption.vtt',
});

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		const language = "en";
		// Obtain a ReadableStream from a file upload, fetch, or other source
		const captionStream: ReadableStream = request.body!;
		const caption = await env.STREAM.video(videoId).captions.upload(language, captionStream);
		return new Response(JSON.stringify({ caption }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true
	},
	"stream": {
		"binding": "STREAM"
	}
}

Workers Stream バインディング API リファレンスを参照してください。

キャプションの追加・変更のレスポンス例

{
  "result": {
    "language": "en",
    "label": "English",
    "generated": false,
    "status": "ready"
  },
  "success": true,
  "errors": [],
  "messages": []
}

動画に関連付けられたキャプションを一覧する

動画に関連付けられたキャプションを確認します。この結果一覧には、inprogress および error 状態の生成キャプションも含まれます。

curl -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const captions = await client.stream.captions.get("<VIDEO_UID>", {
	account_id: '<ACCOUNT_ID>',
});

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		const captions = await env.STREAM.video(videoId).captions.list();
		return new Response(JSON.stringify({ captions }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true
	},
	"stream": {
		"binding": "STREAM"
	}
}

Workers Stream バインディング API リファレンスを参照してください。

動画に関連付けられたキャプション取得のレスポンス例

{
  "result": [
    {
      "language": "en",
      "label": "English (auto-generated)",
      "generated": true,
      "status": "inprogress"
    },
    {
      "language": "de",
      "label": "Deutsch",
      "generated": false,
      "status": "ready"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

キャプションファイルを取得する

WebVTT キャプションファイルを確認するには、GET リクエストを送ります。

curl \
-H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/vtt

動画のキャプションファイル取得のレスポンス例

WEBVTT

1
00:00:00.000 --> 00:00:01.560
This is an example of

2
00:00:01.560 --> 00:00:03.880
a WebVTT caption response.

キャプションを削除する

動画に関連付けられたキャプションを削除するには:

curl -X DELETE \
 -H 'Authorization: Bearer <API_TOKEN>' \
 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

await client.stream.captions.language.delete("<VIDEO_UID>", "en", {
	account_id: '<ACCOUNT_ID>',
});

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		await env.STREAM.video(videoId).captions.delete("en");
		return new Response(JSON.stringify({ success: true }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true
	},
	"stream": {
		"binding": "STREAM"
	}
}

Workers Stream バインディング API リファレンスを参照してください。

レスポンスの errors フィールドに項目がある場合、キャプションは削除されていません。

キャプション削除のレスポンス例

{
  "result": "",
  "success": true,
  "errors": [],
  "messages": []
}

制限

キャプションを付ける前に、動画をアップロードする必要があります。以降の URL 例では、動画の ID を media_id として示します。
Stream がサポートするキャプションファイル形式は WebVTT ↗ のみです。別形式のキャプションファイルがある場合は、アップロード前に WebVTT へ変換するツール ↗ を使います。
1 本の動画に複数言語のキャプションを付けられますが、各言語は一意である必要があります。たとえば英語、フランス語、ドイツ語のキャプションは共存できますが、フランス語のキャプションを 2 つ持つことはできません。
各キャプションファイルのサイズ上限は 10 MB です。より大きなファイルをアップロードする必要がある場合はサポートへ連絡してください。

よく使う言語コード

言語コード	言語
zh	中国語（普通話）
hi	ヒンディー語
es	スペイン語
en	英語
ar	アラビア語
pt	ポルトガル語
bn	ベンガル語
ru	ロシア語
ja	日本語
de	ドイツ語
pa	パンジャーブ語
jv	ジャワ語
ko	韓国語
vi	ベトナム語
fr	フランス語
ur	ウルドゥー語
it	イタリア語
tr	トルコ語
fa	ペルシア語
pl	ポーランド語
uk	ウクライナ語
my	ビルマ語
th	タイ語