@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/11-/345/252/222/344/275/223.md

@@ -0,0 +1,1496 @@
+# 豆包应用插件的端能力 API: 媒体
+
+图片选择、预览、保存、压缩和信息读取；录音管理；背景音频和内部音频播放。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getBackgroundAudioManager](#getbackgroundaudiomanager) | 获取全局唯一的背景音频管理器。 |
+| [saveImageToPhotosAlbum](#saveimagetophotosalbum) | 保存图片到系统相册。 需要先确保应用已具备写入系统相册的权限。 |
+| [previewImage](#previewimage) | 预览图片。 |
+| [getImageInfo](#getimageinfo) | 获取图片信息。 |
+| [chooseImage](#chooseimage) | 选择图片。 |
+| [compressImage](#compressimage) | 压缩图片。 |
+| [createInnerAudioContext](#createinneraudiocontext) | 创建一个内部音频上下文。 |
+| [getRecorderManager](#getrecordermanager) | 获取全局唯一的录音管理器。 |
+
+## API 详情
+
+<a id="getbackgroundaudiomanager"></a>
+### getBackgroundAudioManager()
+
+# getBackgroundAudioManager
+
+获取全局唯一的背景音频管理器。
+
+## 扫码预览
+![扫码预览 getBackgroundAudioManager](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fget-background-audio-manager%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.37`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+- 调用 play 前先设置有效 src；播放结束且不再需要背景播放时调用 stop。
+
+## 调用方式
+
+### 同步 API
+
+```typescript
+getBackgroundAudioManager(): BackgroundAudioManager
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { getBackgroundAudioManager } from '@doubao-dev/framework/api';
+
+const audio = getBackgroundAudioManager();
+audio.title = '示例音频';
+audio.coverImgUrl = 'https://example.com/cover.jpg';
+audio.src = 'https://example.com/audio.mp3';
+audio.onError((error) => console.error(error.errCode, error.errMsg));
+audio.play();
+```
+
+## 返回值
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>buffered</code></td><td><code>number</code></td><td>是</td><td>当前已缓冲到的位置，单位秒。</td></tr>
+<tr><td><code>coverImgUrl</code></td><td><code>string</code></td><td>是</td><td>封面图片地址。</td></tr>
+<tr><td><code>currentTime</code></td><td><code>number</code></td><td>是</td><td>当前播放位置，单位秒。</td></tr>
+<tr><td><code>duration</code></td><td><code>number</code></td><td>是</td><td>音频总时长，单位秒；资源尚未就绪时为 0。</td></tr>
+<tr><td><code>epname</code></td><td><code>string</code></td><td>是</td><td>专辑名称。</td></tr>
+<tr><td><code>offCanplay</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 canplay 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offEnded</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 ended 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offError</code></td><td><code>(callback?: BackgroundAudioManagerErrorCallback) =&gt; void</code></td><td>是</td><td>取消 error 监听；省略 callback 时移除全部错误监听。</td></tr>
+<tr><td><code>offNext</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 next 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offPause</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 pause 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offPlay</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 play 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offPrev</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 prev 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offSeeked</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeked 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offSeeking</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeking 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offStop</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 stop 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offTimeUpdate</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 timeupdate 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offWaiting</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 waiting 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>onCanplay</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听音频可以开始播放的事件。</td></tr>
+<tr><td><code>onEnded</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听自然播放结束事件。</td></tr>
+<tr><td><code>onError</code></td><td><code>(callback: BackgroundAudioManagerErrorCallback) =&gt; void</code></td><td>是</td><td>监听播放、资源或占用冲突错误。</td></tr>
+<tr><td><code>onNext</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听用户在豆包背景播放控件中点击下一首的事件。</td></tr>
+<tr><td><code>onPause</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听暂停事件。</td></tr>
+<tr><td><code>onPlay</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听开始播放事件。</td></tr>
+<tr><td><code>onPrev</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听用户在豆包背景播放控件中点击上一首的事件。</td></tr>
+<tr><td><code>onSeeked</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听完成跳转播放位置的事件。</td></tr>
+<tr><td><code>onSeeking</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听开始跳转播放位置的事件。</td></tr>
+<tr><td><code>onStop</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听停止事件。</td></tr>
+<tr><td><code>onTimeUpdate</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听播放进度更新事件。</td></tr>
+<tr><td><code>onWaiting</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听因缓冲不足而等待的事件。</td></tr>
+<tr><td><code>pause</code></td><td><code>() =&gt; void</code></td><td>是</td><td>暂停播放。</td></tr>
+<tr><td><code>paused</code></td><td><code>boolean</code></td><td>是</td><td>当前是否暂停。</td></tr>
+<tr><td><code>play</code></td><td><code>() =&gt; void</code></td><td>是</td><td>播放音频；调用前需要先设置 src。</td></tr>
+<tr><td><code>playbackRate</code></td><td><code>number</code></td><td>是</td><td>播放速度，默认为 1。</td></tr>
+<tr><td><code>seek</code></td><td><code>(position: number) =&gt; void</code></td><td>是</td><td>跳转到指定播放位置，position 的单位为秒且不能为负数。</td></tr>
+<tr><td><code>singer</code></td><td><code>string</code></td><td>是</td><td>歌手或作者名称。</td></tr>
+<tr><td><code>src</code></td><td><code>string</code></td><td>是</td><td>音频资源地址，支持 HTTP、HTTPS 地址。</td></tr>
+<tr><td><code>startTime</code></td><td><code>number</code></td><td>是</td><td>开始播放的位置，单位秒，默认为 0。</td></tr>
+<tr><td><code>stop</code></td><td><code>() =&gt; void</code></td><td>是</td><td>停止播放并释放当前背景音频占用。</td></tr>
+<tr><td><code>title</code></td><td><code>string</code></td><td>是</td><td>音频标题，用于豆包背景播放信息展示。</td></tr>
+<tr><td><code>webUrl</code></td><td><code>string</code></td><td>是</td><td>音频关联页面地址。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "src": "",
+  "title": "",
+  "epname": "",
+  "singer": "",
+  "coverImgUrl": "",
+  "webUrl": "",
+  "startTime": 0,
+  "currentTime": 0,
+  "duration": 0,
+  "paused": true,
+  "buffered": 0,
+  "playbackRate": 1
+}
+```
+
+## 错误处理
+
+管理器操作失败时通过错误事件回调返回。错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errCode": -1001,
+  "errMsg": "background audio src is empty"
+}
+```
+
+### 错误码
+
+#### 事件错误码
+
+<table>
+<thead>
+<tr><th>错误字段</th><th>值</th><th>错误信息</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>event.errCode</code></td><td><code>-1001</code></td><td><code>background audio src is empty</code></td><td>Android、iOS</td><td>未设置 src 就调用 play</td><td>设置有效 src 后重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-1002</code></td><td><code>background audio play failed</code></td><td>Android</td><td>播放器启动失败</td><td>检查资源地址和网络状态后重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-1003</code></td><td><code>background audio seek failed</code></td><td>Android、iOS</td><td>播放位置跳转失败</td><td>等待 canplay 后在音频时长范围内重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-1004</code></td><td><code>background audio player unavailable</code></td><td>Android、iOS</td><td>播放器无法创建或已经不可用</td><td>重新设置 src 后重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-1005</code></td><td><code>background audio is occupied by another applet</code></td><td>Android、iOS</td><td>另一应用插件正在占用背景音频</td><td>提示用户结束其他背景音频后重试。</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **iOS**：部分系统播放器错误会在 onError 中返回系统错误码和错误信息，请为未识别的 errCode 提供兜底处理。
+
+## 已知限制与注意事项
+
+- 背景音频管理器是全局单例；后一次调用获取到的是同一实例和同一组播放状态。
+
+<a id="saveimagetophotosalbum"></a>
+### saveImageToPhotosAlbum()
+
+# saveImageToPhotosAlbum
+
+保存图片到系统相册。
+
+需要先确保应用已具备写入系统相册的权限。
+
+## 扫码预览
+![扫码预览 saveImageToPhotosAlbum](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fsave-image-to-photos-album%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 权限要求
+
+<table>
+<thead>
+<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td>系统权限</td><td>相册写入权限</td><td>按条件</td><td>Android、iOS</td><td>系统版本要求相册或外部存储写入授权时需要授予</td></tr>
+</tbody>
+</table>
+
+### 授权行为
+
+- **Android**：API 不主动展示应用授权弹窗。系统版本要求外部存储写入权限且权限未授予时，保存会失败；请引导用户在系统设置中开启后重试。
+- **iOS**：首次写入系统相册时由系统请求相册写入权限。用户拒绝或撤销后保存失败；请引导用户在系统设置中开启后重试。
+
+### 前置条件
+
+- 传入豆包应用插件可访问、存在且可解码的本地图片路径
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+saveImageToPhotosAlbum(params: SaveImageToPhotosAlbumParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>filePath</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>需要保存的图片文件路径。支持临时文件路径或持久文件路径，不支持网络图片路径。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { saveImageToPhotosAlbum } from '@doubao-dev/framework/api';
+
+await saveImageToPhotosAlbum({
+  filePath: '/path/to/image.png'
+});
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+<a id="previewimage"></a>
+### previewImage()
+
+# previewImage
+
+预览图片。
+
+## 扫码预览
+![扫码预览 previewImage](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fpreview-image%252Findex)
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：只按字符串形式与 urls 中的完整图片地址匹配，数字下标不能定位图片；传入数字下标时会从第一张图片开始预览。
+> **Android、iOS**：调用时忽略 referrerPolicy，预览请求不会应用该策略；调用方配置的 Referrer 策略不生效。
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- urls 至少包含一个有效图片地址；需要指定首图时传入 urls 中的完整图片地址
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+previewImage(params: PreviewImageParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>current</code></td><td><code>string | number</code></td><td>否</td><td><code>urls 中的第一张</code></td><td>-</td><td>当前显示图片的链接，或当前显示图片的下标。不填时显示 `urls` 中的第一张。Android、iOS：只按字符串形式与 urls 中的完整图片地址匹配，数字下标不能定位图片。</td></tr>
+<tr><td><code>referrerPolicy</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>预览页使用的 Referrer 策略。Android、iOS：调用时忽略 referrerPolicy，预览请求不会应用该策略。</td></tr>
+<tr><td><code>showmenu</code></td><td><code>boolean</code></td><td>否</td><td><code>true</code></td><td>-</td><td>是否显示长按菜单，菜单支持保存图片至本地相册。</td></tr>
+<tr><td><code>urls</code></td><td><code>string[]</code></td><td>是</td><td>-</td><td>-</td><td>需要预览的图片链接列表。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { previewImage } from '@doubao-dev/framework/api';
+
+await previewImage({
+  urls: ['https://example.com/a.png', 'https://example.com/b.png'],
+  current: 'https://example.com/a.png'
+});
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+<a id="getimageinfo"></a>
+### getImageInfo()
+
+# getImageInfo
+
+获取图片信息。
+
+## 扫码预览
+![扫码预览 getImageInfo](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fget-image-info%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- src 为豆包应用插件可访问的本地图片路径，或可直接下载的 HTTP、HTTPS 图片地址
+
+## 使用说明
+
+- 网络图片会产生下载流量；如需重复读取，建议先下载为本地临时文件。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+getImageInfo(params: GetImageInfoParams): Promise<GetImageInfoResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>src</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>图片路径，可以是相对路径、临时文件路径、存储文件路径或网络图片路径。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { getImageInfo } from '@doubao-dev/framework/api';
+
+const { width, height, path } = await getImageInfo({
+  src: '/tmp/image.png'
+});
+
+console.log(width, height, path);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>height</code></td><td><code>number</code></td><td>是</td><td>图片原始高度，单位 px，不考虑旋转。</td></tr>
+<tr><td><code>orientation</code></td><td><code>ImageOrientation</code></td><td>是</td><td>图片方向。</td></tr>
+<tr><td><code>path</code></td><td><code>string</code></td><td>是</td><td>图片路径；网络图片返回原始网络地址，本地图片返回可访问的本地路径。</td></tr>
+<tr><td><code>type</code></td><td><code>string</code></td><td>是</td><td>图片格式。</td></tr>
+<tr><td><code>width</code></td><td><code>number</code></td><td>是</td><td>图片原始宽度，单位 px，不考虑旋转。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "height": 1080,
+  "orientation": "up",
+  "path": "appletfile://temp/example.jpg",
+  "type": "jpeg",
+  "width": 1920
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 104,
+  "errMsg": "src cannot be empty"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>104</code></td><td><code>src cannot be empty</code></td><td>Android</td><td>src 为空字符串</td><td>传入非空的本地图片路径或 HTTP、HTTPS 地址。</td></tr>
+<tr><td><code>104</code></td><td><code>src must not be empty</code></td><td>iOS</td><td>src 为空字符串</td><td>传入非空的本地图片路径或 HTTP、HTTPS 地址。</td></tr>
+<tr><td><code>203</code></td><td><code>file does not exist</code></td><td>Android</td><td>本地图片文件不存在</td><td>检查路径仍在有效期内并重新获取文件。</td></tr>
+<tr><td><code>203</code></td><td><code>file not found</code></td><td>iOS</td><td>本地图片文件不存在</td><td>检查路径仍在有效期内并重新获取文件。</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **iOS**：网络图片下载到临时目录时不保留扩展名，type 可能返回 unknown；如需稳定识别格式，请以图片内容自行判断。
+
+<a id="chooseimage"></a>
+### chooseImage()
+
+# chooseImage
+
+选择图片。
+
+## 扫码预览
+![扫码预览 chooseImage](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fchoose-image%252Findex)
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：选择结果不受 sizeType 影响；调用方无法控制返回图片尺寸。
+> **Android、iOS**：仅当数组只包含 camera 时打开相机；其他组合均打开相册，user 和 environment 不生效；传入多个来源或 user、environment 时实际入口与配置不一致。
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 权限要求
+
+<table>
+<thead>
+<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td>系统权限</td><td>相册访问权限</td><td>按条件</td><td>Android、iOS</td><td>从相册选择图片时，系统或豆包图片选择器可能按系统版本请求访问权限</td></tr>
+<tr><td>系统权限</td><td>相机权限</td><td>按条件</td><td>Android、iOS</td><td>sourceType 只传 camera 时需要使用相机</td></tr>
+</tbody>
+</table>
+
+### 授权行为
+
+- **Android**：API 直接打开豆包图片选择器或相机。系统需要权限时会由对应选择器发起申请；拒绝或撤销后选择失败，请在系统设置中开启相册或相机权限后重试。
+- **iOS**：API 直接打开豆包相册选择器或系统相机。首次需要时系统会请求相册或相机权限；拒绝或撤销后选择失败，请在系统设置中开启后重试。
+
+### 前置条件
+
+- 在可展示图片选择器的前台页面中，由用户操作触发调用
+
+## 使用说明
+
+- 图片属于用户数据，仅在业务必需时选择，并及时释放不再使用的临时文件。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+chooseImage(params?: ChooseImageParams): Promise<ChooseImageResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>count</code></td><td><code>number</code></td><td>否</td><td><code>9</code></td><td>正整数</td><td>最多可选图片张数。使用相机时固定返回一张图片。</td></tr>
+<tr><td><code>imageId</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>H5 场景下可复用的 input 元素 ID。</td></tr>
+<tr><td><code>sizeType</code></td><td><code>ChooseImageSizeType[]</code></td><td>否</td><td><code>-</code></td><td>-</td><td>允许返回的图片尺寸类型。Android、iOS：选择结果不受 sizeType 影响。</td></tr>
+<tr><td><code>sourceType</code></td><td><code>ChooseImageSourceType[]</code></td><td>否</td><td><code>[&quot;album&quot;]</code></td><td>-</td><td>允许选择的图片来源。Android、iOS：仅当数组只包含 camera 时打开相机；其他组合均打开相册，user 和 environment 不生效。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { chooseImage } from '@doubao-dev/framework/api';
+
+const { tempFilePaths } = await chooseImage({
+  count: 1,
+  sourceType: ['album']
+});
+
+console.log(tempFilePaths);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>tempFilePaths</code></td><td><code>string[]</code></td><td>是</td><td>图片临时文件路径列表。</td></tr>
+<tr><td><code>tempFiles</code></td><td><code>ChooseImageFile[]</code></td><td>是</td><td>图片临时文件信息列表。</td></tr>
+<tr><td><code>tempFiles[].originalFileObj</code></td><td><code>File</code></td><td>否</td><td>原始浏览器 File 对象。</td></tr>
+<tr><td><code>tempFiles[].path</code></td><td><code>string</code></td><td>是</td><td>本地临时文件路径。</td></tr>
+<tr><td><code>tempFiles[].size</code></td><td><code>number</code></td><td>是</td><td>文件大小，单位 B。</td></tr>
+<tr><td><code>tempFiles[].type</code></td><td><code>string</code></td><td>否</td><td>文件 MIME 类型。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "tempFilePaths": ["appletfile://temp/example.jpg"],
+  "tempFiles": [
+    {
+      "path": "appletfile://temp/example.jpg",
+      "size": 245760,
+      "type": "image/jpeg"
+    }
+  ]
+}
+```
+
+## 平台差异
+
+- 使用相机时固定返回一张图片。
+
+<a id="compressimage"></a>
+### compressImage()
+
+# compressImage
+
+压缩图片。
+
+## 扫码预览
+![扫码预览 compressImage](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fcompress-image%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- src 指向豆包应用插件可访问、存在且可解码的本地图片
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+compressImage(params: CompressImageParams): Promise<CompressImageResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>compressedHeight</code></td><td><code>number</code></td><td>否</td><td><code>-</code></td><td>正数，且与 compressedWidth 同时传入</td><td>输出图片高度，单位 px。仅在 `compressedWidth` 同时为正数时调整尺寸。</td></tr>
+<tr><td><code>compressedWidth</code></td><td><code>number</code></td><td>否</td><td><code>-</code></td><td>正数，且与 compressedHeight 同时传入</td><td>输出图片宽度，单位 px。仅在 `compressedHeight` 同时为正数时调整尺寸。</td></tr>
+<tr><td><code>quality</code></td><td><code>number</code></td><td>否</td><td><code>80</code></td><td>0 至 100</td><td>JPEG 输出质量。</td></tr>
+<tr><td><code>src</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>图片路径。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { compressImage } from '@doubao-dev/framework/api';
+
+const { tempFilePath } = await compressImage({
+  src: '/tmp/image.png',
+  quality: 80
+});
+
+console.log(tempFilePath);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>tempFilePath</code></td><td><code>string</code></td><td>是</td><td>压缩后 JPEG 图片的临时文件路径。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "tempFilePath": "appletfile://temp/compressed-example.jpg"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 104,
+  "errMsg": "src cannot be empty"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>104</code></td><td><code>src cannot be empty</code></td><td>Android</td><td>src 为空字符串</td><td>传入非空的本地图片路径。</td></tr>
+<tr><td><code>104</code></td><td><code>src must not be empty</code></td><td>iOS</td><td>src 为空字符串</td><td>传入非空的本地图片路径。</td></tr>
+<tr><td><code>203</code></td><td><code>source file does not exist</code></td><td>Android</td><td>本地源图片文件不存在</td><td>检查路径仍在有效期内并重新获取文件。</td></tr>
+</tbody>
+</table>
+
+<a id="createinneraudiocontext"></a>
+### createInnerAudioContext()
+
+# createInnerAudioContext
+
+创建一个内部音频上下文。
+
+## 扫码预览
+![扫码预览 createInnerAudioContext](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fcreate-inner-audio-context%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.37`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+返回的对象拥有独立状态和事件监听。长音频或需要锁屏控制的场景请使用
+`getBackgroundAudioManager()`。
+
+- 调用 play 前先设置有效 src；不再使用实例时调用 destroy 释放资源。
+
+## 调用方式
+
+### 同步 API
+
+```typescript
+createInnerAudioContext(): InnerAudioContext
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { createInnerAudioContext } from '@doubao-dev/framework/api';
+
+const audio = createInnerAudioContext();
+audio.onError((error) => console.error(error.errCode, error.errMsg));
+audio.onEnded(() => audio.destroy());
+audio.src = 'https://example.com/audio.mp3';
+audio.play();
+```
+
+## 返回值
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>autoplay</code></td><td><code>boolean</code></td><td>是</td><td>设置 src 后是否自动播放，默认为 false。</td></tr>
+<tr><td><code>buffered</code></td><td><code>number</code></td><td>是</td><td>当前已缓冲到的位置，单位秒。</td></tr>
+<tr><td><code>currentTime</code></td><td><code>number</code></td><td>是</td><td>当前播放位置，单位秒。</td></tr>
+<tr><td><code>destroy</code></td><td><code>() =&gt; void</code></td><td>是</td><td>销毁当前上下文并释放播放资源；销毁后不能继续调用。</td></tr>
+<tr><td><code>duration</code></td><td><code>number</code></td><td>是</td><td>音频总时长，单位秒；资源尚未就绪时为 0。</td></tr>
+<tr><td><code>loop</code></td><td><code>boolean</code></td><td>是</td><td>是否循环播放，默认为 false。</td></tr>
+<tr><td><code>offCanplay</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 canplay 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offEnded</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 ended 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offError</code></td><td><code>(callback?: InnerAudioContextErrorCallback) =&gt; void</code></td><td>是</td><td>取消 error 监听；省略 callback 时移除全部错误监听。</td></tr>
+<tr><td><code>offPause</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 pause 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offPlay</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 play 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offSeeked</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeked 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offSeeking</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeking 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offStop</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 stop 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offTimeUpdate</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 timeupdate 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>offWaiting</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 waiting 监听；省略 callback 时移除该事件的全部监听。</td></tr>
+<tr><td><code>onCanplay</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听音频可以开始播放的事件。</td></tr>
+<tr><td><code>onEnded</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听自然播放结束事件。</td></tr>
+<tr><td><code>onError</code></td><td><code>(callback: InnerAudioContextErrorCallback) =&gt; void</code></td><td>是</td><td>监听播放、参数或资源错误。</td></tr>
+<tr><td><code>onPause</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听暂停事件。</td></tr>
+<tr><td><code>onPlay</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听开始播放事件。</td></tr>
+<tr><td><code>onSeeked</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听完成跳转播放位置的事件。</td></tr>
+<tr><td><code>onSeeking</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听开始跳转播放位置的事件。</td></tr>
+<tr><td><code>onStop</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听停止事件。</td></tr>
+<tr><td><code>onTimeUpdate</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听播放进度更新事件。</td></tr>
+<tr><td><code>onWaiting</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听因缓冲不足而等待的事件。</td></tr>
+<tr><td><code>pause</code></td><td><code>() =&gt; void</code></td><td>是</td><td>暂停播放。</td></tr>
+<tr><td><code>paused</code></td><td><code>boolean</code></td><td>是</td><td>当前是否暂停。</td></tr>
+<tr><td><code>play</code></td><td><code>() =&gt; void</code></td><td>是</td><td>播放音频；调用前需要先设置 src。</td></tr>
+<tr><td><code>playbackRate</code></td><td><code>number</code></td><td>是</td><td>播放速度，豆包实际使用范围为 0.5 至 2，默认为 1。</td></tr>
+<tr><td><code>seek</code></td><td><code>(position: number) =&gt; void</code></td><td>是</td><td>跳转到指定播放位置，position 的单位为秒且不能为负数。</td></tr>
+<tr><td><code>src</code></td><td><code>string</code></td><td>是</td><td>音频资源地址，支持 HTTP、HTTPS 地址和豆包应用插件本地文件路径。</td></tr>
+<tr><td><code>startTime</code></td><td><code>number</code></td><td>是</td><td>开始播放的位置，单位秒，默认为 0。</td></tr>
+<tr><td><code>stop</code></td><td><code>() =&gt; void</code></td><td>是</td><td>停止播放并将播放位置归零。</td></tr>
+<tr><td><code>volume</code></td><td><code>number</code></td><td>是</td><td>音量，范围 0 至 1，默认为 1。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "src": "",
+  "startTime": 0,
+  "autoplay": false,
+  "loop": false,
+  "volume": 1,
+  "playbackRate": 1,
+  "currentTime": 0,
+  "duration": 0,
+  "paused": true,
+  "buffered": 0
+}
+```
+
+## 错误处理
+
+管理器操作失败时通过错误事件回调返回。错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errCode": -2003,
+  "errMsg": "inner audio src is empty"
+}
+```
+
+### 错误码
+
+#### 事件错误码
+
+<table>
+<thead>
+<tr><th>错误字段</th><th>值</th><th>错误信息</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>event.errCode</code></td><td><code>-2002</code></td><td><code>inner audio instance not found</code></td><td>Android、iOS</td><td>实例已销毁或不存在时继续操作</td><td>重新创建上下文，不要继续使用已销毁实例。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2003</code></td><td><code>inner audio src is empty</code></td><td>Android、iOS</td><td>未设置 src 就调用 play</td><td>设置有效 src 后重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2004</code></td><td><code>inner audio src is invalid</code></td><td>Android、iOS</td><td>src 无法解析或不受支持</td><td>改用有效的 HTTP、HTTPS 地址或豆包应用插件本地文件路径。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2005</code></td><td><code>inner audio player unavailable</code></td><td>Android、iOS</td><td>播放器无法创建或已不可用</td><td>销毁当前实例，重新创建后重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2006</code></td><td><code>inner audio seek failed</code></td><td>Android、iOS</td><td>播放位置跳转失败</td><td>等待 canplay 后在音频时长范围内重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2007</code></td><td><code>inner audio play failed</code></td><td>Android、iOS</td><td>音频播放失败</td><td>检查资源地址和网络状态后重试。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2009</code></td><td><code>inner audio playback is interrupted</code></td><td>Android、iOS</td><td>播放被其他音频任务中断</td><td>根据业务需要在中断结束后重新调用 play。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2010</code></td><td><code>inner audio runtime is unavailable</code></td><td>Android、iOS</td><td>当前页面无法创建音频实例</td><td>确保页面仍处于有效状态后重新创建实例。</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>-2012</code></td><td><code>invalid seek position</code></td><td>Android、iOS</td><td>seek 位置不是有限非负数</td><td>传入大于或等于 0 的秒数。</td></tr>
+</tbody>
+</table>
+
+<a id="getrecordermanager"></a>
+### getRecorderManager()
+
+# getRecorderManager
+
+获取全局唯一的录音管理器。
+
+## 扫码预览
+![扫码预览 getRecorderManager](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fget-recorder-manager%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.36`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 权限要求
+
+<table>
+<thead>
+<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td>应用权限</td><td><code>scope.record</code></td><td>必须</td><td>Android、iOS</td><td>需要应用录音授权</td></tr>
+<tr><td>系统权限</td><td>麦克风权限</td><td>必须</td><td>Android、iOS</td><td>需要使用系统麦克风录音</td></tr>
+</tbody>
+</table>
+
+### 授权行为
+
+- **Android**：首次调用 start 时会依次申请应用录音授权和系统麦克风权限；pause、resume、stop 不重复申请。拒绝、取消或撤销授权后 start 失败，再次调用 start 会重新发起仍可展示的授权；系统不再允许弹窗时需在系统设置中开启麦克风权限。
+- **iOS**：首次调用 start 时会申请应用录音授权和系统麦克风权限；pause、resume、stop 不重复申请。拒绝或撤销后 start 失败；再次调用 start 可重新发起应用授权，系统麦克风权限需在系统设置中开启。
+
+### 前置条件
+
+- 在应用权限声明中配置 scope.record，并在调用 start 前注册需要的 onError、onStop 和 onFrameRecorded 监听
+
+## 使用说明
+
+- 录音包含用户敏感数据，仅在用户明确操作后开始，并在不再需要时及时调用 stop。
+- start.duration 取 1 至 600000 的正整数，单位 ms；start.format 取 aac、pcm 或 wav；start.sampleRate 取 8000、11025、12000、16000、22050、24000、32000、44100 或 48000，单位 Hz。
+- start.numberOfChannels 取 1 或 2；start.encodeBitRate 为仅在 AAC 录音时生效的正整数，单位 bps；start.frameSize 取 0 或 1 至 4096 的整数，单位 KB。
+
+## 调用方式
+
+### 同步 API
+
+```typescript
+getRecorderManager(): RecorderManager
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```ts
+import { getRecorderManager } from '@doubao-dev/framework/api';
+
+const rm = getRecorderManager();
+rm.onError((error) => console.error('录音失败', error.errMsg));
+rm.onStop((result) => console.log('录音完成', result.tempFilePath));
+rm.start({ duration: 10000, format: 'aac' });
+```
+
+## 返回值
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>offError</code></td><td><code>(callback?: RecorderManagerErrorCallback) =&gt; void</code></td><td>是</td><td>取消 error 监听；省略 callback 时移除全部错误监听。</td></tr>
+<tr><td><code>offFrameRecorded</code></td><td><code>(callback?: RecorderManagerFrameRecordedCallback) =&gt; void</code></td><td>是</td><td>取消 frameRecorded 监听；省略 callback 时移除全部分片事件监听。</td></tr>
+<tr><td><code>offPause</code></td><td><code>(callback?: RecorderManagerStateCallback) =&gt; void</code></td><td>是</td><td>取消 pause 监听；省略 callback 时移除全部暂停事件监听。</td></tr>
+<tr><td><code>offResume</code></td><td><code>(callback?: RecorderManagerStateCallback) =&gt; void</code></td><td>是</td><td>取消 resume 监听；省略 callback 时移除全部恢复事件监听。</td></tr>
+<tr><td><code>offStart</code></td><td><code>(callback?: RecorderManagerStateCallback) =&gt; void</code></td><td>是</td><td>取消 start 监听；省略 callback 时移除全部开始事件监听。</td></tr>
+<tr><td><code>offStop</code></td><td><code>(callback?: RecorderManagerStopCallback) =&gt; void</code></td><td>是</td><td>取消 stop 监听；省略 callback 时移除全部停止事件监听。</td></tr>
+<tr><td><code>onError</code></td><td><code>(callback: RecorderManagerErrorCallback) =&gt; void</code></td><td>是</td><td>监听授权、录音状态和录制过程错误；回调参数 errMsg 为错误信息字符串。</td></tr>
+<tr><td><code>onFrameRecorded</code></td><td><code>(callback: RecorderManagerFrameRecordedCallback) =&gt; void</code></td><td>是</td><td>监听录音分片事件；需要在 start 时把 frameSize 设置为大于 0。回调参数包含 ArrayBuffer 类型的 frameBuffer 和布尔值 isLastFrame。</td></tr>
+<tr><td><code>onPause</code></td><td><code>(callback: RecorderManagerStateCallback) =&gt; void</code></td><td>是</td><td>监听录音暂停事件。</td></tr>
+<tr><td><code>onResume</code></td><td><code>(callback: RecorderManagerStateCallback) =&gt; void</code></td><td>是</td><td>监听录音恢复事件。</td></tr>
+<tr><td><code>onStart</code></td><td><code>(callback: RecorderManagerStateCallback) =&gt; void</code></td><td>是</td><td>监听录音开始事件。</td></tr>
+<tr><td><code>onStop</code></td><td><code>(callback: RecorderManagerStopCallback) =&gt; void</code></td><td>是</td><td>监听录音停止事件。回调参数包含 tempFilePath（字符串）、duration（毫秒）和 fileSize（字节）。</td></tr>
+<tr><td><code>pause</code></td><td><code>() =&gt; void</code></td><td>是</td><td>暂停正在进行的录音。</td></tr>
+<tr><td><code>resume</code></td><td><code>() =&gt; void</code></td><td>是</td><td>恢复已暂停的录音。</td></tr>
+<tr><td><code>start</code></td><td><code>(options?: RecorderManagerStartOptions) =&gt; void</code></td><td>是</td><td>开始录音；省略 options 时使用默认录音配置。duration 默认 60000 ms，format 默认 aac，sampleRate 默认 44100 Hz，numberOfChannels 默认 1，encodeBitRate 默认 128000 bps，frameSize 默认 0 KB。</td></tr>
+<tr><td><code>stop</code></td><td><code>() =&gt; void</code></td><td>是</td><td>停止录音并触发 onStop。</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：format 为 pcm 或 wav 时，必须把 frameSize 设置为 1 至 4096；输出文件为 WAV。
+- frameSize 大于 0 时使用 PCM 数据分片并输出 WAV 文件，encodeBitRate 不生效。
+
+## 相关类型
+
+<a id="backgroundaudiomanagereventcallback"></a>
+### BackgroundAudioManagerEventCallback
+
+背景音频普通事件回调。
+
+#### Type
+
+`() => void`
+
+<a id="backgroundaudiomanagererrorcallback"></a>
+### BackgroundAudioManagerErrorCallback
+
+背景音频错误事件回调。
+
+#### Type
+
+`(error: BackgroundAudioError) => void`
+
+<a id="backgroundaudiomanager"></a>
+### BackgroundAudioManager
+
+全局唯一背景音频管理器。
+
+#### Properties
+
+• **src**: `string` - 音频资源地址，支持 HTTP、HTTPS 地址
+• **title**: `string` - 音频标题，用于豆包背景播放信息展示
+• **epname**: `string` - 专辑名称
+• **singer**: `string` - 歌手或作者名称
+• **coverImgUrl**: `string` - 封面图片地址
+• **webUrl**: `string` - 音频关联页面地址
+• **startTime**: `number` - 开始播放的位置，单位秒，默认为 0
+• **currentTime**: `number` - 当前播放位置，单位秒
+• **duration**: `number` - 音频总时长，单位秒；资源尚未就绪时为 0
+• **paused**: `boolean` - 当前是否暂停
+• **buffered**: `number` - 当前已缓冲到的位置，单位秒
+• **playbackRate**: `number` - 播放速度，默认为 1
+• **play**: `() => void` - 播放音频；调用前需要先设置 src
+• **pause**: `() => void` - 暂停播放
+• **stop**: `() => void` - 停止播放并释放当前背景音频占用
+• **seek**: `(position: number) => void` - 跳转到指定播放位置，position 的单位为秒且不能为负数
+• **onCanplay**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听音频可以开始播放的事件
+• **offCanplay**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 canplay 监听；省略 callback 时移除该事件的全部监听
+• **onPlay**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听开始播放事件
+• **offPlay**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 play 监听；省略 callback 时移除该事件的全部监听
+• **onPause**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听暂停事件
+• **offPause**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 pause 监听；省略 callback 时移除该事件的全部监听
+• **onStop**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听停止事件
+• **offStop**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 stop 监听；省略 callback 时移除该事件的全部监听
+• **onEnded**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听自然播放结束事件
+• **offEnded**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 ended 监听；省略 callback 时移除该事件的全部监听
+• **onTimeUpdate**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听播放进度更新事件
+• **offTimeUpdate**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 timeupdate 监听；省略 callback 时移除该事件的全部监听
+• **onError**: `(callback: BackgroundAudioManagerErrorCallback) => void` - 监听播放、资源或占用冲突错误
+• **offError**: `(callback?: BackgroundAudioManagerErrorCallback) => void` - 取消 error 监听；省略 callback 时移除全部错误监听
+• **onWaiting**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听因缓冲不足而等待的事件
+• **offWaiting**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 waiting 监听；省略 callback 时移除该事件的全部监听
+• **onSeeking**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听开始跳转播放位置的事件
+• **offSeeking**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 seeking 监听；省略 callback 时移除该事件的全部监听
+• **onSeeked**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听完成跳转播放位置的事件
+• **offSeeked**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 seeked 监听；省略 callback 时移除该事件的全部监听
+• **onPrev**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听用户在豆包背景播放控件中点击上一首的事件
+• **offPrev**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 prev 监听；省略 callback 时移除该事件的全部监听
+• **onNext**: `(callback: BackgroundAudioManagerEventCallback) => void` - 监听用户在豆包背景播放控件中点击下一首的事件
+• **offNext**: `(callback?: BackgroundAudioManagerEventCallback) => void` - 取消 next 监听；省略 callback 时移除该事件的全部监听
+
+<a id="backgroundaudioerror"></a>
+### BackgroundAudioError
+
+背景音频错误信息。
+
+#### Properties
+
+• **errCode?**: `number` - 错误码。部分系统播放错误可能不提供稳定的业务码
+• **errMsg**: `string` - 错误信息
+
+<a id="saveimagetophotosalbumparams"></a>
+### SaveImageToPhotosAlbumParams
+
+保存图片到系统相册的请求参数。
+
+#### Properties
+
+• **filePath**: `string` - 需要保存的图片文件路径。支持临时文件路径或持久文件路径，不支持网络图片路径
+
+<a id="previewimageparams"></a>
+### PreviewImageParams
+
+预览图片的请求参数。
+
+#### Properties
+
+• **urls**: `string[]` - 需要预览的图片链接列表
+• **current?**: `string | number` - 当前显示图片的链接，或当前显示图片的下标。不填时显示 urls 中的第一张
+• **showmenu?**: `boolean` - 是否显示长按菜单，菜单支持保存图片至本地相册
+• **referrerPolicy?**: `string` - 预览页使用的 Referrer 策略
+
+<a id="getimageinfoparams"></a>
+### GetImageInfoParams
+
+获取图片信息的请求参数。
+
+#### Properties
+
+• **src**: `string` - 图片路径，可以是相对路径、临时文件路径、存储文件路径或网络图片路径
+
+<a id="imageorientation"></a>
+### ImageOrientation
+
+图片方向枚举。
+
+#### Type
+
+`| 'up'
+  | 'up-mirrored'
+  | 'down'
+  | 'down-mirrored'
+  | 'left-mirrored'
+  | 'right'
+  | 'right-mirrored'
+  | 'left'`
+
+<a id="getimageinforesult"></a>
+### GetImageInfoResult
+
+图片信息结果。
+
+#### Properties
+
+• **height**: `number` - 图片原始高度，单位 px，不考虑旋转
+• **orientation**: `ImageOrientation` - 图片方向
+• **path**: `string` - 图片路径；网络图片返回原始网络地址，本地图片返回可访问的本地路径
+• **type**: `string` - 图片格式
+• **width**: `number` - 图片原始宽度，单位 px，不考虑旋转
+
+<a id="chooseimagesizetype"></a>
+### ChooseImageSizeType
+
+可选的图片尺寸类型。
+
+#### Type
+
+`'original' | 'compressed'`
+
+<a id="chooseimagesourcetype"></a>
+### ChooseImageSourceType
+
+可选的图片来源类型。
+
+#### Type
+
+`'album' | 'camera' | 'user' | 'environment'`
+
+<a id="chooseimageparams"></a>
+### ChooseImageParams
+
+选择图片的请求参数。
+
+#### Properties
+
+• **count?**: `number` - 最多可选图片张数。使用相机时固定返回一张图片
+• **sizeType?**: `ChooseImageSizeType[]` - 允许返回的图片尺寸类型
+• **sourceType?**: `ChooseImageSourceType[]` - 允许选择的图片来源
+• **imageId?**: `string` - H5 场景下可复用的 input 元素 ID
+
+<a id="chooseimagefile"></a>
+### ChooseImageFile
+
+选择图片返回的单个文件信息。
+
+#### Properties
+
+• **path**: `string` - 本地临时文件路径
+• **size**: `number` - 文件大小，单位 B
+• **type?**: `string` - 文件 MIME 类型
+• **originalFileObj?**: `File` - 原始浏览器 File 对象
+
+<a id="chooseimageresult"></a>
+### ChooseImageResult
+
+选择图片结果。
+
+#### Properties
+
+• **tempFilePaths**: `string[]` - 图片临时文件路径列表
+• **tempFiles**: `ChooseImageFile[]` - 图片临时文件信息列表
+
+<a id="compressimageparams"></a>
+### CompressImageParams
+
+压缩图片的请求参数。
+
+#### Properties
+
+• **src**: `string` - 图片路径
+• **quality?**: `number` - JPEG 输出质量
+• **compressedWidth?**: `number` - 输出图片宽度，单位 px。仅在 compressedHeight 同时为正数时调整尺寸
+• **compressedHeight?**: `number` - 输出图片高度，单位 px。仅在 compressedWidth 同时为正数时调整尺寸
+
+<a id="compressimageresult"></a>
+### CompressImageResult
+
+压缩图片结果。
+
+#### Properties
+
+• **tempFilePath**: `string` - 压缩后 JPEG 图片的临时文件路径
+
+<a id="inneraudiocontexteventcallback"></a>
+### InnerAudioContextEventCallback
+
+内部音频普通事件回调。
+
+#### Type
+
+`() => void`
+
+<a id="inneraudiocontexterrorcallback"></a>
+### InnerAudioContextErrorCallback
+
+内部音频错误事件回调。
+
+#### Type
+
+`(error: InnerAudioError) => void`
+
+<a id="inneraudiocontext"></a>
+### InnerAudioContext
+
+内部音频上下文。
+
+#### Properties
+
+• **src**: `string` - 音频资源地址，支持 HTTP、HTTPS 地址和豆包应用插件本地文件路径
+• **startTime**: `number` - 开始播放的位置，单位秒，默认为 0
+• **autoplay**: `boolean` - 设置 src 后是否自动播放，默认为 false
+• **loop**: `boolean` - 是否循环播放，默认为 false
+• **volume**: `number` - 音量，范围 0 至 1，默认为 1
+• **playbackRate**: `number` - 播放速度，豆包实际使用范围为 0.5 至 2，默认为 1
+• **currentTime**: `number` - 当前播放位置，单位秒
+• **duration**: `number` - 音频总时长，单位秒；资源尚未就绪时为 0
+• **paused**: `boolean` - 当前是否暂停
+• **buffered**: `number` - 当前已缓冲到的位置，单位秒
+• **play**: `() => void` - 播放音频；调用前需要先设置 src
+• **pause**: `() => void` - 暂停播放
+• **stop**: `() => void` - 停止播放并将播放位置归零
+• **seek**: `(position: number) => void` - 跳转到指定播放位置，position 的单位为秒且不能为负数
+• **destroy**: `() => void` - 销毁当前上下文并释放播放资源；销毁后不能继续调用
+• **onCanplay**: `(callback: InnerAudioContextEventCallback) => void` - 监听音频可以开始播放的事件
+• **offCanplay**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 canplay 监听；省略 callback 时移除该事件的全部监听
+• **onPlay**: `(callback: InnerAudioContextEventCallback) => void` - 监听开始播放事件
+• **offPlay**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 play 监听；省略 callback 时移除该事件的全部监听
+• **onPause**: `(callback: InnerAudioContextEventCallback) => void` - 监听暂停事件
+• **offPause**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 pause 监听；省略 callback 时移除该事件的全部监听
+• **onStop**: `(callback: InnerAudioContextEventCallback) => void` - 监听停止事件
+• **offStop**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 stop 监听；省略 callback 时移除该事件的全部监听
+• **onEnded**: `(callback: InnerAudioContextEventCallback) => void` - 监听自然播放结束事件
+• **offEnded**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 ended 监听；省略 callback 时移除该事件的全部监听
+• **onTimeUpdate**: `(callback: InnerAudioContextEventCallback) => void` - 监听播放进度更新事件
+• **offTimeUpdate**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 timeupdate 监听；省略 callback 时移除该事件的全部监听
+• **onError**: `(callback: InnerAudioContextErrorCallback) => void` - 监听播放、参数或资源错误
+• **offError**: `(callback?: InnerAudioContextErrorCallback) => void` - 取消 error 监听；省略 callback 时移除全部错误监听
+• **onWaiting**: `(callback: InnerAudioContextEventCallback) => void` - 监听因缓冲不足而等待的事件
+• **offWaiting**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 waiting 监听；省略 callback 时移除该事件的全部监听
+• **onSeeking**: `(callback: InnerAudioContextEventCallback) => void` - 监听开始跳转播放位置的事件
+• **offSeeking**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 seeking 监听；省略 callback 时移除该事件的全部监听
+• **onSeeked**: `(callback: InnerAudioContextEventCallback) => void` - 监听完成跳转播放位置的事件
+• **offSeeked**: `(callback?: InnerAudioContextEventCallback) => void` - 取消 seeked 监听；省略 callback 时移除该事件的全部监听
+
+<a id="inneraudioerror"></a>
+### InnerAudioError
+
+内部音频错误信息。
+
+#### Properties
+
+• **errCode?**: `number` - 错误码。部分系统播放错误可能不提供该字段
+• **errMsg**: `string` - 错误信息
+
+<a id="recordermanagerstartoptions"></a>
+### RecorderManagerStartOptions
+
+开始录音的配置参数。
+
+#### Properties
+
+• **duration?**: `number` - 录音时长，单位 ms
+• **format?**: `RecorderFormat` - 录音格式。Android 录制 pcm 或 wav 时必须同时设置大于 0 的 frameSize
+• **sampleRate?**: `RecorderSampleRate` - 采样率
+• **numberOfChannels?**: `RecorderNumberOfChannels` - 录音通道数
+• **encodeBitRate?**: `number` - AAC 编码码率，单位 bps；分片录音输出 PCM/WAV 时不生效
+• **frameSize?**: `number` - 帧大小，单位 KB。大于 0 时通过 onFrameRecorded 回调分片数据，并输出 WAV 文件
+
+<a id="recordermanagerstatecallback"></a>
+### RecorderManagerStateCallback
+
+#### Type
+
+`() => void`
+
+<a id="recordermanagerstopcallback"></a>
+### RecorderManagerStopCallback
+
+#### Type
+
+`(event: RecorderManagerStopEvent) => void`
+
+<a id="recordermanagererrorcallback"></a>
+### RecorderManagerErrorCallback
+
+#### Type
+
+`(event: RecorderManagerErrorEvent) => void`
+
+<a id="recordermanagerframerecordedcallback"></a>
+### RecorderManagerFrameRecordedCallback
+
+#### Type
+
+`(event: RecorderManagerFrameRecordedEvent) => void`
+
+<a id="recordermanager"></a>
+### RecorderManager
+
+全局唯一的录音管理器。通过 getRecorderManager 获取实例。
+
+#### Properties
+
+• **start**: `(options?: RecorderManagerStartOptions) => void` - 开始录音；省略 options 时使用默认录音配置。duration 默认 60000 ms，format 默认 aac，sampleRate 默认 44100 Hz，numberOfChannels 默认 1，encodeBitRate 默认 128000 bps，frameSize 默认 0 KB
+• **pause**: `() => void` - 暂停正在进行的录音
+• **resume**: `() => void` - 恢复已暂停的录音
+• **stop**: `() => void` - 停止录音并触发 onStop
+• **onStart**: `(callback: RecorderManagerStateCallback) => void` - 监听录音开始事件
+• **offStart**: `(callback?: RecorderManagerStateCallback) => void` - 取消 start 监听；省略 callback 时移除全部开始事件监听
+• **onPause**: `(callback: RecorderManagerStateCallback) => void` - 监听录音暂停事件
+• **offPause**: `(callback?: RecorderManagerStateCallback) => void` - 取消 pause 监听；省略 callback 时移除全部暂停事件监听
+• **onResume**: `(callback: RecorderManagerStateCallback) => void` - 监听录音恢复事件
+• **offResume**: `(callback?: RecorderManagerStateCallback) => void` - 取消 resume 监听；省略 callback 时移除全部恢复事件监听
+• **onStop**: `(callback: RecorderManagerStopCallback) => void` - 监听录音停止事件。回调参数包含 tempFilePath（字符串）、duration（毫秒）和 fileSize（字节）
+• **offStop**: `(callback?: RecorderManagerStopCallback) => void` - 取消 stop 监听；省略 callback 时移除全部停止事件监听
+• **onError**: `(callback: RecorderManagerErrorCallback) => void` - 监听授权、录音状态和录制过程错误；回调参数 errMsg 为错误信息字符串
+• **offError**: `(callback?: RecorderManagerErrorCallback) => void` - 取消 error 监听；省略 callback 时移除全部错误监听
+• **onFrameRecorded**: `(callback: RecorderManagerFrameRecordedCallback) => void` - 监听录音分片事件；需要在 start 时把 frameSize 设置为大于 0。回调参数包含 ArrayBuffer 类型的 frameBuffer 和布尔值 isLastFrame
+• **offFrameRecorded**: `(callback?: RecorderManagerFrameRecordedCallback) => void` - 取消 frameRecorded 监听；省略 callback 时移除全部分片事件监听
+
+<a id="recorderformat"></a>
+### RecorderFormat
+
+录音格式。
+
+#### Type
+
+`'aac' | 'pcm' | 'wav'`
+
+<a id="recordersamplerate"></a>
+### RecorderSampleRate
+
+录音采样率。
+
+#### Type
+
+`8000 | 11025 | 12000 | 16000 | 22050 | 24000 | 32000 | 44100 | 48000`
+
+<a id="recordernumberofchannels"></a>
+### RecorderNumberOfChannels
+
+录音通道数。
+
+#### Type
+
+`1 | 2`
+
+<a id="recordermanagerstopevent"></a>
+### RecorderManagerStopEvent
+
+录音停止事件数据。
+
+#### Properties
+
+• **tempFilePath**: `string` - 录音文件的临时路径
+• **duration**: `number` - 录音时长，单位 ms
+• **fileSize**: `number` - 录音文件大小，单位 B
+
+<a id="recordermanagererrorevent"></a>
+### RecorderManagerErrorEvent
+
+录音错误事件数据。
+
+#### Properties
+
+• **errMsg**: `string` - 错误信息
+
+<a id="recordermanagerframerecordedevent"></a>
+### RecorderManagerFrameRecordedEvent
+
+录音分片事件数据。
+
+#### Properties
+
+• **frameBuffer**: `ArrayBuffer` - 当前帧数据，ArrayBuffer 类型
+• **isLastFrame**: `boolean` - 是否为最后一帧