README

面向 PHP 7.3 的阿里云智能媒体服务 Timeline 混剪 SDK，适合海豚PHP、ThinkPHP、Laravel 或原生 PHP 项目后端接入。

当前版本聚焦 Timeline 作业链路：

时间轴剪辑
视频轨 / 图片轨 / 背景图 / 水印
字幕、字幕样式、花字、官方气泡字、自定义气泡字
音乐、音量、淡入淡出
图层顺序
效果轨
提交作业、查询作业、轮询等待结果

暂不包含：

前端编辑器
素材上传 / OSS 直传
回调验签 / 落库同步
ProjectId / TemplateId 类型作业封装

1. 环境要求

PHP ^7.3 || ^8.0
ext-json
阿里云智能媒体服务 IMS 已开通
输出 OSS Bucket 与 IMS 区域保持一致

2. 安装

如果你准备把这个包发布到 Packagist，安装方式可以是：

composer require xxm/aliyun-timeline-sdk

当前仓库本地开发方式：

composer install

核心依赖：

alibabacloud/ice-20201109

3. 目录结构

src/
  Client/        阿里云请求客户端与传输适配
  Config/        AK/SK 与轮询配置
  Exception/     统一异常
  Output/        输出配置与输出目标
  Presets/       字幕预设
  Result/        返回结果对象
  Support/       数组与 JSON 工具
  Timeline/      时间轴 Builder
  Validation/    本地预检
examples/        接入示例
tests/           PHPUnit 测试

4. 核心对象

4.1 客户端

use Xxm\AliyunTimeline\Client\TimelineClient;
use Xxm\AliyunTimeline\Config\ClientConfig;

$client = new TimelineClient(
    ClientConfig::fromArray([
        'accessKeyId' => 'your-ak',
        'accessKeySecret' => 'your-sk',
        'securityToken' => null,
        'regionId' => 'cn-shanghai',
        'endpoint' => null,
        'userAgent' => 'your-app/1.0.0',
    ])
);

4.2 时间轴

TimelineDefinition 是时间轴根对象，当前支持：

canvas($width, $height)
backgroundColor($hexColor)
addVideoTrack(VideoTrack $track)
addAudioTrack(AudioTrack $track)
addSubtitleTrack(SubtitleTrack $track)
addEffectTrack(EffectTrack $track)
raw(array $extra)

4.3 作业请求

JobRequest 负责把 Timeline、输出配置、输出目标组装成 SubmitMediaProducingJob 需要的请求体：

JobRequest::make(TimelineDefinition $timeline, OutputConfig $outputConfig, OutputTarget $outputTarget)
userData(array $userData)
clientToken(string $clientToken)
source(string $source)
editingProduceConfig(array $config)
mediaMetadata(array $metadata)
raw(array $extra)

4.4 输出对象

输出配置：

use Xxm\AliyunTimeline\Output\OutputConfig;

$outputConfig = OutputConfig::mp4()
    ->video([
        'Width' => 720,
        'Height' => 1280,
    ])
    ->audio([
        'Codec' => 'AAC',
    ])
    ->attributes([
        'Bitrate' => 4500,
    ]);

输出目标：

use Xxm\AliyunTimeline\Output\OutputTarget;

$ossTarget = OutputTarget::oss(
    'https://example.oss-cn-shanghai.aliyuncs.com/output/demo.mp4'
);

$vodTarget = OutputTarget::vod('outin-xxxx', 'demo.mp4');

$customTarget = OutputTarget::custom('oss-object', [
    'MediaURL' => 'https://example.oss-cn-shanghai.aliyuncs.com/output/custom.mp4',
]);

5. 快速开始

下面是一个最小可运行的混剪任务：

<?php

require __DIR__ . '/vendor/autoload.php';

use Xxm\AliyunTimeline\Client\TimelineClient;
use Xxm\AliyunTimeline\Config\ClientConfig;
use Xxm\AliyunTimeline\Output\OutputConfig;
use Xxm\AliyunTimeline\Output\OutputTarget;
use Xxm\AliyunTimeline\Timeline\JobRequest;
use Xxm\AliyunTimeline\Timeline\TimelineDefinition;
use Xxm\AliyunTimeline\Timeline\VideoClip;
use Xxm\AliyunTimeline\Timeline\VideoTrack;

$client = new TimelineClient(
    ClientConfig::fromArray([
        'accessKeyId' => 'your-ak',
        'accessKeySecret' => 'your-sk',
        'regionId' => 'cn-shanghai',
    ])
);

