> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# audio

音频播放组件，提供不占用页面布局的音频播放与实例控制能力。

<iframe src="https://developer.doubao.com/docs-preview/component-simulator/?caseId=audio"
  title="组件示例 audio"
  width="100%"
  height="700"
  loading="lazy"
  style="width:100%;height:700px;border:0;border-radius:16px;overflow:hidden;"
></iframe>

## 扫码预览

![扫码预览 audio](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Faudio%252Findex)

## Props

<table>
<thead>
<tr><th width="140">属性名</th><th width="240">类型</th><th width="120">默认值</th><th width="80">必填</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>attached</td><td><code>boolean</code></td><td>-</td><td>否</td><td>是否按需加载播放器实例，用于性能优化，常用于列表场景，其他情况无需设置</td></tr>
<tr><td>autoPlay</td><td><code>boolean</code></td><td>false</td><td>否</td><td>流数据变化后自动播放。</td></tr>
<tr><td>autoPrepare</td><td><code>boolean</code></td><td>true</td><td>否</td><td>在资源准备完成后自动预渲染播放器（显示首帧）</td></tr>
<tr><td>initTime</td><td><code>number</code></td><td>false</td><td>否</td><td>在资源准备完成后自动预渲染播放器（显示首帧）</td></tr>
<tr><td>loop</td><td><code>boolean</code></td><td>false</td><td>否</td><td>循环播放。视频开始播放后，循环状态变化不会改变视频的当前播放/暂停状态。</td></tr>
<tr><td>mute</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否静音实时播放器。</td></tr>
<tr><td>onEnded</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器播放结束。</td></tr>
<tr><td>onError</td><td><code>(e: { errorCode: number; errorMsg: string }) =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器接收到错误信息。</td></tr>
<tr><td>onPause</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器暂停。</td></tr>
<tr><td>onPlay</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器开始播放。</td></tr>
<tr><td>onPrepared</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器准备好播放。</td></tr>
<tr><td>onRedirected</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>如果访问 gecko 资源，加载是异步的</td></tr>
<tr><td>onSeek</td><td><code>(willPlay: boolean) =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器搜索。</td></tr>
<tr><td>onSrcChanged</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>源文件发生变化</td></tr>
<tr><td>onStop</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器停止。</td></tr>
<tr><td>onTimeUpdate</td><td><code>(e: { detail: { current: number; total: number } }) =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器进度更新</td></tr>
<tr><td>pauseOnHide</td><td><code>boolean</code></td><td>false</td><td>否</td><td>指定当 LynxView 退出背景或移出屏幕后是否暂停视频，以防止声音泄漏</td></tr>
<tr><td>playbackSpeed</td><td><code>number</code></td><td>1.0</td><td>否</td><td>指定播放速度</td></tr>
<tr><td>playUrl</td><td><code>string</code></td><td>undefined</td><td>否</td><td>指定视频播放源，一旦设置 play-url，播放器将尝试异步加载资源。在绑定重定向之前，所有播放控制逻辑将无效。</td></tr>
<tr><td>ref</td><td><code>ForwardedRef&lt;VideoEngineRef&gt;</code></td><td>-</td><td>否</td><td>-</td></tr>
<tr><td>videoEngineId</td><td><code>string</code></td><td>'videoengine'</td><td>否</td><td>用于选择 <code>x-video-engine</code>。请确保在整个页面中唯一。</td></tr>
<tr><td>volume</td><td><code>number</code></td><td>1.0</td><td>否</td><td>指定音量，范围：[0.0, 1.0]</td></tr>
</tbody>
</table>
