Developer Guide

Last Updated：2020-09-21

Pipeline

The pipeline is divided into free type and exclusive type:

The transcoding jobs in the free pipeline share about 400 ways of 720P transcoding computing resources provided by Baidu AI Cloud for the transcoding of audio and video.
The exclusive pipeline needs procurement additionally to better meet the users with higher business requirements for transcoding timeliness and stability.

The user can use pipelines to realize job priorities. You can distinguish job priority by creating multiple pipelines. Create most jobs in the pipeline with normal priority, and place high- priority jobs in the pipeline with high priority. Use the principle of first-come-first-served for pipelines to adjust the priority of jobs.

Create New Pipeline

The following code creates a pipeline, and the capacity value is 20 by default:

$pipelineName = "your_pipeline"; 
$sourceBucket = "your_source_bucket"; 
$targetBucket = "your_source_bucket"; 
//Create a Pipeline 
$client->createPipeline($pipelineName, $sourceBucket, $targetBucket);

List All Pipelines

The following code can list all the users' Pipeline:

/Get the user’s Pipeline list 
$response = $client->listPipelines(); 
//Traverse Pipeline list 
foreach ($response->pipelines as $pipeline) { 
    print json_encode($pipeline); 
}

Query Assigned Pipeline

If you only query a certain Pipeline, use the following code:

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

Modify Pipeline

The following code modifies a Pipeline notification:

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

Similar for modifying other parameters

Delete Pipeline

The following code can delete a Pipeline:

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

You should note that if Job associated with the Pipeline is not completed, you cannot delete the Pipeline. You can delete it successfully only after Job is completed.

Job

Job is the most basic execution unit in audio and video transcoding. Each job transcodes an original audio and video resource into a target audio and video resource. Therefore, there is a one-to-one correspondence between jobs and transcoding goals, that is, if the user needs to convert an original video specification into three target specifications, such as transcoding from AVI format to FLV/MP4/HLS format, then the user needs to create three jobs.

Create Job

When creating the job, the user needs to assign the affiliated pipeline, the applied Preset, the BOS Key of the original AV resources and the BOS Key of the target AV resources.

The following code creates a Job and gets the created jobId:

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

Conditionally Filter Job

After creating the job, you can filter the transcoding jobs according to the following four parameters, the parameters interactively work:

pipelineName:pipeline name
jobStatus: Transcoding status
begin: createTime(Create time) upper limit, used for filtering the Jobs with the creation time at or later than begin
end: createTime(Create time) lower limit, used for filtering the Jobs with the creation time at or later than begin

The following example code is used for filtering all the Jobs under the assigned pipeline:

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

The following example code is used for filter all the Jobs with the status of “RUNNING” under the assigned pipeline:

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

The following example code is used for filtering all the Jobs created after 14:30:00 on March 31 2016 under the assigned pipeline:

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

The following example code is used for selecting all the Jobs created between 14:30:00-15:00:00 March 31 in 2016 in the assigned pipeline:

$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); 
}

Query assigned Job Information

The user can read a certain Job through the following code:

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

Preset

A preset is a preset set of definitions required for a video resource to perform transcoding calculations. Users can more easily apply a preset to one or more video transcoding jobs, so that these jobs output target video resources of the same specifications.

MCT provides the users with rich and complete system presets to meet the user's common requirements for format, code rate, resolution, encryption and decryption, watermark and others in terms of target specifications, and it is the best choice for the users who do not want to know too much about the complex technological background of audios and videos. Baidu has abundant accumulated users in AV technology, providing customized transcoding presets to satisfy the transcoding requirements under complicated business conditions of them.

When you only have to modify the container format of audio and video, Baidu provides Transmux presets to help you quickly convert the container format in a second-level delay, such as converting from MP4 to HLS, while keeping the original audio and video property unchanged.

Query the Presets of current user and all system Presets

You can query all the Presets via the following code.

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

Query assigned Preset information

The user can assign certain Preset through the following code:

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

Create Preset

If the Preset in the system cannot meet the user's requirements, the user can custom their own Preset. Use different interfaces to create Preset according to different coding requirements.

Create the preset that only supports container format conversion

Only the container format conversion Preset is executed for the creation of the following codes:

$presetName = "your_preset"; 

