字幕配置--视频直播-火山引擎

文档中心

立即注册

导航

字幕配置

最近更新时间：2024.09.14 11:16:51首次发布时间：2024.09.14 11:16:51

阅读本文，您可以获取 PHP SDK 字幕配置的接口调用示例，实现快速开发。

说明

本文的调用示例包含接口的部分参数。由于参数间可能存在互斥关系，在调用时，请您参考注释，进行调整。

调用说明

本文提供的接口调用示例均通过 AK 和 SK 初始化实例。
接口的参数说明和错误码等信息可通过接口文档或打开 API Explorer 的文档说明页签查看。

前提条件

调用接口前，请先完成 PHP SDK 的安装及初始化操作。

调用示例

本节为您介绍字幕配置相关接口的功能和调用示例。

添加字幕配置

您可以调用 CreateSubtitleTranscodePreset 接口添加字幕配置。详细的参数说明可参见 CreateSubtitleTranscodePreset 接口文档。

接口调用示例如下所示。

<?php
include_once "./vendor/autoload.php";

use Volc\Service\Live\V20230101\Live;

// 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
// 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
$client = Live::getInstance();

$client->setAccessKey(getenv("VOLC_ACCESSKEY"));

$client->setSecretKey(getenv("VOLC_SECRETKEY"));

