短视频 SDK Android（剪同款）

一、相关接口类

注意：说明：

注意：剪同款场景统一使用 TAVTemplateEditor：通过 TAVMagicFactory.createTemplateEditor() 创建；TAVMagicFactory.createEditor() 返回的 TAVEditor 用于普通短视频编辑。

二、创建剪同款编辑器

// 剪同款入口TAVTemplateEditor editor = TAVMagicFactory.createTemplateEditor();// 初始化预览（必须在其它接口之前调用）editor.initWithPreview(previewParam);

initWithPreview 的两个关键参数：

·videoView：预览容器（FrameLayout），传 null 为离屏渲染。

·scene：SCENE_PLAY（创建渲染链、可上屏）或 SCENE_EXPORT（仅保留编辑信息，用于导出）。

三、剪同款主链路

剪同款编辑的完整调用顺序（全部由 TAVTemplateEditor 承载）：

四、设置模板路径

/** * 设置模板路径 * * @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 字段：

八、替换模板素材

/** * 替换模板中指定素材的内容 * * 根据 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 文档对应章节：

注意：TAVTemplateEditor 不包含 BGM 精细编辑、滤镜、动效、转场、贴纸、画中画、草稿等接口，这些能力仍由 TAVEditor 提供；剪同款模板内的音视频、转场等由模板 JSON 驱动。

十二、TAVTemplateConfig 结构说明

TAVTemplateConfig 的公开字段：

注意：说明：

注意：坑位信息通过 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();

十四、错误处理指南