更新记录

1.0.0（2026-07-17）

首次发布

平台兼容性

uni-app(5.0)

uni-app x(5.0)

ax-video-compress 视频压缩插件

这是一个基于 UTS (Uni TypeScript) 开发的高性能原生视频压缩插件，专为 uni-app x 和 uni-app 环境打造，支持 Android 和 iOS 双端。

本插件底层直接调用移动端系统级的原生音视频 API，相比于传统的 JS 或 WASM 方案，拥有不可比拟的极速体验和内存优势。尤其是针对 Android 碎片化和高分辨率视频处理，内置了大厂级的智能优化策略。

✨ 核心特性

• ⚡ 纯原生硬编硬解：Android 端基于 MediaCodec + OpenGL，iOS 端基于 AVAssetExportSession，压榨每一滴硬件算力。
• 🧠 智能等比降维 (Android)：自动识别 4K/2K 超清视频，根据所选质量智能降维至 1080P/720P，杜绝 4K 视频压缩极慢且发热的问题。
• 📊 动态码率算法 (BPP)：摒弃死板的固定码率，采用先进的 BPP (Bits Per Pixel) 算法，针对不同分辨率视频动态分配最合理的码率，保证 4K 不被压糊，720P 不会体积过剩。
• 🛡️ 越压越大保护机制：智能嗅探原视频码率，如果计算出的目标码率高于原视频，会自动降级为原码率的 90%，彻底杜绝“视频越压越大”的乌龙。
• ✅ 偶数对齐兼容 (Android)：智能规避 Android 硬件编码器（如联发科芯片）对奇数分辨率报错的底层 Bug，兼容性拉满。

📦 快速上手

引入插件

由于符合 uni_modules 规范，直接在页面中导入即可使用：

import { compressVideo } from '@/uni_modules/ax-video-compress'

基本用法

// 假设你通过 uni.chooseVideo 拿到了一段视频的本地路径 sourcePath
const sourcePath = res.tempFilePath;

// 构造输出的绝对路径 (注意必须是物理绝对路径)
const fileName = 'compressed_' + Date.now() + '.mp4';
const targetPath = plus.io.convertLocalFileSystemURL('_doc/' + fileName);

compressVideo({
  sourceFilePath: plus.io.convertLocalFileSystemURL(sourcePath), // 原视频绝对路径
  targetFilePath: targetPath, // 压缩后保存的绝对路径
  quality: 'very_high', // 可选：very_high | high | medium | low
  progress: (percent) => {
    console.log('压缩进度:', percent + '%');
  },
  success: (result) => {
    console.log('压缩完成，文件保存在:', result.targetFilePath);
  },
  fail: (err) => {
    console.error('压缩失败:', err.msg);
  }
});

📚 API 参数参考

compressVideo(options: CompressVideoOptions)

💡 进阶行为说明

Android 端智能降维规则

在 没有 强行传入 width 和 height 的前提下，插件会根据 quality 参数触发智能降维：

• low: 限制最大分辨率为 480P (854x854 边界等比缩放)
• medium: 限制最大分辨率为 720P (1280x1280 边界等比缩放)
• high / very_high: 限制最大分辨率为 1080P (1920x1920 边界等比缩放)
• 如果原视频分辨率小于边界值，则保持原分辨率不变。

iOS 端的差异

iOS 拥有极为封闭但智能的硬件编码生态。iOS 端直接调用底层的 AVAssetExportSession，苹果系统自带了极其强大的智能动态码率调节器。因此，在 iOS 端：

• width 和 height 参数不生效，完全交由苹果系统的 Preset 自动接管画质控制。
• 极高自定义码率会被自动映射为苹果的最高质量预设。