智汇云-企业数智化核心引擎

首页> 开发者中心>SDK管理>剪辑SDK>Android>开发文档

#Android剪辑SDK接入文档

## 1. 概述
剪辑SDK是360视频云以SDK形式提供短视频剪辑服务，可以帮助开发者快速集成短视频剪辑能力。

### 1.1 产品特点
**支持多轨道、多段编辑**

* 支持同时导入不同格式的视频、图片，进行多段混剪
* 支持多轨道，能够满足画中画、分屏、配音等多种玩法

**支持多种输入、输出样式**

支持多种格式、多种分辨率的输入素材，素材既可以是本地的也可以是云端url地址，同时开发者可以根据需求自定义输出分辨率。

**制作效果实时预览**

通过预览播放器可以在制作过程中实时预览制作效果，大大提高了制作体验，节省了制作成本和时间。

**丰富的基础编辑功能**

剪辑SDK包含丰富的基础编辑功能，开发者可以根据自己的需求灵活组合使用。

**支持自定义特效**

特效完全插件化，开发者还可以根据需要扩展自定义特效。

### 1.2 版本功能

|功能点(标准/商业版版) | 标准版 |商业版 |
|-------------------|-------|------|
|文件导入（图片、视频）|    √    | √
|合成导出    | √ | √
|预览播放器 | √    | √
|移序    | √    | √
|删除    | √    | √
|云端url剪辑    | √ | √
|音视频分离    | √ | √
|背景音乐    | √ | √
|画中画 | √    | √
|转场（基础）| √ |     √
|缩略图 | √    | √
|渲染模式 |    √    | √
|背景样式(颜色、图片、毛玻璃)    | √| √
|输出码率    | √    | √
|输出分辨率|    √    | √
|输出帧率    | √ | √
|调节音量    | √ | √
|旋转    | √ | √
|镜像    | √ | √
|画面裁剪    | √ | √
|缩放    | √ | √
|变调    | √ | √
|文件变速(变速不变调、变速变调)    | √ | √
|特效-画中画混合模式 |    × | √
|特效-静态字幕 | √    | √
|特效-静态贴纸 |√ | √
|特效-滤镜（基础）| √    | √
|特效-单色调色| √    | √
|特效-二维码、水印 | √    | √
|转场特效（高级）| × | √
|特效-画质 | ×    | √
|特效-字幕、视频、图片关键帧动画 | √ | √ 
|动态贴纸| √ | √
|特效-动态字幕（Ass字幕）| × | √ 
|特效-字幕、视频、图片支持AE轨迹 | √ | √
|特效-变焦（kenburns）| × | √
|特效-马赛克 | √ |    √
|特效-去水印    | × | √
|特效-动效（抖音式特效）| × | √
|音频波形图 | √ | √
|特效-音乐动效（缓入缓出、淡入淡出）| √ | √

|工具 | 标准版 |商业版 |
|-----------|-------|------|
|生成倒放文件    | √ | √
|vp8 webm透明格式文件生成    | √ | √
|生成gif文件    | √ | √
|生成滤镜缩略图    | √ | √

## 2. 功能说明

### 2.1 核心功能说明

| 功能 | 说明 |
| --- | --- |
| 多段合并 | 将多段视频素材拼接一个文件，并且支持剪切头部尾部冗余内容|
| 画面变化 | 对视频画面进行裁剪、旋转、缩放、镜像、添加背景等操作|
| 缩略图 | 实时获取文件缩略图，精确到帧画面，方便剪辑预览 |
| 背景音乐 | 添加背景音乐与原音进行实时混合 |
| 音量调节 | 无级调节音量大小，同时支持添加缓入缓出循序渐进效果|
| 画中画 | 多层画面叠加实现画中画的效果，例如分屏、9宫格画面 |
| 转场 | 相邻文件衔接处添加转场效果，为客户提供60余种效果进行选择 |
| 倍速 | 无级慢速、快速调节，支持1/8-8倍速 |
| 变声 | 调节音调，实现不同的声音效果，例如男声变女声 |
| 字幕、贴纸、水印 | 添加字幕、贴纸、水印丰富视频内容 |
| 滤镜 | 添加不同lut快速替换风格，支持自定义 |

