← Cloudflare Stream / stream / edit-videos

Добавление субтитров

Добавление субтитров в вашу видеотеку.

Добавить субтитры к видео можно двумя способами: сгенерировать их с помощью ИИ или загрузить файл субтитров.

Чтобы создать или изменить субтитры для видео, API-токен Cloudflare ↗ обязательно.

<LANGUAGE_TAG> должен соответствовать Формат BCP 47 ↗. Для удобства предоставлены многие распространённые языковые коды в конце этого документа. Если добавляемого языка нет в таблице, нужное значение можно найти через Реестр IANA ↗, в котором ведётся список языковых кодов. Чтобы найти нужное значение, найдите нужный язык в списке. Ниже приведён пример значения из IANA для турецких субтитров:

%%

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

Subtag код означает значение tr. Это значение, которое вам нужно отправить в качестве language в конце HTTP запроса.

Метка формируется на основе указанного языка. Она будет отображаться в списке выбора языка в плеере. Например, если передано tr, метка Türkçe будет создан; если отправлено de, метка Deutsch будет создан.

Автоматически созданные субтитры используют технологию преобразования речи в текст на основе искусственного интеллекта для создания скрытых субтитров к вашим видео.

Прежде чем создавать субтитры, видео должно быть загружено и находиться в состоянии ready. В примерах URL-адресов ниже UID видео обозначается как <VIDEO_UID>. Чтобы получать вебхуки при переходе видео в статус ready после загрузки, следуйте инструкциям, приведённым в с помощью вебхуков.

Субтитры можно создавать для следующих языков:

• cs - чешский
• nl - нидерландский
• en - английский
• fr - французский
• de - немецкий
• it - итальянский
• ja - японский
• ko - корейский
• pl - польский
• pt - португальский
• ru - русский
• es - испанский

При создании субтитров создавайте их на языке, звучащем в аудиодорожке.

Видео может содержать субтитры на нескольких языках, но каждый язык должен быть уникальным. Например, у видео могут быть английские, французские и немецкие субтитры, но не может быть двух английских субтитров одновременно. Если для видео уже загружены английские субтитры, сначала удалите их, чтобы создать автоматически сгенерированные английские субтитры. Инструкции по удалению субтитров приведены ниже.

<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>',
});

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

Пример ответа:

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

Результат предоставит status указывающее прогресс генерации субтитров.
Существует три статуса: inprogress, ready и error. Обратите внимание, что к названию применяется (auto-generated).

Как только сгенерированные субтитры будут готовы, они автоматически появятся в видеоплеере и манифесте видео.

Если субтитры переходят в состояние ошибки, вы можете попытаться создать их заново, для этого сначала удалите их, а затем используйте конечную точку, указанную выше. Инструкции по удалению приведены ниже.

Учтите два изменения при редактировании сгенерированных субтитров: поле 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"
	}
}

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

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

Если есть запись в errors поле ответа, субтитры не были удалены.

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

• Прежде чем прикреплять субтитры к видео, его нужно загрузить. В примерах URL-адресов ниже ID видео обозначается как media_id.
• Stream поддерживает только WebVTT ↗ файлов с субтитрами в этом формате. Если у вас файл субтитров другого формата, используйте инструмент для конвертации файла в WebVTT ↗ перед его загрузкой.
• Видео может содержать субтитры на нескольких языках, но каждый язык должен быть уникальным. Например, у видео могут быть английские, французские и немецкие субтитры, но не может быть двух французских субтитров одновременно.
• Размер каждого файла субтитров ограничен 10 МБ. Обратиться в поддержку если вам нужно загрузить файл большего размера.