$timeline = TimelineDefinition::create()
    ->canvas(720, 1280)
    ->addVideoTrack(
        VideoTrack::make()->addClip(
            VideoClip::fromMediaUrl('https://example.oss-cn-shanghai.aliyuncs.com/input/main.mp4')
                ->timeline(0, 8)
        )
    );

$job = JobRequest::make(
    $timeline,
    OutputConfig::mp4(),
    OutputTarget::oss('https://example.oss-cn-shanghai.aliyuncs.com/output/minimal.mp4')
)->userData([
    'scene' => 'minimal',
]);

$submit = $client->submitTimelineJob($job);
$result = $client->waitForJob($submit->jobId());

echo $result->status() . PHP_EOL;
echo $result->mediaUrl() . PHP_EOL;

6. Timeline Builder 使用说明

6.1 视频轨与图层顺序

图层顺序不额外定义 zIndex，直接按 VideoTracks 的加入顺序序列化。

先加的轨道在前
后加的轨道可理解为更上层

示例：

use Xxm\AliyunTimeline\Timeline\VideoClip;
use Xxm\AliyunTimeline\Timeline\VideoTrack;

$timeline
    ->addVideoTrack(
        VideoTrack::make()->addClip(
            VideoClip::globalImage('https://example.oss-cn-shanghai.aliyuncs.com/materials/bg.png')
                ->timeline(0, 12)
                ->opacity(0.3)
        )
    )
    ->addVideoTrack(
        VideoTrack::make()
            ->addClip(
                VideoClip::fromMediaUrl('https://example.oss-cn-shanghai.aliyuncs.com/input/main.mp4')
                    ->timeline(0, 12)
                    ->position(0, 0)
                    ->size(720, 1280)
                    ->adaptMode('Cover')
            )
            ->addClip(
                VideoClip::watermark('https://example.oss-cn-shanghai.aliyuncs.com/materials/logo.png')
                    ->timeline(0, 12)
                    ->position(24, 24)
                    ->size(120, 120)
            )
    );

VideoClip 当前支持：

fromMediaUrl()
fromMediaId()
image()
globalImage()
watermark()
timeline()
source()
position()
size()
opacity()
adaptMode()
speed()
addEffect()
raw()

6.2 音频轨

use Xxm\AliyunTimeline\Timeline\AudioClip;
use Xxm\AliyunTimeline\Timeline\AudioTrack;
use Xxm\AliyunTimeline\Timeline\Effect;

$timeline->addAudioTrack(
    AudioTrack::make()->addClip(
        AudioClip::fromMediaUrl('https://example.oss-cn-shanghai.aliyuncs.com/audio/bgm.mp3')
            ->timeline(0, 12)
            ->loop(true)
            ->addEffect(Effect::volume(0.75))
            ->addEffect(Effect::audioFadeIn(1.5))
            ->addEffect(Effect::audioFadeOut(2.0))
    )
);

6.3 字幕、花字、气泡字

use Xxm\AliyunTimeline\Presets\SubtitlePresetFactory;
use Xxm\AliyunTimeline\Timeline\SubtitleClip;
use Xxm\AliyunTimeline\Timeline\SubtitleTrack;

$timeline->addSubtitleTrack(
    SubtitleTrack::make()
        ->addClip(
            SubtitleClip::text('标题字')
                ->timeline(0, 3)
                ->position(160, 160)
                ->applyPreset(SubtitlePresetFactory::title())
        )
        ->addClip(
            SubtitleClip::text('官方气泡字')
                ->timeline(3, 6)
                ->position(180, 960)
                ->applyPreset(SubtitlePresetFactory::bubbleOfficial('BS0001-000001'))
        )
        ->addClip(
            SubtitleClip::text('自定义花字')
                ->timeline(6, 10)
                ->position(90, 1080)
                ->applyPreset(
                    SubtitlePresetFactory::bubbleCustom(
                        'https://example.oss-cn-shanghai.aliyuncs.com/materials/bubble.png',
                        320,
                        96
                    )
                )
                ->applyPreset(SubtitlePresetFactory::artTextBasic('#F97316'))
        )
);

SubtitleClip 当前支持：

text(string $content)
subtitleFile(string $fileUrl = null)
timeline()
position()
size()
font()
color()
angle()
applyPreset(array $preset)
addEffect(Effect $effect)
raw()

6.4 效果轨