$body = [
    // 域名空间，即直播流地址的域名所属的域名空间。您可以调用 [ListDomainDetail](https://www.volcengine.com/docs/6469/1126815) 接口或在视频直播控制台的[域名管理](https://console.volcengine.com/live/main/domain/list)页面，查看直播流使用的域名所属的域名空间。
    "Vhost" => "push.example.com",
    // 应用名称，取值与直播流地址中 AppName 字段取值相同。支持由大小写字母（A - Z、a - z）、数字（0 - 9）、下划线（_）、短横线（-）和句点（.）组成，长度为 1 到 30 个字符。
    "App" => "live",
    // 字幕配置的名称，不可以与其他已有的配置名称重复。默认为空，表示由系统将自动分配配置名称。
    "PresetName" => "OriginPreset",
    // 字幕配置的描述信息。
    "Description" => "subtitleconfig0001",
    // 关联的转码配置后缀，一个字幕配置支持关联多个转码配置后缀。
    "Suffixes" => ["hd", "bd"],
    // 预设配置，使用预设配置是系统将自动对字体大小、字幕行数、每行最大字符数和边距参数（MarginVertical 和 MarginHorizontal）进行智能化适配。默认为空，表示不使用预设配置，支持的预设配置如下所示。
    // <li> small ：小字幕。 </li>
    // <li> medium：中字幕。 </li>
    // <li> large：大字幕。 </li>
    // note：
    // 使用预设配置时，字幕行数、每行最大字符数、左右边距和底部边距参数不生效，系统将使用预设配置自动进行计算。
    "DisplayPreset" => "small",
    // 字幕展示的行数，同时适用于原文字幕和译文字幕，支持的取值及含义如下所示。
    // <li> 0：（默认值）根据字幕字数自动进行分行展示； </li>
    // <li> 1：每种字幕展示一行； </li>
    // <li> 2：每种字幕展示两行。 </li>
    // note：
    // <li> 使用预设配置时，字幕行数为自动分行展示。 </li>
    // <li> 超出行内字数限制时表示字幕将超过显示范围，此时字幕内容将被截断。 </li>
    "MaxRowNumber" => 0,
    // 字幕位置设置，通过设置字幕距离画面左右边距和底部边距来指定字幕位置。
    // note：
    // <li> 使用预设配置时，字幕位置设置不生效。 </li>
    // <li> 不使用预设配置时，字幕位置设置必填。 </li>
    "Position" => [],
    // 原文字幕展示参数配置。
    "SourceLanguage" => [
        // 原文字幕的语言，取值及含义如下所示。
        // <li> zh：中英混合； </li>
        // <li> en：英语； </li>
        // <li> ko：韩语； </li>
        // <li> ja：日语。 </li>
        "Language" => "zh",
        // 原文字幕的字体，原文字幕字体根据原文字幕语言取值不同而不同，取值及含义如下所示。
        // <li> 当原文字幕的语言是 zh 时，支持以下字体取值。 </li>
        // <li> siyuanheiti：思源黑体； </li>
        // <li> songtixi：宋体细； </li>
        // <li> songticu：宋体粗； </li>
        // <li> heitifan：黑体繁； </li>
        // <li> kaiti：楷体。 </li>
        // <li> 当原文字幕的语言是 en 时，支持以下字体取值。 </li>
        // <li> inter：Inter； </li>
        // <li> roboto：Roboto； </li>
        // <li> opposans：OPPOSans； </li>
        // <li> siyuansongti：思源宋体； </li>
        // <li> montserrat：Montserrat。 </li>
        // <li> 当原文字幕的语言是 ko 和 ja 时，支持 notosans(Noto Sans) 字体。 </li>
        "Font" => "siyuanheiti",
        // 原文字幕的字体颜色，支持以下几种方法进行定义。
        // <li> 支持以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+十六进制/百分比来表示的透明度值，来定义字幕的字体颜色。例如，设置 RGB 值为 FF0000，透明度为 5%的颜色时，您可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。 </li>
        // <li> 支持使用前端框架 FFmpeg 规定的颜色关键字，来定义字幕的字体颜色。例如，AliceBlue 表示 0xF0F8FF、AntiqueWhite 表示 0xFAEBD7、Black 表示 0x000000 等。 </li>
        // note：
        // 查看详细颜色定义方法及更多颜色关键字，请参考 [FFmpeg 的颜色定义语法](https://ffmpeg.org/ffmpeg-utils.html#color-syntax)。
        "FontColor" => "0xFF0000@0.5",
        // 原文字幕的字体描边配置。
        "Border" => [
            // 描边的宽度，单位为 px。
            "Width" => 2,
            // 描边的颜色，支持以下几种方法进行定义。
            // <li> 支持以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+十六进制/百分比来表示的透明度值，来定义字幕的字体颜色。例如，设置 RGB 值为 FF0000，透明度为 5%的颜色时，您可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。 </li>
            // <li> 支持使用前端框架 FFmpeg 规定的颜色关键字，来定义字幕的字体颜色。例如，AliceBlue 表示 0xF0F8FF、AntiqueWhite 表示 0xFAEBD7、Black 表示 0x000000 等。 </li>
            // note：
            // 查看详细颜色定义方法及更多颜色关键字，请参考 [FFmpeg 的颜色定义语法](https://ffmpeg.org/ffmpeg-utils.html#color-syntax)。
            "Color" => "White",
        ],
    ],
    // 译文字幕展示参数配置列表，当前最多支持配置一种译文。
    "TargetLanguage" => [
        [
            // 译文字幕的语言，取值及含义如下所示。
            // <li> zh：中英混合； </li>
            // <li> zh-Hant：繁体中文； </li>
            // <li> en：英语； </li>
            // <li> ko：韩语； </li>
            // <li> ja：日语； </li>
            // <li> ar：阿拉伯语； </li>
            // <li> de：德语； </li>
            // <li> es：西班牙语； </li>
            // <li> fr：法语； </li>
            // <li> hi：印地语； </li>
            // <li> pt：葡萄牙语； </li>
            // <li> ru：俄语； </li>
            // <li> vi：越南语； </li>
            // <li> th：泰语。 </li>
            "Language" => "en",
            // 译文字幕的字体，译文字幕字体根据译文字幕语言取值不同而不同，取值及含义如下所示。
            // <li> 当译文字幕的语言是 zh 时，支持以下字体取值。 </li>
            // <li> siyuanheiti：思源黑体； </li>
            // <li> songtixi：宋体细； </li>
            // <li> songticu：宋体粗； </li>
            // <li> heitifan：黑体繁； </li>
            // <li> kaiti：楷体。 </li>
            // <li> 当译文字幕的语言是 zh-Hant 时，支持 siyuanheiti （思源黑体）字体。 </li>
            // <li> 当译文字幕的语言是 en 时，支持以下字体取值。 </li>
            // <li> inter：Inter； </li>
            // <li> roboto：Roboto； </li>
            // <li> opposans：OPPOSans； </li>
            // <li> siyuansongti：思源宋体； </li>
            // <li> montserrat：Montserrat。 </li>
            // <li> 当译文字幕的语言是 ko、ja、ar、de、es、fr、hi、pt、 ru、 vi、 th  时，支持 notosans(Noto Sans) 字体。 </li>
            "Font" => "inter",
            // 译文字幕的字体颜色，支持以下几种方法进行定义。
            // <li> 支持以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+十六进制/百分比来表示的透明度值，来定义字幕的字体颜色。例如，设置 RGB 值为 FF0000，透明度为 5%的颜色时，您可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。 </li>
            // <li> 支持使用前端框架 FFmpeg 规定的颜色关键字，来定义字幕的字体颜色。例如，AliceBlue 表示 0xF0F8FF、AntiqueWhite 表示 0xFAEBD7、Black 表示 0x000000 等。 </li>
            // note：
            // 查看详细颜色定义方法及更多颜色关键字，请参考 [FFmpeg 的颜色定义语法](https://ffmpeg.org/ffmpeg-utils.html#color-syntax)。
            "FontColor" => "Black",
            // 译文字幕的字体描边配置。
            "Border" => [
                "Color" => "white",
            ],
        ],
    ],
    // 原文字幕识别时使用的热词词库，总长度不超过为 10000 个字符，默认为空。
    "HotWordList" => ["视频直播", "赛事直播", "智能家居"],
    // 原文翻译成译文时使用的热词词库，总长度不超过 10000 个字符，默认为空。
    "GlossaryWordList" => ["ArtificialIntelligence", "MachineLearning", "AI"],
];

