README

Shotstack PHP 视频编辑器和云视频编辑 API 的 PHP SDK。

Shotstack 是一个基于云的视频编辑平台，允许使用代码进行视频编辑。

该平台使用 API 和 JSON 格式来指定视频的编辑方式以及应使用哪些资源和标题。

基于服务器的渲染农场负责渲染视频，允许同时创建多个视频。

有关如何使用 SDK 通过代码创建视频的示例，请查看 PHP 示例存储库：https://github.com/shotstack/php-demos

内容

使用 PHP SDK
API 文档和指南

使用 PHP SDK

需求

需要 PHP7.4+ 和使用 Guzzle7.3+。

安装

使用 SDK 的推荐方式是作为 composer 包。使用以下命令安装

composer require shotstack/shotstack-sdk-php

视频编辑

Shotstack SDK 通过 Edit API 的 render 端点实现程序化视频编辑。使用提供的模式类准备 JSON 编辑，并通过 POST 发送到 API 进行渲染。

视频编辑示例

以下示例裁剪视频剪辑的开始部分并播放 8 秒。编辑使用 SDK 模型准备，然后发送到 API 进行渲染。

<?php
require 'vendor/autoload.php';

use Shotstack\Client\Api\EditApi;
use Shotstack\Client\Configuration;
use Shotstack\Client\Model\Edit;
use Shotstack\Client\Model\Output;
use Shotstack\Client\Model\Timeline;
use Shotstack\Client\Model\Track;
use Shotstack\Client\Model\Clip;
use Shotstack\Client\Model\VideoAsset;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.shotstack.io/stage')
    ->setApiKey('x-api-key', 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'); // use the correct API key

$client = new EditApi(null, $config);

$videoAsset = new VideoAsset();
$videoAsset
    ->setSrc('https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/skater.hd.mp4')
    ->setTrim(3);

$videoClip = new Clip();
$videoClip
    ->setAsset($videoAsset)
    ->setLength(8)
    ->setStart(0);

$track = new Track();
$track->setClips([$videoClip]);

$timeline = new Timeline();
$timeline->setTracks([$track]);

$output = new Output();
$output
    ->setFormat('mp4')
    ->setResolution('sd');

$edit = new Edit();
$edit
    ->setTimeline($timeline)
    ->setOutput($output);

$render = $client->postRender($edit)->getResponse();

状态检查示例

以下示例请求可以在上述渲染发布后几秒内调用。它将返回渲染状态，这可能需要几秒钟才能处理。它使用 render->getId() 方法，这是由 postRender 请求返回的。

use Shotstack\Client\Api\EditApi;
use Shotstack\Client\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.shotstack.io/stage')
    ->setApiKey('x-api-key', 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'); // use the correct API key

$client = new EditApi(null, $config);

$video = $client->getRender($render->getId())->getResponse();

if ($video->getStatus() === 'done') {
    echo $video->getUrl();
}

保存模板示例

以下示例使用我们在视频编辑示例中创建的编辑并将其保存为模板。模板可以在以后的时间渲染，并且可以包含占位符。渲染时可以使用合并字段来替换占位符。

此示例使用视频src（URL）、裁剪（TRIM）和长度（LENGTH）的占位符，以便您可以使用模板裁剪任何视频。

<?php
require 'vendor/autoload.php';

use Shotstack\Client\Api\EditApi;
use Shotstack\Client\ApiException;
use Shotstack\Client\Configuration;
use Shotstack\Client\Model\Edit;
use Shotstack\Client\Model\Output;
use Shotstack\Client\Model\Timeline;
use Shotstack\Client\Model\Track;
use Shotstack\Client\Model\Clip;
use Shotstack\Client\Model\VideoAsset;
use Shotstack\Client\Model\Template;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.shotstack.io/stage')
    ->setApiKey('x-api-key', 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'); // use the correct API key

$client = new EditApi(null, $config);

$videoAsset = new videoAsset();
$videoAsset
    ->setSrc('{{ URL }}')
    ->setTrim('{{ TRIM }}');

$videoClip = new Clip();
$videoClip
    ->setAsset($videoAsset)
    ->setStart(0)
    ->setLength('{{ LENGTH }}');

$track = new Track();
$track
    ->setClips([$videoClip]);

$timeline = new Timeline();
$timeline
    ->setTracks([$track]);

$output = new Output();
$output
    ->setFormat('mp4')
    ->setResolution('sd');

$edit = new Edit();
$edit
    ->setTimeline($timeline)
    ->setOutput($output);

$template = new Template();
$template
    ->setName('Trim Template')
    ->setTemplate($edit);

$response = $client->postTemplate($template)->getResponse();

渲染模板示例

以下示例渲染了前面示例中创建的模板，并包括将替换占位符的合并字段。一旦提交，使用返回的渲染ID调用状态检查示例以获取渲染进度。它使用由postTemplate请求返回的response->getId()方法。

use Shotstack\Client\Api\EditApi;
use Shotstack\Client\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.shotstack.io/stage')
    ->setApiKey('x-api-key', 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'); // use the correct API key

$client = new EditApi(null, $config);

$mergeFieldUrl = new MergeField();
$mergeFieldUrl
    ->setFind('URL')
    ->setReplace('https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/skater.hd.mp4');

$mergeFieldTrim = new MergeField();
$mergeFieldTrim
    ->setFind('TRIM')
    ->setReplace(3);

$mergeFieldLength = new MergeField();
$mergeFieldLength
    ->setFind('LENGTH')
    ->setReplace(6);

$template = new TemplateRender();
$template
    ->setId($response->id)
    ->setMerge([
        $mergeFieldUrl,
        $mergeFieldTrim,
        $mergeFieldLength,
    ]);

$video = $client->postTemplateRender($template)->getResponse();

if ($video->getStatus() === 'done') {
    echo $video->getUrl();
}

视频编辑模式

以下架构用于准备视频编辑。

编辑()

编辑定义了视频在时间线上的排列、音频编辑或图像设计以及输出格式。

示例

use Shotstack\Client\Model\Edit;

$edit = new Edit();
$edit
  ->setTimeline($timeline)
  ->setOutput($output)
  ->setMerge($merge)
  ->setCallback('https://my-server.com/callback.php')
  ->setDisk('local');

方法

时间线()

时间线表示视频编辑随时间的内容，音频编辑随时间，以秒为单位，或图像布局。时间线由称为轨道的层组成。轨道由标题、图像、音频、html或视频段（称为剪辑）组成，这些剪辑放置在轨道上，从特定的起始点开始，持续特定的时间。

示例

use Shotstack\Client\Model\Timeline;

$timeline = new Timeline();
$timeline
  ->setSoundtrack($soundtrack)
  ->setBackground('#000000')
  ->setFonts($fonts)
  ->setTracks($tracks)
  ->setCache(true);

方法

配乐()

一首mp3格式的音乐或音频文件，播放时长为渲染视频的持续时间或音频文件的长度，以较短者为准。

示例

use Shotstack\Client\Model\Soundtrack;

$soundtrack = new Soundtrack();
$soundtrack
  ->setSrc('https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/music/disco.mp3')
  ->setEffect('fadeIn')
  ->setVolume(1);

方法

字体()

下载自定义字体以与HTML资产类型一起使用，使用CSS或字体标签中的字体名称。有关详细信息，请参阅我们的自定义字体入门指南。

示例

use Shotstack\Client\Model\Font;

$font = new Font();
$font
  ->setSrc('https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/fonts/OpenSans-Regular.ttf');

方法

轨道()

轨道包含剪辑数组。轨道按数组的顺序叠加。最顶层的轨道将渲染在最下面的轨道之上。

示例

use Shotstack\Client\Model\Track;

$track = new Track();
$track
  ->setClips($clips);

方法

剪辑()

剪辑是特定类型资产的容器，例如标题、图像、视频、音频或html。您使用剪辑来定义资产将在时间线上的显示时间、播放时长以及要应用于它的过渡、滤镜和效果。

示例

use Shotstack\Client\Model\Clip;

$clip = new Clip();
$clip
  ->setAsset($asset)
  ->setStart(2)
  ->setLength(5)
  ->setFit('crop')
  ->setScale(0)
  ->setPosition('center')
  ->setOffset($offset)
  ->setTransition($transition)
  ->setEffect('zoomIn')
  ->setFilter('greyscale')
  ->setOpacity(1)
  ->setTransform($transform);

方法

视频资源()

VideoAsset用于从视频文件创建视频序列。src必须是一个公开可访问的视频资源URL，例如mp4文件。

示例

use Shotstack\Client\Model\VideoAsset;

$videoAsset = new VideoAsset();
$videoAsset
  ->setSrc('https://shotstack-assets.s3.aws.com/mountain.mp4')
  ->setTrim(5)
  ->setVolume(0.5)
  ->setVolumeEffect('fadeIn')
  ->setCrop($crop);

方法

图片资源()

ImageAsset用于从图像创建视频以组合图像。src必须是一个公开可访问的图像资源URL，例如jpg或png文件。

示例

use Shotstack\Client\Model\ImageAsset;

$imageAsset = new ImageAsset();
$imageAsset
  ->setSrc('https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/images/earth.jpg')
  ->setCrop($crop);

方法

标题资源()

TitleAsset剪辑类型允许您从文本字符串创建视频标题并应用样式和定位。

示例

use Shotstack\Client\Model\TitleAsset;

$titleAsset = new TitleAsset();
$titleAsset
  ->setText('My Title')
  ->setStyle('minimal')
  ->setColor('#ffffff')
  ->setSize('medium')
  ->setBackground('#000000')
  ->setPosition('center')
  ->setOffset($offset);

方法

HTML 资源()

HtmlAsset剪辑类型允许您使用HTML和CSS创建基于文本的布局和格式。您还可以设置HTML内容的边界框的高度和宽度。文本和元素将在边界框内换行。

示例

use Shotstack\Client\Model\HtmlAsset;

$htmlAsset = new HtmlAsset();
$htmlAsset
  ->setHtml('<p>Hello <b>World</b></p>')
  ->setCss('p { color: #ffffff; } b { color: #ffff00; }')
  ->setWidth(400)
  ->setHeight(200)
  ->setBackground('transparent')
  ->setPosition('center);

方法

音频资源()

AudioAsset用于在时间线上的特定间隔添加声音效果和音频。src必须是一个公开可访问的音频资源URL，例如mp3文件。

示例

use Shotstack\Client\Model\AudioAsset;

$audioAsset = new AudioAsset();
$audioAsset
  ->setSrc('https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/unminus/lit.mp3')
  ->setTrim(2)
  ->setVolume(0.5)
  ->setEffect('fadeInFadeOut');

方法

亮度资源()

LumaAsset用于创建亮度蒙版、过渡和效果。亮度蒙版是灰度图像或动画视频，其中黑色区域是透明的，白色区域是实心的。亮度蒙版动画应以mp4视频文件提供。src必须是一个公开可访问的文件URL。

示例

use Shotstack\Client\Model\LumaAsset;

$lumaAsset = new LumaAsset();
$lumaAsset
  ->setSrc('https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/examples/luma-mattes/paint-left.mp4')
  ->setTrim(5);

方法

转场()

Transition剪辑类型允许您定义剪辑的进入和退出过渡 - 即淡入和淡出。

示例

use Shotstack\Client\Model\Transition;

$transition = new Transition();
$transition
  ->setIn('fade')
  ->setOut('fade');

方法

偏移()

通过相对距离水平或垂直偏移资产的位置。

示例

use Shotstack\Client\Model\Offset;

$offset = new Offset();
$offset
  ->setX(0.1)
  ->setY(-0.2);

方法

裁剪()

通过相对量裁剪资产的两边。裁剪的大小使用0到1之间的比例指定，相对于屏幕宽度 - 例如，左裁剪0.5将从左边裁剪资产的一半，顶部裁剪0.25将从顶部裁剪资产的四分之一。

示例

use Shotstack\Client\Model\Crop;

$crop = new Crop();
$crop
  ->setTop(0.15)
  ->setBottom(0.15)
  ->setLeft(0)
  ->setRight(0);

方法

变换()

对一个剪辑应用一个或多个转换。转换改变剪辑的视觉属性，可以组合起来创建新的形状和效果。

示例

use Shotstack\Client\Model\Transformation;

$transformation = new Transformation();
$transformation
  ->setRotate($rotate)
  ->setSkew($skew)
  ->setFlip($flip);

方法

旋转变换()

按指定的角度（以度为单位）旋转剪辑。旋转原点基于剪辑的 position。

示例

use Shotstack\Client\Model\RotateTransformation;

$rotateTransformation = new RotateTransformation();
$rotateTransformation
  ->setAngle(45);

方法

倾斜变换()

使剪辑的边缘倾斜一个角度。使用0到3之间的值。超过3，剪辑将被倾斜得几乎平坦。

示例

use Shotstack\Client\Model\SkewTransformation;

$skewTransformation = new SkewTransformation();
$skewTransformation
  ->setX(0.5)
  ->setY(0.5);

方法

翻转变换()

垂直或水平翻转剪辑。作为剪辑沿选定平面的镜像效果。

示例

use Shotstack\Client\Model\FlipTransformation;

$flipTransformation = new FlipTransformation();
$flipTransformation
  ->setHorizontal(true)
  ->setVertical(true);

方法

合并字段()

合并字段由一个键；find，和一个value；替换组成。合并字段可以用于在JSON编辑中替换占位符以创建可重复使用的模板。占位符应是一个带有双花括号分隔符的字符串，例如 "{{NAME}}"。占位符可以用于JSON编辑中的任何值。

示例

use Shotstack\Client\Model\MergeField;

$mergeField = new MergeField();
$mergeField
  ->setFind('NAME')
  ->setReplace('Jane');

方法

模板模式

以下模式指定如何使用模板来存储和渲染模板。模板允许您保存一个编辑，该编辑可以通过其模板ID渲染，并且可以选择包含在渲染时与模板合并的合并字段。

模板()

模板是一个保存的编辑，可以加载和重复使用。

示例

use Shotstack\Client\Model\Template;

$template = new Template();
$template
  ->setName('My Template')
  ->setTemplate($edit);

方法

模板渲染()

配置id和可选的合并字段以通过id渲染模板。

示例

use Shotstack\Client\Model\TemplateRender;

$render = new TemplateRender();
$render
  ->setId('21e781c0-8232-4418-fec1-cc99f0280c21')
  ->setMerge($merge);

方法

输出模式

以下模式指定输出格式和设置。

输出()

输出格式、渲染范围和要生成的媒体类型。

示例

use Shotstack\Client\Model\Output;

$output = new Output();
$output
  ->setFormat('mp4')
  ->setResolution('sd')
  ->setAspectRatio('16:9')
  ->setSize($size)
  ->setFps(25)
  ->setScaleTo('preview')
  ->setQuality('mediue')
  ->setRepeat(true)
  ->setMute(false)
  ->setRange($range)
  ->setPoster($poster)
  ->setThumbnail($thumbnail)
  ->setDestinations($destinations);

方法

大小()

为视频或图像设置自定义大小。当使用自定义大小时，省略 resolution 和 aspectRatio。自定义大小必须根据编码器规范可被2整除。

示例

use Shotstack\Client\Model\Size;

$size = new Size();
$size
  ->setWidth(1200)
  ->setHeight(800);

方法

范围()

指定要渲染的时间范围，例如，仅渲染视频或音频文件的一部分。省略此设置以导出整个视频。范围也可以用于在特定时间点渲染一个帧 - 将范围和输出格式设置为 jpg 将在 start 点输出一个单帧图像。

示例

use Shotstack\Client\Model\Range;

$range = new Range();
$range
  ->setStart(3)
  ->setLength(6);

方法

海报()

从时间轴的特定位置生成视频的海报图像。海报图像的大小将与输出视频的大小匹配。

示例

use Shotstack\Client\Model\Poster;

$poster = new Poster();
$poster
  ->setCapture(1);

方法

缩略图()

从时间轴的特定位置生成视频或图像的缩略图。

示例

use Shotstack\Client\Model\Thumbnail;

$thumbnail = new Thumbnail();
$thumbnail
  ->setCapture(1)
  ->setScale(0.3);

方法

目标

Shotstack 目标()

将渲染后的资产发送到Shotstack托管和CDN服务。默认启用此目的地。

示例

use Shotstack\Client\Model\ShotstackDestination;

$shotstackDestination = new ShotstackDestination();
$shotstackDestination
  ->setProvider('shotstack')
  ->setExclude(false);

方法

Mux 目标()

将渲染的视频发送到Mux视频托管和流媒体服务。需要Mux凭据，并通过仪表板添加，而不是在请求中。

示例

use Shotstack\Client\Model\MuxDestination;

$muxDestination = new MuxDestination();
$muxDestination
  ->setProvider('mux')
  ->setOptions($muxDestinationOptions);

方法

Mux 目标选项()

传递额外的选项以控制Mux如何处理视频。目前支持播放策略选项。

示例

use Shotstack\Client\Model\MuxDestinationOptions;

$muxDestinationOptions = new MuxDestinationOptions();
$muxDestinationOptions
  ->setPlaybackPolicy(['public']);

方法

S3 目标()

将渲染的视频发送到Amazon S3存储桶。将文件发送到任何区域，并使用您自己的前缀和文件名。需要AWS凭据，并通过仪表板添加，而不是在请求中。

示例

use Shotstack\Client\Model\S3Destination;

$s3Destination = new S3Destination();
$s3Destination
  ->setProvider('s3')
  ->setOptions($s3DestinationOptions);

方法

S3 目标选项()

传递额外的选项以控制如何在S3中存储文件。

示例

use Shotstack\Client\Model\S3DestinationOptions;

$s3DestinationOptions = new S3DestinationOptions();
$s3DestinationOptions
  ->setRegion('us-east-1');
  ->setBucket('my-bucket');
  ->setPrefix('my-renders');
  ->setFilename('my-file');
  ->setAcl('public-read');

方法

渲染响应模式

以下模式由渲染请求和状态请求返回。

排队响应()

提交渲染请求后收到的响应。渲染任务被排队以进行渲染，并返回一个唯一的渲染ID。

方法

排队响应数据()

QueuedResponseData 是与 QueuedResponse 一起返回的响应数据。

方法

渲染响应()

在提交渲染状态请求后，将接收到 RenderResponse。该响应包括渲染状态和输出URL的详细信息。

方法

渲染响应数据()

RenderResponseData 是随 RenderResponse 请求返回的数据，包括状态和URL。

方法

模板响应模式

以下架构由模板端点返回，包括创建、更新和渲染模板。

模板响应()

提交模板后接收到的响应。模板被保存，并返回一个唯一的模板ID。

方法

模板响应数据()

随 TemplateResponse 返回的响应数据。

方法

模板数据响应()

包括模板名称和编辑的模板数据。

方法

模板数据响应数据()

随 TemplateDataResponse 返回的响应数据。

方法

模板列表响应()

之前保存的模板列表。

方法

模板列表响应数据()

随 TemplateListResponse 返回的响应数据。

方法

模板列表响应项()

随 TemplateListResponseData 模板列表返回的单独模板项。

方法

检查媒体

SDK的 probe 端点可用于检查在线托管媒体。只需传递要检查的资产的URL。

探查示例

以下示例检查（探测）GitHub上托管的视频，并返回有关文件的元数据。

use Shotstack\Client\Api\EditApi;
use Shotstack\Client\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.shotstack.io/stage')
    ->setApiKey('x-api-key', 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'); // use the correct API key

$client = new EditApi(null, $config);

$url = 'https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4';

$response = $client->probe($url)->getResponse();

foreach ($response['metadata']->streams as $stream) {
    if ($stream->codec_type === 'video') {
        echo 'Example settings for: ' . $response['metadata']->format->filename, PHP_EOL, PHP_EOL;
        echo 'Width: ' . $stream->width . 'px', PHP_EOL;
        echo 'Height: ' . $stream->height . 'px', PHP_EOL;
        echo 'Framerate: ' . $stream->r_frame_rate . ' fps', PHP_EOL;
        echo 'Duration: ' . $stream->duration . ' secs', PHP_EOL;
    }
}

探查模式

以下架构由探测请求返回。

探查响应()

在提交探测请求后，将返回 ProbeResponse。探测请求返回FFprobe格式的JSON数据。

方法

管理资源

默认情况下，由编辑API生成的所有资产都由Shotstack托管并通过我们的CDN提供服务。SDK提供了访问Serve API的权限，以检索托管文件的信息。还可以删除文件。

按渲染 ID 获取资源示例

以下示例使用渲染ID查找与渲染关联的托管资产。请注意，可以为渲染创建多个资产，例如视频、缩略图和海报。每个资产都有一个唯一的资产ID，与渲染ID不同。

use Shotstack\Client\Api\ServeApi;
use Shotstack\Client\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.shotstack.io/stage')
    ->setApiKey('x-api-key', 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'); // use the correct API key

$client = new ServeApi(null, $config);

$renderId = '140924c6-077d-4334-a89f-94befcfc0155'; // Use a valid render ID

$response = $client->getAssetByRenderId($renderId)->getData();

foreach ($response as $asset) {
    if ($asset->getAttributes()->getStatus() === 'ready') {
        echo "Status: " . strtoupper($asset->getAttributes()->getStatus()), PHP_EOL, PHP_EOL;
        echo ">> Asset CDN URL: " . $asset->getAttributes()->getUrl(), PHP_EOL, PHP_EOL;
        echo ">> Asset ID: " . $asset->getAttributes()->getId(), PHP_EOL, PHP_EOL;
        echo ">> Render ID: " . $asset->getAttributes()->getRenderId(), PHP_EOL, PHP_EOL;
    }
}

按资源 ID 获取资源示例

每个资产都有一个唯一的资产ID，以下示例通过资产ID查找资产。

use Shotstack\Client\Api\ServeApi;
use Shotstack\Client\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.shotstack.io/stage')
    ->setApiKey('x-api-key', 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'); // use the correct API key

$client = new ServeApi(null, $config);

$renderId = 'ed43eae3-4825-4c03-979d-f7dc47b9997c'; // Use a valid asset ID

$response = $client->getAsset($renderId)->getData();

foreach ($response as $asset) {
    if ($asset->getAttributes()->getStatus() === 'ready') {
        echo "Status: " . strtoupper($asset->getAttributes()->getStatus()), PHP_EOL, PHP_EOL;
        echo ">> Asset CDN URL: " . $asset->getAttributes()->getUrl(), PHP_EOL, PHP_EOL;
        echo ">> Asset ID: " . $asset->getAttributes()->getId(), PHP_EOL, PHP_EOL;
        echo ">> Render ID: " . $asset->getAttributes()->getRenderId(), PHP_EOL, PHP_EOL;
    }
}

资源模式

以下架构由Serve API的请求返回。

资源响应()

AssetResponse 是Serve API 获取资产请求返回的响应。包括托管视频、图像、音频文件、缩略图或海报图像的详细信息。响应遵循json:api规范。

方法

资源渲染响应()

AssetRenderResponse 是Serve API 通过渲染ID获取资产请求返回的响应。响应是包含视频、图像、音频、缩略图和海报图像的资产资源的数组。响应遵循json:api规范。

shotstack / shotstack-sdk-php

维护者

详情