帮你快速理解、总结文档立即下载

Android

最近更新时间:2026-11-11 21:20:00
本文档已由 AI 辅助审校
我的收藏

功能概览

剪同款能够实现一键成片,通过剪同款功能接口能加载制作好的模板,用户添加视频或图片能实现音乐卡点及炫酷转场视频。

相关接口类

接口类名
描述
TAVTemplateEditor
剪同款编辑入口类(已由 TAVEditor 替换为 TAVTemplateEditor)。
TAVTemplateConfig
模板配置信息类。
TAVReplaceItem
模板中可替换素材的描述。
TAVTextReplaceItem
文字类型替换项(TAVReplaceItem 子类)。
说明:
剪同款场景统一使用 TAVTemplateEditor:通过 TAVMagicFactory.createTemplateEditor() 创建;TAVMagicFactory.createEditor() 返回的 TAVEditor 用于普通短视频编辑。

创建剪同款编辑器

// 剪同款入口
TAVTemplateEditor editor = TAVMagicFactory.createTemplateEditor();

// 初始化预览(必须在其它接口之前调用)
editor.initWithPreview(previewParam);
initWithPreview 的两个关键参数:
videoView:预览容器(FrameLayout),传 null 为离屏渲染。
scene:SCENE_PLAY(创建渲染链、可上屏)或 SCENE_EXPORT(仅保留编辑信息,用于导出)。

剪同款主链路

剪同款编辑的完整调用顺序(全部由 TAVTemplateEditor 承载):
步骤
操作
接口
1
创建编辑器。
TAVMagicFactory.createTemplateEditor()
2
初始化预览。
initWithPreview(TAVEditorConstants.PreviewParam)
3
设置模板目录。
setTemplateDir(String path) → 0 / -1 / -2
4
读取模板配置。
getTemplateConfig(String templatePath) → TAVTemplateConfig
5
填充素材。
addVideoClip / addImageClip / setClipRange
6
替换模板素材。
getReplaceItems() → replaceItem(TAVReplaceItem)
7
刷新与播放。
flushImmediately() / startPlay()
8
导出成片。
generateVideo(int level, String path, listener) 或 fork() 后离屏导出
9
释放。
release()

剪同款相关方法

设置模板路径

/**
* 设置模板路径
*
* @param path 模板目录绝对路径
* @return 操作结果代码:
* 0: 成功
* -1: 路径无效
* -2: 授权无效
*/
int setTemplateDir(String path);

获取模板路径

/**
* 获取当前设置的模板路径
*
* @return 模板目录的绝对路径
*/
String getTemplateDir();

获取模板配置

/**
* 获取模板配置信息
*
* 通常在 setTemplateDir 成功后调用,用于读取模板的坑位数量、媒体类型限制(视频/图片/混合)、每个坑位的时长要求等
* 以便在添加媒体资源前做合法性校验。该方法不会返回 null,路径无效时的具体结果取决于底层模板解析
*
* @param templatePath 模板路径
* @return 模板配置对象
*/
TAVTemplateConfig getTemplateConfig(String templatePath);

获取可替换素材列表

/**
* 获取模板中可替换的素材列表
*
* 遍历当前模板中所有支持替换的素材,通过 TAVReplaceItem#type 区分类型
*
* @return 可替换素材列表
*/
List<TAVReplaceItem> getReplaceItems();
TAVReplaceItem 字段:
字段
类型
说明
id
int
素材唯一标识,替换时用于定位。
type
TAVEditorConstants.TAVReplaceType
替换类型,当前仅 TEXT。
timeRange
TAVTimeRange
该素材在时间轴上的区间。
screenTransform
ScreenTransform
Light Entity 的定位组件,SDK 内部用于计算 renderRect。
renderRect
RectF
该素材在预览容器坐标系下的包围矩形(像素),可直接用于绘制高亮框。

替换模板素材

/**
* 替换模板中指定素材的内容
*
* 根据 TAVReplaceItem#id 定位目标素材,按 type 执行对应替换逻辑:
* TEXT:传入 TAVTextReplaceItem,替换文字内容
*
* @param item 替换素材信息,需先通过 getReplaceItems() 取到再修改内容后传入
*/
void replaceItem(TAVReplaceItem item);
文字替换示例(editor 为上文创建的 TAVTemplateEditor 实例):
for (TAVReplaceItem item : editor.getReplaceItems()) {
if (item.type == TAVEditorConstants.TAVReplaceType.TEXT) {
TAVTextReplaceItem textItem = new TAVTextReplaceItem(
item.id, item.type, "新的文案", item.timeRange);
editor.replaceItem(textItem);
}
}

设置预览分辨率(剪同款专用)

/**
* 设置剪同款模式下的预览分辨率(像素)
*
* 不调用时 SDK 按设备等级最大长边 + 9:16 自动计算
* 建议在添加资源前调用,避免渲染链重建
* 剪同款固定 9:16 竖屏,非该比例的入参会按「长边对齐」换算:
* 取较大值为长边,短边按 9:16 重算后四舍五入并调整为偶数。例如 (1080, 1080) → (608, 1080)。
*/
void setRenderSize(int width, int height);

