tmui-cli 2.0.1 → 2.0.2

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xFfmpegS /351/237/263/350/247/206/351/242/221/345/244/204/347/220/206.md"

@@ -0,0 +1,114 @@
+# x-ffmpeg-s 音视频处理
+
+App 三端音视频处理：剪辑、拼接、压缩、转码、抽帧、抽音、静音、合并、缩放、旋转、水印、滤镜。输出请写到 `getCacheDir()` 等可写目录，路径不要带 `file://`。
+
+**Web / 微信不能跑处理任务。** `getMediaInfo` 可用，其它任务返回不支持。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 不支持 | 不支持 |
+
+### 调用
+
+```ts
+import { getCacheDir, getMediaInfo, cut, cancel } from "@/uni_modules/x-ffmpeg-s"
+
+getMediaInfo({
+  path: videoPath,
+  success: (res) => {
+    console.log(res.info)
+  }
+})
+
+cut({
+  input: videoPath,
+  output: getCacheDir() + "/cut-" + Date.now() + ".mp4",
+  startTime: 2,
+  duration: 4,
+  videoCodec: "copy",
+  audioCodec: "copy",
+  onProgress: (p) => {
+    console.log(p)
+  },
+  success: (res) => {
+    console.log(res.output, res.cancelled)
+  }
+})
+
+cancel()
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| getCacheDir | 无 | 返回可写缓存目录，输出路径建议拼在这里 |
+| getRuntimeInfo | 无 | 返回当前平台与编码器信息 |
+| getMediaInfo | `path` | 读媒体信息，Web / 微信也可用 |
+| cut | `input`、`output`，可选 `startTime`、`duration`、编码器 | 按时间裁剪 |
+| concat | `inputs`（至少 2 个）、`output` | 拼接多个文件 |
+| extractFrame | `input`、`output`（.jpg/.png）、`frameTime` | 抽一帧封面 |
+| extractAudio | `input`、`output` | 抽出音轨 |
+| muteVideo | `input`、`output` | 去掉视频声音 |
+| mergeVideoAudio | `input`（视频）、`audio`、`output` | 把音频合进视频 |
+| mergeTimed | `input`、`audio`、`output`、`audioStart`，可选 `audioDuration` | 从指定秒开始贴一段音乐 |
+| scale | `input`、`output`、`width?`、`height?` | 缩放 |
+| rotateVideo | `input`、`output`、`rotate`（0/90/180/270） | 旋转 |
+| compress | `input`、`output`，可选码率 | 压缩 |
+| transcode | `input`、`output`，可选编码器 | 转码 |
+| watermark | `input`、`watermark`、`output`，可选 `position`、`margin`、`opacity` | 加图片水印，文字水印不可用 |
+| filterVideo | `input`、`output`，可选 `filter`、`audioFilter` | 自定义滤镜链 |
+| cancel | 无 | 取消当前任务，成功回调里 `cancelled=true` |
+
+多数任务共用字段：
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| input / output | 绝对路径 | 必填 |
+| startTime | 起始秒 | `0` |
+| duration | 时长秒，不传则到结尾 | 到结尾 |
+| width / height | 目标尺寸，0 为等比 | 原尺寸 |
+| rotate | 0 / 90 / 180 / 270 | `0` |
+| flip | `horizontal` / `vertical` | - |
+| fps | 帧率 | 原帧率 |
+| videoCodec / audioCodec | 编码器，`copy` 为流拷贝 | 按扩展名 |
+| videoBitrate / audioBitrate | 如 `2M` / `800k`，不要小数 | - |
+| onProgress / success / fail / complete | 回调 | - |
+
+`concat`：`inputs`（至少 2 个）、`output`。
+
+`extractFrame`：`input`、`output`（`.jpg` / `.png`）、`frameTime` 必填。
+
+`mergeVideoAudio`：`input`（视频）、`audio`、`output`。
+
+`mergeTimed`：`input`、`audio`、`output`、`audioStart` 必填，`audioDuration` 默认整段音乐。
+
+`watermark`：`input`、`watermark`（png/jpg）、`output`、`position`（默认 `bottom-right`）、`margin`（20）、`scale`（0 原尺寸）、`opacity`（1）、`startTime` / `duration`。
+
+`filterVideo`：`filter` 视频滤镜链，`audioFilter` 音频滤镜链。
+
+`XFfmpegTaskResult`：`output`、`size`、`durationMs`、`cancelled`。`cancel()` 后仍走 success，且 `cancelled=true`。
+
+文字水印不可用，请用 png + `watermark`。
+
+### 平台差异
+
+1. 仅 Android / iOS / 鸿蒙可执行处理任务。
+2. 输出必须是可写绝对路径。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-08-01）
+- 基于 FFmpeg 7.1 + x264 交叉编译三平台原生依赖包。
+- Android：NDK 30 编译 arm64-v8a，AAR 内置 8 个 .so（含 MediaCodec 硬解）。
+- HarmonyOS：OHOS NDK 编译 arm64-v8a，HAR 内置 8 个 .so，NAPI + Worker 架构。
+- iOS：Xcode 编译 arm64 静态框架 XFfmpegCore.framework，ObjC++ + Swift 边界。
+- 提供剪辑、拼接、压缩、转码、抽帧、抽音、静音、合并、缩放、旋转、翻转、媒体信息探测、取消等完整 API。
+- UTS 层统一 DCloud 三回调风格（success/fail/complete），耗时任务支持进度回调。
+- 编写交叉编译脚本与构建文档（native-src/*/BUILDING.md）。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xHtmlU HTML/345/256/211/345/205/250/346/270/262/346/237/223.md"

@@ -0,0 +1,68 @@
+# x-html-u HTML安全渲染
+
+安全渲染 HTML。丢弃 script / iframe 等危险标签，支持标题、列表、表格、链接、图片，段落可系统选区复制。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```vue
+<x-html-u
+  ref="htmlRef"
+  :html="htmlContent"
+  :dark="false"
+  :font-size="17"
+  @linkclick="onLinkClick"
+  @imageclick="onImageClick"
+  @rendered="onRendered"
+></x-html-u>
+```
+
+只解析不渲染：
+
+```ts
+import { xHtmlParse } from "@/uni_modules/x-html-u"
+
+xHtmlParse(html, {
+  success: (res) => {
+    console.log(res.plainText, res.ir)
+  }
+})
+```
+
+### 参数
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| html | HTML 内容 | `""` |
+| dark | 深色 | `false` |
+| fontSize | 基础字号 px | `15` |
+| lineHeight | 行高倍数 | `1.4` |
+
+### 事件
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| sizechange | `{ width, height }` | 内容尺寸变化 |
+| linkclick | `{ href, text, title }` | 点击链接 |
+| imageclick | `{ src, alt, title }` | 点击图片 |
+| rendered | `{ blockCount, parseMs, droppedNodeCount, droppedAttributeCount }` | 渲染完成 |
+| error | `{ errSubject, errCode, errMsg }` | 解析或渲染失败 |
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| setContent | `html: string` | 全量更新 HTML |
+| getContent | 无 | 返回当前原始 HTML |
+| getPlainText | 无 | 返回解析后的纯文本 |
+| getIR | 无 | 返回渲染中间层 JSON |
+| xHtmlParse | `html`，可选 `success` / `fail` / `complete` | 只解析不渲染，独立函数 |
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xKeyboardS /350/275/257/351/224/256/347/233/230.md"

@@ -0,0 +1,101 @@
+# x-keyboard-s 软键盘
+
+软键盘高度监听、收起键盘、读取当前输入框光标/选区。函数与类型均加 `x` 前缀，避免与官方同名冲突。一次性 API 使用 DCloud `success / fail / complete`。
+
+### 兼容性
+
+| Harmony | iOS | Android | WEB | 微信小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+鸿蒙端 `xGetSelectedTextRange` 无法读取系统输入框选区，会走 `fail 1005`。
+
+### 调用
+
+```ts
+import {
+  xOnKeyboardHeightChange,
+  xOffKeyboardHeightChange,
+  xHideKeyboard,
+  xGetSelectedTextRange,
+  XHideKeyboardOptions,
+  XGetSelectedTextRangeOptions
+} from "@/uni_modules/x-keyboard-s"
+
+const listenId = xOnKeyboardHeightChange((res) => {
+  console.log(res.height)
+})
+
+xHideKeyboard({
+  success: (res) => {
+    console.log(res.errMsg)
+  }
+} as XHideKeyboardOptions)
+
+xGetSelectedTextRange({
+  success: (res) => {
+    console.log(res.start, res.end)
+  },
+  fail: (err) => {
+    console.log(err.errCode, err.errMsg)
+  }
+} as XGetSelectedTextRangeOptions)
+
+xOffKeyboardHeightChange(listenId)
+```
+
+### 方法
+
+| 名称 | 说明 |
+| --- | --- |
+| xOnKeyboardHeightChange | 监听键盘高度变化，返回监听 id |
+| xOffKeyboardHeightChange | 移除监听；不传 id 则移除本插件全部监听 |
+| xHideKeyboard | 收起软键盘 |
+| xGetSelectedTextRange | 读取当前获焦输入框的光标/选区，仅 focus 时有效 |
+
+### 结果
+
+`XKeyboardHeightChangeResult.height` 为逻辑像素，收起时为 `0`。
+
+`XGetSelectedTextRangeResult`：`start` / `end` 为字符下标。
+
+错误码：`1001` 系统错误，`1002` 参数错误，`1005` 当前没有获焦的输入框，`1008` 当前平台不支持。
+
+### 平台差异
+
+**Android**
+
+- 高度：根视图 `OnGlobalLayoutListener` + 可视区域差值，再除以 density。
+- 收起：`InputMethodManager.hideSoftInputFromWindow`。
+- 选区：当前 focus 的 `TextView` / `EditText`。
+
+**iOS**
+
+- 高度：`keyboardWillChangeFrame`。
+- 收起：`endEditing`。
+- 选区：当前 first responder 的 `UITextInput`。
+
+**HarmonyOS**
+
+- 高度：`window.on('keyboardHeightChange')`，px 转 vp。
+- 收起：`inputMethod.getController().hideSoftKeyboard` / `stopInputSession`。
+- 选区：无全局可读选区，`fail 1005`。
+
+**Web**
+
+- 高度：`visualViewport` 与 `window.innerHeight` 差值。
+- 收起：`document.activeElement.blur()`。
+- 选区：当前 `input` / `textarea` 的 `selectionStart` / `selectionEnd`。
+
+**微信小程序**
+
+- 直接转发 `wx.onKeyboardHeightChange` / `wx.offKeyboardHeightChange` / `wx.hideKeyboard` / `wx.getSelectedTextRange`。
+
+### 版本
+
+版权归 https://xui.tmui.design 你不得修改及二次开发，仅供 TMUI4 会员商用使用。不得转给非 VIP 会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-08-16）
+* 新增 x-keyboard-s：xOnKeyboardHeightChange、xOffKeyboardHeightChange、xHideKeyboard、xGetSelectedTextRange。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xLoadingS /345/205/250/345/261/217/345/212/240/350/275/275.md"

@@ -0,0 +1,97 @@
+# x-loading-s 全屏加载
+
+居中加载提示，用来替代 `uni.showLoading`。支持自定义文字、图标和颜色，需手动关闭。
+
+**微信内使用官方 `uni.showLoading`，图标、颜色、尺寸等样式字段不生效，仅保留签名。**
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持（官方 Loading） |
+
+### 调用
+
+```ts
+import { showLoading, hideLoading, XLOADINGS_TYPE } from "@/uni_modules/x-loading-s"
+
+showLoading({
+  title: "正在提交...",
+  success: () => {
+    console.log("已弹出")
+  }
+} as XLOADINGS_TYPE)
+
+// 或不传参
+showLoading()
+```
+
+主动关闭：
+
+```ts
+hideLoading()
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| showLoading | 可选 `XLOADINGS_TYPE` | 弹出加载，不传参用默认样式 |
+| hideLoading | 无 | 关闭加载。页面卸载也会自动关 |
+| hideXloading | 无 | `hideLoading` 的兼容别名 |
+
+### 参数
+
+`XLOADINGS_TYPE`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| title | 提示文字 | `""` |
+| iconCode | Remix 图标 unicode，如 `EEC4`。微信不支持 | `EEC4` |
+| iconColor | 图标颜色 | `rgb(5,121,255)` |
+| iconSize | 图标大小 px | `36` |
+| titleSize | 文字字号 px | `12` |
+| titleColor | 文字色 | `#a0a1a7` |
+| contentBgColor | 内容底色 | `#ffffff` |
+| maskBgColor | 遮罩色 | `rgba(0,0,0,0.6)` |
+| size | 内容宽度 px，最小高 100 | `100` |
+| success | 弹出成功 | - |
+| fail | 弹出失败 | - |
+| complete | 调用结束 | - |
+
+没有 `close` 回调，关闭请调 `hideLoading()`。页面卸载时会自动隐藏。
+
+### 平台差异
+
+1. 微信小程序：`uni.showLoading`，仅 `title` 有效（空则 `"..."`），遮罩固定开启。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.1.1（2026-08-14）
+* 配置新增 success / fail / complete 回调，对齐 DCloud 函数风格：弹出成功走 success，失败走 fail，两者之后都会走 complete
+### 1.1.0（2026-08-13）
+* 重构为与 x-modal-s 一致的 DCloud 函数风格：新增 hideLoading()（对齐 uni.hideLoading 命名），hideXloading 保留为兼容别名
+* showLoading(options?) 支持无参调用，五端签名统一
+* 性能优化：安卓端 remixicon 字体缓存、代次隔离防止重入竞态、Activity 销毁时自动释放弹层防泄漏
+* iOS 端 hide 后释放视图引用并增加代次守卫
+* web 端字体只加载一次，入场动画改用 requestAnimationFrame 触发
+### 1.0.8（2026-04-21）
+* 修复可能存在的内存泄露风险
+### 1.0.7（2026-01-30）
+* 使用了sdk4.65+推出的接口来避免与官方的弹层冲突导致无法显示。
+### 1.0.6（2025-08-17）
+* 兼容原生鸿蒙
+### 1.0.3（2025-04-13）
+* 安卓端修改了布局结构现会覆盖官方的dialog-page了并且会自动隐藏状态栏,并可以覆盖底部安全区域
+### 1.0.2（2025-02-23）
+* 安卓添加了显示背景遮罩动画,及关闭遮罩动画
+* ios添加了显示背景遮罩动画,及关闭遮罩动画
+* 上述添加后,不管是显示和关闭都更加的自然
+### 1.0.1（2024-09-06）
+* 更新支持Uniapp
+### 1.0.0（2024-08-06）
+安卓,ios,web可用。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xLocationS /345/256/232/344/275/215.md"

