功能概览
剪同款能够实现一键成片,通过剪同款功能接口能加载制作好的模板,用户添加视频或图片能实现音乐卡点及炫酷转场视频。
相关接口类
接口类名 | 描述 |
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() {@Overridepublic void onGenerateStarted() { }@Overridepublic void onGenerateProgress(float progress) { }@Overridepublic void onGenerateCompleted(TAVEditorGenerateResult result) { }@Overridepublic void onGenerateCanceled() { }});} else {// 处理错误switch (result) {case -1:Log.e("Template", "无效的模板路径");break;case -2:Log.e("Template", "模板授权无效");break;}}// 9. 离开编辑页时释放editor.release();
错误处理指南
错误代码 | 含义 | 解决方案 |
-1 | 路径无效。 | 检查路径是否存在且有读取权限。 |
-2 | 授权无效。 | 检查模板授权文件是否有效。 |