### 2.2 核心模块说明

剪辑SDK主要分为几个模块，分别为：时间线、特效、预览播放器、合成器。其中时间线内包含音/视频轨道，轨道内包含文件素材，特效。

#### 2.2.1 时间线（Timeline）

* 时间线是所有剪辑事件按照时间先后顺序排列的集合，也是所有剪辑事件在时间上的体现。时间线的长短和最终合成输出的文件时间一一对应，时间线时长即代表最终合成输出文件的时长。

* 理论上，同时可以存在多个时间线实例对象，但对大多数产品来说，同一时间存在一个时间线实例对象即可。

* 添加在时间线上的特效不会随着轨道内容的变化而变化。当时间线被删除时，时间线内的所有内容都会被删除。

|参数          |说明                                        |
|-------------|--------------------------------------------|
|输出分辨率     |必填，预览和合成都需参考                       |
|输出帧率      |默认30帧，预览和合成都会参考                    |
|输出码率      |默认按输出分辨率自动匹配合适码率                 |
|输出文件路径   |合成输出文件路径                              |
|视频帧填充样式 |默认黑边填充                                  |
|视频背景样式   |默认填充黑色背景，仅在视频帧填充样式为背景填充时生效|
|时间线时长    |以时间线内所有轨道结束时间点最大值为结束时间点      |
|倍速         |影响所有素材、特效渲染速度                       |
|音量         |原声的百分比音量，影响所有素材、特效音量           |

|功能             |说明                           |
|------------------|------------------------------|
|初始化||
|释放|会清除所有参数/配置|
|添加轨道||
|删除轨道|根据轨道id删除某轨道|
|获取轨道信息|支持获取单个/所有轨道信息|
|添加时间线特效|位于轨道特效之后处理|
|删除时间线特效|根据特效id删除某特效|
|修改时间线特效|根据特效id修改某特效属性|
|获取时间线特效|支持获取单个/所有时间线特效信息|

#### 2.2.2 轨道（Track）

* 轨道分为顺序轨道和画中画轨道。

* 轨道上可添加、删除、获取文件片段。同一轨道上素材持续时间段不可叠加。添加在轨道上的特效不会随着轨道内素材的变化而变化。当轨道被删除时，添加在轨道上的轨道特效会跟着删除。

* 如果要实现画中画，可以添加两条视频轨道。音频轨道一般用来给视频添加音乐或者配音功能。

* 相邻文件间可以添加转场效果。若素材上已添加转场效果，需先移除转场效果再修改插入时间点。

|参数          |说明                                        |
|-------------|--------------------------------------------|
|轨道ID        |轨道唯一标识                                      |
|轨道类型       |音频或视频                                      |
|轨道排序类型   |顺序轨道/自由轨道                             |
|渲染层级       |默认按轨道ID从小到大顺序渲染                   |
|倍速          |影响轨道上所有素材、特效渲染速度                 |
|音量          |原声的百分比音量，影响轨道上素材、特效音量        |
|渲染信息       |批量设置轨道内clip的渲染信息: 填充样式、背景样式等|
|轨道时长       |以轨道内最后一个文件的结束时刻为结束时间点        |

