开发者指南

更新时间：2021-10-19

Pipeline（队列）

队列分为免费型与专享性：

免费型队列中的转码任务分享百度智能云为音视频转码所提供的约400路720P转码计算资源。
专享型队列需额外采购，以便更好的满足那些对于转码时效性和稳定性有更高要求的用户的业务需求。

用户可以利用队列实现任务优先级。用户通过创建多个队列达到区分任务优先级的目的，将大部分任务创建至普通优先级队列，将高优的任务放入高优先级的队列，以利用队列先到先服务的工作原理来实现任务的优先级调整。

新建Pipeline

如下代码可以新建一个Pipeline，默认的capacity值为20：

$pipelineName = "your_pipeline";
$sourceBucket = "your_source_bucket";
$targetBucket = "your_source_bucket";
// 新建一个Pipeline
$client->createPipeline($pipelineName, $sourceBucket, $targetBucket);

列出全部Pipeline

如下代码可以列出用户所有的Pipeline：

/ 获取用户的Pipeline列表
$response = $client->listPipelines();
// 遍历Pipeline列表
foreach ($response->pipelines as $pipeline) {
    print json_encode($pipeline);
}

查询指定的Pipeline

若只是查询某个Pipeline，则使用如下代码：

$pipelineName = "your_pipeline";
$response = $client->getPipeline($pipelineName);
print json_encode($response);

修改Pipeline

如下代码可以修改一个Pipeline的通知：

$pipelineName = "your_pipeline";
$pipeline = $this->client->getPipeline($pipelineName);
$pipeline->config->notification = "your_notification";
$this->client->updatePipeline($pipelineName, json_decode(json_encode( $pipeline),true));

修改其他参数类似

删除Pipeline

如下代码可以删除一个Pipeline：

$pipelineName = "your_pipeline";
client->deletePipeline(pipelineName);

需要注意的是，如果Pipeline有关联的Job未完成，则Pipeline无法被删除，必须等Job执行结束后才能成功删除。

Job（任务）

Job(任务)是音视频转码中最基本的执行单元，每个任务将一个原始的音视频资源转码成目标规格的音视频资源。因此，任务和转码的目标是一一对应的，也就是说如果用户需要将一个原始多媒体文件转换成三种目标规格，比如从AVI格式转码成FLV/MP4/HLS格式，那么用户将会需要创建三个任务。

创建Job

用户在创建任务时，需要为任务指定所属的Pipeline、所需应用的Preset以及原始音视频资源的BOS Key以及目标音视频资源BOS Key。

如下代码创建一个Job, 并获取新创建的jobID：

$pipelineName = "your_pipeline";
$sourceKey = "your_source_key";
$targetKey = "your_target_key";
$presetName = "your_preset";
$client->createSimpleJob($pipelineName, $sourceKey, $targetKey, $presetName);

对Job进行条件筛选

创建任务后，您可以通过下述四个参数对转码任务进行条件筛选，参数之间可相互配合：

pipelineName: 队列名称
jobStatus：转码状态
begin: createTime（创建时间）上限，用于筛选创建时间等于或者晚于begin的Job
end: createTime（创建时间）下限，用于筛选创建时间等于或者早于end的Job

下述示例代码用于筛选指定队列下的所有Job:

$pipelineName = "your_pipeline";
$response = $client->listJobs($pipelineName);
foreach($response->jobs as $job) {
    print json_encode($job);
}

下述示例代码用于筛选指定队列下状态为“RUNNING”的所有Job:

$pipelineName = "your_pipeline";
$response = $client->listJobs($pipelineName, "RUNNING");
foreach($response->jobs as $job) {
    print json_encode($job);
}

下述示例代码用于筛选指定队列下创建于2016年3月31日14:30:00之后的所有Job:

$pipelineName = "your_pipeline";
$response = $client->listJobs($pipelineName, null, "2016-03-31T14:30:00Z");
foreach($response->jobs as $job) {
    print json_encode($job);
}