派生独立编辑器

/**
* 基于当前模板编辑状态创建一个独立的 TAVTemplateEditor
*
* 返回实例保留当前模板、素材、裁剪、音量及文字替换状态
* 传入 SCENE_EXPORT 可创建仅用于导出的离屏实例
* 返回实例由调用方负责 release()
*
* @param param 预览参数;传 null 时创建默认离屏实例
* @return 独立编辑器;编辑状态尚未就绪或已释放时返回 null
*/
TAVTemplateEditor fork(TAVEditorConstants.PreviewParam param);

TAVTemplateEditor 其余能力

以下方法与 TAVEditor 同名同签名,实现细节见 API 文档对应章节:
分类
方法
素材
addVideoClip、addImageClip、getClipCount、removeClip、setClipRange、setClipRect、setVideoClipVolume、setAllClipsVolume、getVideoClipVolume、setVideoClipSpeed、getVideoClipSpeed、getVideoInfo
播放
startPlay、setPlayTimeRange、resumePlay、pausePlay、getTotalDuration、isPlaying、seekToTime
刷新
flushImmediately()、flushImmediately(String tag, TAVConsumer<String> callback)
导出
generateVideo(int level, String path, listener)、generateVideo(TAVEditorGenerateConfig, String path, listener)、cancelGenerate
其它
getThumbnailProvider、setVideoPreviewListener、getRenderSize、release
注意:
TAVTemplateEditor 不包含 BGM 精细编辑、滤镜、动效、转场、贴纸、画中画、草稿等接口,这些能力仍由 TAVEditor 提供;剪同款模板内的音视频、转场等由模板 JSON 驱动。

TAVTemplateConfig 结构说明

TAVTemplateConfig 的公开字段:
字段
类型
说明
mediaType
TAVMediaType
模板兼容的媒体类型(视频 / 图片 / 混合)。
minAssetCount
int
模板可填充素材数量的下限。
maxAssetCount
int
模板可填充素材数量的上限。
clipPlaceHolders
TAVClipPlaceHolder[]
视频/图片坑位列表,contentDuration 为每个坑位要求的素材时长(微秒)。
audioPlaceHolders
TAVAudioPlaceHolder[]
音频(背景音)坑位列表。
说明:
坑位信息通过 clipPlaceHolders 与 audioPlaceHolders 两个数组字段读取。

使用示例

// 1. 创建剪同款编辑器并初始化预览
TAVTemplateEditor editor = TAVMagicFactory.createTemplateEditor();
editor.initWithPreview(previewParam);

// 2. 设置模板路径
int result = editor.setTemplateDir(context.getFilesDir() + "/templates/project1");
if (result == 0) {
// 3. 获取模板路径与配置
String templateDir = editor.getTemplateDir();
TAVTemplateConfig config = editor.getTemplateConfig(templateDir);

// 4. 读取坑位信息
TAVMediaType mediaType = config.mediaType;
int minCount = config.minAssetCount;
int maxCount = config.maxAssetCount;

TAVClipPlaceHolder[] clipHolders = config.clipPlaceHolders;
for (TAVClipPlaceHolder holder : clipHolders) {
long contentDuration = holder.contentDuration; // 该坑位要求的素材时长(微秒)
}

// 5. 按坑位填充素材
editor.addVideoClip(context.getFilesDir() + "/a.mp4");
// TAVTemplateEditor 不兜底 duration:传 0 或负数时图片时长为 0,需显式传入坑位要求时长
editor.addImageClip(context.getFilesDir() + "/b.jpg", clipHolders[1].contentDuration);
editor.flushImmediately();

// 6. 替换模板中的文字
for (TAVReplaceItem item : editor.getReplaceItems()) {
if (item.type == TAVEditorConstants.TAVReplaceType.TEXT) {
editor.replaceItem(new TAVTextReplaceItem(
item.id, item.type, "新的文案", item.timeRange));
}
}

// 7. 启动播放
editor.startPlay();

// 8. 导出成片
editor.generateVideo(TAVEditorConstants.VIDEO_LEVEL_720P,
context.getFilesDir() + "/out/template.mp4", new TAVEditorGenerateListener() {
@Override
public void onGenerateStarted() { }

@Override
public void onGenerateProgress(float progress) { }

@Override
public void onGenerateCompleted(TAVEditorGenerateResult result) { }

@Override
public void onGenerateCanceled() { }
});
} else {
// 处理错误
switch (result) {
case -1:
Log.e("Template", "无效的模板路径");
break;
case -2:
Log.e("Template", "模板授权无效");
break;
}
}

// 9. 离开编辑页时释放
editor.release();

错误处理指南

错误代码
含义
解决方案
-1
路径无效。
检查路径是否存在且有读取权限。
-2
授权无效。
检查模板授权文件是否有效。