tmui4x 2.0(Vapor)

主题

TMUI4x2026-09-21
1402
5.6m

x-mediaplay-s 媒体播放与录制 ​

音频播放与录音。播放走系统播放器；录音输出 mp3 / wav。全局单例，新的播放或录音会抢占上一会话。

兼容性 ​

HarmonyIOSAndroidWEB小程序
支持支持支持支持支持

调用 ​

ts
import { startRecord, stopRecord, play, pause, resume, stop } from "@/uni_modules/x-mediaplay-s"

startRecord({
  format: "mp3",
  sampleRate: 16000,
  channelCount: 1,
  bitrate: 48,
  maxDurationMs: 60000,
  levelInterval: 150,
  onLevel: (db) => {
    console.log(db)
  },
  onWave: (value) => {
    console.log(value)
  },
  success: (res) => {
    console.log(res.path, res.durationMs)
  }
})

play({
  url: recordedPath,
  autoplay: true,
  volume: 1,
  infoInterval: 300,
  onInfo: (info) => {
    console.log(info.state, info.current, info.total)
  }
})

方法 ​

名称需要说明
playXMediaPlayOptions，见下方播放音频，会抢占上一会话
pause无暂停
resume无从暂停处继续
stop无停止播放
seekpositionMs: number跳到指定毫秒
setVolumevolume: number，0~1设置音量
getPlayInfo无返回 { current, total, state, percent }
isPlaying无是否正在播放
startRecordXMediaRecordOptions，见下方开始录音，会抢占上一会话
stopRecord无停止并保存，走 success
cancelRecord无取消并丢弃当前录音
getRecordState无返回 idle / recording / stopping
isRecording无是否正在录音
getVersion无原生核心版本，微信为空

参数 ​

XMediaPlayOptions

字段说明默认
url本地 / http(s) / blob必填
autoplay就绪后自动播true
loop循环false
volume音量 0~11
startPosition起播位置 ms0
infoIntervalonInfo 间隔 ms，小于 100 按 100500
onInfo进度与状态-
success起播成功-
fail失败-
complete结束-

XMediaRecordOptions

字段说明默认
formatmp3 / wavmp3
sampleRate采样率，wav 可用 4410016000
channelCount声道1
bitratemp3 码率 kbps，wav 忽略48
maxDurationMs到点自动 success60000
savePath输出路径，Web 忽略各端缓存
levelIntervalonLevel / onWave 间隔 ms200
onLevel音量 dBFS，[-100, 0]-
onWave波纹峰值，[-1, 1]；微信不回调-
success正常结束-
fail失败-
complete结束-

XMediaPlayInfo：current / total（ms，未知为 -1）、state、percent（缓冲 0~100）。

XMediaRecordResult：path、format、durationMs、size、sampleRate、channelCount。Web 的 path 为 blob。

平台差异 ​

  1. Web 需 HTTPS 或 localhost；savePath 忽略；无用户手势时 autoplay 可能失败。
  2. 微信：onLevel / onWave 不回调（签名保留）；maxDurationMs 上限 600000；getVersion() 为空；结果为临时路径。
  3. 录音需要麦克风权限。

版本 ​

版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。

更新日志 ​

1.0.3（2026-08-15） ​

录制增加 onWave 波纹回调。录制期间按 levelInterval 上报当前采集窗的归一化峰值，范围 [-1, 1]，方便外部画微信/iOS 式波形。Android / iOS / HarmonyOS / Web 从 PCM 取绝对值最大采样并保留符号；微信小程序无采集帧接口，签名保留但不回调。测试页用不超过 12 根柱循环展示录制波纹。

1.0.2（2026-08-05） ​

修复单声道 MP3 录音全是噪声（滋滋声）。共享核心的 Mp3Encoder 一律调用 lame_encode_buffer_interleaved，而该接口内部把读取步长写死为 2（lame_copy_inbuffer(..., jump=2)）， 只适用于立体声交错数据。单声道缓冲区只有 frames 个采样，LAME 却按 pcm[0], pcm[2], … pcm[2*frames-2] 去读，导致两个后果叠加：前半段信号被抽取成二倍频混叠，后半段读到缓冲区之外的堆内存。 默认录音配置就是单声道，因此 Android / iOS / HarmonyOS / Web 四端的 MP3 录音全部受影响（WAV 为裸拷贝，不受影响）。 现改为单声道走步长为 1 的 lame_encode_buffer，立体声保持 interleaved。

  • 四端原生产物（HAR / AAR / framework / wasm）均已重新构建，升级后需重新打包自定义基座。
  • 宿主测试新增 mono_mp3_fidelity：编码 1kHz 单声道正弦后用 afconvert 解码回 PCM， 以 Goertzel 量测 1kHz 与 2kHz 分量。修复前 1kHz 幅度仅 0.75（原始音调消失），修复后为 15565。 此前的断言只检查文件魔数与大小，无法发现内容层面的损坏。

1.0.1（2026-08-04） ​

单例与抢占语义。插件全局仍只有一个播放器、一个录制会话，但不再要求调用方先 stop 再重新开始：

  • 播放：新的 play() 抢占旧会话，旧会话必定收到 onInfo(stop)；尚未起播成功的再补 fail(1009) + complete(null)。stop() 在起播就绪前调用也会补终态。此前旧 options 的回调会被静默丢弃，调用方永远等不到 complete，闭包也一直被 @UTSJS.keepAlive 持有。
  • 录制：startRecord() 在录制中调用时，先把上一段正常收尾（出文件、旧 success 拿到完整结果）再启动新录制，不丢数据；此前直接 fail(1010) 拒绝。
  • 五端共用新的 libs/session.uts 做会话仲裁，success/fail/complete 严格只触发一次，抢占后立即释放旧回调引用；被抢占会话的迟到事件按会话 id 丢弃。
  • HarmonyOS：teardown 改为等 AudioCapturer 真正 stop() + release() 完成后再置 idle 并回调 onDone，避免紧接着开新录音时撞上仍被占用的麦克风。
  • 错误码 1009 语义扩展为「操作已取消或被新的请求中断」，具体原因见 errMsg。

1.0.0（2026-08-04） ​

首个可用版本，五端（Android / iOS / HarmonyOS / Web / 微信小程序）播放与录制全部落地。

播放：各端系统播放器统一到一套状态机与进度回调（onInfo + success/fail/complete），支持 pause/resume/seek/setVolume/getPlayInfo。

录制：采集 PCM → C++ 共享核心（声道合并 + 有理数相位重采样 + 流式编码 MP3(LAME)/WAV）。 Android 走 AudioRecord + JNI，iOS 走 AVAudioEngine + ObjC++，HarmonyOS 走 AudioCapturer + NAPI， Web 走 AudioWorklet + WASM，微信小程序走平台 RecorderManager 直出。 支持时长上限自动停止（默认 60s）、onLevel 实时 dBFS 音量回调、cancelRecord 丢弃产物。

最近更新