|轨道排序类型 |功能               |说明                 |
|-----------|------------------|--------------------|
| 顺序轨道    |初始化|依赖时间线对象
|           |释放|会清除轨道上所有参数/配置|
|           |更新素材属性||
|           |根据素材id删除某素材||
|           |获取素材信息|支持获取单个/所有素材信息|
|           |添加素材至轨道末尾||
|           |在指定索引位置插入素材||
|           |移动素材至指定索引位置|素材属性/配置会一起移动|
|           |删除指定索引位置的素材||
|           |获取指定索引位置素材信息||
|           |添加转场|支持设置转场位置、持续时长、样式等|
|           |更新转场属性|支持修改转场位置、持续时长、样式等
|           |删除转场||
|画中画轨道   |添加素材至指定时刻|时刻为相对Timeline的时刻|
|           |修改某素材的插入时刻|时刻为相对Timeline的时刻|

#### 2.2.3 素材片段（Clip）

当素材被删除时，添加在素材上的素材特效会跟着删除。

|参数          |说明                                        |
|-------------|--------------------------------------------|
|素材ID        |素材唯一标识                                      |
|素材类型       |图片、音/视频等                              |
|素材路径      |本地文件                           |
|片段裁剪入点  |素材相对于物理文件的开始时间点，图片文件可不填      |
|片段裁剪出点   |素材相对于物理文件的结束时间点，图片文件可不填     |
|插入时间点    |只读，相对于Timeline，素材插入轨道的时刻         |
|倍速          |影响轨素材及素材特效的渲染速度                  |
|音量          |原声的百分比音量，影响素材及素材特效的音量        |
|音调          |在原声的基础上改变音调，默认为0，变调范围-12~12  |
|水平镜像       |默认不镜像                                  |
|垂直镜像       |默认不镜像                                  |
|裁剪区域       |相对源素材的裁剪区域，默认为源素材大小，原点对齐   |
|渲染信息       |默认同track样式，clip和track都设置该属性时按clip属性生效|

|功能             |说明                           |
|------------------|------------------------------|
|初始化             |依赖时间线对象
|添加素材特效        ||
|删除素材特效        |根据特效id删除某特效|
|修改素材特效        ||
|获取素材特效        |支持获取单个/所有特效信息|

#### 2.2.4 特效（Effect）

* 特效是特效的载体，可以针对素材片段、轨道或者时间线添加、获取、删除，特效分为音、视频特效。
* 每个特效包含不同的自有属性，通用属性如下：

|参数          |说明                                        |
|-------------|--------------------------------------------|
|特效ID        |特效唯一标识|
|特效类型      |视频特效、音频特效、图层混合特效|
|开始时间点     |相对被添加对象的开始时间点|
|结束时间点     |相对被添加对象的结束时间点|

#### 2.2.5 预览播放器（Player）

* 预览播放器和传统播放器相比，具备实时预览效果，所有添加的特效都可以通过预览播放器实时渲染。
* 预览过程中，特效并没有真正添加进源素材文件内。

|功能             |说明                           |
|------------------|------------------------------|
|初始化             |依赖时间线对象|
|释放              | |
|是否处于播放状态    | |
|设置预览画布        | |
|重置播放器         | 播放器初始化后有文件操作均需重置播放器|
|刷新播放器         | 添加特效后实时预览更新效果|
|播放              | |
|停止              | |
|跳转至某个时间点    | |
|获取当前时间戳      | |
|获取当前视频帧      |若添加特效，视频帧为特效处理后的效果|
|错误回调           | |
|播放完成回调        | |
|首帧渲染回调        | |

|需重置播放器的场景：       |
|-----------------------|
|添加、删除轨道           |
|添加、删除素材           |
|变速                    |
|变调                    |
|添加、删除转场，修改转场时长|

|需刷新播放器的场景：      |
|-----------------------|
|修改转场样式、缓动函数类型 |
|添加、删除、修改特效|

#### 2.2.6 合成器（Producer）

* 合成器会读取素材文件，并按特效指令处理素材文件，最终按照配置合成新的媒体文件。

|功能             |说明                           |
|------------------|------------------------------|
|初始化             |依赖时间线对象
|释放              ||
|设置输出地址        ||
|开始合成           || 
|停止合成           |用于打断操作                    |
|合成状态           |进度、状态                      |

