短视频 SDK Android（预览与导出）

三、初始化预览

// 通过 TAVMagicFactory 创建编辑器实例TAVEditor editor = TAVMagicFactory.createEditor();TAVEditorConstants.PreviewParam param = new TAVEditorConstants.PreviewParam();param.videoView = frameLayout; // 预览容器，为null时会进行离屏渲染param.loopPlay = true; // 循环播放param.autoPlay = true; // 自动播放// 使用场景：// SCENE_EXPORT 只保留编辑信息不创建渲染链，也无法进行预览；通常需要配合fork接口离开编辑页面执行导出逻辑时使用，例如Tiktok的发布页面导出视频并上传// SCENE_PLAY 创建渲染链可以正常上屏预览；通常在编辑页面使用param.scene = TAVEditorConstants.SCENE_PLAY;editor.initWithPreview(param);

四、剪同款预览

如果不需要此功能可跳过该步骤，直接进行短视频制作预览。

注意：说明：

注意：剪同款场景使用 TAVTemplateEditor（TAVMagicFactory.createTemplateEditor()），不要用上面的 TAVEditor。

// 创建剪同款编辑器并初始化预览（参数同上）TAVTemplateEditor templateEditor = TAVMagicFactory.createTemplateEditor();templateEditor.initWithPreview(param);// 设置模板路径int ret = templateEditor.setTemplateDir("模板路径");// 获取模板配置TAVTemplateConfig config = templateEditor.getTemplateConfig("模板文件夹路径");// 兼容的媒体格式 VIDEO（视频） PHOTO（图片） MULTI（混合）TAVMediaType mediaType = config.mediaType;// 可填充的数量限制TAVClipPlaceHolder[] clipHolders = config.clipPlaceHolders;// 每个坑位要求的素材时长（微秒）long firstHolderDuration = clipHolders[0].contentDuration;// 剪同款模式下，选择的视频源时长应该大于等于对应的TAVClipPlaceHolder的播放时长// 根据模板需要的媒体格式添加一个或多个媒体源// 添加视频作为媒体源templateEditor.addVideoClip("视频文件路径");// 设置播放区间，播放时长需要和TAVClipPlaceHolder的时长保持一致templateEditor.setClipRange(0, 0, clipHolders[0].contentDuration);// 添加图片作为媒体源templateEditor.addImageClip("图片文件路径", clipHolders[1].contentDuration);// 刷新当前帧让资源生效templateEditor.flushImmediately();

五、短视频剪辑预览

// 添加视频资源editor.addVideoClip("视频路径");// 添加3s的图片资源editor.addImageClip("图片路径", 3000000);// 刷新当前帧让资源生效editor.flushImmediately();

注意：说明：

注意：TAVTemplateEditor.addImageClip 不兜底 duration：传0或负数时图片时长为0；TAVMagicFactory.createEditor() 返回的 TAVEditor 则会按3秒兜底。

七、刷新机制

想让你设置的资源生效，需要调用 flushImmediately 即可刷新当前帧让效果上屏。

/** * 立即刷新 */ void flushImmediately(); /** * 立即刷新 * * @param tag 当前刷新操作tag * @param callback 需要在刷新后执行的任务 */ void flushImmediately(@Nullable String tag, @Nullable TAVConsumer<String> callback);

八、设置画布尺寸

通过 setRenderSizeRatio 接口设置宽/高比，SDK 会根据设备等级支持的最大分辨率和接口设置的宽高比自动计算实际的分辨率。

/** * 设置画布大小属性，此处需要传入的宽高实际上是宽高比，内部并不会直接使用此处传入的宽高作为画布的最终宽高 * * @param width 画布比例宽度 * @param height 画布比例高度 */ void setRenderSizeRatio(int width, int height); /** * 获取当前预览使用的渲染大小 * * @return 渲染大小 */ Size getRenderSize();

九、复制一个渲染实例

/** * 从当前编辑对象创建一个实例 * * @param param param.videoView = null 创建可编辑的离屏实例（有渲染链） * param.videoView != null 创建可编辑的上屏实例（有渲染链） * param = null 创建可编辑的默认离屏实例（有渲染链） * param != null 根据param.scene选择是否创建渲染链 * @return TAVEditor */ TAVEditor fork(@Nullable TAVEditorConstants.PreviewParam param);

十、释放资源

离开编辑页面时，需要调用 release()方法来销毁 editor 释放编辑资源。

十二、添加及删除媒体资源

/** * 向末尾添加一个视频资源 * * @param path 视频路径 * @return 返回成功添加后的索引 */ int addVideoClip(String path); /** * 指定位置添加编辑视频 * * @param clipIndex 添加的位置 * @param paths 编辑的视频源路径 * @return 返回成功添加后的索引 */ int addVideoClip(int clipIndex, List<String> paths); /** * 向末尾添加一张图片资源 * * @param path 编辑的图片源路径 * @param duration 时长，小于等于0会默认使用3s时长 * @return 返回成功添加后的索引 */ int addImageClip(String path, long duration); /** * 指定位置添加图片资源 * * @param clipIndex 添加的位置 * @param paths 编辑的图片源路径 * @param duration 时长，小于等于0会默认使用3s时长 * @return 返回成功添加后的索引 */ int addImageClip(int clipIndex, List<String> paths, long duration); /** * 获取当前正在编辑的资源数量 * * @return 资源数量 */ int getClipCount(); /** * 移除指定位置的视频或者图片资源 * * @param clipIndex 资源下标 */ void removeClip(int clipIndex);

十三、修改媒体资源

