本文主要介绍短视频 SDK 的 Android 端 API 接口文档，以便于查阅和使用。
TAVMagicBase
TAVMagicBase 提供 TAVMagic SDK 的初始化、AI 模型资源安装、缩略图缓存配置以及日志系统配置等基础能力的静态工具方法。
API | 描述 |
初始化 SDK。支持两种形式： 1. initSDK(Context context, String resPath) 使用静态库并指定 light_assets 目录。2. initSDK(Context context, String resPath, String libsPath) 支持自定义动态库目录。 | |
拷贝 AI 模型文件：将已下载好的 AI 模型文件从 srcPath 复制到 resDir 对应的资源目录。返回 0 表示成功，-1 表示 srcPath 不存在，-2 表示 IO 错误。 | |
将 assets 下的 AI 模型文件拷贝到本地指定路径 path，需与 initSDK 传入的路径保持一致。返回 0 表示成功，-1 表示 context 为空，-2 表示 IO 错误。 | |
获取 SDK 初始化时保存的全局 Application Context。 | |
获取当前 SDK 版本号，格式为 VERSION_NAME.VERSION_CODE。 | |
获取当前使用的 light assets 根目录路径。 | |
设置缩略图文件缓存目录根路径。 | |
设置缩略图的内存缓存大小。 | |
设置缩略图的磁盘缓存容量上限。 | |
设置缩略图软件解码使用的线程数量。 | |
设置 SDK 日志等级。 setLogLevel(int level) 仅设置日志等级；setLogLevel(int level, ITELogger logger) 同时设置日志等级并接入自定义日志回调。 |
initSDK
描述
初始化 TAV Magic SDK，使用内置静态库方式加载依赖，并安装 Light Assets 资源、设置缩略图缓存目录。
通常在应用进程启动后、第一次使用 SDK 前调用一次即可。
接口
public static boolean initSDK(Context context, String resPath)参数
参数名 | 类型 | 说明 |
context | Context | Android 上下文对象，内部会使用 getApplicationContext() 保存全局引用。 |
resPath | String | Light Assets 根目录路径，用于安装 light_assets 资源。 |
返回值
类型：
boolean 说明：初始化成功返回
true，加载 SO 或资源失败返回 false。initSDK
描述
初始化 TAV Magic SDK，使用自定义动态库目录加载依赖（动态 SO），并安装 Light Assets 资源、设置缩略图缓存目录。
适用于业务方自行管理或下载 SO 到自定义目录的场景。
接口
public static boolean initSDK(Context context, String resPath, String libsPath)参数
参数名 | 类型 | 说明 |
context | Context | Android 上下文对象，内部会使用 getApplicationContext() 保存全局引用。 |
resPath | String | Light Assets 根目录路径，用于安装 light_assets 资源。 |
libsPath | String | 自定义动态库目录路径，用于加载 TAV 相关 SO 文件。 |
返回值
类型：
boolean 说明：初始化成功返回
true，加载 SO 或资源失败返回 false。installAIModelFile
描述
拷贝 AI 模型文件到指定资源目录。
将客户已下载好的 AI 模型文件从本地目录复制到 SDK 对应的模型目录下。
接口
public static int installAIModelFile(String srcPath, String resDir)参数
参数名 | 类型 | 说明 |
srcPath | String | 存放 AI 模型文件的源目录路径（已下载完成的模型文件所在目录）。 |
resDir | String | 用于存放美颜资源的根目录，此目录与创建 XmagicApi 对象时传入的路径一致。 |
返回值
类型：
int 说明：
0：拷贝成功。-1：srcPath 不存在。-2：IO 错误。installAIModelFilesFromAssets
描述
将 APK
assets 目录下的 AI 模型文件拷贝到本地指定路径。 适用于在 APK 内预置 AI 模型文件的场景。
接口
public static int installAIModelFilesFromAssets(Context context, String path)参数
参数名 | 类型 | 说明 |
context | Context | Android 上下文对象，拷贝 assets 资源时需要使用。 |
path | String | 拷贝资源的目标路径，需要与 initSDK 时传入的 Light Assets 路径保持一致。 |
返回值
类型：
int 说明：
0：复制成功。-1：context 为 null。-2：IO 错误。getApplicationContext
描述
获取在
initSDK 时保存的 Application Context，用于在 SDK 内部全局复用，避免泄漏 Activity / Service 等组件。 接口
public static Context getApplicationContext()参数
无
返回值
类型：
Context 说明：返回 SDK 内部持有的 Application 级别
Context；如未初始化可能为 null（调用前请确保已执行 initSDK）。getSDKVersion
描述
获取当前集成的 TAV Magic SDK 版本号。
接口
public static String getSDKVersion()参数
无
返回值
类型：
String 说明：返回形如
"{VERSION_NAME}.{VERSION_CODE}" 的版本字符串，例如：1.2.3.45。getLightAssetsDir
描述
获取当前生效的 Light Assets 根目录路径。
接口
public static String getLightAssetsDir()参数
无
返回值
类型：
String 说明：返回通过
initSDK 传入并经 TAVResourceUtil.fixPathSuffix 处理后的 Light Assets 根目录；若未初始化可能为 null。setThumbnailCacheDir
描述
设置缩略图文件缓存的根目录，用于存放生成的缩略图文件（磁盘缓存）。
initSDK 内部会默认设置为 context.getCacheDir()/thumbnails，如业务需要自定义目录可再次调用该方法覆盖。 接口
public static void setThumbnailCacheDir(String cacheDirPath)参数
参数名 | 类型 | 说明 |
cacheDirPath | String | 缩略图磁盘缓存目录的路径（文件夹）。 |
返回值
类型：
void 说明：无返回值。
setThumbnailMemoryCacheSize
描述
设置缩略图在内存中的缓存大小（单位依赖
TAVFrameExtractorConfig 的实现），用于控制缩略图内存占用。 接口
public static void setThumbnailMemoryCacheSize(int cacheSize)参数
参数名 | 类型 | 说明 |
cacheSize | int | 内存缓存大小配置值。 |
返回值
类型：
void 说明：无返回值。
setThumbnailCacheCapacity
描述
设置缩略图磁盘缓存容量上限，用于控制缩略图在磁盘上的最大占用空间。
接口
public static void setThumbnailCacheCapacity(long capacity)参数
参数名 | 类型 | 说明 |
capacity | long | 磁盘缓存最大容量（单位：字节）。 |
返回值
类型：
void 说明：无返回值。
setThumbnailThreadCount
描述
设置缩略图生成 / 解码使用的线程数量（软件解码线程数），用于平衡解码性能与 CPU 占用。
接口
public static void setThumbnailThreadCount(int count)参数
参数名 | 类型 | 说明 |
count | int | 线程数量（>0 的整数）。 |
返回值
类型：
void 说明：无返回值。
setLogLevel
描述
设置 SDK 的日志输出级别。
该方法为便捷重载，等价于
setLogLevel(level, null)，仅控制内部统一日志级别，不接入自定义日志回调。 接口
public static void setLogLevel(int level)参数
参数名 | 类型 | 说明 |
level | int | 日志级别，推荐使用 Log.VERBOSE / Log.DEBUG / Log.INFO / Log.WARN / Log.ERROR / TAVMagicBase.NO_LOG。 |
返回值
类型：
void 说明：无返回值。
setLogLevel
描述
设置 SDK 的日志输出级别，并接入自定义日志回调
ITELogger。 接口
public static void setLogLevel(int level, ITELogger logger)参数
参数名 | 类型 | 说明 |
level | int | 日志级别，推荐使用 Log.VERBOSE / Log.DEBUG / Log.INFO / Log.WARN / Log.ERROR / TAVMagicBase.NO_LOG。 |
logger | ITELogger | 自定义日志回调接口实现；传入 null 则仅通过内部 TELog 输出，不再回调到业务层。 |
返回值
类型：
void 说明：无返回值。
TAVEditor
TAVEditor 提供播放器控制、特效管理、视频合成等编辑相关操作接口。
API | 描述 |
初始化编辑器，传入预览参数（父容器和渲染方式等）。 | |
销毁编辑器，释放内部资源。 | |
设置模板目录路径，返回模板加载结果码。 0：SUCCESS -1：PATH_INVALID -2：AUTH_INVALID | |
获取当前模板目录的绝对路径。 | |
获取指定模板路径的坑位配置信息（模板占位、文案、素材要求等）。 | |
从当前编辑对象复制创建一个新的编辑实例，可根据预览参数创建上屏 / 离屏实例并决定是否创建渲染链。 | |
读取当前渲染画面的快照，结果通过回调异步返回。 | |
获取当前预览使用的渲染尺寸。 | |
根据导出质量等级获取导出视频使用的渲染尺寸。 | |
设置画布宽高比例（存为比例，不直接作为最终像素宽高）。 | |
添加视频资源：支持在末尾追加或在指定位置插入视频列表，返回成功添加后的索引。 | |
添加图片资源：支持在末尾追加或在指定位置插入图片列表，可指定播放时长，返回成功添加后的索引。 | |
获取当前正在编辑的资源（视频/图片）总数量。 | |
按资源下标移除对应的视频或图片资源。 | |
设置指定资源的播放时间区间（startTimeUs ~ endTimeUs），视频会在该区间内截取播放。 | |
设置指定视频资源的音量（0–1f）。 | |
设置所有输入资源的统一背景音量（0–1f）。 | |
获取指定视频资源的当前音量。 | |
设置指定视频资源的播放速度。 | |
获取指定视频资源的播放速度。 | |
调整资源顺序，将资源从旧下标移动到新下标，返回是否调整成功。 | |
获取输入视频路径对应的基础信息（时长、宽、高等）。 | |
获取原始视频帧抽帧接口，可配置是否强制使用软解码。 | |
添加背景音乐，指定插入到视频时间轴的位置、素材起始时间和播放时长，返回唯一 BGM ID。 | |
按 BGM 唯一 ID 删除背景音乐，返回删除是否成功。 | |
调整背景音乐在视频时间轴上的起始播放位置。 | |
设置指定背景音乐在素材内的播放区间（开始时间和持续时长）。 | |
设置指定背景音乐的音量（建议范围 0–3f）。 | |
设置所有背景音乐的统一音量（建议范围 0–3f）。 | |
获取指定背景音乐的当前音量。 | |
设置指定背景音乐的播放速度。 1为正常 大于1为变快 小于1为变慢 | |
获取指定背景音乐的播放速度。 | |
设置播放器是否启用循环播放。 | |
设置预览监听器，用于接收播放进度、完成、错误等回调。 | |
开始播放预览。 | |
设置预览播放的时间区间（开始时间与持续时长）。 | |
在暂停后继续播放预览。 | |
暂停当前预览播放。 | |
获取当前工程的总播放时长（单位：us）。 | |
判断当前是否处于播放中状态。 | |
将播放位置移动到指定时间点，可选择非精准 seek（跳到临近关键帧）。 | |
设置指定视频资源的顺时针旋转角度（0–360°）。 | |
设置指定视频资源的裁剪区域（相对渲染尺寸归一化的 RectF）。 | |
设置自定义纹理处理回调，用于对渲染纹理做二次处理。 | |
移除自定义纹理处理回调。 | |
添加滤镜效果，传入 LUT 路径、强度和时间区间，返回唯一滤镜 ID。 | |
调整指定滤镜的强度（0–1f）。 | |
删除指定滤镜效果。 | |
获取贴纸管理接口，用于添加、编辑和删除贴纸。 | |
获取画中画管理接口，用于添加、编辑和删除画中画内容。 | |
在指定位置设置转场素材，配置资源路径与时长，返回转场 ID。 | |
更新指定转场效果的持续时长。 | |
删除指定转场效果，返回删除是否成功。 | |
添加动效，支持基础版本和带 scaleMode 的版本，返回动效 ID。 | |
调整指定动效的播放时间区间（开始节点与持续时长）。 | |
删除指定动效。 | |
获取某一时间点的渲染结果图像，按长边缩放并指定渲染场景，通过回调返回。 | |
获取帧提供接口，根据长边长度和渲染场景持续生成渲染结果。 | |
导出视频：支持按预设导出等级或自定义编码配置导出至指定路径，并通过监听器获取进度和结果。 | |
取消当前正在进行的视频导出任务。 | |
立即刷新当前渲染，支持无参调用或携带 tag 与回调，在刷新完成后执行回调。 | |
获取草稿管理接口，用于保存、恢复和管理编辑草稿。 |
initWithPreview
描述
初始化播放器预览环境，需传入父容器和渲染方式等参数。
接口
void initWithPreview(TAVEditorConstants.PreviewParam param)参数
参数名 | 类型 | 说明 |
param | 预览参数（父容器、渲染方式等）。 |
返回值
类型：
void 说明：无返回值。
release
描述
销毁当前编辑器实例，释放内部占用的资源。调用后该编辑器实例不应再继续使用。
接口
void release()参数
无
返回值
类型：
void 说明：无返回值。
fork
描述
基于当前编辑对象创建一个新的编辑实例。
param.videoView = null：创建离屏实例。param.videoView != null：创建上屏实例。param = null：创建默认离屏实例。param != null：根据 param.scene 决定是否创建渲染链。接口
TAVEditor fork(TAVEditorConstants.PreviewParam param)参数
参数名 | 类型 | 说明 |
param | 新实例的预览配置参数。 |
返回值
类型：
TAVEditor 说明：基于当前编辑状态创建的新编辑器实例。
readSnapshot
描述
读取当前渲染结果的快照（截图），通过回调返回。
接口
void readSnapshot(TAVSnapshotCallback callback)参数
参数名 | 类型 | 说明 |
callback | TAVSnapshotCallback | 快照获取成功时回调。 |
返回值
类型：
void 说明：无返回值，结果通过回调返回。
setTemplateDir
描述
设置模板资源目录路径。
接口
int setTemplateDir(String path)参数
参数名 | 类型 | 说明 |
path | String | 模板目录路径。 |
返回值
类型：
int 说明：模板授权与路径校验结果，
TAVTemplateCode：0表示 SUCCESS，-1为 PATH_INVALID，-2为 AUTH_INVALID。getTemplateDir
描述
获取当前已设置的模板目录路径。
接口
String getTemplateDir()参数
无
返回值
类型：
String 说明：模板目录的绝对路径。
getTemplateConfig
描述
获取指定模板路径对应的模板坑位等配置信息。
接口
TAVTemplateConfig getTemplateConfig(String templatePath)参数
参数名 | 类型 | 说明 |
templatePath | String | 模板路径。 |
返回值
类型：
TAVTemplateConfig 说明：模板坑位等配置信息。
getRenderSize
描述
获取当前预览使用的渲染大小，一般为预览画布实际输出分辨率。
接口
Size getRenderSize()参数
无
返回值
类型：
Size 说明：当前预览渲染使用的宽高信息。
getGeneratingRenderSize
描述
根据导出质量等级获取导出视频时要使用的渲染大小。
分辨率最高不超过指定等级，例如：
VIDEO_LEVEL_360P = 0：360×640 VIDEO_LEVEL_480P = 1：640×480 VIDEO_LEVEL_540P = 2：960×540 VIDEO_LEVEL_720P = 3：1280×720 VIDEO_LEVEL_1080P = 4：1920×1080接口
Size getGeneratingRenderSize(@TAVEditorConstants.GenerateLevel int level)参数
参数名 | 类型 | 说明 |
level | int（@GenerateLevel） | 导出质量等级（分辨率档位）。 |
返回值
类型：
Size 说明：按指定导出质量计算得到的目标渲染宽高。
setRenderSizeRatio
描述
设置画布大小属性。此处传入的宽高代表画布的宽高比，内部不会直接使用此处的数值作为最终像素宽高。
接口
void setRenderSizeRatio(int width, int height)参数
参数名 | 类型 | 说明 |
width | int | 画布比例宽度。 |
height | int | 画布比例高度。 |
返回值
类型：
void 说明：无返回值。
addVideoClip
描述
向末尾添加一个视频资源，插入到当前时间线末尾。
接口
int addVideoClip(String path)参数
参数名 | 类型 | 说明 |
path | String | 视频文件路径。 |
返回值
类型：
int 说明：成功添加后的视频片段索引，下标从 0 开始。
addVideoClip
描述
在指定位置插入一段或多段视频资源。插入位置之后的资源顺延。
接口
int addVideoClip(int clipIndex, List<String> paths)参数
参数名 | 类型 | 说明 |
clipIndex | int | 插入位置的目标下标。 |
paths | List\\<String> | 待编辑的视频源路径列表。 |
返回值
类型：
int 说明：成功添加后的第一个视频片段索引。
addImageClip
描述
向末尾添加一张图片资源，以图片形式参与时间线。
当
duration <= 0 时默认使用 3 秒时长。接口
int addImageClip(String path, long duration)参数
参数名 | 类型 | 说明 |
path | String | 图片源路径。 |
duration | long | 图片展示时长（单位：us，<=0 默认 3s）。 |
返回值
类型：
int 说明：成功添加后的图片片段索引。
addImageClip
描述
在指定位置插入一张或多张图片资源。插入位置之后的资源顺延。
当
duration <= 0 时默认使用 3 秒时长。接口
int addImageClip(int clipIndex, List<String> paths, long duration)参数
参数名 | 类型 | 说明 |
clipIndex | int | 插入位置的目标下标。 |
paths | List\\<String> | 图片源路径列表。 |
duration | long | 每张图片展示时长（单位：us，<=0 默认 3s）。 |
返回值
类型：
int 说明：成功添加后的第一个图片片段索引。
getClipCount
描述
获取当前时间线上正在编辑的资源（视频 + 图片）数量。
接口
int getClipCount()参数
无
返回值
类型：
int 说明：当前时间线上资源片段的总数量。
removeClip
描述
移除指定位置的视频或图片资源。
接口
void removeClip(int clipIndex)参数
参数名 | 类型 | 说明 |
clipIndex | int | 需要移除的下标。 |
返回值
类型：
void 说明：无返回值。
setClipRange
描述
修改指定资源的播放时长区间。
对于视频资源，
startTimeUs 和 endTimeUs 用于截取视频的播放区间。接口
void setClipRange(int clipIndex, long startTimeUs, long endTimeUs)参数
参数名 | 类型 | 说明 |
clipIndex | int | 资源下标。 |
startTimeUs | long | 资源播放开始时间（us）。 |
endTimeUs | long | 资源播放结束时间（us）。 |
返回值
类型：
void 说明：无返回值。
setVideoClipVolume
描述
设置指定视频资源的背景音量。
接口
void setVideoClipVolume(int clipIndex, float volume)参数
参数名 | 类型 | 说明 |
clipIndex | int | 视频资源下标。 |
volume | float | 音量，范围 0–1f。 |
返回值
类型：
void 说明：无返回值。
setAllClipsVolume
描述
统一设置所有视频/图片资源的背景音量。
接口
void setAllClipsVolume(float volume)参数
参数名 | 类型 | 说明 |
volume | float | 音量，范围 0–1f。 |
返回值
类型：
void 说明：无返回值。
getVideoClipVolume
描述
获取指定视频资源当前背景音量。
接口
float getVideoClipVolume(int clipIndex)参数
参数名 | 类型 | 说明 |
clipIndex | int | 视频下标。 |
返回值
类型：
float 说明：该视频片段当前音量值。
setVideoClipSpeed
描述
调整指定视频资源的播放速度。
接口
void setVideoClipSpeed(int clipIndex, float speed)参数
参数名 | 类型 | 说明 |
clipIndex | int | 视频下标。 |
speed | float | 播放速度倍数。 |
返回值
类型：
void 说明：无返回值。
getVideoClipSpeed
描述
获取指定视频资源当前播放速度。
接口
float getVideoClipSpeed(int clipIndex)参数
参数名 | 类型 | 说明 |
clipIndex | int | 视频下标。 |
返回值
类型：
float 说明：该视频片段当前播放速度倍数。
updateClipIndex
描述
调整资源在时间线中的顺序，将某个资源从旧位置移动到新位置。
接口
boolean updateClipIndex(int oldClipIndex, int newClipIndex)参数
参数名 | 类型 | 说明 |
oldClipIndex | int | 调整前的下标。 |
newClipIndex | int | 调整后的下标。 |
返回值
类型：
boolean 说明：调整是否成功。
getVideoInfo
描述
获取输入视频资源的信息，包括时长、宽度、高度等。
接口
TAVVideoInfo getVideoInfo(String path)参数
参数名 | 类型 | 说明 |
path | String | 视频文件路径。 |
返回值
类型：
TAVVideoInfo 说明：视频资源信息，如时长、宽度、高度等。
getThumbnailProvider
描述
获取视频原始帧抽帧接口提供者，可用于自定义缩略图或帧提取逻辑。
接口
ITAVThumbProvider getThumbnailProvider(boolean forceUseSoftwareDecoding)参数
参数名 | 类型 | 说明 |
forceUseSoftwareDecoding | boolean | 是否强制使用软解码抽帧。 |
返回值
说明：缩略图/帧抽取接口提供对象。
addBgm
描述
添加一段背景音乐到时间线中。
接口
int addBgm(String path, long startAtVideoTimeUS, long startTimeUS, long duration)参数
参数名 | 类型 | 说明 |
path | String | 背景音乐素材文件路径。 |
startAtVideoTimeUS | long | 音乐添加到视频中的时间位置（us）。 |
startTimeUS | long | 音频素材自身的起始播放时间（us）。 |
duration | long | 音频播放时长（us）。 |
返回值
类型：
int 说明：背景音乐素材唯一 ID，用于后续操作。
removeBgm
描述
根据唯一 ID 删除一段背景音乐。
接口
boolean removeBgm(int bgmID)参数
参数名 | 类型 | 说明 |
bgmID | int | 添加背景音乐时生成的唯一ID。 |
返回值
类型：
boolean 说明：删除是否成功。
updateBgmPlayOffset
描述
调整背景音乐在视频中的位置（在时间线中的偏移）。
接口
void updateBgmPlayOffset(int bgmID, long videoStartTime)参数
参数名 | 类型 | 说明 |
bgmID | int | 背景音乐唯一 ID。 |
videoStartTime | long | 在视频中的起始 position（Us）。 |
返回值
类型：
void 说明：无返回值。
updateBgmPlayRange
描述
设置背景音乐的播放区间。
接口
void updateBgmPlayRange(int bgmID, long startTime, long duration)参数
参数名 | 类型 | 说明 |
bgmID | int | 背景音乐唯一 ID。 |
startTime | long | 背景音乐开始播放时间（us）。 |
duration | long | 背景音乐持续时长（us）。 |
返回值
类型：
void 说明：无返回值。
setBgmVolume
描述
调整单个背景音乐的音量。
接口
void setBgmVolume(int bgmID, float volume)参数
参数名 | 类型 | 说明 |
bgmID | int | 背景音乐唯一 ID。 |
volume | float | 音量，建议范围 0–3f。 |
返回值
类型：
void 说明：无返回值。
setAllBgmVolume
描述
统一调整所有背景音乐的音量。
接口
void setAllBgmVolume(float volume)参数
参数名 | 类型 | 说明 |
volume | float | 音量，建议范围 0–3f。 |
返回值
类型：
void 说明：无返回值。
getBgmVolume
描述
获取指定背景音乐的当前音量。
接口
float getBgmVolume(int bgmID)参数
参数名 | 类型 | 说明 |
bgmID | int | 背景音乐唯一 ID。 |
返回值
类型：
float 说明：当前背景音乐的音量值。
setBgmSpeed
描述
调整指定背景音乐的播放速度。
接口
void setBgmSpeed(int bgmID, float speed)参数
参数名 | 类型 | 说明 |
bgmID | int | 背景音乐唯一 ID。 |
speed | float | 播放速度倍数，1 为正常，大于 1 变快，小于 1 变慢。 |
返回值
类型：
void 说明：无返回值。
getBgmSpeed
描述
获取指定背景音乐当前播放速度。
接口
float getBgmSpeed(int bgmID)参数
参数名 | 类型 | 说明 |
bgmID | int | 背景音乐唯一 ID。 |
返回值
类型：
float 说明：当前 BGM 播放速度倍数。
setPlayerLoop
描述
设置播放器是否循环播放。
接口
void setPlayerLoop(boolean loop)参数
参数名 | 类型 | 说明 |
loop | boolean | 是否循环播放。 |
返回值
类型：
void 说明：无返回值。
setVideoPreviewListener
描述
设置预览播放的监听回调。
接口
void setVideoPreviewListener(TAVPreviewListener listener)参数
参数名 | 类型 | 说明 |
listener | 预览播放监听回调。 |
返回值
类型：
void 说明：无返回值。
startPlay
描述
开始播放当前时间线内容，从当前播放位置开始。
接口
void startPlay()参数
无
返回值
类型：
void 说明：无返回值。
setPlayTimeRange
描述
设置播放区间，仅在指定时间范围内进行播放。
接口
void setPlayTimeRange(long startTime, long duration)参数
参数名 | 类型 | 说明 |
startTime | long | 播放开始时间（us）。 |
duration | long | 播放持续时长（us）。 |
返回值
类型：
void 说明：无返回值。
resumePlay
描述
在暂停后继续播放（续播）。
接口
void resumePlay()参数
无
返回值
类型：
void 说明：无返回值。
pausePlay
描述
暂停当前播放。
接口
void pausePlay()参数
无
返回值
类型：
void 说明：无返回值。
getTotalDuration
描述
获取当前时间线的总播放时长。
接口
long getTotalDuration()参数
无
返回值
类型：
long 说明：总时长（单位：us）。
isPlaying
描述
判断当前是否处于播放中状态。
接口
boolean isPlaying()参数
无
返回值
类型：
boolean 说明：
true 表示正在播放，false 表示未播放。seekToTime
描述
跳转到指定时间点进行预览（seek）。
接口
void seekToTime(long timeUs, boolean isInAccurate)参数
参数名 | 类型 | 说明 |
timeUs | long | 跳转的目标时间（us）。 |
isInAccurate | boolean | 是否开启非精准 seek： true 跳至临近关键帧，false 精准到指定位置。 |
返回值
类型：
void 说明：无返回值。
setClipRotation
描述
设置指定视频片段的旋转角度（顺时针方向）。
接口
void setClipRotation(int clipIndex, @FloatRange(from = 0, to = 360f) float degrees)参数
参数名 | 类型 | 说明 |
clipIndex | int | 视频片段索引。 |
degrees | float | 旋转角度，范围 0–360（度数）。 |
返回值
类型：
void 说明：无返回值。
setClipRect
描述
设置指定视频片段的裁剪区域。
rectF 为相对于渲染尺寸归一化后的裁剪矩形。接口
void setClipRect(int clipIndex, RectF rectF)参数
参数名 | 类型 | 说明 |
clipIndex | int | 视频片段索引。 |
rectF | RectF | 相对渲染尺寸归一化的裁剪区域矩形。 |
返回值
类型：
void 说明：无返回值。
setCustomVideoProcessListener
描述
设置纹理处理回调，可在外部对渲染纹理进行二次处理（自定义特效等）。
接口
void setCustomVideoProcessListener(TAVCustomProcessListener listener)参数
参数名 | 类型 | 说明 |
listener | TAVCustomProcessListener | 自定义纹理处理回调。 |
返回值
类型：
void 说明：无返回值。
removeCustomVideoProcessListener
描述
移除自定义纹理处理回调。
接口
void removeCustomVideoProcessListener()参数
无
返回值
类型：
void 说明：无返回值。
addFilter
描述
添加一个滤镜效果。
接口
int addFilter(String lutPath, float strength, long startPts, long endPts)参数
参数名 | 类型 | 说明 |
lutPath | String | 滤镜素材路径（LUT 文件等）。 |
strength | float | 滤镜强度（0–1f）。 |
startPts | long | 生效开始时间（us）。 |
endPts | long | 生效结束时间（us）。 |
返回值
类型：
int 说明：滤镜的唯一 ID，可用于后续调整或删除。
setFilterStrength
描述
调整指定滤镜的强度。
接口
void setFilterStrength(int filterId, float strength)参数
参数名 | 类型 | 说明 |
filterId | int | 滤镜唯一 ID。 |
strength | float | 滤镜强度（0–1f）。 |
返回值
类型：
void 说明：无返回值。
removeFilter
描述
删除指定滤镜。
接口
void removeFilter(int filterId)参数
参数名 | 类型 | 说明 |
filterId | int | 滤镜唯一 ID。 |
返回值
类型：
void 说明：无返回值。
getStickerManager
描述
获取贴纸操作管理接口，用于添加、编辑、删除贴纸等操作。
接口
ITAVStickerManager getStickerManager()参数
无
返回值
说明：贴纸管理接口对象。
getPipManager
描述
获取画中画（PIP）操作管理接口。
接口
ITAVPipManager getPipManager()参数
无
返回值
说明：画中画管理接口对象。
setTransition
描述
为指定位置设置转场素材。
接口
int setTransition(int clipIndex, String path, long durationUS)参数
参数名 | 类型 | 说明 |
clipIndex | int | 转场所在位置（片段之间的索引）。 |
path | String | 转场资源路径。 |
durationUS | long | 转场持续时长（us）。 |
返回值
类型：
int 说明：转场素材 ID。
updateTransitionDuration
描述
更新指定转场的时长。
接口
void updateTransitionDuration(int transitionId, long durationUS)参数
参数名 | 类型 | 说明 |
transitionId | int | 转场 ID |
durationUS | long | 新的转场时长（us） |
返回值
类型：
void 说明：无返回值。
removeTransition
描述
删除指定转场效果。
接口
boolean removeTransition(int transitionId)参数
参数名 | 类型 | 说明 |
transitionId | int | 转场 ID |
返回值
类型：
boolean 说明：删除是否成功。
addMotionEffect
描述
添加一段动效（特效）到时间线中。
接口
int addMotionEffect(String path, long startOffset, long duration)参数
参数名 | 类型 | 说明 |
path | String | 动效素材路径 |
startOffset | long | 生效开始时间偏移（us） |
duration | long | 播放时长（us） |
返回值
类型：
int 说明：动效唯一 ID。
addMotionEffect
描述
添加一段动效，并指定缩放模式。
接口
int addMotionEffect(String path, long startOffset, long duration, int scaleMode)参数
参数名 | 类型 | 说明 |
path | String | 动效素材路径 |
startOffset | long | 生效开始时间偏移（us） |
duration | long | 播放时长（us） |
scaleMode | int | 缩放模式 |
返回值
类型：
int 说明：动效唯一 ID。
updateMotionEffectPlayRange
描述
调整已有动效的播放时间范围。
接口
void updateMotionEffectPlayRange(int motionId, long startOffset, long duration)参数
参数名 | 类型 | 说明 |
motionId | int | 动效唯一 ID |
startOffset | long | 生效开始时间偏移（us） |
duration | long | 播放时长（us） |
返回值
类型：
void 说明：无返回值。
removeMotionEffect
描述
删除指定动效。
接口
void removeMotionEffect(int motionId)参数
参数名 | 类型 | 说明 |
motionId | int | 动效唯一 ID |
返回值
类型：
void 说明：无返回值。
getFrameAtTime
描述
获取某一时间点的渲染结果（单帧），异步返回。
接口
void getFrameAtTime(long positionUs, int longSideLength, int scene, TAVGetFrameListener listener)参数
参数名 | 类型 | 说明 |
positionUs | long | 时间点（us） |
longSideLength | int | 输出图片的最长边长度，内部会按比例计算另一边 |
scene | int（@RenderScene） | 渲染场景，参考 TAVEditorConstants.SCENE_PLAY 等 |
listener | TAVGetFrameListener | 获取结果回调 |
返回值
类型：
void 说明：无返回值，结果通过回调返回。
getFrameProvider
描述
获取渲染帧提供器，可用于按需生成多帧画面。
接口
ITAVFrameProvider getFrameProvider(int longSideLength, @TAVEditorConstants.RenderScene int scene)参数
参数名 | 类型 | 说明 |
longSideLength | int | 输出帧的长边长度，会按渲染比例缩放到长边对齐 |
scene | int（@RenderScene） | 渲染场景，参考 TAVEditorConstants.SCENE_PLAY 等 |
返回值
类型：
ITAVFrameProvider（可为 null） 说明：帧生成器对象，用于按时间获取渲染结果。
generateVideo
描述
按预设导出质量档位导出视频。
接口
void generateVideo(int level, String outputPath, TAVEditorGenerateListener listener)参数
参数名 | 类型 | 说明 |
level | int（@GenerateLevel） | 导出质量等级（360P / 480P / 540P / 720P / 1080P 等） |
outputPath | String | 导出文件路径 |
listener | 导出过程回调（进度、完成、错误等） |
返回值
类型：
void 说明：无返回值，导出结果通过回调返回。
generateVideo
描述
使用自定义配置导出视频，可设置分辨率、帧率、码率、Profile 等参数。
接口
void generateVideo(TAVEditorGenerateConfig config, String outputPath, TAVEditorGenerateListener listener)参数
参数名 | 类型 | 说明 |
config | 导出配置，如 width/height/frameRate/videoBitRate/profile 等 | |
outputPath | String | 导出文件路径 |
listener | 导出过程回调 |
返回值
类型：
void 说明：无返回值，导出结果通过回调返回。
cancelGenerate
描述
取消当前正在进行的视频导出任务。
接口
void cancelGenerate()参数
无
返回值
类型：
void 说明：无返回值。
flushImmediately
描述
立即刷新编辑器内部状态和渲染结果，用于确保修改实时生效。
接口
void flushImmediately()参数
无
返回值
类型：
void 说明：无返回值。
flushImmediately
描述
立即刷新编辑器内部状态，并在刷新完成后执行指定回调。
接口
void flushImmediately(@Nullable String tag, @Nullable TAVConsumer<String> callback)参数
参数名 | 类型 | 说明 |
tag | String（可为 null） | 当前刷新操作的标记 |
callback | TAVConsumer\\<String>（可为 null） | 刷新完成后回调执行的任务，参数为 tag |
返回值
类型：
void 说明：无返回值。
getDraftManager
描述
获取草稿管理接口，可用于保存、读取当前编辑工程的草稿。
接口
TAVDraftManager getDraftManager()参数
无
返回值
类型：
TAVDraftManager 说明：草稿管理接口对象。
ITAVThumbProvider
抽帧器操作接口。
API | 描述 |
设置抽帧输入源，传入视频路径和目标抽帧尺寸的最长边；若 longSide < 16，则按视频原始分辨率抽帧。 | |
按时间间隔批量抽帧，根据给定间隔（微秒）从视频中提取连续帧，通过回调返回结果。 | |
按指定时间点列表批量抽帧，结合颗粒度（秒/帧）从 ptsList 对应位置提取帧，通过回调返回结果。 | |
获取指定时间点（微秒）的单帧图像，结合颗粒度（秒/帧）抽取对应帧，通过回调返回结果。 | |
从内存或磁盘缓存中获取指定视频、时间点、尺寸和颗粒度对应的已缓存帧，可能返回空。 | |
将某一时间点、指定尺寸与颗粒度对应的帧图像缓存到内存/磁盘，用于后续快速读取。 | |
获取当前视频的时长，单位为微秒（us）。 | |
请求停止当前正在进行的抽帧任务。 | |
释放抽帧相关资源，清理内部状态。 |
setDataSource
描述
设置抽帧的输入视频源及目标缩略图尺寸。
当
longSide 小于 MIN_LONG_SIDE 时，会按视频原始分辨率进行抽帧。 接口
void setDataSource(String videoPath, int longSide)参数
参数名 | 类型 | 说明 |
videoPath | String | 视频文件路径 |
longSide | int | 目标抽帧尺寸的最长边长度，若小于 MIN_LONG_SIDE 则使用原始分辨率抽帧 |
返回值
类型：
void 说明：无返回值，仅配置抽帧输入源与目标尺寸。
getFramesInterval
描述
按照固定时间间隔抽取缩略图帧。
会从当前数据源视频中，按给定的时间间隔（微秒）依次抽帧，并通过回调返回。
接口
void getFramesInterval(long intervalUs, FrameExtractingCallback callback)参数
参数名 | 类型 | 说明 |
intervalUs | long | 抽帧时间间隔（单位：微秒） |
callback | FrameExtractingCallback | 抽帧结果回调接口 |
返回值
类型：
void 说明：无返回值，抽帧结果通过回调异步返回。
getFrames
描述
按照指定时间点列表批量抽取缩略图帧。
支持传入多个时间点
ptsList，并指定一个“颗粒度（granularity）”用于控制帧间隔精度。 接口
void getFrames(List<Long> ptsList, float granularity, FrameExtractingCallback callback)参数
参数名 | 类型 | 说明 |
ptsList | List\\<Long> | 需要抽帧的时间点列表（单位：微秒） |
granularity | float | 颗粒度，代表多少秒一帧，用于控制抽帧间隔的精度/容差 |
callback | FrameExtractingCallback | 抽帧结果回调接口 |
返回值
类型：
void 说明：无返回值，所有指定时间点的帧会通过回调批量异步返回。
getFrameAtTime
描述
抽取指定时间点的一帧缩略图。
可通过
granularity 控制帧间隔精度，用于在时间附近选择合适的关键帧。 接口
void getFrameAtTime(long pts, float granularity, FrameExtractingCallback callback)参数
参数名 | 类型 | 说明 |
pts | long | 目标抽帧时间点（单位：微秒） |
granularity | float | 颗粒度，代表多少秒一帧，用于控制抽帧间隔的精度/容差 |
callback | FrameExtractingCallback | 抽帧结果回调接口 |
返回值
类型：
void 说明：无返回值，指定时间点的帧会通过回调异步返回。
getCacheFrame
描述
从内存或磁盘缓存中获取指定视频在指定时间点的抽帧结果。
若缓存中不存在对应帧，则返回
null。 接口
Bitmap getCacheFrame(String path, long pts, int longSide, float granularity)参数
参数名 | 类型 | 说明 |
path | String | 视频路径，与抽帧时的输入路径保持一致 |
pts | long | 目标时间点（单位：微秒） |
longSide | int | 抽帧目标长边，与抽帧时使用的 longSide 一致 |
granularity | float | 颗粒度，与抽帧时使用的 granularity 一致 |
返回值
类型：
Bitmap 说明：命中缓存时返回对应时间点的帧图像；若缓存不存在则返回
null。saveCacheFrame
描述
将抽帧结果保存到缓存（内存或磁盘），以便后续通过
getCacheFrame 快速复用。 接口
void saveCacheFrame(String path, Bitmap bmp, long pts, int longSide, float granularity)参数
参数名 | 类型 | 说明 |
path | String | 视频路径 |
bmp | Bitmap | 需要缓存的帧图像 |
pts | long | 该帧对应的时间点（单位：微秒） |
longSide | int | 抽帧目标长边尺寸 |
granularity | float | 抽帧颗粒度，用于缓存索引区分不同精度的抽帧结果 |
返回值
类型：
void 说明：无返回值，仅负责写入缓存。
getDuration
描述
获取当前数据源视频的总时长。
接口
long getDuration()参数
无
返回值
类型：
long 说明：视频总时长，单位为微秒（us）。
requestStop
描述
请求停止当前正在进行的抽帧任务。
可用于用户取消操作或页面销毁时中断耗时任务。
接口
void requestStop()参数
无
返回值
类型：
void 说明：无返回值，调用后正在执行的抽帧过程会尝试尽快终止。
release
描述
释放抽帧相关资源。
应在不再需要使用该抽帧提供器时调用，以避免内存与系统资源泄露。
接口
void release()参数
无
返回值
类型：
void 说明：无返回值，调用后当前实例不应再继续使用。
ITAVStickerManager
贴纸操作相关接口。
API | 描述 |
创建一个贴纸对象，指定贴纸类型和贴纸资源路径，返回新建的 TAVSticker。 | |
加载一个贴纸并立即渲染到画面上。 | |
移除指定贴纸对象，立即生效。 | |
添加贴纸观察者，用于监听贴纸列表变化等事件。 | |
移除指定贴纸观察者。 | |
获取当前已加载的所有贴纸列表。 | |
通过贴纸 ID 获取对应的贴纸对象，不存在时返回 null。 | |
注册保底字体，当 PAG 未找到字体时优先回退到注册的字体列表，而不是系统字体，返回是否注册成功。 |
createSticker
描述
创建一个贴纸实例，但不会自动加入渲染队列，需配合
loadSticker 使用后才会显示在画面中。接口
TAVSticker createSticker(TAVSticker.TAVStickerType type, String stickerPath)参数
参数名 | 类型 | 说明 |
type | TAVSticker.TAVStickerType | 贴纸类型 |
stickerPath | String | 贴纸资源路径 |
返回值
类型：
TAVSticker 说明：新创建的贴纸对象实例，仅完成内存中对象构建，不会自动渲染。
loadSticker
描述
加载一个贴纸到当前编辑场景中，并立即参与渲染。
接口
void loadSticker(TAVSticker sticker)参数
参数名 | 类型 | 说明 |
sticker | TAVSticker | 要加载的贴纸对象 |
返回值
类型：
void 说明：无返回值，调用后贴纸立即加入渲染队列。
removeSticker
描述
从当前编辑场景中移除指定贴纸，操作立即生效。
接口
void removeSticker(TAVSticker sticker)参数
参数名 | 类型 | 说明 |
sticker | TAVSticker | 要移除的贴纸对象 |
返回值
类型：
void 说明：无返回值，调用后贴纸立即从渲染队列中移除。
addStickerObserver
描述
添加一个贴纸观察者，用于监听贴纸列表的变化（如新增、删除、更新等）。
接口
void addStickerObserver(ITAVStickerContextObserver observer)参数
参数名 | 类型 | 说明 |
observer | ITAVStickerContextObserver | 贴纸列表监听器 |
返回值
类型：
void 说明：无返回值。
removeStickerObserver
描述
移除已添加的贴纸观察者，取消对贴纸列表变化的监听。
接口
void removeStickerObserver(ITAVStickerContextObserver observer)参数
参数名 | 类型 | 说明 |
observer | ITAVStickerContextObserver | 要移除的监听器 |
返回值
类型：
void 说明：无返回值。
getStickers
描述
获取当前所有已加载的贴纸列表。
接口
List<TAVSticker> getStickers()参数
无
返回值
类型：
List<TAVSticker> 说明：当前场景中所有已加载贴纸对象的列表。
getSticker
描述
通过贴纸 ID 获取对应的贴纸对象。
接口
TAVSticker getSticker(int id)参数
参数名 | 类型 | 说明 |
id | int | 贴纸 ID |
返回值
类型：
TAVSticker 说明：指定 ID 对应的贴纸对象；如果贴纸不存在，则返回
null。registerFallbackFont
描述
注册保底字体。当 PAG 动画中未找到所需字体时，优先从注册的字体列表中回退查找，而不是直接使用系统字体，以保证模板显示效果更一致。
接口
boolean registerFallbackFont(String fontPath)参数
参数名 | 类型 | 说明 |
fontPath | String | 字体文件路径 |
返回值 | | |
类型：
boolean 说明：
true 表示注册成功，false 表示注册失败（例如路径无效或读取失败）。ITAVPipManager
画中画操作相关接口。
API | 描述 |
创建一个画中画对象，指定媒体类型和视频/图片路径，返回 TAVPip 实例。 | |
加载一个画中画并立即渲染到画面上。 | |
移除指定画中画对象，立即生效。 | |
添加画中画观察者，用于监听画中画列表变化等事件。 | |
移除指定画中画观察者。 | |
获取当前已加载的所有画中画列表。 | |
通过画中画 ID 获取对应的画中画对象，不存在时返回 null。 |
createPip
描述
创建一个画中画对象，但不会自动加入渲染队列。
接口
TAVPip createPip(TAVMediaType type, String mediaPath)参数
参数名 | 类型 | 说明 |
type | TAVMediaType | 资源类型（视频 / 图片等） |
mediaPath | String | 画中画媒体资源路径（视频或图片路径） |
返回值
类型：
TAVPip 说明：新创建的画中画对象实例，仅完成内存中对象构建，不会自动参与渲染。
loadPip
描述
加载一个画中画到当前编辑场景中，并立即参与渲染。
通常在通过
createPip 创建画中画对象之后调用。 接口
void loadPip(TAVPip pip)参数
参数名 | 类型 | 说明 |
pip | TAVPip | 要加载的画中画对象 |
返回值
类型：
void 说明：无返回值，调用后画中画立即加入渲染队列并显示在画面中。
removePip
描述
从当前编辑场景中移除指定画中画，操作立即生效。
接口
void removePip(TAVPip pip)参数
参数名 | 类型 | 说明 |
pip | TAVPip | 要移除的画中画对象 |
返回值
类型：
void 说明：无返回值，调用后画中画立即从渲染队列中移除。
addPipObserver
描述
添加一个画中画观察者，用于监听画中画列表的变化（如新增、删除、属性更新等）。
接口
void addPipObserver(ITAVPipContextObserver observer)参数
参数名 | 类型 | 说明 |
observer | ITAVPipContextObserver | 画中画列表监听器 |
返回值
类型：
void 说明：无返回值。
removePipObserver
描述
移除已添加的画中画观察者，取消对画中画列表变化的监听。
应与
addPipObserver 成对使用，避免内存泄漏。 接口
void removePipObserver(ITAVPipContextObserver observer)参数
参数名 | 类型 | 说明 |
observer | ITAVPipContextObserver | 要移除的监听器 |
返回值
类型：
void 说明：无返回值。
getPips
描述
获取当前所有已加载并参与渲染的画中画列表。
可用于遍历当前场景中的画中画状态或做批量操作。
接口
List<TAVPip> getPips()参数
无
返回值
类型：
List<TAVPip> 说明：当前场景中所有已加载画中画对象的列表；若无画中画则返回空列表。
getPip
描述
通过画中画 ID 获取对应的画中画对象。
适用于根据业务层保存的画中画 ID 快速定位实例。
接口
TAVPip getPip(int id)参数
参数名 | 类型 | 说明 |
id | int | 画中画 ID |
返回值
类型：
TAVPip 说明：指定 ID 对应的画中画对象；如果画中画不存在，则返回
null。TAVSticker
贴纸数据结构，包含了贴纸所需的相关信息。
API | 描述 |
设置贴纸进度处理器，用于外部自定义贴纸播放进度计算，返回当前 TAVSticker 支持链式调用。 | |
计算在指定时间点的贴纸播放进度（0~1），优先使用外部注册的进度处理器，否则根据时间范围与动画模式自动计算。 | |
设置贴纸文字内容，将新的 TAVStickerTextItem 替换原有文字图层内容。 | |
获取贴纸文字内容，返回当前的 TAVStickerTextItem，若不存在则返回 null。 | |
设置贴纸图片内容，将新的 TAVStickerImageItem 替换原有图片图层内容。 | |
获取贴纸图片内容，返回当前的 TAVStickerImageItem，若不存在则返回 null。 | |
获取贴纸动画持续时长，单位为微秒（us），内部基于 PAGFile.duration()。 | |
获取贴纸对应 PAG 资源的宽度，像素单位。 | |
获取贴纸对应 PAG 资源的高度，像素单位。 | |
获取文字区域相对于整个贴纸的偏移矩形区域，仅在文字贴纸（TEXT 类型）下有效。 | |
获取图片相对于整个贴纸的偏移矩形区域，仅在图片贴纸（IMAGE 类型）下有效。 | |
获取贴纸资源文件路径（本地路径或 assets 资源路径）。 | |
设置贴纸是否自动播放， true 自动循环播放，false 不自动播放，返回当前 TAVSticker 支持链式调用。 | |
获取当前贴纸是否开启自动播放标志。 | |
获取贴纸类型，如动画贴纸、文字贴纸、图片贴纸等。 | |
设置贴纸层级，从 0 开始，数值越大层级越高，返回当前 TAVSticker 支持链式调用。 | |
获取贴纸当前的层级索引，从 0 开始，数值越大层级越高。 | |
获取贴纸动画播放模式（循环、播放到最后一帧静止、拉伸时长等）。 | |
设置贴纸动画播放模式，并同步更新内部 PAG 的 TimeStretch 模式。 | |
获取贴纸当前是否可见。 | |
设置贴纸是否可见，控制贴纸在渲染结果中的显示与否。 | |
设置贴纸的生效时间区间，并将时间范围同步到内部 PAG 图层，返回当前 TAVSticker 支持链式调用。 | |
设置贴纸在画布中的位置，支持传入 PointF 或 x/y 坐标，返回当前 TAVSticker 支持链式调用。 | |
设置贴纸整体缩放比例，返回当前 TAVSticker 支持链式调用。 | |
设置贴纸允许的最小缩放比例，返回当前 TAVSticker 支持链式调用。 | |
设置贴纸允许的最大缩放比例，返回当前 TAVSticker 支持链式调用。 | |
设置贴纸旋转角度，单位为度，返回当前 TAVSticker 支持链式调用。 | |
设置贴纸是否可编辑（是否响应手势等交互），返回当前 TAVSticker 支持链式调用。 | |
克隆当前贴纸对象， clone() 为默认浅拷贝，内部调用 clone(boolean deep)。 | |
克隆当前贴纸对象， clone(boolean deep) 可控制是否对文字、图片图层做深拷贝。 |
setProgressHandler
描述
设置贴纸进度处理器，用于外部自定义贴纸的播放进度计算逻辑。
设置后，在渲染时会优先调用外部提供的
ITAVStickerProgressHandler。接口
public TAVSticker setProgressHandler(ITAVStickerProgressHandler progressHandler)参数
参数名 | 类型 | 说明 |
progressHandler | ITAVStickerProgressHandler | 自定义贴纸进度处理器回调接口 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。computeProgress
描述
计算在给定时间点下贴纸的播放进度。
若设置了
progressHandler，则优先调用其 computeProgress，否则按照贴纸时长、时间范围及 animationMode 自动计算： 默认模式循环播放；
FREEZE 播放至最后一帧后静止； SCALE_UP 在用户选择时长大于原始时长时以慢速播放。接口
public double computeProgress(long presentationTimeUs)参数
参数名 | 类型 | 说明 |
presentationTimeUs | long | 当前时间点（单位：微秒） |
返回值
类型：
double 说明：贴纸播放进度，范围为 [0.0, 1.0]。
setTextItem
描述
设置贴纸的文字内容。
内部会保持原有文字图层的
layerIndex，仅替换文字内容数据。接口
public void setTextItem(TAVStickerTextItem textItem)参数
参数名 | 类型 | 说明 |
textItem | TAVStickerTextItem | 文本内容对象 |
返回值
类型：
void 说明：无返回值。
getTextItem
描述
获取贴纸当前的文字内容对象。
若贴纸中不包含文本图层或读取失败，则返回
null。接口
public TAVStickerTextItem getTextItem()参数
无
返回值
类型：
TAVStickerTextItem 说明：当前贴纸的文本内容对象；若不存在文本图层则返回
null。setImageItem
描述
设置贴纸的图片内容。
内部会保持原有图片图层的
layerIndex，仅替换图片内容数据。接口
public void setImageItem(TAVStickerImageItem imageItem)参数
参数名 | 类型 | 说明 |
imageItem | TAVStickerImageItem | 图片内容对象 |
返回值
类型：
void 说明：无返回值。
getImageItem
描述
获取贴纸当前的图片内容对象。
若贴纸中不包含图片图层或读取失败，则返回
null。接口
public TAVStickerImageItem getImageItem()参数
无
返回值
类型：
TAVStickerImageItem 说明：当前贴纸的图片内容对象；若不存在图片图层则返回
null。durationTime
描述
获取贴纸动画的持续时长。
接口
public long durationTime()参数
无
返回值
类型：
long 说明：贴纸动画的总时长（单位：微秒）。若
pagFile 为空则返回 0。getWidth
描述
获取贴纸对应 PAG 资源的宽度。
接口
public int getWidth()参数
无
返回值
类型：
int 说明：PAG 文件的宽度（像素）。若
pagFile 为空则返回 0。getHeight
描述
获取贴纸对应 PAG 资源的高度。
接口
public int getHeight()参数
无
返回值
类型：
int 说明：PAG 文件的高度（像素）。若
pagFile 为空则返回 0。getTextOffsetRect
描述
获取文本图层相对于整个贴纸内容的偏移矩形区域。
仅在贴纸类型为
TAVStickerType.TEXT 时有效；其他类型返回 null。 内部会在必要时通过新建
PAGPlayer 来规避可见区域为 0 的情况。接口
public RectF getTextOffsetRect()参数
无
返回值
类型：
RectF 说明：文本相对于 PAG 画布的偏移矩形；若贴纸类型不是文本或数据无效则返回
null。getImageOffsetRect
描述
获取图片内容相对于整个贴纸内容的偏移矩形区域。
内部会根据图片宽高与 PAG 尺寸进行等比缩放与居中，计算最终在 PAG 中的包围矩形。
仅在贴纸类型为
TAVStickerType.IMAGE 且图片有效时返回有效矩形。接口
public RectF getImageOffsetRect()参数
无
返回值
类型：
RectF 说明：图片相对于 PAG 画布的偏移矩形；若类型不是图片贴纸或图片无效则返回
null。getPath
描述
获取贴纸资源文件路径。
接口
public String getPath()参数
无
返回值
类型：
String 说明：贴纸资源（*.pag 文件）的路径，可为本地路径或 assets 下资源路径。
setAutoPlay
描述
设置贴纸是否自动播放。
接口
public TAVSticker setAutoPlay(boolean autoPlay)参数
参数名 | 类型 | 说明 |
autoPlay | boolean | true 表示自动播放，false 表示不自动播放 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。isAutoPlay
描述
获取当前贴纸是否自动播放。
接口
public boolean isAutoPlay()参数
无
返回值
类型：
boolean 说明：
true 表示自动播放，false 表示不自动播放。getType
描述
获取贴纸的类型。
接口
public TAVStickerType getType()参数
无
返回值
类型：
TAVStickerType 说明：贴纸类型枚举，如
MOTION、TEXT、IMAGE。setLayerIndex
描述
设置贴纸的层级信息。
从 0 开始，数值越大层级越高，显示时越靠上。
接口
public TAVSticker setLayerIndex(int layerIndex)参数
参数名 | 类型 | 说明 |
layerIndex | int | 贴纸层级索引 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。getLayerIndex
描述
获取贴纸层级信息。
接口
public int getLayerIndex()参数
无
返回值
类型：
int 说明：贴纸层级，从 0 开始，数值越大层级越高。
getAnimationMode
描述
获取贴纸动画播放方式。
接口
public TAVStickerAnimationMode getAnimationMode()参数
无
返回值
类型：
TAVStickerAnimationMode 说明：当前贴纸动画播放模式，如
DEFAULT（循环）、FREEZE（播放后静止）、SCALE_UP（慢放）。setAnimationMode
描述
设置贴纸动画播放方式，并同步更新内部 PAG 的时间拉伸模式。
接口
public void setAnimationMode(TAVStickerAnimationMode animationMode)参数
参数名 | 类型 | 说明 |
animationMode | TAVStickerAnimationMode | 贴纸动画播放模式 |
返回值
类型：
void 说明：无返回值。
isVisible
描述
获取贴纸当前是否可见。
接口
public boolean isVisible()参数
无
返回值
类型：
boolean 说明：
true 表示贴纸当前可见，false 表示不可见。setVisible
描述
设置贴纸是否可见。
接口
public void setVisible(boolean visible)参数
参数名 | 类型 | 说明 |
visible | boolean | 是否可见， true 为可见 |
返回值
类型：
void 说明：无返回值。
setTimeRange
描述
设置贴纸在时间线中的显示时间区间（覆盖父类同名方法）。
同时会将时间区间同步设置到内部
PAGFile 图层上。接口
@Override public TAVSticker setTimeRange(TAVTimeRange timeRange)参数
参数名 | 类型 | 说明 |
timeRange | TAVTimeRange | 贴纸在时间线上的时间范围 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。setPosition(PointF)
描述
设置贴纸在画布中的位置（覆盖父类同名方法），坐标为归一化坐标或具体坐标（取决于父类定义）。
接口
@Override public TAVSticker setPosition(PointF point)参数
参数名 | 类型 | 说明 |
point | PointF | 贴纸中心位置坐标 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。setPosition(float x, float y)
描述
通过 x、y 坐标设置贴纸在画布中的位置（覆盖父类同名方法）。
接口
@Override public TAVSticker setPosition(float x, float y)参数
参数名 | 类型 | 说明 |
x | float | X 坐标 |
y | float | Y 坐标 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。setScale
描述
设置贴纸整体缩放比例（覆盖父类同名方法）。
接口
@Override public TAVSticker setScale(float scale)参数
参数名 | 类型 | 说明 |
scale | float | 缩放比例因子 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。setMinScale
描述
设置贴纸允许的最小缩放比例（覆盖父类同名方法）。
接口
@Override public TAVSticker setMinScale(float minScale)参数
参数名 | 类型 | 说明 |
minScale | float | 最小缩放比例 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。setMaxScale
描述
设置贴纸允许的最大缩放比例（覆盖父类同名方法）。
接口
@Override public TAVSticker setMaxScale(float maxScale)参数
参数名 | 类型 | 说明 |
maxScale | float | 最大缩放比例 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。setRotate
描述
设置贴纸旋转角度（覆盖父类同名方法）。
接口
@Override public TAVSticker setRotate(float rotate)参数
参数名 | 类型 | 说明 |
rotate | float | 旋转角度，单位：度 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。setEditable
描述
设置贴纸是否可编辑（覆盖父类同名方法）。
例如可否响应手势缩放、拖动、旋转等交互。
接口
@Override public TAVSticker setEditable(boolean editable)参数
参数名 | 类型 | 说明 |
editable | boolean | 是否允许编辑 |
返回值
类型：
TAVSticker 说明：返回当前
TAVSticker 实例，便于链式调用。clone
描述
克隆当前贴纸对象，创建一个新的
TAVSticker 实例。 等价于调用
clone(false)，即浅拷贝文本与图片项引用。接口
@Override public TAVSticker clone()参数
无
返回值
类型：
TAVSticker 说明：克隆后的贴纸对象，包含与原贴纸相同的基础属性与
PAGFile 内容。clone(boolean deep)
描述
克隆当前贴纸对象，并可指定是否进行深拷贝。
当
deep == false 时：textList、imageList 引用与原对象共享； 当
deep == true 时：重新读取文本与图片图层，并逐项拷贝数据，形成独立副本。接口
public TAVSticker clone(boolean deep)参数
参数名 | 类型 | 说明 |
deep | boolean | 是否进行深拷贝： true 深拷贝，false 浅拷贝 |
返回值
类型：
TAVSticker 说明：克隆后的贴纸对象，包含时间范围、位置、缩放、旋转、可编辑状态等属性的拷贝。
TAVPip
画中画数据结构，包含了画中画所需的相关信息。
API | 描述 |
获取画中画资源文件路径。 | |
获取画中画对应的媒体类型（视频或图片）。 | |
获取画中画当前音量，范围为 [0, 3]。 | |
设置画中画音量，范围为 [0, 3]。 | |
获取画中画当前播放速度。 | |
设置画中画播放速度。 | |
获取画中画在主视频时间轴上的起始时间（单位：微秒）。 | |
设置画中画在主视频时间轴上的起始时间（单位：微秒）。 | |
获取画中画原始媒体时长（单位：微秒）。 | |
获取画中画源媒体的宽度（像素）。 | |
获取画中画源媒体的高度（像素）。 | |
设置画中画在时间轴上的生效区间，返回当前 TAVPip，支持链式调用。 | |
设置画中画在画布中的位置（支持传入 PointF 或 x/y 坐标），返回当前 TAVPip，支持链式调用。 | |
设置画中画的整体缩放比例，返回当前 TAVPip，支持链式调用。 | |
设置画中画允许的最小缩放比例，返回当前 TAVPip，支持链式调用。 | |
设置画中画允许的最大缩放比例，返回当前 TAVPip，支持链式调用。 | |
设置画中画旋转角度，返回当前 TAVPip，支持链式调用。 | |
设置画中画是否可编辑（是否响应手势等交互），返回当前 TAVPip，支持链式调用。 | |
克隆当前画中画对象，生成一个具有相同路径、时间区间、变换参数等属性的新 TAVPip 实例。 |
getPath
描述
获取当前画中画资源的路径。
接口
public String getPath()参数
无
返回值
类型：
String 说明：画中画媒体资源路径，一般为视频或图片的本地文件路径。
getMediaType
描述
获取画中画资源的媒体类型。
接口
public TAVMediaType getMediaType()参数
无
返回值
类型：
TAVMediaType 说明：画中画资源的媒体类型，例如视频、图片等。
getVolume
描述
获取当前画中画的音量。
接口
public float getVolume()参数
无
返回值
类型：
float 说明：画中画当前音量值，范围为 [0, 3]。1 表示原始音量。
setVolume
描述
设置画中画音量。
接口
public void setVolume(float volume)参数
参数名 | 类型 | 说明 |
volume | float | 画中画音量，范围为 [0, 3]，1 为原始音量 |
返回值
类型：
void 说明：无返回值。
getSpeed
描述
获取画中画的播放速度。
接口
public float getSpeed()参数
无
返回值
类型：
float 说明：画中画当前播放速度倍数。通常 1 为正常速度。
setSpeed
描述
设置画中画播放速度。
接口
public void setSpeed(float speed)参数
参数名 | 类型 | 说明 |
speed | float | 播放速度倍数，范围建议 [0, 1] |
返回值
类型：
void 说明：无返回值。
getStartAtVideoUs
描述
获取画中画在主视频时间线中的起始时间。
接口
public long getStartAtVideoUs()参数
无
返回值
类型：
long 说明：画中画在主视频中的开始时间，单位为微秒（us）。
setStartAtVideoUs
描述
设置画中画在主视频时间线中的起始时间。
接口
public void setStartAtVideoUs(long startAtVideoUs)参数
参数名 | 类型 | 说明 |
startAtVideoUs | long | 画中画在主视频中的开始时间，单位：微秒（us） |
返回值
类型：
void 说明：无返回值。
getOriginDuration
描述
获取画中画原始媒体的时长。
接口
public long getOriginDuration()参数
无
返回值
类型：
long 说明：画中画原始媒体时长（未剪裁前的时长），单位为微秒（us）。
getWidth
描述
获取画中画的宽度（像素）。
内部返回的是源媒体实际宽度。
接口
public int getWidth()参数
无
返回值
类型：
int 说明：画中画媒体宽度（像素）。
getHeight
描述
获取画中画的高度（像素）。
内部返回的是源媒体实际高度。
接口
public int getHeight()参数
无
返回值
类型：
int 说明：画中画媒体高度（像素）。
setTimeRange
描述
设置画中画在时间线上的显示时间区间。
会覆盖父类中对应实现，并返回当前
TAVPip 以支持链式调用。接口
public TAVPip setTimeRange(TAVTimeRange timeRange)参数
参数名 | 类型 | 说明 |
timeRange | TAVTimeRange | 画中画在时间线中的时间范围 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。setPosition(PointF)
描述
设置画中画在画布中的位置（中心点位置），使用
PointF 指定。接口
public TAVPip setPosition(PointF point)参数
参数名 | 类型 | 说明 |
point | PointF | 画中画中心位置坐标 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。setPosition(float x, float y)
描述
通过 x、y 坐标设置画中画在画布中的位置（中心点）。
接口
public TAVPip setPosition(float x, float y)参数
参数名 | 类型 | 说明 |
x | float | X 坐标 |
y | float | Y 坐标 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。setScale
描述
设置画中画整体缩放比例。
接口
public TAVPip setScale(float scale)参数
参数名 | 类型 | 说明 |
scale | float | 缩放比例因子 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。setMinScale
描述
设置画中画允许的最小缩放比例。
接口
public TAVPip setMinScale(float minScale)参数
参数名 | 类型 | 说明 |
minScale | float | 最小缩放比例 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。setMaxScale
描述
设置画中画允许的最大缩放比例。
接口
public TAVPip setMaxScale(float maxScale)参数
参数名 | 类型 | 说明 |
maxScale | float | 最大缩放比例 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。setRotate
描述
设置画中画的旋转角度。
接口
public TAVPip setRotate(float rotate)参数
参数名 | 类型 | 说明 |
rotate | float | 旋转角度，单位：度 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。setEditable
描述
设置画中画是否可编辑，例如是否响应拖动、缩放、旋转等交互。
接口
public TAVPip setEditable(boolean editable)参数
参数名 | 类型 | 说明 |
editable | boolean | 是否允许编辑 |
返回值
类型：
TAVPip 说明：返回当前
TAVPip 实例，便于链式调用。clone
描述
克隆当前画中画对象，创建一个新的
TAVPip 实例。 会拷贝时间范围、路径、音量、缩放、旋转、位置、可编辑状态等属性。
接口
public TAVPip clone()参数
无
返回值
类型：
TAVPip 说明：克隆后的画中画对象，内部共享或拷贝的字段与当前实例保持一致（注意
extraInfo 为同一引用）。TAVDraftManager
草稿操作相关接口。
API | 描述 |
设置草稿保存目录路径，后续所有草稿读写都会使用该目录。 | |
读取当前草稿保存目录下的所有草稿列表，并按时间倒序排序返回。 | |
删除指定草稿对象对应的草稿文件及目录，返回是否删除成功。 | |
删除当前草稿保存目录下的所有草稿文件及目录，返回是否删除成功。 | |
保存当前编辑状态为草稿，使用给定封面图路径，返回生成的草稿路径，失败时返回 null。 | |
加载指定草稿对象，加载完成后通过 DraftLoadingCallback 回调草稿加载结果。 | |
设置草稿状态监听器，用于监听是否可撤销、可重做等草稿状态变化。 | |
重置草稿记录，从头开始记录草稿变更历史。 | |
提交一次草稿快照，如果自上次提交以来效果未发生变化，则本次提交不生效，返回是否生效。 | |
判断当前是否存在可撤销的草稿记录。 | |
判断当前是否存在可重做的草稿记录。 | |
获取当前的草稿模型实例 TAVDraft。 | |
设置草稿组件变更监听器，当草稿中的 TAVDraftComponent 发生变化时回调通知。 |
setDraftStorageDir
描述
设置草稿保存目录的根路径。
若传入路径末尾未包含文件分隔符（
File.separator），内部会自动追加。接口
public static void setDraftStorageDir(String storageDir)参数
参数名 | 类型 | 说明 |
storageDir | String | 草稿保存根目录的绝对路径 |
返回值
类型：
void 说明：无返回值。
readDraftList
描述
读取当前草稿存储目录下的所有草稿记录。
会自动过滤无效目录，并按时间戳倒序排序（最近的草稿排在最前）。
接口
public static List<TAVDraft> readDraftList()参数
无
返回值
类型：
List<TAVDraft> 说明：返回已解析的草稿列表；当目录不存在或无有效草稿时，返回空列表。
deleteDraft
描述
删除指定草稿对象及其对应的本地目录。
接口
public static boolean deleteDraft(TAVDraft draft)参数
参数名 | 类型 | 说明 |
draft | TAVDraft | 需要删除的草稿对象 |
返回值
类型：
boolean 说明：删除操作是否执行成功；当
draft == null 时直接返回 false。deleteAllDrafts
描述
删除当前草稿存储目录下的所有草稿数据。
接口
public static boolean deleteAllDrafts()参数
无
返回值
类型：
boolean 说明：删除操作是否执行成功。
generateDraft
描述
保存当前编辑状态为一条草稿记录，并生成对应的草稿目录与描述信息。
需在具体实现类中完成序列化逻辑。
接口
public abstract String generateDraft(String thumbPath)参数
参数名 | 类型 | 说明 |
thumbPath | String | 草稿封面图文件的路径 |
返回值
类型：
String 说明：成功保存时返回草稿目录路径；若保存失败则返回
null。loadDraft
描述
从指定草稿对象加载草稿内容，并恢复到当前编辑器/工程中。
接口
public abstract void loadDraft(TAVDraft draft, DraftLoadingCallback callback)参数
参数名 | 类型 | 说明 |
draft | TAVDraft | 需要加载的草稿对象 |
callback | 草稿加载过程与结果回调 |
返回值
类型：
void 说明：无返回值，结果通过回调异步通知。
setDraftStateListener
描述
设置草稿状态监听器，用于监控草稿相关的生命周期事件（如保存、恢复、清理等）。
接口
public abstract void setDraftStateListener(DraftStateListener listener)参数
参数名 | 类型 | 说明 |
listener | 草稿状态监听器实现 |
返回值
类型：
void 说明：无返回值。
resetDraftRecord
描述
重置当前草稿记录链路，清空历史的操作记录缓存。
通常在开始一个新的编辑会话或重新进入工程时调用。
接口
public abstract void resetDraftRecord()参数
无
返回值
类型：
void 说明：无返回值。
commit
描述
提交一次草稿快照，记录当前编辑状态。
如果自上一次提交以来编辑状态没有发生变化，则本次提交不会生效。
接口
public abstract boolean commit(String tag)参数
参数名 | 类型 | 说明 |
tag | String | 本次提交的标记字符串 |
返回值
类型：
boolean 说明：本次提交是否真实生效，
true 表示生成了新的草稿记录，false 表示状态未变化未生成新记录。canUndo
描述
判断当前是否存在可撤销的草稿操作记录。
接口
public abstract boolean canUndo()参数
无
返回值
类型：
boolean 说明：
true 表示当前可以执行撤销操作，false 表示无可撤销记录。canRedo
描述
判断当前是否存在可回退（重做）的草稿操作记录。
接口
public abstract boolean canRedo()参数
无
返回值
类型：
boolean 说明：
true 表示当前可以执行回退/重做操作，false 表示无可回退记录。undo
描述
执行一次撤销操作，将编辑状态回滚到上一个草稿记录。
操作结果通过
DraftActionCallback 回调通知。接口
public abstract void undo(DraftActionCallback callback)参数
参数名 | 类型 | 说明 |
callback | 撤销动作结果回调 |
返回值
类型：
void 说明：无返回值，撤销结果通过回调异步通知。
redo
描述
执行一次回退（重做）操作，将编辑状态前进到下一条草稿记录。
接口
public abstract void redo(DraftActionCallback callback)参数
参数名 | 类型 | 说明 |
callback | 回退动作结果回调 |
返回值
类型：
void 说明：无返回值，回退结果通过回调异步通知。
getCurrentDraft
描述
获取当前编辑状态对应的草稿模型对象。
通常用于展示当前草稿信息或与外部业务同步。
接口
public abstract TAVDraft getCurrentDraft()参数
无
返回值
类型：
TAVDraft 说明：当前编辑状态对应的草稿实例。
setDraftComponentObserver
描述
设置草稿组件变更的监听器，用于监听草稿内部组件（如轨道、特效、素材等）的变更事件。
接口
public abstract void setDraftComponentObserver(DraftComponentObserver observer)参数
参数名 | 类型 | 说明 |
observer | 草稿组件变更监听器实例 |
返回值
类型：
void 说明：无返回值。
DraftStateListener
草稿状态回调
onUndoStateChange
描述
草稿撤销能力状态回调。当当前是否可撤销的状态发生变化时触发，用于更新 UI 状态（例如撤销按钮的可用性）。
接口
void onUndoStateChange(boolean canUndo)参数
参数名 | 类型 | 说明 |
canUndo | boolean | 当前是否存在可撤销的操作记录状态 |
返回值
类型：
void 说明：无返回值，通过回调通知状态变化。
onRedoStateChange
描述
草稿重做能力状态回调。当当前是否可重做的状态发生变化时触发，用于更新 UI 状态（例如重做按钮的可用性）。
接口
void onRedoStateChange(boolean canRedo)参数
参数名 | 类型 | 说明 |
canRedo | boolean | 当前是否存在可重做的操作记录状态 |
返回值
类型：
void 说明：无返回值，通过回调通知状态变化。
DraftActionCallback
草稿撤销/重做回调。
onCheckoutDraft
描述
在执行撤销或重做操作时回调该方法，用于通知业务侧当前已切换到哪一次草稿提交，以及本次切换过程中发生了哪些差异。
接口
void onCheckoutDraft(String tag, TAVDiffResult diffResult)参数
参数名 | 类型 | 说明 |
tag | String | 提交草稿时传入的标记（TAG），用于区分不同提交 |
diffResult | TAVDiffResult | 本次切换草稿时发生的变更结果模型 |
返回值
类型：
void 说明：无返回值，通过回调告知调用方草稿切换结果与差异信息。
onError
描述
在撤销或重做过程中发生错误时回调该方法，用于通知业务侧进行错误处理或兜底提示。
接口
void onError(int errorCode)参数
参数名 | 类型 | 说明 |
errorCode | int | 错误码，用于标识具体错误类型 |
返回值
类型：
void 说明：无返回值，通过回调告知调用方出现异常场景。
DraftLoadingCallback
加载草稿回调。
onDraftLoadingFinished
描述
草稿加载完成时的回调方法。
在调用
loadDraft 进行草稿恢复操作结束后触发，用于通知业务侧本次草稿加载的结果状态及相关信息。 接口
void onDraftLoadingFinished(DraftLoadingResult result)参数
参数名 | 类型 | 说明 |
result | 草稿加载结果模型，包含本次加载是否成功及附加信息 |
返回值
类型：
void 说明：无返回值，通过回调向调用方告知草稿加载结果。
DraftComponentObserver
草稿组件变化监听。
onComponentUpdate
描述
草稿组件变化监听回调。
当草稿中的任意一个
TAVDraftComponent 发生变化（新增、删除、更新等）时，都会触发该方法，用于通知业务侧进行 UI 刷新或状态同步。接口
void onComponentUpdate(TAVDraftComponent component)参数
参数名 | 类型 | 说明 |
component | TAVDraftComponent | 发生变化的草稿组件实例 |
返回值
类型：
void 说明：无返回值，通过回调通知外部草稿组件变更事件。
DraftLoadingResult
草稿加载结果数据模型，用于封装一次草稿加载操作过程中产生的错误信息与差异结果。
isSuccess
描述
判断本次草稿加载是否成功。
当
errors == null 或 errors.length == 0 时视为加载成功。接口
public boolean isSuccess()参数
无
返回值
类型：
boolean 说明：
true 表示本次草稿加载无错误；false 表示加载过程中存在至少一个组件加载错误。TAVEditorGenerateListener
导出视频监听。
onGenerateStarted
描述
开始导出视频任务时回调，用于通知业务层导出流程已启动（可用于更新 UI 状态，如显示加载对话框、禁用编辑操作等）。
接口
void onGenerateStarted()参数
无
返回值
类型：
void 说明：无返回值，仅作为导出开始的事件通知。
onGenerateProgress
描述
导出过程中的进度回调。
进度以
0-1f 的浮点数形式返回，调用频率由内部导出流程控制。 接口
void onGenerateProgress(float progress)参数
参数名 | 类型 | 说明 |
progress | float | 导出进度，范围为 0.0-1.0 |
返回值
类型：
void 说明：无返回值，业务层可根据进度更新进度条等 UI。
onGenerateCompleted
描述
导出流程正常结束时回调（无论结果是成功还是失败，通常由
TAVEditorGenerateResult 中的状态字段区分）。 接口
void onGenerateCompleted(TAVEditorGenerateResult result)参数
参数名 | 类型 | 说明 |
result | TAVEditorGenerateResult | 导出结果数据模型，如导出文件路径、状态码等 |
返回值
类型：
void 说明：无返回值，业务层可在该回调中处理导出结果（如保存路径、提示用户等）。
onGenerateCanceled
描述
导出任务被取消时回调（例如用户主动取消或上层逻辑中断导出流程）。
接口
void onGenerateCanceled()参数
无
返回值
类型：
void 说明：无返回值，业务层可在该回调中恢复 UI 状态或进行清理操作。
TAVEditorGenerateConfig
自定义导出配置总结构体，包含视频配置
VideoConfig 与音频配置 AudioConfig。 用于
TAVEditor.generateVideo(TAVEditorGenerateConfig config, String outputPath, TAVEditorGenerateListener listener) 接口，实现对导出分辨率、帧率、码率、声道数等参数的精细控制。VideoConfig
描述
视频导出配置项，用于控制导出分辨率、帧率、视频码率以及编码 Profile 等参数。
在使用
TAVEditorGenerateConfig 自定义导出配置时，通过修改该对象的字段来调整视频输出质量和时长约束。参数
参数名 | 类型 | 说明 |
width | int | 导出视频宽度（像素），默认值为 720。 |
height | int | 导出视频高度（像素），默认值为 1280。 |
frameRate | int | 导出视频帧率（FPS），默认值为 30。 |
videoBitRate | int | 视频码率（bps，bit per second），默认值约为 720 * 1280 * 30 * 0.08，比特率因子推荐范围 0.05~0.1。 |
profile | VideoConfig.Profile | H.264 编码 Profile，默认 H264_BASE，可选：H264_BASE / H264_HIGH。 |
maxGenerateDuration | long | 最大导出时长（微秒），超过该时长的内容会被裁剪；默认值为 -1 表示不限制。 |
minGenerateDuration | long | 最小导出时长（微秒），小于该时长会报错；默认值为 -1 表示不限制。 |
AudioConfig
描述
音频导出配置项，控制导出音频的声道数、采样率以及音频比特率。
SDK 使用 AAC 格式进行音频编码，位深固定为 16bit。
参数
参数名 | 类型 | 说明 |
channelCount | int | 声道数，默认值为 1，可选：单声道（1）、立体声（2）。 |
sampleRate | int | 采样率（Hz），默认值为 44100。 |
audioBitRate | int | 音频比特率（bps），默认值为 128000（约 128kbps）；未压缩比特率 = 采样率 × 位深 × 声道数。 |
TAVPreviewListener
播放器预览进度监听。
onPreviewProgress
描述
预览播放进度回调。
在视频预览播放过程中被周期性调用，用于通知当前播放到的时间位置。
接口
void onPreviewProgress(long time)参数
参数名 | 类型 | 说明 |
time | long | 当前预览时间，单位：us（微秒） |
返回值
类型：
void 说明：无返回值，通过回调告知当前预览播放进度。
onStatusChanged
描述
预览播放器状态变化回调。
当预览播放器的状态（如播放、暂停、完成等）发生变化时触发，用于驱动 UI 更新或业务逻辑处理。
接口
void onStatusChanged(@Nullable TAVEditorConstants.EditorPlayerStatus status)参数
参数名 | 类型 | 说明 |
status | TAVEditorConstants.EditorPlayerStatus|null | 播放器当前状态；可能为 null 表示未知或未初始化 |
返回值
类型：
void 说明：无返回值，通过回调通知预览播放器状态变化。
TAVEditorConstants
视频编辑关键类型定义。
PreviewParam
描述
短视频预览参数配置结构体。
用于在初始化编辑器预览（例如
TAVEditor.initWithPreview(PreviewParam param)、TAVEditor.fork(PreviewParam param)）时指定预览容器、手势层、是否自动/循环播放、渲染场景以及预览渲染尺寸等。参数
参数名 | 类型 | 说明 |
videoView | FrameLayout | 用于承载视频预览画面的父容器 View，内部会在该容器中创建渲染 Surface 等 |
contentView | TAVWidgetContentView | 手势操作层 View，用于承载贴纸、画中画等可交互组件的触摸事件与显示 |
autoPlay | boolean | 是否在预览初始化完成后自动开始播放，默认值为 true |
loopPlay | boolean | 是否循环播放，播放到末尾后是否自动从头开始，默认值为 true |
scene | int ( @RenderScene) | 使用场景，默认 SCENE_PLAY SCENE_PLAY：预览场景 SCENE_EXPORT 导出场景 |
renderSize | Size|null | 指定渲染尺寸（宽高），若为 null 则由 SDK 根据输入素材与容器自动适配 |
RenderScene（SCENE_PLAY / SCENE_EXPORT）
描述
预览/渲染使用场景常量及对应注解，控制渲染链路在「预览」或「导出」场景下的行为。
参数
常量名 | 类型 | 说明 |
SCENE_PLAY | int | 预览场景，用于编辑页面实时预览、交互渲染 |
SCENE_EXPORT | int | 导出场景，用于离屏高质量渲染与视频导出 |
EditorPlayerStatus
描述
编辑器预览播放器状态枚举。
用于通过
TAVPreviewListener.onStatusChanged 回调通知业务方当前播放状态，以便更新 UI 和逻辑控制。参数
枚举值 | 说明 |
IDLE | 空闲状态，尚未准备或已释放 |
READY | 已准备好，可调用播放 |
PLAYING | 正在播放 |
STOPPED | 已停止播放 |
PAUSED | 已暂停播放 |
COMPLETED | 播放到预设区间末尾触发完成回调 |
FINISHED | 播放流程结束 |
ERROR | 播放过程中发生错误 |
REPLAY | 完成后重新开始播放（循环播放触发的状态） |
GenerateLevel（视频质量级别）
描述
短视频导出质量等级常量，用于快速按预设分辨率导出视频。
通常在
TAVEditor.generateVideo(@GenerateLevel int level, ...) 中作为导出质量参数传入。参数
常量名 | 类型 | 分辨率说明 |
VIDEO_LEVEL_480P | int | 压缩至 480P（640×480） |
VIDEO_LEVEL_540P | int | 压缩至 540P（960×540） |
VIDEO_LEVEL_720P | int | 压缩至 720P（1280×720） |
VIDEO_LEVEL_1080P | int | 压缩至 1080P（1920×1080） |
FillMode（画布背景填充模式）
描述
画布背景填充模式常量，用于在视频与画布比例不一致时控制背景的填充效果。
参数
常量名 | 类型 | 说明 |
FILL_MODE_GAUSSIAN_BLUR | int | 使用高斯模糊处理背景填充 |
FILL_MODE_SOLID_COLOR | int | 使用纯色背景填充画布 |
OpenGL 渲染线程常量
描述
控制渲染链路运行线程的常量，用于内部或高级用法区分预览/导出使用的 GL 线程。
参数
常量名 | 类型 | 说明 |
PREVIEW_GL_THREAD | int | 预览渲染使用的 GL 线程 |
GENERATE_GL_THREAD | int | 导出渲染使用的 GL 线程 |
TAVTemplateCode
描述
模板路径设置（如
setTemplateDir）时的错误码常量集合。 用于标识设置模板目录时的执行结果（成功/路径错误/鉴权失败等）。
参数
常量名 | 类型 | 说明 |
SUCCESS | int | 设置模板目录成功 |
PATH_INVALID | int | 模板目录路径无效 |
AUTH_INVALID | int | 模板鉴权失败 |
导出错误码
错误码 | 错误信息 | 描述 |
-1 | BuildRenderChainManager failed | 渲染链创建异常1 |
-4 | BuildRenderChainManager failed | 渲染链创建异常2 |
-10 | "error code ${errCode}: TAVMagic export error | 导出结束过程中出现问题 |
-14 | | 导出时视频帧处理异常 |
-15 | | 导出时音频帧处理异常 |
-16 | | 导出器初始化视频解码失败 |
-17 | | 导出器初始化音频解码失败 |
-18 | | 启动编码失败 |
-19 | | 启动解码失败 |
-101 | "error code ${errCode}: TAVMagic export error | 启动视频编码失败 |
-102 | | 启动音频编码失败 |
-103 | | 视频编码信息配置失败 |
-104 | | 音频编码信息配置失败 |
-105 | Failed to create output file | 创建文件失败 |
-111 | "error code ${errCode}: TAVMagic export error | 导出渲染异常1 |
-112 | | 导出渲染异常2 |
-113 | | 导出渲染异常3 |
-121 | | 写入视频样本异常 |
-122 | | 写入音频样本异常 |
-123 | | 结束写入视频样本异常 |
-124 | | 结束写入音频样本异常 |
-131 | | 停止 muxer 异常 |
-132 | | 停止编码器异常 |
-201 | Minimum generate duration cannot exceed maximum duration | 设置的最小导出时长，大于最大导出时长 |
-202 | The total generate duration is shorter than the minimum required duration | 总时长小于最小导出时长 |
-203 | Retry software encode error. Config is null. | 软编码重试失败，配置文件为空 |
-1001 | on load asset error | 加载资源异常 |