#### 2.2.7 缩略图

* 辅助功能，用来获取源素材某个时刻或某段时间内的缩略图。

|功能             |说明                             |
|------------------|---------------------------------|
|初始化             ||
|释放              |会清除临时文件
|批量获取缩略图      |获取文件某时间段内任意数量任意尺寸缩略图|
|获取单张缩略图      |获取文件某时刻任意尺寸缩略图         |

## 3. 接入说明

### 3.1 输入输出规范

**输入规范：**

* 视频格式：MP4、MOV、WMV、M2V、MPG等
* 音频格式：MP3、FLAC、AAC、M4A
* 图片格式：JPG、PNG
* 视频编码：H264、H265、WMV、MPEG4等
* 音频编码：MP3、AAC、PCM、FLAC等

**输出规范：**

* 视频格式：MP4
* 视频编码：H264
* 音频编码：AAC

### 3.2 运行环境

系统版本：Android 4.1 及以上

请在真机上运行，暂不支持模拟器版本

### 3.3  SDK说明
SDK包含如下文件：
* jar:

qhvc_videoedit_sdk.jar
      qhvc_tools_sdk.jar

* so:

libtranscore.so 
      libvideoeditor.so

### 3.4  配置说明
将qhvc_videoedit_sdk.jar和qhvc_tools_sdk.jar放到工程的libs目录下，在build.gradle中配置：
```code
dependencies {
    compile fileTree(include: ['*.jar'], dir: 'libs')
}
```

将libtranscore.so和libvideoeditor.so放到工程src/main/jniLibs/armeabi-v7a/目录下，在build.gradle中配置：
```code
android {
    defaultConfig {
        ndk {
            // 设置支持的CPU架构，目前只支持armeabi-v7a架构（该架构兼容armeabi、arm64-v8a、x86、x86_64架构）
            abiFilters 'armeabi-v7a'
        }
    }
}
```

#### 权限配置
在AndroidManifest.xml文件中申请相应权限：
```code
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

```
### 3.5  SDK初始化

需要调用`QHVCSdk.getInstance().init()`，接口说明如下：

