更新记录
1.0.0(2026-11-16)
- Android 提供 getVideoInfo、getVideoFrame、compressVideo。
- 兼容 content URI、应用本地路径,以及缺少码率或旋转信息的视频。
- 封面写入 Pictures 目录,压缩结果默认写入 cache/movie。
平台兼容性
uni-app(4.25)
| Vue2 | Vue2插件版本 | Vue3 | Vue3插件版本 | Chrome | Safari | app-vue | app-vue插件版本 | app-nvue | app-nvue插件版本 | Android | Android插件版本 | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| √ | 1.0.0 | √ | 1.0.0 | × | × | √ | 1.0.0 | √ | 1.0.0 | 5.0 | 1.0.0 | × | × |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
uni-app x(4.25)
| Chrome | Safari | Android | Android插件版本 | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|---|
| × | × | 5.0 | 1.0.0 | × | × | × |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
安澜视频(anlan-videosdk)使用说明
本文面向业务开发者,说明如何在 uni-app / uni-app x 项目中接入 anlan-videosdk。插件当前版本为 1.0.0。
问题反馈:如果在试用或使用过程中遇到问题,请将错误日志贴到插件市场评论区,或发送到沟通群中,两种方式都可以。看到后会及时回复。
1. 功能概览
anlan-videosdk 在 Android App 上提供三个接口:
getVideoInfo:读取编码宽高、显示宽高、旋转角、时长和码率。页面布局用显示宽高getVideoFrame:截取靠近第一帧的画面,保存为 jpgcompressVideo:压缩视频,并可回传进度和封面。默认规则见第 5 节
视频和封面只在设备本地处理,插件不会上传文件,也不申请存储权限。
iOS、鸿蒙目前返回 9010001(平台不支持)。Web 和小程序不可用。
2. 平台与版本
| 平台 | 读取信息 | 截取封面 | 压缩 |
|---|---|---|---|
| Android App | 支持 | 支持 | 支持 |
| iOS | 返回平台不支持 | 返回平台不支持 | 返回平台不支持 |
| HarmonyOS | 返回平台不支持 | 返回平台不支持 | 返回平台不支持 |
| Web / 小程序 | 不支持 | 不支持 | 不支持 |
版本要求:
- HBuilderX 最低版本:
4.25 - uni-app Vue 2:HBuilderX
3.6.8起可调用 UTS 插件,本插件因包含 Java 混编,仍要求4.25及以上 - Android 最低版本:Android 5.0(API 21)
Vue 版本兼容
| 项目类型 | 三个视频接口 |
|---|---|
| uni-app Vue 2 App(vue / nvue) | 支持,使用普通 JavaScript 调用 |
| uni-app Vue 3 App(vue / nvue) | 支持,可使用 JavaScript 或 TypeScript 调用 |
| uni-app x | 支持,.uvue 页面使用 UTS 类型 |
Vue 2 项目不要求业务页面使用 TypeScript。不要把 .uvue 示例中的 as GetVideoInfoOptions、参数类型注解或 <script setup lang="uts"> 直接复制到普通 .vue 页面,否则会被 Babel 按 JavaScript 解析并产生语法错误。
3. 安装与原生基座
插件位于:
uni_modules/anlan-videosdk
如果项目尚未放入该目录,可将插件目录完整复制到项目的 uni_modules 下。
重要:重新制作自定义基座
插件的编解码实现是 Java 混编,代码在 utssdk/app-android。首次接入,以及修改其中的 Java、Kotlin 后,都需要重新制作自定义调试基座或正式安装包。基座使用的 App ID 要和当前项目一致。
标准基座不含这套 Java 代码。在标准基座里调用时,读取信息、截封面和压缩不会生效。这是基座里没有当前插件原生实现的正常表现,业务参数本身没有写错。
只改业务页面上的路径、宽高、码率和帧率时,不需要重新制作基座。这些参数随前端资源更新。
4. 视频路径
三个接口的 oriPath 使用同一种路径。下面这些都可以:
uni.chooseVideo返回的tempFilePath- 应用本地路径,例如
_doc/video/a.mp4 file://开头的路径content://开头的媒体库地址- 以
/开头的绝对路径
网络地址 http://、https:// 不支持,会返回 9010002。
返回的视频和封面要交给 video、image 或 uni.uploadFile 时,路径用法见第 9 节。
选择视频时建议关闭系统自带压缩,把原视频交给插件处理:
uni.chooseVideo({
sourceType: ['album', 'camera'],
compressed: false,
success(res) {
const videoPath = res.tempFilePath
}
})
5. 原理说明
压缩使用 Android 原生 MediaCodec,在设备本地完成。输出容器是 mp4,视频为 8-bit H.264,音频为 AAC。
5.1 默认压缩
不传 outWidth、outHeight、outBitrate、outFrameRate 时,按下面的规则计算。小于等于 0 同样视为不传。
短边小于 720 时,倍率按 2 计算,宽高各除以 2。编码短边 640 时,输出短边约为 320。短边大于等于 720 时,按 短边 / 720 缩小,比例保留两位小数。算出的宽或高小于 2 时,按 2 输出。
码率用同样的分档。原码率大于等于 1600000 时,按 原码率 / 1600000 缩小;否则除以 2。读不到原码率时使用 1600000。单位是 bps,1600kbps 等于 1600000。
这套默认值对着短边 720、码率约 1600kbps。按这个码率,一分钟视频大约是 10MB 这一档。文件里还有音频,实际大小会随原片和机型变化。
输出宽高按原片比例折算,保持原来的宽高比。16:9 横屏的编码尺寸大约是 1280×720。手机竖拍视频会先按旋转角换算编码方向,再输出。
默认帧率是 20。outFrameRate 设得过低时,画面会发顿。
要更小或更大时,先调用 getVideoInfo,用返回的 width、height、bitrate 自己计算后再传入。outWidth、outHeight 填编码宽高。页面上展示视频用 displayWidth、displayHeight。
5.2 格式
输入能解哪些容器,取决于手机上的 MediaCodec。说明里的示例按 mp4 验证。没有对应解码器时压缩失败,返回 9010005,具体原因在 errMsg。
5.3 任务怎么跑
多次调用 compressVideo 会在同一条压缩线程上依次执行。onProgress 和成功结果里的 oriPath 用来区分是哪一个文件。前一个还没结束时再次调用,会排队。
插件没有取消接口。离开页面后,当前这次压缩仍会跑完。
onProgress 里的 progress 取值是 0 到 1。界面上要显示百分比时,乘以 100。
6. 示例代码
读取编码宽高、按旋转换算后的显示宽高、旋转角、时长和码率。
平台:Android 框架:Vue 2 / Vue 3 / uni-app x
Vue 2 使用普通 JavaScript,不导入仅用于类型检查的 GetVideoInfoOptions。
<template>
<view>
<button @click="chooseVideoFile">选择视频</button>
<button @click="readInfo">读取信息</button>
<text>{{ resultText }}</text>
</view>
</template>
<script>
import { getVideoInfo } from '@/uni_modules/anlan-videosdk'
export default {
data() {
return {
videoPath: '',
resultText: ''
}
},
methods: {
chooseVideoFile() {
uni.chooseVideo({
sourceType: ['album', 'camera'],
compressed: false,
success: (res) => {
this.videoPath = res.tempFilePath
}
})
},
readInfo() {
if (!this.videoPath) {
this.resultText = '请先选择视频'
return
}
getVideoInfo({
oriPath: this.videoPath,
success: (res) => {
this.resultText = '显示 ' + res.displayWidth + '×' + res.displayHeight
+ ',时长 ' + res.duration + 'ms'
},
fail: (err) => {
this.resultText = err.errCode + ' ' + err.errMsg
}
})
}
}
}
</script>
Vue 3 可以使用普通 JavaScript 或 TypeScript。下面的示例不依赖 UTS 类型。
<template>
<view>
<button @click="chooseVideoFile">选择视频</button>
<button @click="readInfo">读取信息</button>
<text>{{ resultText }}</text>
</view>
</template>
<script setup>
import { ref } from 'vue'
import { getVideoInfo } from '@/uni_modules/anlan-videosdk'
const videoPath = ref('')
const resultText = ref('')
function chooseVideoFile() {
uni.chooseVideo({
sourceType: ['album', 'camera'],
compressed: false,
success(res) {
videoPath.value = res.tempFilePath
}
})
}
function readInfo() {
if (!videoPath.value) {
resultText.value = '请先选择视频'
return
}
getVideoInfo({
oriPath: videoPath.value,
success(res) {
resultText.value = '显示 ' + res.displayWidth + '×' + res.displayHeight
+ ',时长 ' + res.duration + 'ms'
},
fail(err) {
resultText.value = err.errCode + ' ' + err.errMsg
}
})
}
</script>
uni-app x 页面使用 .uvue 和 UTS 类型。
<template>
<view>
<button @click="readInfo">读取信息</button>
<text>{{ resultText }}</text>
</view>
</template>
<script setup lang="uts">
import { getVideoInfo, GetVideoInfoOptions } from '@/uni_modules/anlan-videosdk'
const videoPath = ref<string>('')
const resultText = ref<string>('')
function readInfo(): void {
getVideoInfo({
oriPath: videoPath.value,
success: (res) => {
resultText.value = `显示 ${res.displayWidth}×${res.displayHeight},时长 ${res.duration}ms`
},
fail: (err) => {
resultText.value = `${err.errCode} ${err.errMsg}`
}
} as GetVideoInfoOptions)
}
</script>
截取靠近第一帧的画面,保存为 jpg。framePicPath 是本地绝对路径,可直接作为 image 的 src;绝对路径建议加上 file://。
平台:Android 框架:Vue 2 / Vue 3 / uni-app x
<template>
<view>
<button @click="captureFrame">截取封面</button>
<image v-if="frameSrc" :src="frameSrc" mode="widthFix"></image>
</view>
</template>
<script>
import { getVideoFrame } from '@/uni_modules/anlan-videosdk'
export default {
data() {
return {
videoPath: '',
frameSrc: ''
}
},
methods: {
captureFrame() {
getVideoFrame({
oriPath: this.videoPath,
success: (res) => {
const path = res.framePicPath
this.frameSrc = path.indexOf('/') === 0 ? 'file://' + path : path
},
fail: (err) => {
console.error(err.errCode, err.errMsg)
}
})
}
}
}
</script>
<script setup>
import { ref } from 'vue'
import { getVideoFrame } from '@/uni_modules/anlan-videosdk'
const videoPath = ref('')
const frameSrc = ref('')
function captureFrame() {
getVideoFrame({
oriPath: videoPath.value,
success(res) {
const path = res.framePicPath
frameSrc.value = path.indexOf('/') === 0 ? 'file://' + path : path
},
fail(err) {
console.error(err.errCode, err.errMsg)
}
})
}
</script>
<script setup lang="uts">
import { getVideoFrame, GetVideoFrameOptions } from '@/uni_modules/anlan-videosdk'
const videoPath = ref<string>('')
const frameSrc = ref<string>('')
function captureFrame(): void {
getVideoFrame({
oriPath: videoPath.value,
success: (res) => {
const path = res.framePicPath
frameSrc.value = path.startsWith('/') ? 'file://' + path : path
},
fail: (err) => {
console.error(err.errCode, err.errMsg)
}
} as GetVideoFrameOptions)
}
</script>
压缩本地视频。onProgress 会多次回调,progress 范围是 0 到 1。success 只在结束时回调一次。
平台:Android 框架:Vue 2 / Vue 3 / uni-app x
<template>
<view>
<button @click="compressCurrent">压缩</button>
<text>{{ progressText }}</text>
<text>{{ resultText }}</text>
</view>
</template>
<script>
import { compressVideo } from '@/uni_modules/anlan-videosdk'
export default {
data() {
return {
videoPath: '',
progressText: '0%',
resultText: ''
}
},
methods: {
compressCurrent() {
compressVideo({
oriPath: this.videoPath,
isNeedFramePic: true,
onProgress: (event) => {
this.progressText = Math.round(event.progress * 100) + '%'
},
success: (res) => {
this.progressText = '100%'
this.resultText = res.path
},
fail: (err) => {
this.resultText = err.errCode + ' ' + err.errMsg
}
})
}
}
}
</script>
<script setup>
import { ref } from 'vue'
import { compressVideo } from '@/uni_modules/anlan-videosdk'
const videoPath = ref('')
const progressText = ref('0%')
const resultText = ref('')
function compressCurrent() {
compressVideo({
oriPath: videoPath.value,
isNeedFramePic: true,
onProgress(event) {
progressText.value = Math.round(event.progress * 100) + '%'
},
success(res) {
progressText.value = '100%'
resultText.value = res.path
},
fail(err) {
resultText.value = err.errCode + ' ' + err.errMsg
}
})
}
</script>
<script setup lang="uts">
import { compressVideo, CompressVideoOptions } from '@/uni_modules/anlan-videosdk'
const videoPath = ref<string>('')
const progressText = ref<string>('0%')
const resultText = ref<string>('')
function compressCurrent(): void {
compressVideo({
oriPath: videoPath.value,
isNeedFramePic: true,
onProgress: (event) => {
progressText.value = `${Math.round(event.progress * 100)}%`
},
success: (res) => {
progressText.value = '100%'
resultText.value = res.path
},
fail: (err) => {
resultText.value = `${err.errCode} ${err.errMsg}`
}
} as CompressVideoOptions)
}
</script>
回调说明:onProgress 可以调用多次,progress 从 0 到 1。success 和 fail 互斥,结束后还会再走一次 complete。
默认压缩见第 5 节。参数、返回值、输出目录和错误码见下方章节。
7. 主要参数
7.1 公共参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
oriPath |
string |
是 | 本地视频路径,见第 4 节 |
success |
function |
否 | 成功回调,只调用一次 |
fail |
function |
否 | 失败回调,参数里有 errCode、errMsg |
complete |
function |
否 | 无论成功失败都会调用一次 |
7.2 压缩参数
只在 compressVideo 中使用。不传可选参数,或传入小于等于 0 的数值时,按第 5 节的默认规则计算。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
outWidth |
number |
见第 5 节 | 输出编码宽度 |
outHeight |
number |
见第 5 节 | 输出编码高度 |
outBitrate |
number |
见第 5 节 | 输出码率,单位 bps |
outFrameRate |
number |
20 |
输出帧率 |
outPath |
string |
应用缓存目录 | 输出 mp4 的路径,见第 9 节 |
isNeedFramePic |
boolean |
false |
压缩成功后是否再截一张封面 |
onProgress |
function |
无 | 可多次触发。progress 从 0 到 1,乘以 100 为百分比 |
8. 返回值
8.1 getVideoInfo
{
oriPath: string
width: number
height: number
bitrate: number
rotation: number
duration: number
displayWidth: number
displayHeight: number
}
width、height 是文件里的编码宽高,不含旋转。rotation 是 0、90、180、270。displayWidth、displayHeight 已按旋转角对调,页面布局用这两个值。duration 单位是毫秒。bitrate 单位是 bps,读不到时为 0。
8.2 getVideoFrame
{
oriPath: string
framePicPath: string
}
framePicPath 是 jpg 的绝对路径,按原视频画面的像素尺寸保存。交给 image 或上传时的路径写法见第 9 节。
8.3 compressVideo
进度:
{
oriPath: string
progress: number
}
progress 从 0 到 1。
成功:
{
oriPath: string
path: string
framePicPath: string
}
path 是压缩后的 mp4。isNeedFramePic 为 true 时,封面从压缩完成的视频上截取,尺寸与输出视频一致。未要求封面,或封面截取失败时,framePicPath 为空字符串,压缩结果仍然算成功。路径写法见第 9 节。
9. 输出目录
未传 outPath 时,视频写入应用内部缓存:
/data/user/0/<包名>/cache/movie/<原文件名>scale_video.mp4
同名文件已存在时自动加序号,例如 scale_video1.mp4。
这个目录属于应用缓存。系统清理缓存时,这里的视频可能被删掉。需要留存时,在 success 里把 path 拷到 _doc 或其他业务目录。
封面写入应用外部私有目录,不需要存储权限。清理缓存时,封面不和 cache/movie 里的视频一起删除:
/storage/emulated/0/Android/data/<包名>/files/Pictures/<时间戳>_<序号>.jpg
调用方传入 outPath 时使用该路径,已有文件会先删除。该路径要是应用能写的本地路径。传入 content:// 或网络地址会返回 9010006。
path 和 framePicPath 经常是以 / 开头的绝对路径。交给 video、image 或 uni.uploadFile 时,在前面加上 file://。已经是 file://、content:// 或以 _doc 开头的路径保持原样。
10. 错误码
| 错误码 | 含义 |
|---|---|
9010001 |
当前平台未实现。iOS、鸿蒙会返回这个错误 |
9010002 |
参数无效。路径为空,或传入了网络地址 |
9010003 |
读取视频信息失败 |
9010004 |
截取封面失败 |
9010005 |
压缩失败 |
9010006 |
输出路径不可写 |
fail 回调里的 errMsg 会带上具体原因。业务侧用 errCode 分支,把 errMsg 打到日志里即可。
11. 权限与数据处理
插件不申请相机、麦克风或存储权限。
- 读取用户刚选择的视频时,使用系统选择器给的临时路径或
content://,不需要READ_MEDIA_VIDEO。 - 压缩结果写在应用缓存目录,封面写在应用外部私有目录。目录是否会被清理,见第 9 节。
- 视频和封面只在设备本地处理,插件不会上传。
- 输出格式和输入格式见第 5 节。
如果业务要读取公共目录里任意一个视频文件,而不是用户刚选中的文件,权限由宿主自己申请,插件不会额外弹出授权。
12. 常见问题
标准基座里调用没有效果
见第 3 节。需要制作包含 anlan-videosdk 的自定义调试基座。
Vue 2 页面报语法错误
见第 2 节。按本文 Vue 2 页签里的 export default 写法调用。
竖拍视频的宽高反了
width、height 是编码尺寸。展示和布局使用 displayWidth、displayHeight,见第 8 节。
压缩后帧率变成 20
默认帧率是 20,见第 5 节。需要更高帧率时传入 outFrameRate。
同一秒截了两张封面,后一张把前一张盖掉了吗
不会。封面文件名包含毫秒和递增序号。
修改压缩宽高后需要重新打包吗
只改调用参数时不需要,见第 3 节。
返回的视频或封面路径无法播放、无法上传
以 / 开头的绝对路径,前面加 file://。见第 9 节。
控制台里的进度比压缩本身慢
onProgress 是异步回调。用 console.log 打印时,HBuilderX 控制台可能成批刷出,看起来还在压缩,文件可能已经写完。界面上的进度以回调为准,结束以 success 为准。
想压得比默认更小
见第 5 节。先 getVideoInfo,再传入自己的宽高、码率和帧率。
同时压多个视频会怎样
会排队,同一时间只有一路压缩。用回调里的 oriPath 区分文件,见第 5 节。
离开页面后压缩还会继续吗
会。插件没有取消接口,当前任务会跑完,见第 5 节。
压缩完的视频找不到了
默认写在应用缓存里,系统清理缓存时可能删除。需要留存就自行拷贝,见第 9 节。
不是 mp4 也能压吗
见第 5 节。输出固定是 mp4,输入取决于手机上的 MediaCodec。
13. 从旧版原生插件迁移
旧版 Android 原生插件(插件市场 id 2827,K-VideoCompressModule)的三个能力对应到现在的接口:
| 旧调用 | 现在 |
|---|---|
uni.requireNativePlugin 后调用 compressAction |
import { compressVideo },用 success、fail、onProgress |
getVideoInfo |
getVideoInfo。除宽高和码率外,增加旋转角、时长和显示宽高 |
getVideoFrame |
getVideoFrame |
回调里 code === "0",进度和结果走同一个函数 |
进度走 onProgress,成功走 success,失败走 fail |
返回路径的用法见第 9 节。默认压缩、任务排队和取消见第 5 节。
14. 插件自测
下面用于核对插件本身。业务接入按前面的章节即可。
- 使用与项目一致的 App ID 制作 Android 自定义调试基座。
- 在真机上分别验收相册视频和相机录制的视频。
- 验收竖拍视频的
displayWidth、displayHeight。 - 验收
content://路径和uni.chooseVideo的tempFilePath。 - 验收压缩进度从 0 走到结束,以及失败时的错误码。
- 验收不传
outPath时文件出现在cache/movie/,封面出现在files/Pictures/。

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 598
赞赏 1
下载 12771421
赞赏 1959
赞赏
京公网安备:11010802035340号