@@ -0,0 +1,104 @@
+# x-location-s 定位
+
+一次性定位、持续定位，以及 WGS84 / GCJ02 / BD09 坐标互转。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```ts
+import { getLocation, startLocationUpdate, stopLocationUpdate, onLocationChange, offLocationChange, convertCoordinate } from "@/uni_modules/x-location-s"
+
+getLocation({
+  type: "wgs84",
+  isHighAccuracy: true,
+  success: (res) => {
+    console.log(res.latitude, res.longitude, res.accuracy)
+  }
+})
+
+const id = onLocationChange((res) => {
+  console.log(res.latitude, res.longitude)
+})
+startLocationUpdate({
+  background: true,
+  type: "wgs84",
+  minUpdateInterval: 5000
+})
+
+convertCoordinate({
+  from: "wgs84",
+  to: "gcj02",
+  latitude: 39.9,
+  longitude: 116.4,
+  success: (res) => {
+    console.log(res.latitude, res.longitude)
+  }
+})
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| getLocation | `type?`、`altitude?`、`isHighAccuracy?`、`highAccuracyExpireTime?`、`success` | 一次性定位 |
+| startLocationUpdate | `background?`、`minUpdateInterval?`、`minUpdateDistance?`、`type?` 等 | 开始持续定位，结果走 `onLocationChange` |
+| stopLocationUpdate | 无 | 停止持续定位 |
+| onLocationChange | `(res) => void` | 订阅位置变化，返回监听 id |
+| offLocationChange | `id` | 取消对应订阅 |
+| convertCoordinate | `from`、`to`、`latitude`、`longitude`、`success` | WGS84 / GCJ02 / BD09 互转 |
+
+### 参数
+
+`getLocation`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| type | `wgs84` / `gcj02` / `bd09` | `wgs84` |
+| altitude | 是否要海拔 | `false` |
+| isHighAccuracy | 高精度 | `false` |
+| highAccuracyExpireTime | 高精度超时 ms | `8000` |
+| success / fail / complete | 回调 | - |
+
+`startLocationUpdate`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| background | 后台持续定位。Web / 微信忽略 | `false` |
+| minUpdateInterval | 最小间隔 ms | `5000` |
+| minUpdateDistance | 最小距离米，0 不限 | `0` |
+| type | 坐标系 | `wgs84` |
+| altitude | 是否要海拔 | `false` |
+| isHighAccuracy | 高精度 | `false` |
+| notificationTitle / notificationText | Android 前台服务通知 | - |
+
+`XLocationResult`：`latitude`、`longitude`、`accuracy`、`altitude`、`speed`、`direction`、`coordSystem`、`timestamp`。
+
+### 平台差异
+
+1. Web 需 HTTPS；`background: true` 会失败。
+2. Android 后台定位走前台服务；Android 11+ 后台权限需用户到设置里开。
+3. iOS 后台需「始终允许」。
+4. 微信须在 app.json 声明定位 scope 与 `requiredPrivateInfos`。
+5. 鸿蒙后台需配置 `backgroundModes`（可参考插件 `harmony-configs`）。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+# x-location-s
+
+### 1.0.0（2026-07-31）
+
+- 首次发布
+- 提供 `getLocation` 获取当前位置
+- 提供 `startLocationUpdate` / `stopLocationUpdate` 前后台持续定位
+- 提供 `onLocationChange` / `offLocationChange` 位置变化监听
+- 提供 `convertCoordinate` WGS84 / GCJ02 / BD09 坐标互转
+- 兼容 Android / iOS / Web / 微信小程序 / 鸿蒙

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xMakephoneS /346/213/250/346/211/223/347/224/265/350/257/235.md"

@@ -0,0 +1,59 @@
+# x-makephone-s 拨打电话
+
+拨打电话，对齐 `uni.makePhoneCall` 的跨端调用。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```ts
+import { makePhone, XMakePhoneOptions } from "@/uni_modules/x-makephone-s"
+
+makePhone({
+  tel: "10086",
+  success: (res) => {
+    console.log(res.errCode)
+  },
+  fail: (err) => {
+    console.log(err.errCode, err.errMsg)
+  }
+} as XMakePhoneOptions)
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| makePhone | `tel`，可选 `success` / `fail` / `complete` | 调起拨号 |
+
+### 参数
+
+`XMakePhoneOptions`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| tel | 电话号码 | 必填 |
+| success | 成功，`errCode` 为 0 | - |
+| fail | 失败 | - |
+| complete | 结束 | - |
+
+错误码：`1001` 缺少号码，`1002` 不支持或失败，`1003` 拨号权限被拒绝（Android）。
+
+### 平台差异
+
+1. Android 10+ 打开拨号盘；更低版本可能直接拨打。
+2. 微信走 `wx.makePhoneCall`。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-07-31）
+
+- 持 Android / iOS / HarmonyOS / Web / 微信小程序

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xMediaplayS /345/252/222/344/275/223/346/222/255/346/224/276/344/270/216/345/275/225/345/210/266.md"