$response = $client->createSubtitleTranscodePreset($body);
print_r($response);

查询字幕配置列表

您可以调用 ListVhostSubtitleTranscodePreset 接口查询字幕配置列表。详细的参数说明可参见 ListVhostSubtitleTranscodePreset 接口文档。

接口调用示例如下所示。

<?php
include_once "./vendor/autoload.php";

use Volc\Service\Live\V20230101\Live;

// 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
// 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
$client = Live::getInstance();

$client->setAccessKey(getenv("VOLC_ACCESSKEY"));

$client->setSecretKey(getenv("VOLC_SECRETKEY"));

$body = [
    // 域名空间，即直播流地址的域名所属的域名空间。您可以调用 [ListDomainDetail](https://www.volcengine.com/docs/6469/1126815) 接口或在视频直播控制台的[域名管理](https://console.volcengine.com/live/main/domain/list)页面，查看直播流使用的域名所属的域名空间。
    "Vhost" => "push.example.com",
];

$response = $client->listVhostSubtitleTranscodePreset($body);
print_r($response);

更新字幕配置

您可以调用 UpdateSubtitleTranscodePreset 接口更新字幕配置。详细的参数说明可参见 UpdateSubtitleTranscodePreset 接口文档。

接口调用示例如下所示。

<?php
include_once "./vendor/autoload.php";

use Volc\Service\Live\V20230101\Live;

// 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
// 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
$client = Live::getInstance();

$client->setAccessKey(getenv("VOLC_ACCESSKEY"));

$client->setSecretKey(getenv("VOLC_SECRETKEY"));