下述示例代码用于筛选指定队列下创建于2016年3月31日14:30:00-15:00:00之间的所有Job:

$pipelineName = "your_pipeline";
$response = $client->listJobs($pipelineName, null, "2016-03-31T14:30:00Z", "2016-03-31T15:00:00Z");
foreach($response->jobs as $job) {
    print json_encode($job);
}

查询指定的Job信息

用户可以通过如下代码通过jobId读取某个Job：

$jobId = "your_job";
$response = $client->getJob($jobId);
print json_encode($response);

Preset(模板)

模板是系统预设的对于一个视频资源在做转码计算时所需定义的集合。用户可以更简便的将一个模板应用于一个和多个视频的转码任务，以使这些任务输出相同规格的目标视频资源。

音视频转码为用户预设了丰富且完备的系统模板，以满足用户对于目标规格在格式、码率、分辨率、加解密、水印等诸多方向上的普遍需求，对于不希望过多了解音视频复杂技术背景的用户来说，是最佳的选择。百度为那些在音视频技术上有着丰富积累的用户，提供了可定制化的转码模板，以帮助他们满足复杂业务条件下的转码需求。

当用户仅需对于音视频的容器格式做变化时，百度提供Transmux模板帮助用户以秒级的延迟快速完成容器格式的转换，比如从MP4转换成HLS，而保持原音视频的属性不变。

查询当前用户Preset及所有系统Preset

用户可以通过如下代码查询所有的Preset：

$response = $client->listPresets();
foreach($response->presets as $preset) {
    print json_encode($preset);
}

查询指定的Preset信息

用户可以通过如下代码指定的某个Preset：

$presetName = "your_preset";
$response = $client->getPreset($presetName);
print json_encode($response);

创建Preset

如果系统预设的Preset无法满足用户的需求，用户可以自定义自己的Preset。根据不同的转码需求，可以使用不同的接口创建Preset。

创建仅支持容器格式转换的Preset

如下代码创建仅执行容器格式转换Preset：

$presetName = "your_preset";

//指定转换后的容器格式，可选值：mp4, flv, hls, mp3, m4a
$container = "mp4";

//指定仅需要容器格式转换
$options = array(
    'transmux' => true,
);

$client->createPreset($presetName, $container, $options);

创建音频文件的转码Preset，不需要截取片段和加密

如果创建一个不需要截取片段和加密的音频文件转码Preset，可以参考如下代码：

$presetName = "your_preset";
$container = "mp4";
$options = array(
    "audio" => array(
        "bitRateInBps" => 80000,
        "sampleRateInHz" => 22050,
        "channels" => 2，
    ),
);
$client->createPreset($presetName, $container, $options);

创建音频文件转码Preset，需要设置片段截取属性和加密属性

如果创建一个支持截取片段和加密的音频文件转码Preset，可以参考如下代码：

$presetName = "your_preset";
$container = "mp4";
$options = array(
    "audio" => array(
        "bitRateInBps" => 80000,
        "sampleRateInHz" => 22050,
        "channels" => 2，
    ),
    "clip" => array(
        "startTimeInSecond" => 0,
        "durationInSecond" => 60,
    ),
    "encryption" => array(
        "aesKey" => "abcdefghij1234567",
        "strategy" => "Fixed",
    ),
);

$client->createPreset($presetName, $container, $options);

创建视频文件转码Preset，不需要截取片段和加密

如果创建一个不需要截取片段和加密的音频文件转码Preset，可以参考如下代码：

$presetName = "your_preset";
$container = "mp4";
$options = array(
    "audio" => array(
        "bitRateInBps" => 80000,
        "sampleRateInHz" => 22050,
        "channels" => 2，
    ),
    "video" => array(
        "codec" => "h264",
        "codecOptions" =>array(
            "profile" => "baseline"
        ),
        "bitRateInBps" => 32000,
        "maxFrameRate" => 30,
        "maxWidthInPixel" => 4096,
        "maxHeightInPixel"=> 96,
        "sizingPolicy" => "stretch",
    ),
);

$client->createPreset($presetName, $container, $options);

