内置 API

https://developers.weixin.qq.com/miniprogram/dev/api/

音视频 API

音视频文件通常先由客户端选择或录制，再按需压缩并上传。选择、压缩和录音得到的都是本地临时文件；业务服务端应校验文件类型、大小、时长和上传结果。

视频选择与压缩

wx.chooseMedia 可拍摄或从相册选择图片、视频。选择视频后，先根据大小和时长决定是否压缩；不应假定 sizeType: ['compressed'] 已满足业务的体积要求。

async function chooseAndCompressVideo() {
  const { tempFiles } = await wx.chooseMedia({
    count: 1,
    mediaType: ['video'],
    sourceType: ['album', 'camera'],
    maxDuration: 30,
    sizeType: ['original'],
  })

  const file = tempFiles[0]
  if (!file || file.fileType !== 'video') {
    throw new Error('未选择视频')
  }

  const { tempFilePath, size } = await wx.compressVideo({
    src: file.tempFilePath,
    quality: 'medium',
  })

  return { tempFilePath, size }
}

wx.compressVideo 支持 low、medium、high 三档 quality。若需精细控制，可改用 bitrate（kbps）、fps 和 resolution（相对原视频的比例，取值为 (0, 1]）；传入 quality 时这三个参数会被忽略。返回的 size 单位为 kB，选择媒体返回的 size 单位为 B，比较前需统一单位。

上传与保存

临时路径应尽快上传；不要把本地临时路径直接作为业务数据提交。上传成功仅表示文件传输完成，仍要以服务端的校验与素材记录为准。

async function uploadVideo(filePath) {
  const result = await wx.uploadFile({
    url: 'https://api.example.com/media/videos',
    filePath,
    name: 'file',
    formData: { scene: 'post' },
  })

  const body = JSON.parse(result.data)
  if (result.statusCode !== 200 || body.code !== 0) {
    throw new Error(body.message || '视频上传失败')
  }
  return body.data
}

wx.saveVideoToPhotosAlbum 仅支持保存本地 MP4 视频，并需要 scope.writePhotosAlbum 授权。应在用户明确点击“保存到相册”后调用；拒绝授权时可通过 wx.openSetting 让用户自行调整。

视频播放控制

为 video 组件设置稳定的 id，再用 wx.createVideoContext 获取上下文进行播放、暂停、全屏等控制。自定义组件内需传入当前组件实例。

xml

<video id="preview" src="{{videoUrl}}" controls></video>
<button bindtap="playPreview">播放</button>

Page({
  playPreview() {
    wx.createVideoContext('preview', this).play()
  },
})

录音与音频播放

wx.getRecorderManager() 返回全局唯一的录音管理器。注册事件应在开始录音前完成；在 onStop 中取得临时文件并上传，页面卸载时停止仍在进行的录音。

const recorder = wx.getRecorderManager()

recorder.onStop(async ({ tempFilePath, duration }) => {
  if (duration < 1_000) return
  await uploadAudio(tempFilePath)
})

function startRecord() {
  recorder.start({ duration: 60_000, format: 'mp3' })
}

function stopRecord() {
  recorder.stop()
}

wx.createInnerAudioContext() 用于短音效或业务音频播放。短且高频的音频可启用 useWebAudioImplement；长音频保持默认实现。该对象不会自动释放，不再使用时必须调用 destroy()，并清理事件监听。

const audio = wx.createInnerAudioContext({ useWebAudioImplement: true })
audio.src = 'https://cdn.example.com/notice.mp3'
audio.onError((error) => console.error('音频播放失败', error.errMsg))
audio.play()

// 页面或组件销毁时执行
audio.destroy()

使用边界

使用前检查最低基础库版本，并在真机验证拍摄、压缩和播放差异。
录音、相册保存等能力只在用户触发后调用；取消、拒绝授权和中断属于正常分支。
上传前限制客户端文件大小与时长，服务端仍需重新检测 MIME 类型、实际大小、时长和内容安全。
大文件上传应展示进度并支持取消或重试；不要在主线程反复压缩同一视频。

内置 API ​

音视频 API ​

视频选择与压缩 ​

上传与保存 ​

视频播放控制 ​

录音与音频播放 ​

使用边界 ​