$body = [
    // 域名空间，您可以调用 [ListVhostSubtitleTranscodePreset](https://www.volcengine.com/docs/6469/1288712) 接口，获取待更新字幕配置的 Vhost 取值。
    "Vhost" => "push.example.com",
    // 应用名称，您可以调用 [ListVhostSubtitleTranscodePreset](https://www.volcengine.com/docs/6469/1288712) 接口，获取待更新字幕配置的 App 取值。
    "App" => "live",
    // 截图配置的名称，您可以调用 [ListVhostSubtitleTranscodePreset](https://www.volcengine.com/docs/6469/1288712) 接口，获取待更新字幕配置的 PresetName 取值。
    "PresetName" => "OriginPreset",
    // 字幕配置的描述信息。
    "Description" => "subtitleconfig0001",
    // 关联转码配置后缀，一个字幕配置支持关联多个转码配置后缀。
    "Suffixes" => ["hd", "bd"],
    // 预设配置，使用预设配置是系统将自动对字体大小、字幕行数、每行最大字符数和边距参数（MarginVertical 和 MarginHorizontal）进行智能化适配。默认为空，表示不使用预设配置，支持的预设配置如下所示。
    // <li> small ：小字幕。 </li>
    // <li> medium：中字幕。 </li>
    // <li> large：大字幕。 </li>
    // note：
    // 使用预设配置时，字幕行数、每行最大字符数、左右边距和底部边距参数不生效，系统将使用预设配置自动进行计算。
    "DisplayPreset" => "small",
    // 字幕展示的行数，同时适用于原文字幕和译文字幕，支持的取值及含义如下所示。
    // <li> 0：（默认值）根据字幕字数自动进行分行展示； </li>
    // <li> 1：每种字幕展示一行； </li>
    // <li> 2：每种字幕展示两行。 </li>
    // note：
    // <li> 使用预设配置时，字幕行数为自动分行展示。 </li>
    // <li> 超出行内字数限制时表示字幕将超过显示范围，此时字幕内容将被截断。 </li>
    "MaxRowNumber" => 0,
    // 字幕位置设置，通过设置字幕距离画面左右边距和底部边距来指定字幕位置。
    // note：
    // <li> 使用预设配置时，字幕位置设置不生效。 </li>
    // <li> 不使用预设配置时，字幕位置设置必填。 </li>
    "Position" => [],
    // 原文字幕展示参数配置。
    "SourceLanguage" => [
        // 原文字幕的语言，取值及含义如下所示。
        // <li> zh：中英混合； </li>
        // <li> en：英语； </li>
        // <li> ko：韩语； </li>
        // <li> ja：日语。 </li>
        "Language" => "zh",
        // 原文字幕的字体，原文字幕字体根据原文字幕语言取值不同而不同，取值及含义如下所示。
        // <li> 当原文字幕的语言是 zh 时，支持以下字体取值。 </li>
        // <li> siyuanheiti：思源黑体； </li>
        // <li> songtixi：宋体细； </li>
        // <li> songticu：宋体粗； </li>
        // <li> heitifan：黑体繁； </li>
        // <li> kaiti：楷体。 </li>
        // <li> 当原文字幕的语言是 en 时，支持以下字体取值。 </li>
        // <li> inter：Inter； </li>
        // <li> roboto：Roboto； </li>
        // <li> opposans：OPPOSans； </li>
        // <li> siyuansongti：思源宋体； </li>
        // <li> montserrat：Montserrat。 </li>
        // <li> 当原文字幕的语言是 ko 和 ja 时，支持 notosans(Noto Sans) 字体。 </li>
        "Font" => "simhei",
        // 原文字幕的字体颜色，支持以下几种方法进行定义。
        // <li> 支持以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+十六进制/百分比来表示的透明度值，来定义字幕的字体颜色。例如，设置 RGB 值为 FF0000，透明度为 5%的颜色时，您可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。 </li>
        // <li> 支持使用前端框架 FFmpeg 规定的颜色关键字，来定义字幕的字体颜色。例如，AliceBlue 表示 0xF0F8FF、AntiqueWhite 表示 0xFAEBD7、Black 表示 0x000000 等。 </li>
        // note：
        // 查看详细颜色定义方法及更多颜色关键字，请参考 [FFmpeg 的颜色定义语法](https://ffmpeg.org/ffmpeg-utils.html#color-syntax)。
        "FontColor" => "black",
        // 原文字幕的阴影配置。
        "Border" => [
            // 描边的颜色，支持以下几种方法进行定义。
            // <li> 支持以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+十六进制/百分比来表示的透明度值，来定义字幕的字体颜色。例如，设置 RGB 值为 FF0000，透明度为 5%的颜色时，您可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。 </li>
            // <li> 支持使用前端框架 FFmpeg 规定的颜色关键字，来定义字幕的字体颜色。例如，AliceBlue 表示 0xF0F8FF、AntiqueWhite 表示 0xFAEBD7、Black 表示 0x000000 等。 </li>
            // note：
            // 查看详细颜色定义方法及更多颜色关键字，请参考 [FFmpeg 的颜色定义语法](https://ffmpeg.org/ffmpeg-utils.html#color-syntax)。
            "Color" => "white",
        ],
    ],
    // 译文字幕展示参数配置列表，当前最多支持配置一种译文。
    "TargetLanguage" => [
        [
            // 译文字幕的语言，取值及含义如下所示。
            // <li> zh：中英混合； </li>
            // <li> zh-Hant：繁体中文； </li>
            // <li> en：英语； </li>
            // <li> ko：韩语； </li>
            // <li> ja：日语； </li>
            // <li> ar：阿拉伯语； </li>
            // <li> de：德语； </li>
            // <li> es：西班牙语； </li>
            // <li> fr：法语； </li>
            // <li> hi：印地语； </li>
            // <li> pt：葡萄牙语； </li>
            // <li> ru：俄语； </li>
            // <li> vi：越南语； </li>
            // <li> th：泰语。 </li>
            "Language" => "en",
            // 译文字幕的字体，译文字幕字体根据译文字幕语言取值不同而不同，取值及含义如下所示。
            // <li> 当译文字幕的语言是 zh 时，支持以下字体取值。 </li>
            // <li> siyuanheiti：思源黑体； </li>
            // <li> songtixi：宋体细； </li>
            // <li> songticu：宋体粗； </li>
            // <li> heitifan：黑体繁； </li>
            // <li> kaiti：楷体。 </li>
            // <li> 当译文字幕的语言是 zh-Hant 时，支持 siyuanheiti （思源黑体）字体。 </li>
            // <li> 当译文字幕的语言是 en 时，支持以下字体取值。 </li>
            // <li> inter：Inter； </li>
            // <li> roboto：Roboto； </li>
            // <li> opposans：OPPOSans； </li>
            // <li> siyuansongti：思源宋体； </li>
            // <li> montserrat：Montserrat。 </li>
            // <li> 当译文字幕的语言是 ko、ja、ar、de、es、fr、hi、pt、 ru、 vi、 th  时，支持 notosans(Noto Sans) 字体。 </li>
            "Font" => "simhei",
            // 译文字幕的字体颜色，支持以下几种方法进行定义。
            // <li> 支持以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+十六进制/百分比来表示的透明度值，来定义字幕的字体颜色。例如，设置 RGB 值为 FF0000，透明度为 5%的颜色时，您可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。 </li>
            // <li> 支持使用前端框架 FFmpeg 规定的颜色关键字，来定义字幕的字体颜色。例如，AliceBlue 表示 0xF0F8FF、AntiqueWhite 表示 0xFAEBD7、Black 表示 0x000000 等。 </li>
            // note：
            // 查看详细颜色定义方法及更多颜色关键字，请参考 [FFmpeg 的颜色定义语法](https://ffmpeg.org/ffmpeg-utils.html#color-syntax)。
            "FontColor" => "black",
            // 译文字幕的字体描边配置。
            "Border" => [
                "Color" => "white",
            ],
        ],
    ],
    // 原文字幕识别时使用的热词词库，总长度不超过为 10000 个字符，默认为空。
    "HotWordList" => ["视频直播", "赛事直播", "智能家居"],
    // 原文翻译成译文时使用的热词词库，总长度不超过 10000 个字符，默认为空。
    "GlossaryWordList" => ["ArtificialIntelligence", "MachineLearning", "AI"],
];