创建视频文件转码Preset，需要设置片段截取属性和加密属性

如果创建一个截取片段和加密的音频文件转码Preset，可以参考如下代码：

$presetName = "your_preset";
$container = "mp4";
$options = array(
    "audio" => array(
        "bitRateInBps" => 80000,
        "sampleRateInHz" => 22050,
        "channels" => 2，
    ),
    "video" => array(
        "codec" => "h264",
        "codecOptions" =>array(
            "profile" => "baseline"
        ),
        "bitRateInBps" => 32000,
        "maxFrameRate" => 30,
        "maxWidthInPixel" => 4096,
        "maxHeightInPixel"=> 96,
        "sizingPolicy" => "stretch",
    ),
    "clip" => array(
        "startTimeInSecond" => 0,
        "durationInSecond" => 60,
    ),
    "encryption" => array(
        "aesKey" => "abcdefghij1234567",
        "strategy" => "Fixed",
    ),
);

$client->createPreset($presetName, $container, $options);

创建Preset，指定所有的参数

如果需要定制所有配置参数，可以参考如下代码：

$presetName = "your_preset";
$container = "mp4";
$options = array(
    "description" => "this is a demo preset",
    "transmux" => "false",
    "audio" => array(
        "bitRateInBps" => 80000,
        "sampleRateInHz" => 22050,
        "channels" => 2，
    ),
    "video" => array(
        "codec" => "h264",
        "codecOptions" =>array(
            "profile" => "baseline"
        ),
        "bitRateInBps" => 32000,
        "maxFrameRate" => 30,
        "maxWidthInPixel" => 4096,
        "maxHeightInPixel"=> 96,
        "sizingPolicy" => "stretch",
    ),
    "clip" => array(
        "startTimeInSecond" => 0,
        "durationInSecond" => 60,
    ),
    "encryption" => array(
        "aesKey" => "abcdefghij1234567",
        "strategy" => "Fixed",
    ),
);

$client->createPreset($presetName, $container, $options);

修改Preset

如下代码可以更新一个Preset：

$presetName = "your_preset";
$preset = $this->client->getPreset($presetName);
$preset->audio->bitRateInBps = 800000;
$this->client->updatePreset($presetName, json_decode(json_encode( $preset),true));

修改其他参数类似

Mediainfo(媒体信息)

对于BOS中某个Object，可以通过下面代码获其媒体信息：

$bucket = "your_bucket";
$key = "your_key";
$response = $client->getMediaInfoOfFile($bucket, $key);
print json_encode($response);

Thumbnail Job(缩略图任务)

创建缩略图任务

如果要创建一个缩略图任务，可以参考如下代码：

$pipelineName = "your_pipeline";
$source = array("key" => "your_key");

//设置可选参数，包括缩略图输出方法及截取规则
$options = array(
    "target" => array(
        "keyPrefix" => "thumbnail_target_key_prefix",
        "format" => "jpg",
        "sizingPolicy" => "keep",
        "widthInPixel" => 600,
        "heightInPixel" => 400,
    ),
    "capture" => array(
        "mode" => "manual",
        "startTimeInSecond" => 0,
        "endTimeInSecond" => 50,
        "intervalInSecond" => 10,
    ),
);

$response = $client->createThumbnailJob($pipelineName, $source, $options);
print $response->jobId;

接口返回的是包含了jobId的一个对象。

查询指定缩略图任务

如果需要获取一个已创建的缩略图任务的信息，可以参考如下代码：

$jobId = "your_jobId";
$response = client->getThumbnailJob($jobId);
print json_encode($response);

对Thumbnail Job进行条件筛选

创建缩略图任务后，您可以通过下述四个参数对缩略图任务进行条件筛选，参数之间可相互配合：

pipelineName: 队列名称
jobStatus：转码状态
begin: createTime（创建时间）上限，用于筛选创建时间等于或者晚于begin的Thumbnail Job
end: createTime（创建时间）下限，用于筛选创建时间等于或者早于end的Thumbnail Job