@@ -0,0 +1,151 @@
+# x-mediaplay-s 媒体播放与录制
+
+音频播放与录音。播放走系统播放器；录音输出 mp3 / wav。全局单例，新的播放或录音会抢占上一会话。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```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)
+  }
+})
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| play | `XMediaPlayOptions`，见下方 | 播放音频，会抢占上一会话 |
+| pause | 无 | 暂停 |
+| resume | 无 | 从暂停处继续 |
+| stop | 无 | 停止播放 |
+| seek | `positionMs: number` | 跳到指定毫秒 |
+| setVolume | `volume: number`，0~1 | 设置音量 |
+| getPlayInfo | 无 | 返回 `{ current, total, state, percent }` |
+| isPlaying | 无 | 是否正在播放 |
+| startRecord | `XMediaRecordOptions`，见下方 | 开始录音，会抢占上一会话 |
+| stopRecord | 无 | 停止并保存，走 `success` |
+| cancelRecord | 无 | 取消并丢弃当前录音 |
+| getRecordState | 无 | 返回 `idle` / `recording` / `stopping` |
+| isRecording | 无 | 是否正在录音 |
+| getVersion | 无 | 原生核心版本，微信为空 |
+
+### 参数
+
+`XMediaPlayOptions`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| url | 本地 / http(s) / blob | 必填 |
+| autoplay | 就绪后自动播 | `true` |
+| loop | 循环 | `false` |
+| volume | 音量 0~1 | `1` |
+| startPosition | 起播位置 ms | `0` |
+| infoInterval | `onInfo` 间隔 ms，小于 100 按 100 | `500` |
+| onInfo | 进度与状态 | - |
+| success | 起播成功 | - |
+| fail | 失败 | - |
+| complete | 结束 | - |
+
+`XMediaRecordOptions`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| format | `mp3` / `wav` | `mp3` |
+| sampleRate | 采样率，wav 可用 44100 | `16000` |
+| channelCount | 声道 | `1` |
+| bitrate | mp3 码率 kbps，wav 忽略 | `48` |
+| maxDurationMs | 到点自动 success | `60000` |
+| savePath | 输出路径，Web 忽略 | 各端缓存 |
+| levelInterval | `onLevel` / `onWave` 间隔 ms | `200` |
+| 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` 丢弃产物。