更新记录

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:截取靠近第一帧的画面,保存为 jpg
  • compressVideo:压缩视频,并可回传进度和封面。默认规则见第 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/。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

视频和封面只在设备本地读取、压缩和保存,插件不会上传文件。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。