//Specify the container format after conversion, an optional value: mp4, flv, hls, mp3, m4a 
$container = "mp4"; 

//Assign to only need container format switchover 
$options = array( 
    'transmux' => true, 
); 

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

To create the transcoding Preset of audio file, you do not need to make an episode and encryption

If you create an audio file transcoding Preset without clip interception and encryption, you can refer to the following code

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

Create audio file transcoding Preset, the clip interception attribute and encryption attribute should be set

If you create a video file transcoding Preset supporting clip interception and encryption, you can refer to the following code

$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);

Create video file transcoding Preset, the clip interception and encryption are not needed

If you create an audio file transcoding Preset without clip interception and encryption, you can refer to the following code

$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);

Create video file transcoding Preset, the clip interception attribute and encryption attribute should be set

If you create a captured clip and encrypted audio file transcoding Preset, you can refer to the following code:

$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);

Create Preset and assign all the parameters

If you need to customize all the configuration parameters, you can refer to the following code:

$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);

Modify Preset

The following code updates a Preset:

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

Similar for modifying other parameters

Mediainfo (Media Information)

As for the certain Object in BOS, you can get the media information through the following code

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

Thumbnail Job

Create Thumbnail Job

To create a thumbnail job, you can refer to the following codes:

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

//Set the optional parameters, including thumbnail output method and capture rules 
$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;

The interface returns an object containing the jobId.

Query assigned thumbnail jobs

If you need to get a created thumbnail job information, you can refer to the following code:

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

Execute conditional filtering to Thumbnail Job

After creating the thumbnail job, you can execute conditional filtering through the following four parameters for the thumbnail job, and the parameters can be interactive:

pipelineName:pipeline name
jobStatus： Transcoding status
begin: createTime(Create time) upper limit, used for filtering the Thumbnail Jobs with the creation time at or later than begin
end: createTime(Create time) lower limit, used for filtering the Thumbnail Jobs with the creation time at or later than begin

The following example code is used for filtering all the Thumbnail Jobs under the assigned pipeline:

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

The following example code is used for filtering all the Thumbnail Jobs with the status of “RUNNING” under the assigned pipeline:

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

The following example code is used for filtering all the Thumbnail Jobs created after 14:30:00 on March 31 2016 under the assigned pipeline:

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

The following example code is used for filtering all the Thumbnail Jobs created between 14:30:00 and 15:00:00 on March 31 2016 under the assigned pipeline:

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

Watermark

Create watermark

You can use the picture object in BOS to create a watermark, and then you can set video watermark when creating a custom transcoding preset.

Create a watermark and use the default position parameter

If you need to create a watermark (the default position is upper left), you can refer to the following codes:

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

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

The interface returns an object containing watermarkId

Create a watermark and assign the position parameter

If you need to customize the watermark position parameter, you can refer to the following code:

$bucket = "your_bucket"; 
$key = "your_key"; 
$options = array( 
    //Optional value: top/center/bottom 
    "verticalAlignment" => "top", 
    //Optional value: left/center/right 
    "horizontalAlignment" => "left", 
    "verticalOffsetInPixel" => 0, 
    "horizontalOffsetInPixel" => 0, 
); 

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

Query assigned watermark

If you need to query the created watermark, you can refer to the following code:

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

Query the watermark of the current user

If you need to query all the watermarks created by the current user, you can refer to the following code:

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

Delete watermark

If you need to delete a watermark with a given watermarkId, you can refer to the following code:

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

Notification

The MCT service uses pipeline notification service (QNS) for notification, and will push messages to the developer server when the job status of the MCT is transferred.

Create notification

The following code can create a Notification:

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

List all notifications

The following code can list all the users' Notification:

//Get the user Notification list 
$response = $client->listNotifications(); 
// Traverse Notification list 
foreach ($response->notifications as $notification) { 
    print json_encode($notification); 
}

Query assigned notification

If you just query a certain Notification, use the following code:

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

Notification deletion

The following code can delete a Notification:

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

Exception handling

There are three reminders for Media abnormity:

Exception method	Description
BceBaseException	Anthology of exceptions
BceClientException	Client exception
BceServerException	Server exception
InvalidArgumentException	System built-in exception, parameter error

You can use try-catch to get exceptions generated by an event:

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

Getting Started

Version Change Record

Multimedia Cloud Processing