use Xxm\AliyunTimeline\Timeline\EffectTrack;
use Xxm\AliyunTimeline\Timeline\EffectTrackItem;

$timeline->addEffectTrack(
    EffectTrack::make()->addItem(
        EffectTrackItem::filter('m7')->timeline(2, 8)
    )
);

7. 内置字幕预设

预设工厂：Xxm\AliyunTimeline\Presets\SubtitlePresetFactory

当前内置：

title()
subtitle()
stroke($color = '#000000', $width = 2)
shadow($color = '#000000', $offsetX = 0, $offsetY = 2, $blur = 0)
artTextBasic($primaryColor = '#FF8A3D')
bubbleOfficial($styleId)
bubbleCustom($imageUrl, $width, $height)

预设本质上是数组，可与 applyPreset()、raw() 组合使用。

8. 提交、查询、轮询

8.1 提交作业

$submit = $client->submitTimelineJob($job);

echo $submit->jobId();
echo $submit->requestId();

8.2 查询作业

$result = $client->getJob($submit->jobId());

echo $result->status();
echo $result->mediaId();
echo $result->mediaUrl();
echo $result->timelineJson();

8.3 轮询等待

use Xxm\AliyunTimeline\Config\PollOptions;

$result = $client->waitForJob(
    $submit->jobId(),
    PollOptions::make(30, 5.0)
);

默认轮询配置：

最多 30 次
每次间隔 5 秒
成功状态：Success、Finished
失败状态：Failed、Canceled、Cancelled

9. 本地预检规则

TimelineClient::submitTimelineJob() 会先走本地校验。

当前规则：

Timeline 至少有一条视频轨或音频轨
同一素材片段不能同时定义 MediaURL 和 MediaId
In 不能大于 Out
TimelineIn 不能大于 TimelineOut
字幕类型为 Subtitle 时必须提供 FileURL
音频轨和字幕轨会给出简单的时间重叠 warning
设置 AdaptMode 但未设置宽高时，会给出 warning

如果校验失败，会抛出 ValidationException。

10. 异常说明

当前异常体系：

ConfigurationException
ValidationException
RequestException
JobFailedException
TimeoutException
AliyunTimelineException

建议至少捕获：

use Xxm\AliyunTimeline\Exception\AliyunTimelineException;

try {
    $submit = $client->submitTimelineJob($job);
    $result = $client->waitForJob($submit->jobId());
} catch (AliyunTimelineException $e) {
    echo $e->getMessage();
}

11. ThinkPHP / 海豚PHP 接入示例

项目里可以把 SDK 当作一个普通服务类注册。

use Xxm\AliyunTimeline\Client\TimelineClient;
use Xxm\AliyunTimeline\Config\ClientConfig;

$config = [
    'aliyun_timeline' => [
        'accessKeyId' => 'your-ak',
        'accessKeySecret' => 'your-sk',
        'securityToken' => '',
        'regionId' => 'cn-shanghai',
    ],
];

$timelineClient = new TimelineClient(
    ClientConfig::fromArray($config['aliyun_timeline'])
);

现成示例见：

examples/06-thinkphp.php

12. 示例脚本

当前示例：

examples/01-minimal.php
examples/02-vertical-mix.php
examples/03-background-watermark.php
examples/04-subtitle-presets.php
examples/05-music-fade.php
examples/06-thinkphp.php

运行方式：

php examples/01-minimal.php
php examples/04-subtitle-presets.php

13. 测试

运行单元测试：

vendor/bin/phpunit --configuration phpunit.xml.dist

或者：

composer test

13.1 真实环境 smoke test

测试文件：

tests/Unit/IntegrationSmokeTest.php

启用前需要配置环境变量：

ALIYUN_ACCESS_KEY_ID
ALIYUN_ACCESS_KEY_SECRET
ALIYUN_SECURITY_TOKEN 可选
ALIYUN_REGION_ID 可选，默认 cn-shanghai
ALIYUN_TIMELINE_SMOKE_INPUT
ALIYUN_TIMELINE_SMOKE_OUTPUT

未配置时该测试会自动跳过。

14. 官方参考

15. 当前版本说明

这个版本已经适合做“后端混剪能力层”接入，但仍建议把下面能力放到后续版本：

OSS 上传与媒资准备
回调验签与任务状态同步
ProjectId / TemplateId 作业类型
更完整的特效 / 转场 / 模板库
更细的字幕样式字段映射

xxm_yajie / aliyun-timeline-sdk

Maintainers

Package info

Statistics

Security