/** * 修改指定资源的时长 * 对于视频资源startTime和endTime会根据视频本身截取一个播放区间 * * @param clipIndex 资源下标 * @param startTimeUs 资源播放的开始时间 * @param endTimeUs 资源播放的结束时间 */ void setClipRange(int clipIndex, long startTimeUs, long endTimeUs); /** * 设置指定资源背景音量 * * @param clipIndex 资源下标 * @param volume 音量，建议0-3f，1是原声音量 */ void setVideoClipVolume(int clipIndex, float volume); /** * 设置所有资源背景音量 * * @param volume 音量，建议0-3f，1是原声音量 */ void setAllClipsVolume(float volume); /** * 根据资源下标获取音量 * * @param clipIndex 资源下标 * @return 音量 */ float getVideoClipVolume(int clipIndex); /** * 调整视频播放速度 * * @param clipIndex 视频下标 * @param speed 播放速度 */ void setVideoClipSpeed(int clipIndex, float speed); /** * 根据资源下标获取播放速度 * * @param clipIndex 资源下标 * @return 播放速度 */ float getVideoClipSpeed(int clipIndex); /** * 调整资源下标 * * @param oldClipIndex 调整前下标 * @param newClipIndex 调整后下标 * @return 调整结果 */ boolean updateClipIndex(int oldClipIndex, int newClipIndex); /** * 设置裁剪区域 * * @param clipIndex 视频索引 * @param rectF 相对于渲染尺寸归一化的裁剪区域 */ void setClipRect(int clipIndex, RectF rectF); /** * 设置旋转角度（顺时针旋转） * * @param clipIndex 视频索引 * @param degrees 旋转角度 */ void setClipRotation(int clipIndex, @FloatRange(from = 0, to = 360f) float degrees);

十五、播放状态管理

// 开始播放void startPlay();// 暂停播放void pausePlay();// 继续播放void resumePlay();// 检查播放状态boolean isPlaying();

十六、播放进度控制

// 获取总时长（微秒）long getTotalDuration();// 跳转到指定位置void seekToTime(long timeUs, boolean isInAccurate);// 设置播放区间（duration 为持续时长，不是结束时间）void setPlayTimeRange(long startTime, long duration);

十七、导出操作

注意：说明：

注意：剪同款成片导出请调用 TAVTemplateEditor.generateVideo(…)（签名与 TAVEditor 一致，见 剪同款预览 一节的 templateEditor 实例）；TAVEditor.generateVideo 用于普通短视频编辑导出。

十八、快速导出

// 导出等级常量：等级决定输出短边，长边按画面比例计算TAVEditorConstants.VIDEO_LEVEL_480P; // 短边 480TAVEditorConstants.VIDEO_LEVEL_540P; // 短边 540TAVEditorConstants.VIDEO_LEVEL_720P; // 短边 720TAVEditorConstants.VIDEO_LEVEL_1080P; // 短边 1080editor.generateVideo(TAVEditorConstants.VIDEO_LEVEL_720P, outputPath, new TAVEditorGenerateListener() { @Override public void onGenerateStarted() { // 开始导出 } @Override public void onGenerateProgress(float progress) { // 导出进度，取值 0~1 } @Override public void onGenerateCompleted(TAVEditorGenerateResult result) { // 导出完成：result.isSucceed() 为 true 时，result.outputPath 为成片路径；失败时查看 result.code / result.msg } @Override public void onGenerateCanceled() { // 导出已取消 }});

十九、自定义导出

TAVEditorGenerateConfig config = new TAVEditorGenerateConfig();// 视频配置config.videoConfig.width = 1280;config.videoConfig.height = 720;config.videoConfig.frameRate = 30;// 音频配置config.audioConfig.sampleRate = 44100;config.audioConfig.audioBitRate = 192000;editor.generateVideo(config, outputPath, listener);

20、渲染错误诊断

TAVEditor 提供渲染侧错误回调，覆盖预览（PREVIEW）、导出（EXPORT）、封面（COVER）三类场景。该回调只做错误通知，不改变播放器状态、不重建渲染链、也不中断导出流程，适用于日志上报与线上问题定位。

21、注册监听

editor.setErrorListener(error -> { Log.w(TAG, "render error: scene=" + error.scene + ", source=" + error.source + ", code=" + error.code + ", msg=" + error.message + ", path=" + error.path);});// 不再需要时传入 null 清除监听editor.setErrorListener(null);

22、TAVEditorError 字段

23、使用建议

·仅用于错误上报与诊断，不要用它驱动 UI 状态切换或重试逻辑。

·导出失败的业务判定仍以 TAVEditorGenerateListener 的 onGenerateCompleted(TAVEditorGenerateResult) / onGenerateCanceled() 为准。

·剪同款入口 TAVTemplateEditor 未提供 setErrorListener，该场景下拿不到此回调。

24、使用示例

// 1. 初始化预览TAVEditor editor = TAVMagicFactory.createEditor();editor.initWithPreview(previewParam);// 2. 添加资源int videoIndex = editor.addVideoClip(context.getFilesDir() + "/video.mp4");int imageIndex = editor.addImageClip(context.getFilesDir() + "/image.jpg", 3_000_000);// 3. 配置资源TAVVideoInfo info = editor.getVideoInfo(context.getFilesDir() + "/video.mp4");editor.setClipRange(videoIndex, 0, info.duration);editor.setVideoClipVolume(videoIndex, 0.8f);// 4. 播放控制editor.startPlay();editor.seekToTime(5_000_000, false);// 5. 导出视频editor.generateVideo(TAVEditorConstants.VIDEO_LEVEL_720P, context.getFilesDir() + "/output.mp4", listener);// 6. 释放资源editor.release();