appId(也叫businessId)是为业务分配的业务ID（appId获取地址：登录[视频云官网](https://zyun.360.cn/)-控制台-SDK-应用管理-新建应用）【见下图】；version为业务端APP的版本号；machineId为设备唯一标识；uid为业务方用户标识，只要保证唯一即可。
![创建AppId截图](http://p5.qhimg.com/t011da35ea7b6063845.png)

[点此查看应用ID](https://zyun.360.cn/console/sdk/application)

> 对appId和channelID这两个参数的引入，在设计之初目的是为了每个业务有独立的ID，通过appId来获取云端的一些参数控制，特别是视频缓冲策略、P2P行为、硬解码黑白名单以及解码库类型；channelID更多的为数据统计打点的唯一标注，可以通过云点播和云直播的服务标识来获取，以此获取播放数据反馈。UserID的设计是为了业务方和视频云唯一的沟通桥梁，只要保持唯一即可，一般为用户ID的加密字符串，通过UserID可以排查到一个用户的级别的失败日志；

```
QHVCSdkConfig.Builder builder = new QHVCSdkConfig.Builder(this)
        .setAppId("businessId")
        .setAppVersion("version")
        .setMachineId("machineId")
        .setUserId("uid");

QHVCSdk.getInstance().init(builder.build());

```

### 3.6  APPID合法性验证

需要调用 `public int validityCheck(String appId, String authorization, long authTime, int randomNum, final QHVCAppAuth.ResultCallback<String> callback)`，接口说明如下：

合法性验证需要用到appId, Access Key(简称AK)和Secret Key(简称SK)。AK、SK获取地址： 登录[视频云官网](https://zyun.360.cn/)-用户中心-秘钥管理【见下图】。
只有appId、Access Key以及Secret Key相匹配，才能通过鉴权，否则将无法正常使用SDK。
![秘钥获取](http://p2.qhimg.com/t0146c3d44e71ae7a62.png)

[点此查看秘钥](https://zyun.360.cn/console/usercenter/accesskey)

==注意：此接口必须在启动APP后120秒内调用，否则将无法正常使用SDK。==

appId使用和SDK初始化时同样的内容，callback可以用来监听合法性验证结果。 计算authorization时需要使用AK、SK以及当前系统的时间戳和随机数。
**为了保证AK、SK的安全，请业务接入时，务必把AK和SK存储在服务端，并且把authorization的计算也放在服务端来做。**

计算authorization的示例代码如下：

```
    private void videocloudValidCheck() {
        int randomNum = new Random(100000000).nextInt(); //随机数
        long authTime = System.currentTimeMillis() / 1000; //时间戳 (unix时间戳（10位）)

//TODO 为了保证ak、sk的安全，请业务接入时，务必把AK和SK存储在服务端，并且把authorization的计算也放在服务端来做。
        String authorization = getServerAuthorization(appId, AK, SK, randomNum, authTime);

QHVCSdk.getInstance().validityCheck(appId, authorization, authTime, randomNum, new QHVCAppAuth.ResultCallback<String>() {

@Override
            public void onSuccess(String data) {
                Logger.i(TAG, "validityCheck onSuccess, data: " + data);
            }

@Override
            public void onFailed(int errCode, String errMsg) {
                Logger.e(TAG, "validityCheck onFailed, errCode: " + errCode + ", errMsg: " + errMsg);
            }
        });
    }

private String getServerAuthorization(String appID, String ak, String sk, int randNum, long authTime) {
        HashMap<String, String> mapParams = new HashMap<>();
        mapParams.put("appid", appID);

String strParams = getParams(mapParams);
        String paramSign = makeParamSign(strParams, randNum);
        String authString = ak + "\n" + authTime + "\n" + randNum + "\n" + paramSign;
        String encryptString = null;
        try {
            encryptString = encryptHMAC(authString, sk);
        } catch (Exception e) {
            e.printStackTrace();
        }
        Logger.i(TAG, "apiAuth(), encryptString: " + encryptString);
        return ak + ":" + encryptString;
    }

private String getParams(Map<String, String> mapParams) {
        String strParams;
        if (mapParams == null || mapParams.isEmpty()) {
            strParams = "";
        } else {
            StringBuilder sbParams = new StringBuilder();
            Object[] key_arr = mapParams.keySet().toArray();
            Arrays.sort(key_arr);/*key升序排列*/
            for (Object key : key_arr) {
                String value = mapParams.get(key);
                if (!TextUtils.isEmpty(value)) {
                    sbParams.append("&").append(key).append("=").append(value);
                }
            }
            strParams = sbParams.substring(1);
        }
        return strParams;
    }

private String makeParamSign(String param, int randNum) {
        return MD5.encryptMD5(MD5.encryptMD5(param) + randNum);
    }

public String encryptHMAC(String data, String key) throws Exception {
        final String KEY_MAC = "HmacSHA1";
        SecretKey secretKey = new SecretKeySpec(key.getBytes(), KEY_MAC);
        Mac mac = Mac.getInstance(KEY_MAC);
        mac.init(secretKey);
        byte[] rawHmac = mac.doFinal(data.getBytes());
        return Base64.encodeToString(rawHmac, Base64.DEFAULT);
    }
```

相关错误码：

```
int AUTH_OK = 1;                  //鉴权成功
int AUTH_FAILED = -11001;         //鉴权未通过（鉴权失败）
int AUTH_NOT_INVOKED = -11002;    //未调用鉴权接口
```
### 3.7  使用流程

实现视频编辑的一般步骤：

1. 配置app信息(SDK初始化和APPID合法性验证)
1. 创建时间线
2. 添加轨道
3. 添加文件片段
4. 添加特效
5. 添加实时预览播放器
6. 合成媒体文件

其中，6、7顺序可颠倒，实时预览、合成器均可单独使用。

![image](https://p3.ssl.qhimg.com/t014f4d90ecf2fb0386.png)

### 3.8 注意事项
1. 剪辑基础版功能均为免费，使用前需在云平台配置应用信息
2. 剪辑SDK内所有时间单位均为毫秒

## 4. 代码示例

### 4.1 创建时间线

时间线是剪辑SDK的入口，是剪辑SDK的上下文。在使用剪辑SDK时，需要先初始化QHVCEditTimeline类，不再使用时释放QHVCEditTimeline类对象，请务必保证不要在剪辑过程中销毁QHVCEditTimeline类对象！

**4.1.1 创建时间线**

```code
timeLine = new QHVCEditTimeLine();
```
**4.1.2 设置输出分辨率**

创建时间线时，需要预先设置输出分辨率，合成和预览效果都会依赖输出分辨率。其他输出参数可根据用户需求自定义配置。

```code
timeLine.setOutputSize(width, height);
```

**4.1.3 销毁时间线**

```code
timeLine.release();
```

### 4.2 轨道操作

轨道是文件素材（TrackClip）的载体，也就是文件列表。
视频轨道上可以添加视频、图片文件；音频轨道上能添加音频、视频文件，音频轨道上添加视频文件时只会处理音频部分。
同一轨道上的文件间不能重叠，否则后添加的文件无法添加成功。

**4.2.1 视频顺序轨道**

一般情况下创建一条视频顺序轨道作为主视频轴。顺序轨道内的素材（clip）是依次顺序排列的，轨道内素材操作依赖素材下标或素材ID来操作。

* 创建轨道

```code
sequenceTrack = new QHVCEditSequenceTrack(timeLine, QHVCEditTrack.Type.Video);
```

* 轨道添加到时间线内

```code
timeLine.addTrack(sequenceTrack);
```

**4.2.2 视频画中画轨道**

一般情况下，一个素材对应一条画中画轨道，素材可被添加至轨道任意时间点，轨道内素材操作都依赖素材ID来操作。

* 创建轨道

```code
overlayTrack = new QHVCEditOverlayTrack(timeLine, QHVCEditTrack.Type.Video);
```

* 轨道添加到时间线内

```code
timeLine.addTrack(overlayTrack);
```

**4.2.3 音频轨道**

音频轨道多用来添加背景音乐，可根据用户场景具体来定是使用顺序轨道还是画中画轨道。

* 创建轨道

```code
sequenceAudioTrack = new QHVCEditSequenceTrack(timeLine, QHVCEditTrack.Type.Audio);
```

* 轨道添加到时间线内

```code
timeLine.addTrack(sequenceAudioTrack);
```

**4.2.4 转场操作**

只有顺序轨道可以添加转场。AB两个素材间添加转场，transferIndex为B的索引, transferTime为转场持续时间, transferType为转场类型。

* 添加转场

```code
videoTransition = new QHVCEditVideoTransition();
videoTransition.setClipIndex(transferIndex);
videoTransition.setDuration(transferTime);
videoTransition.setType(transferType);
sequenceTrack.addVideoTransition(videoTransition);
```

* 更新转场

```code
sequenceTrack.editVideoTransition(videoTransition);
```

* 删除转场

```code
sequenceTrack.removeVideoTransitionByIndex(transferIndex);
```

### 4.3 文件片段操作

图片、视频素材都是通过文件路径添加到轨道上的。

**4.3.1 创建素材**

```code
//初始化
sequenceClip = new QHVCEditSequenceClip(sequenceVideoTrack, QHVCEditClip.Type.Video);

//设置路径
sequenceClip.setPath(path);

//设置起止时间
sequenceClip.setStartTime(0);
sequenceClip.setEndTime(3000);

//设置文件位置索引
sequenceClip.setIndex(0);
```

**4.3.2 添加素材至轨道**

```code
sequenceTrack.addClip(sequenceClip);
```

**4.3.3 更新素材属性**

```code
sequenceTrack.editClip(sequenceClip);
```

**4.3.4 删除素材**

```code
sequenceTrack.deleteClip(sequenceClip);
```

### 4.4 特效操作

**4.4.1 创建特效**

所有特效都继承QHVCEditEffect类，不同特效有各自不同的属性，详见各效果接口说明。此处以滤镜为例。

```code
//初始化
videoEffect = new QHVCEditVideoFilterEffect(timeLine);
//设置起始时间
videoEffect.setStartTime(0);
//设置结束时间
videoEffect.setEndTime(3000);
//设置查色图文件路径
videoEffect.setPathes(path);
```

**4.4.2 添加特效**

根据用户需求，特效可被添加至时间线、轨道、素材任意时间段内。

```code
//添加至时间线
timeLine.addEffect(videoEffect);
 
//添加至轨道
track.addEffect(videoEffect);
 
//添加至素材
clip.addEffect(videoEffect);
```

**4.4.3 更新特效**

特效属性修改后，需显式更新。

```code
//时间线更新特效
timeLine.editEffect(videoEffect);

//轨道更新特效
track.editEffect(videoEffect);

//素材更新特效
clip.editEffect(videoEffect);
```

**4.4.4 删除特效**

```code
//时间线删除特效
timeline.deleteEffect(videoEffect);

//轨道删除特效
track.deleteEffect(videoEffect);

//素材删除特效
clip.deleteEffect(videoEffect);
```

### 4.5 预览播放器

预览播放器和传统播放器相比，具备实时预览效果，所有添加的特效都可以通过预览播放器实时渲染。预览过程中，特效并没有真正添加进素材文件内。

*此处仅展示预览播放器基本功能，更多功能详见播放器接口。*

**4.5.1 创建预览播放器**

预览播放器需要设置预览画布，预览播放器会根据时间线输出分辨率来处理数据帧，为保证体验，建议预览画布尺寸和输出分辨率保持相同的宽高比。

```code
//初始化
QHVCEditPlayer player = new QHVCEditPlayer(timeLine);
player.init();

//设置状态回调
player.setStateCallback(stateCallback);

//设置预览画布
player.setPreview(surface, width, height);
```

**4.5.2 释放预览播放器**

请务必保证播放器相关方法在释放前调用。

```code
player.releasePreview();
player.release();
```

**4.5.3 定位操作**

* 播放器可以seek至时间线内任意时间点，满足精确seek需求。
* 定位操作分为强制、非强制两种，强制seek保证一定会seek到请求的时间点，反之非强制seek不保证。
* 为保证体验和效率，建议多次连续seek时，尽量使用非强制seek，最后一次请求使用强制方式。

```code
player.seek(1000);
```

**4.5.4 刷新操作**

* 播放器初始化之后，若有效果变动需显式刷新播放器，例如添加、删除、修改等操作

```code
player.refresh();
```

|需刷新播放器的场景：|
|-----------------------|
|添加、删除特效|
|修改特效|
|调节音量|

**4.5.5 重置操作**

* 播放器初始化之后，若有轨道、素材相关操作需重置播放器

```code
player.reset();
```

|需重置播放器的场景：|
|-----------------------|
|添加、删除轨道|
|添加、删除、移动素材|
|变速|
|变调|
|添加、修改、删除转场|

### 4.6 合成器

合成器会读取素材文件，并按特效指令处理素材文件，最终按照配置合成新的媒体文件。
开始合成前，请务必保证合成输出文件所在目录已存在。

**4.6.1 初始化**

```code
QHVCEditProcesser processer = new QHVCEditProcesser(timeLine);
processer.init(stateCallback);
```

**4.6.2 释放**

清除合成过程中生成的缓存数据，不会清除合成输出的文件。
请务必保证所有合成操作在释放前进行。

```code
processer.release();
```

**4.6.3 开始合成**

开始合成后，会在回调函数里返回当前进度或异常。

```code
processer.export();
```

**4.6.4 取消合成**

用于合成打断操作，无需在合成结束后额外调用。

```code
processer.cancelToExport();
```

### 4.7 其他

**4.7.1 缩略图**

用于源文件抽帧操作，支持获取某个时间点，或指定任意时间段内指定数量的缩略图。

* 初始化

```code
QHVCEditVideoFileThumbnailer thumbnailer = new QHVCEditVideoFileThumbnailer(listener);
```

* 取消获取

```code
thumbnailer.cancel();
```

* 释放

会清除获取缩略图过程中的缓存数据

```code
thumbnailer.release();
```

* 获取单张

支持指定返回图的尺寸，会根据设定的尺寸按源素材尺寸等比缩放处理。

```code
thumbnailer.getVideoThumbnail(path, width, height, startTime, endTime, angle, 1, ex);
```

* 批量获取

支持指定返回图的尺寸，会根据设定的尺寸按源素材尺寸等比缩放处理。
支持指定获取任意时间段内任意个数的缩略图，会根据个数在时间段内均匀取图。
为保证体验，会多次触发回调函数及时返回缩略图。

```code
thumbnailer.getVideoThumbnail(path, width, height, startTime, endTime, angle, count, ex);
```

## 错误码

**基本状态码：**

|模块|接口名           |注释|
|:---:|---------------|---|
|基本错误码|ErrorCode|通用错误码，所有带int类型返回值的接口均返回该类型错误码|
|播放器状态码|PlayCode|预览播放器状态回调码|
|合成状态码|ProcessCode|合成状态回调码|
|缩略图状态码|ThumbnailCode|缩略图获取状态回调码|

**详细错误码：**
    
|模块| 状态码 | 注释        |
|--- |-----|------------|
|通用| -999  | 内存分配失败 |
|通用| -998  | 文件打开失败 |
|通用| -997  | 文件内容不对 |
|通用| -996  | 特效已存在 |
|通用| -995  | 特效不存在 |
|通用| -899  | 输入参数错误 |
|合成| -799  | 合成中，不能操作参数配置 |
|合成| -798  | 参数配置为空就开始合成（轨道上没有视频）|
|合成| -797  | 视频流不存在 |
|合成| -796  | 音频流不存在 |
|合成| -795  | 创建流失败   |
|合成| -794  | 没有合适的解码器 |
|合成| -793  | 解码器打开失败 |
|合成| -792  | 编码器打开失败 |
|合成| -791  | 编码失败 |
|合成| -790  | 解码失败 |
|合成| -789  | 创建特效失败 |
|合成| -788  | seek失败 |
|合成| -787  | 写文件失败 |
|合成| -786  | 填充音频失败 |
|合成| -785  | 合成内部参数错误 |
|播放器| -699  | 获取配置参数出错 |
|播放器| -698  | 打开文件失败 |
|播放器| -697  | seek失败 |
|播放器| -695  | 解码失败 |
|播放器| -694  | 连接失败 |

存储服务

AI开发平台

视觉分析

内容审核

人脸与人体识别

OCR识别

图像技术

AI市场

基础组件

视频应用

视频工具

物联网平台

网络与CDN

应用开发

研发效能

视频应用

企业工具

安全应用

云计算

大数据

容器服务

AI开发平台

视频

物联网

数据上云

IoT设备

账号体系

智慧城市

电商视频解决方案

教育

全屋智能

医疗

智能制造

游戏

SDK管理

电话咨询：

热门产品

帮助文档

服务条款

关注或联系我们

请您联系我们

小安提醒您

1对1免费 咨询智汇云专属顾问

为您量身定制产品解决方案

1对1免费咨询智汇云专属顾问