下述示例代码用于筛选指定队列下的所有Thumbnail Job:

$pipelineName = "your_pipeline";
$response = $client->listThumbnailJobsByPipelineName($pipelineName);
print json_encode($response);

下述示例代码用于筛选指定队列下状态为“RUNNING”的所有Thumbnail Job:

$pipelineName = "your_pipeline";
$response = $client->listThumbnailJobsByPipelineName($pipelineName, "RUNNING");
print json_encode($response);

下述示例代码用于筛选指定队列下创建于2016年3月31日14:30:00之后的所有Thumbnail Job:

$pipelineName = "your_pipeline";
$response = $client->listThumbnailJobsByPipelineName($pipelineName, "2016-03-31T14:30:00Z");
print json_encode($response);

下述示例代码用于筛选指定队列下创建于2016年3月31日14:30:00-15:00:00之间的所有Thumbnail Job:

$pipelineName = "your_pipeline";
$response = $client->listThumbnailJobsByPipelineName($pipelineName, "2016-03-31T14:30:00Z", "2016-03-31T15:00:00Z");
print json_encode($response);

Watermark(水印)

创建水印

可以使用BOS中的图片对象创建一个水印，后续可以在创建自定义转码模板时设置视频水印。

创建水印，使用默认位置参数

如果需要创建一个水印（水印的默认位置是左上），可以参考如下代码：

$bucket = "your_bucket";
$key = "your_key";

$response = $client->createWatermark(
    $bucket,
    $key
);
print $response->watermarkId;

接口返回的是包含了watermarkId的一个对象。

创建水印，指定位置参数

如果需要定制水印的位置参数，可以参考如下代码：

$bucket = "your_bucket";
$key = "your_key";
$options = array(
    //可选值：top/center/bottom
    "verticalAlignment" => "top", 
    //可选值：left/center/right
    "horizontalAlignment" => "left",
    "verticalOffsetInPixel" => 0,
    "horizontalOffsetInPixel" => 0,
);

$client->createWatermark(
    $bucket,
    $key,
    $options
);

查询指定水印

如果需要查询已创建的水印，可以参考如下代码：

$watermarkId = "your_watermarkId";
$response = $client->getWatermark($watermarkId);
print json_encode($response);

查询当前用户水印

如果需要查询出本用户所创建的全部水印，可以参考如下代码：

$response = $client->listWatermarks();
print json_encode($response);

删除水印

如果需要删除某个已知watermarkId的水印，可以参考如下代码：

$watermarkId = "your_watermarkId";
$client->deleteWatermark($watermarkId);

Notification（通知）

通知功能可以在音视频转码任务状态转换时主动向开发者服务器推送消息。

新建通知

如下代码可以新建一个Notification：

$name= "your_notification";
$endpoint= "your_endpoint";
$this->client->createNotification($name, $endpoint)
);

列出全部Notification

如下代码可以列出用户所有的Notification：

// 获取用户的Notification列表
$response = $client->listNotifications();
// 遍历Notification列表
foreach ($response->notifications as $notification) {
    print json_encode($notification);
}

查询指定的Notification

若只是查询某个Notification，则使用如下代码：

$name = "your_notification";
$response = $client->getNotification($name);
print json_encode($response);

删除Notification

如下代码可以删除一个Notification：

$name = "your_notification";
client->deleteNotification($name);

异常处理

Media异常提示有如下三种方式：

异常方法	说明
BceBaseException	异常总集
BceClientException	客户端异常
BceServerException	服务器异常
InvalidArgumentException	系统自带异常，参数错误

用户可以使用try-catch获取某个事件所产生的异常：

    try {
        $client->listPresets();
    }catch (\BaiduBce\Exception\BceBaseException $e) {
        print $e->getMessage();
        if (stcmp(gettype($e), "BceClientException") == 0) {
            print "Catch a client exception";
        }
        if (stcmp(gettype($e), "BceServerException") == 0) {
            print "Catch a server exception";
        }
    }

快速入门

版本变更记录

音视频处理 MCP