本文主要介绍短视频编辑 UIKit SDK 的 Android 端 API 接口文档，以便于查阅和使用。
TAVEditorUIKit
短视频编辑的一体化 UI 组件。
API | 描述 |
设置权限提供器，用于在编辑流程中处理运行时权限（如存储、麦克风等）。 | |
使用一组素材路径初始化编辑器时间线，构建工程并刷新预览与时长信息。 | |
使用已有草稿初始化编辑器，加载草稿内容并重置草稿上下文。 | |
宿主页面 onResume 时调用，根据是否需要恢复播放控制播放器恢复或刷新，并通知面板恢复。 | |
宿主页面 onPause 时调用，暂停播放器播放并通知面板暂停。 | |
判断当前播放器是否处于播放中状态。 | |
处理返回键事件，优先由面板和图层消费，返回是否已处理该返回事件。 | |
宿主销毁时调用，释放播放器相关资源并清理全局 Toast 引用等。 | |
设置素材提供器，用于 UI 内部拉取、选择或展示业务素材资源。 | |
获取预编辑层对应的 FrameLayout，用于外部在预编辑界面添加自定义视图。 | |
根据传入的枚举切换编辑层（预编辑、主编辑、全屏预览、动效编辑等）。 | |
根据传入的枚举切换功能面板（文本、配音、滤镜、贴纸等），或关闭当前面板。 | |
设置面板变化监听器，当功能面板发生切换时回调当前面板类型。 | |
设置图层变化监听器，当编辑图层发生切换时回调当前图层类型。 | |
保存当前编辑状态为草稿，返回生成的 TAVDraft 对象。 | |
获取当前的草稿对象，用于外部持久化或再次恢复。 | |
派生一个离屏编辑器实例，返回离屏编辑器标识，用于后台渲染或导出。 | |
设置“下一步”点击回调，在用户点击下一步时回调并返回当前帧等结果。 | |
设置最大可编辑时长，并根据该时长自动更新播放区间。 | |
设置最小可编辑时长，用于限制工程时长下限。 | |
获取离屏帧提供器，根据指定长边像素获取编辑结果帧序列。 | |
获取指定时间点的一帧画面 Bitmap，通过回调异步返回结果。 | |
设置编辑拦截器，在关键编辑行为（如删除、应用特效等）前做拦截和自定义处理。 | |
设置播放器状态监听器，用于监听播放状态变化（播放、暂停、结束等）。 | |
设置草稿变化监听器，当草稿内容发生变更时回调通知。 | |
设置离屏视频播放器提供者，自定义离屏播放/渲染实现。 | |
获取当前预览的渲染尺寸，用于适配 UI。 | |
设置编辑 UI 使用的资源根路径。 |
setPermissionProvider
描述
设置权限提供器，用于处理编辑过程中涉及的运行时权限请求（如麦克风录制、存储读写等）。
接口
public void setPermissionProvider(ITAVPermissionProvider provider)参数
参数名 | 类型 | 说明 |
provider | 权限提供/请求适配接口实例。 |
返回值
类型：
void 说明：无返回值。
initWithClipPath
描述
以一组视频/图片路径初始化编辑工程。
会重置播放器、刷新时长信息并重置草稿上下文，适用于“新建工程”或“重新加载素材”场景。
接口
public void initWithClipPath(List<String> pathList)参数
参数名 | 类型 | 说明 |
pathList | List\\<String> | 素材路径列表，可为视频或图片文件路径。 |
返回值
类型：
void 说明：无返回值。内部会自动触发首帧渲染与时长计算。
initWithDraft
描述
使用已有草稿初始化编辑工程。
会加载草稿中的轨道、特效、文字、画中画等内容，并重置草稿上下文。
接口
public void initWithDraft(TAVDraft draft)参数
参数名 | 类型 | 说明 |
draft | TAVDraft | 已保存的草稿对象。 |
返回值
类型：
void 说明：无返回值。草稿加载完成后，UI 会同步至草稿对应状态。
onResume
描述
通知 UI 组件所在页面进入可见/前台状态。
可选地恢复播放或仅刷新当前帧，内部会同步调用面板的
onResume。接口
public void onResume(boolean resumePlay)参数
参数名 | 类型 | 说明 |
resumePlay | boolean | 是否自动恢复播放：true 则尽量恢复播放，false 则仅刷新画面。 |
返回值
类型：
void 说明：无返回值。
onPause
描述
通知 UI 组件所在页面进入不可见/后台状态。
会暂停播放器并通知面板进入暂停状态，适用于 Activity/Fragment 的
onPause() 回调中调用。接口
public void onPause()参数
无
返回值
类型：
void 说明：无返回值。
isPlaying
描述
查询当前播放器是否处于“正在播放”状态。
接口
public boolean isPlaying()参数
无
返回值
类型：
boolean 说明：true 表示当前播放器正在播放，false 表示未播放（暂停、停止或未准备）。
onBackPressed
描述
处理返回键事件。
优先交由面板与图层控制器消费，例如关闭当前弹出的面板或退出编辑层；若内部未消费，则返回
false 交由外层处理。接口
public boolean onBackPressed()参数
无
返回值
类型：
boolean 说明：true 表示内部已消费返回事件，false 表示未消费，应由外部 Activity/Fragment 继续处理。
onDestroy
描述
销毁 UI 组件内部资源。
会释放播放器资源、清理全局 Toast 引用等，适用于 Activity/Fragment 的
onDestroy() 中调用。接口
public void onDestroy()参数
无
返回值
类型：
void 说明：无返回值。调用后不应继续使用该实例。
setMaterialProvider
描述
设置素材提供器，用于为 UI 工具栏、特效面板等提供滤镜、贴纸、动效等素材数据。
接口
public void setMaterialProvider(ITAVMaterialProvider provider)参数
参数名 | 类型 | 说明 |
provider | 素材数据提供接口实例。 |
返回值
类型：
void 说明：无返回值。
getPreEditLayer
描述
获取“预编辑层”的根布局容器。
可用于上层手动在预编辑阶段叠加自定义 View 等。
接口
public FrameLayout getPreEditLayer()参数
无
返回值
类型：
FrameLayout 说明：预编辑图层的容器视图实例。可能为内部创建的
FrameLayout。showLayer
描述
切换当前展示的编辑图层（如预编辑、主编辑、全屏预览、动效编辑等）。
内部会根据传入的枚举类型切换对应的
BaseLayer，并触发图层变更回调。接口
public void showLayer(TAVEditorUIConstants.TAVLayer layer)参数
参数名 | 类型 | 说明 |
layer | TAVEditorUIConstants.TAVLayer | 期望展示的图层类型，例如 PRE_EDIT、MAIN_EDIT、FULL_PREVIEW、MOTION_EDIT |
返回值
类型：
void 说明：无返回值。
showPanel
描述
切换当前展示的编辑面板（如文字面板、配音面板、滤镜面板、贴纸面板等）。
接口
public void showPanel(TAVEditorUIConstants.TAVPanel panel)参数
参数名 | 类型 | 说明 |
panel | TAVEditorUIConstants.TAVPanel | 需要展示的面板类型，例如 NONE、TEXT、VOICEOVER、FILTER、STICKER |
返回值
类型：
void 说明：无返回值。
setPanelChangedListener
描述
设置面板切换监听器，用于在面板展示状态发生变化时接收回调（例如从主面板切到文字面板等）。
接口
public void setPanelChangedListener(TAVPanelChangedListener listener)参数
参数名 | 类型 | 说明 |
listener | TAVPanelChangedListener | 面板变更监听器实例，可为 null 取消监听。 |
返回值
类型：
void 说明：无返回值。
setLayerChangedListener
描述
设置图层切换监听器，用于在编辑图层（预编辑、主编辑、全屏预览、动效编辑等）发生切换时回调给上层。
接口
public void setLayerChangedListener(TAVLayerChangedListener listener)参数
参数名 | 类型 | 说明 |
listener | TAVLayerChangedListener | 图层变更监听器实例，可为 null 取消监听。 |
返回值
类型：
void 说明：无返回值。
saveDraft
描述
保存当前编辑状态为草稿。
会将轨道、特效、文字、画中画等信息序列化为
TAVDraft 对象，并返回该草稿。接口
public TAVDraft saveDraft()参数
无
返回值
类型：
TAVDraft 说明：当前编辑状态对应的草稿对象。具体落盘路径可由
TAVDraft 自身字段/接口获取。getDraft
描述
获取当前正在编辑的草稿模型对象。
与
saveDraft 不同，该方法仅返回内存中的草稿对象引用，不会主动保存。接口
public TAVDraft getDraft()参数
无
返回值
类型：
TAVDraft 说明：当前编辑会话关联的草稿对象。
getEditOperator
描述
获取编辑操作入口接口，用于执行具体的编辑命令（如片段增删、特效添加、文字编辑等）。
接口
public ITAVEditOperator getEditOperator()参数
无
返回值
说明：编辑操作接口实例，可用于对工程进行具体编辑操作。
forkOffscreenEditor
描述
从当前编辑上下文派生一个离屏编辑器实例，用于离屏渲染、封面生成等操作。
返回的 Key 可用于后续通过其他模块/接口查找并使用该离屏编辑器。
接口
public String forkOffscreenEditor()参数
无
返回值
类型：
String 说明：离屏编辑器实例的唯一标识 Key。
setNextClickCallback
描述
设置“下一步”按钮点击回调，用于在用户点击编辑完成/下一步时，将当前画面快照等信息回调给上层。
接口
public void setNextClickCallback(TAVCallback<Bitmap> callback)参数
参数名 | 类型 | 说明 |
callback | TAVCallback\\<Bitmap> | “下一步”点击时的回调，参数为封面或当前帧 Bitmap，可为 null 取消回调。 |
返回值
类型：
void 说明：无返回值。
setMaxEditDuration
描述
设置当前工程允许的最大编辑时长。
当素材总时长超过该值时，在预编辑层会自动限制播放/编辑范围。
接口
public void setMaxEditDuration(long duration)参数
参数名 | 类型 | 说明 |
duration | long | 最大编辑时长，单位：微秒（us）。 |
返回值
类型：
void 说明：无返回值。内部会立即更新播放区间。
setMinEditDuration
描述
设置当前工程允许的最小编辑时长，用于约束内容长度下限（例如平台发布要求的最短视频时长）。
接口
public void setMinEditDuration(long duration)参数
参数名 | 类型 | 说明 |
duration | long | 最小编辑时长，单位：微秒（us）。 |
返回值
类型：
void 说明：无返回值。
getFrameProvider
描述
获取离屏帧提供器，用于按指定长边尺寸获取当前工程的渲染帧（例如封面生成、预览缩略图等）。
接口
public ITAVFrameProvider getFrameProvider(int longSide)参数
参数名 | 类型 | 说明 |
longSide | int | 目标渲染图像的最长边尺寸，单位：像素。 |
返回值
类型：
ITAVFrameProvider 说明：帧提供器接口，可用于按时间获取当前工程的渲染结果。
getFrameAtTime
描述
获取指定时间点的离屏渲染帧。
内部会按给定长边尺寸渲染，并通过回调返回对应的
Bitmap。接口
public void getFrameAtTime(long timeUs, int longSide, TAVConsumer<Bitmap> consumer)参数
参数名 | 类型 | 说明 |
timeUs | long | 目标时间点，单位：微秒（us）。 |
longSide | int | 渲染图像最长边尺寸，单位：像素。 |
consumer | TAVConsumer\\<Bitmap> | 渲染结果回调，参数为对应时间点的 Bitmap。 |
返回值
类型：
void 说明：无返回值，结果通过回调异步返回。
setEditInterceptor
描述
设置编辑拦截器，用于在执行编辑操作前进行校验或拦截（例如权限校验、业务限制、埋点等）。
接口
public void setEditInterceptor(ITAVEditInterceptor interceptor)参数
参数名 | 类型 | 说明 |
interceptor | ITAVEditInterceptor | 编辑操作拦截器实例，可为 null 取消拦截。 |
返回值
类型：
void 说明：无返回值。
setPlayerStatusListener
描述
设置播放器状态监听器，用于接收更细粒度的播放器状态变化通知。
接口
public void setPlayerStatusListener(TAVPlayerStatusListener listener)参数
参数名 | 类型 | 说明 |
listener | TAVPlayerStatusListener | 播放器状态监听器实例，可为 null 取消监听。 |
返回值
类型：
void 说明：无返回值。
setDraftChangeListener
描述
设置草稿变化监听器，用于在草稿被保存、修改或重置时通知业务层。
接口
public void setDraftChangeListener(TAVDraftChangeListener listener)参数
参数名 | 类型 | 说明 |
listener | TAVDraftChangeListener | 草稿变化监听器实例，可为 null 取消监听。 |
返回值
类型：
void 说明：无返回值。
setOffScreenVideoPlayer
描述
设置离屏视频播放器提供器，用于控制导出/离屏预览时所使用的底层播放器实现。
接口
public void setOffScreenVideoPlayer(ITAVProvider<ITAVOffScreenVideoPlayer> provider)参数
参数名 | 类型 | 说明 |
provider | ITAVProvider<ITAVOffScreenVideoPlayer> | 离屏播放器提供器，用于创建实际播放实例。 |
返回值
类型：
void 说明：无返回值。
getRenderSize
描述
获取当前实际渲染区域的尺寸。
该尺寸通常由画布比例、预览容器大小以及工程内容共同决定。
接口
public Size getRenderSize()参数
无
返回值
类型：
Size 说明：当前渲染区域的宽高信息。
setResourceRootPath
描述
设置资源根目录路径。
接口
public void setResourceRootPath(String path)参数
参数名 | 类型 | 说明 |
path | String | 资源根目录绝对路径或前缀。 |
返回值
类型：
void 说明：无返回值。
ITAVPermissionProvider
TAVEditorUIKIt 内所需的权限提供者。
hasPermission
描述
判断当前是否已经授予指定的运行时权限。
通常在执行需要敏感权限的操作前调用，用于决定是直接执行还是发起权限请求。
接口
boolean hasPermission(String permission)参数
参数名 | 类型 | 说明 |
permission | String | 需要检查的权限名称（如 android.permission.RECORD_AUDIO）。 |
返回值
类型：
boolean 说明：有权限则返回 true，否则返回 false。
requirePermission
描述
立即发起指定权限的请求。
请求结果会通过
PermissionResultReceiver 回调异步通知调用方。接口
void requirePermission(String permission, int requestCode, PermissionResultReceiver receiver)参数
参数名 | 类型 | 说明 |
permission | String | 需要请求的权限名称（如 android.permission.RECORD_AUDIO）。 |
requestCode | int | 权限请求的请求码，用于在上层区分不同请求场景。 |
receiver | PermissionResultReceiver | 权限请求结果回调接收器实例，用于接收授权结果。 |
返回值
类型：
void 说明：无返回值，权限结果通过
PermissionResultReceiver 异步回调通知。onPermissionResult
描述
权限请求结果回调。当调用
requirePermission 后，用户在系统权限弹框中完成操作（允许/拒绝）时触发该回调。接口
void onPermissionResult(boolean granted)参数
参数名 | 类型 | 说明 |
granted | boolean | 为 true 表示权限授予成功；为 false 表示用户拒绝或授权失败。 |
返回值
类型：
void 说明：无返回值，调用方可在此回调中根据授权结果决定后续逻辑（继续操作或提示用户）。
ITAVMaterialProvider
TAVEditorUIKit 所需的媒体文件提供者。
getBgmFile
描述
触发选择背景音乐文件的流程。
具体选择逻辑（弹窗形式、本地文件或内置素材等）由业务方实现，选择结果通过
ITAVBgmResultHandler 回调返回。接口
void getBgmFile(int requestCode, ITAVBgmResultHandler handler)参数
参数名 | 类型 | 说明 |
requestCode | int | 请求码，用于区分不同业务场景下的 BGM 选择请求。 |
handler | 背景音乐选择结果回调接口，用于返回用户选中的素材。 |
返回值
类型：
void 说明：无返回值，BGM 文件选择结果通过
handler 异步回调通知。getAlbumFiles
描述
触发打开相册选择素材（视频/图片等）的流程。
通过
TAVAlbumOptions 控制最大选择数量、素材类型以及来源等，选择结果由 ITAVAlbumResultHandler 回调返回。接口
void getAlbumFiles(int requestCode, TAVAlbumOptions options, ITAVAlbumResultHandler handler)参数
参数名 | 类型 | 说明 |
requestCode | int | 请求码，用于区分不同相册选择请求场景。 |
options | 相册选择配置项，包括最大选择数量、资源类型、来源等。 | |
handler | 相册选择结果回调接口，用于返回用户选中的素材列表。 |
返回值
类型：
void 说明：无返回值，相册选择结果通过
handler 异步回调通知。ITAVBgmResultHandler
用于处理业务方的背景音乐选择结果。
onBgmSelectResult
描述
当通过
ITAVMaterialProvider.getBgmFile(...) 触发的 BGM 选择流程结束后（无论成功或失败），都需要回调该方法，通知UIKit请求对应的选择结果。 接口
void onBgmSelectResult(int requestCode, TAVBgmResource resource)参数
参数名 | 类型 | 说明 |
requestCode | int | 本次 BGM 选择请求的请求码，用于区分不同业务场景下的选择结果。 |
resource | TAVBgmResource | 选择到的 BGM 资源对象；具体字段由 TAVBgmResource 定义，可能在用户取消时为 null。 |
返回值
类型：
void 说明：无返回值，通过回调告知调用方本次 BGM 选择的最终结果。
ITAVAlbumResultHandler
用于处理业务方的相册文件选择结果。
onAlbumSelectResult
描述
当通过
ITAVMaterialProvider.getAlbumFiles(...) 触发的相册选择流程结束后（无论用户是否真正选择了素材），都需要回调该方法，通知UIKit请求对应的选择结果。 接口
void onAlbumSelectResult(int requestCode, List<TAVAlbumResource> resourceList)参数
参数名 | 类型 | 说明 |
requestCode | int | 本次相册选择请求的请求码，用于区分不同业务场景的选择结果。 |
resourceList | List\\<TAVAlbumResource> | 用户选中的相册素材列表；当用户未选择或取消时可能为空列表。 |
返回值
类型：
void 说明：无返回值，通过回调向调用方返回本次相册选择的最终结果。
TAVAlbumOptions
描述
相册素材选择的配置项，用于约束可选择的素材数量、类型以及素材来源。
在调用
getAlbumFiles 时传入，用于指导 UI 和素材过滤逻辑。参数
字段名 | 类型 | 说明 |
count | int | 可选择的最大素材数量，例如 1 表示仅可选择单个文件。 |
type | 资源类型（例如仅视频、仅图片或混合类型），由 TAVBaseResource.TYPE 定义。 | |
from | TAVEditorUIConstants.TAVResourceFrom | 素材来源类型（如系统相册、内置素材等），由 TAVResourceFrom 定义。 |
TAVBaseResource.TYPE
描述
资源类型枚举，用于标识素材在编辑器中的具体类别，例如背景音乐、图片、视频或多类型混合选择。
参数
枚举值 | 说明 |
BGM | 背景音乐资源，仅音频类型。 |
PHOTO | 图片资源，仅静态图片类型。 |
VIDEO | 视频资源，仅视频文件类型。 |
MULTI | 多类型混合资源，可同时包含图片与视频等。 |
TAVPanelChangedListener
TAVEditorUIKit 内编辑面板切换监听。
onPanelChanged
描述
编辑面板切换时的回调监听方法。
当编辑器内部当前展示的功能面板（如文字面板、配音面板等）发生变化时触发，用于通知外部同步 UI 或业务状态。
接口
void onPanelChanged(TAVEditorUIConstants.TAVPanel panel)参数
参数名 | 类型 | 说明 |
panel | TAVEditorUIConstants.TAVPanel | 当前展示的面板类型，例如 TEXT、VOICEOVER、FILTER 等。 |
返回值
类型：
void 说明：无返回值，通过回调告知当前面板已发生变化。
TAVLayerChangedListener
TAVEditorUIKit 内编辑图层切换监听。
onLayerChanged
描述
编辑图层切换时的回调监听方法。
当编辑器当前展示的图层（如预编辑层、主编辑层、全屏预览层）发生变化时触发，用于通知外部同步 UI 或业务状态。
接口
void onLayerChanged(TAVEditorUIConstants.TAVLayer layer)参数
参数名 | 类型 | 说明 |
layer | TAVEditorUIConstants.TAVLayer | 当前展示的图层类型，例如 PRE_EDIT、MAIN_EDIT 等。 |
返回值
类型：
void 说明：无返回值，通过回调告知外部当前图层已发生变化。
ITAVEditOperator
提供编辑操作入口，用于执行具体的编辑命令（如片段增删、特效添加、文字编辑等）
API | 描述 |
获取当前工程中的所有主轨道片段模型列表 List<TAVClipModel>。 | |
获取当前工程中的所有背景音乐模型列表 List<TAVBgmModel>。 | |
获取当前工程中的所有配音模型列表 List<TAVVoiceoverModel>。 | |
获取当前工程中的所有文本模型列表 List<TAVTextModel>。 | |
获取当前工程中的所有画中画模型列表 List<TAVOverlayModel>。 | |
批量更新编辑模型列表（如 BGM、文本、配音、画中画），按传入的模型内容同步更新工程。 | |
给当前工程新增编辑模型列表。 | |
从当前工程中批量移除指定的编辑模型列表。 | |
激活指定的编辑模型，通常用于使该元素成为当前选中项并进入可编辑状态。 |
getClipModels
描述
获取当前工程中所有主轨剪辑片段（Clip）的模型列表。
接口
List<TAVClipModel> getClipModels()参数
无
返回值
类型：
List<TAVClipModel> 说明：返回当前工程中所有剪辑片段对应的模型列表。
getBgmModels
描述
获取当前工程中所有背景音乐（BGM）的模型列表。
接口
List<TAVBgmModel> getBgmModels()参数
无
返回值
类型：
List<TAVBgmModel> 说明：返回当前工程中所有 BGM 模型列表。
getVoiceoverModels
描述
获取当前工程中所有配音（Voiceover）的模型列表。
接口
List<TAVVoiceoverModel> getVoiceoverModels()参数
无
返回值
类型：
List<TAVVoiceoverModel> 说明：返回当前工程中所有配音模型列表。
getTextModels
描述
获取当前工程中所有文字（Text）元素的模型列表。
接口
List<TAVTextModel> getTextModels()参数
无
返回值
类型：
List<TAVTextModel> 说明：返回当前工程中所有文字模型列表。
getOverlayModels
描述
获取当前工程中所有画中画（Overlay）元素的模型列表。
接口
List<TAVOverlayModel> getOverlayModels()参数
无
返回值
类型：
List<TAVOverlayModel> 说明：返回当前工程中所有画中画模型列表。
updateEditModels
描述
根据传入的编辑模型列表增量更新现有编辑数据。
通常用于对部分 BGM/配音/文字等已存在模型进行属性修改，而不是完全替换整个列表。
接口
void updateEditModels(List<? extends TAVEditModel<?>> models)参数
参数名 | 类型 | 说明 |
models | List<? extends TAVEditModel<?>> | 需要更新的编辑模型列表，支持 BGM、配音、文字等类型。 |
返回值
类型：
void 说明：无返回值，内部会根据模型标识/ID 对应更新已有编辑元素的属性。
setEditModels
描述
设置新增的编辑模型列表。
接口
void setEditModels(List<? extends TAVEditModel<?>> models)参数
参数名 | 类型 | 说明 |
models | List<? extends TAVEditModel<?>> | 新增的编辑模型列表。 |
返回值
类型：
void 说明：无返回值，调用后在当前工程中新增对应的编辑数据。
removeEditModel
描述
从当前工程中批量删除指定的编辑模型。
接口
void removeEditModel(List<? extends TAVEditModel<?>> models)参数
参数名 | 类型 | 说明 |
models | List<? extends TAVEditModel<?>> | 需要被删除的编辑模型列表，按模型 ID/标识进行移除。 |
返回值
类型：
void 说明：无返回值，调用后传入的模型对应的编辑元素会从工程中移除。
activeEditModel
描述
激活指定的编辑模型。
激活操作通常会驱动 UI 高亮对应元素。
接口
void activeEditModel(TAVEditModel<?> model)参数
参数名 | 类型 | 说明 |
model | TAVEditModel<?> | 需要激活的编辑模型，可为 BGM、配音、文字等。 |
返回值
类型：
void 说明：无返回值，调用后该模型会成为当前“激活/选中”的编辑对象，UI 与内部状态会同步更新。