$response = $client->updateSubtitleTranscodePreset($body);
print_r($response);

删除字幕配置

您可以调用 DeleteSubtitleTranscodePreset 接口删除字幕配置。详细的参数说明可参见 DeleteSubtitleTranscodePreset 接口文档。

接口调用示例如下所示。

<?php
include_once "./vendor/autoload.php";

use Volc\Service\Live\V20230101\Live;

// 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
// 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
$client = Live::getInstance();

$client->setAccessKey(getenv("VOLC_ACCESSKEY"));

$client->setSecretKey(getenv("VOLC_SECRETKEY"));

$body = [
    // 应用名称，您可以调用 [ListVhostSubtitleTranscodePreset](https://www.volcengine.com/docs/6469/1288712) 接口，获取待删除字幕配置的 App 取值。
    "App" => "live",
    // 域名空间，您可以调用 [ListVhostSubtitleTranscodePreset](https://www.volcengine.com/docs/6469/1288712) 接口，获取待删除字幕配置的 Vhost 取值。
    "Vhost" => "push.example.com",
    // 截图配置的名称，您可以调用 [ListVhostSubtitleTranscodePreset](https://www.volcengine.com/docs/6469/1288712) 接口，获取待删除字幕配置的 PresetName 取值。
    "PresetName" => "testPreset",
];

$response = $client->deleteSubtitleTranscodePreset($body);
print_r($response);