# @capawesome/capacitor-audio-session 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-audio-session/

版本：0\.1\.2
npm 元数据更新时间：2026-09-02T08:21:52.052Z
中文译文更新时间：2026-11-09T05:04:00.100Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-audio-session
原文对照：https://npmcn.com/package/%40capawesome/capacitor-audio-session/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/audio-session/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：92.1 kB，35 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T06:20:31.205Z
- 最新版本发布：2026-09-02T08:21:51.665Z
- 近 30 天下载量：10254（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

用于配置和观察iOS音频会话的电容插件.

## 安装

```sh
npm install @capawesome/capacitor-audio-session
```

也可以使用：`pnpm add @capawesome/capacitor-audio-session`、`yarn add @capawesome/capacitor-audio-session`、`bun add @capawesome/capacitor-audio-session`

## README

# 电源音频会话插件

配置和观察 iOS 的电容插件 [音频会话](https://developer.apple.com/documentation/avfaudio/avaudiosession)。 。 。 .

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

Capacitor音频会话插件是Capacitor应用程序最完整的音频会话管理解决方案之一. 以下是一些关键特征:

-   🎛️ **配置**: 设置音频会话类别、模式和选项.
-   🔌 **激活**: 启动并关闭音频会话.
-   🔊 **输出路由**: 读取当前音频输出并覆盖输出端口.
-   📡 **活动**: 观察中断和路由更改事件.
-   🤝 **兼容性**: 与 [音频播放器](https://capawesome.io/docs/sdks/capacitor/audio-player/) 财务报告和审定财务报表 [录音机](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

音频会话插件通常在应用程序需要精细控制iOS上的音频行为时使用,例如:

-   **媒体播放应用程序**配置 `playback` 类,所以在其他应用程序被关闭时音频会继续播放 .
-   **语音和视频聊天**: 使用输出覆盖在接收器和内置扬声器之间切换.
-   **与其他应用程序相混合**: 让你的音频与使用分类选项的其他应用程序的音频一起播放( 或鸭子) .
-   **接听电话**:当会话中断时暂停播放,当中断结束时恢复播放.
-   **耳机意识**:在耳机或蓝牙设备通过观察路由变化而插入或出时进行反应.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-audio-session` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capawesome/capacitor-audio-session
npx cap sync
```

此插件仅可用于 **iOS系统**。在Android和Web上,所有方法都否认未执行.

## 配置

此插件不需要配置 .

## 使用量

以下示例显示如何配置音频会话,激活或关闭音频会话,读取当前音频输出,路由回放到内置扬声器,倾听中断和路由更改,并删除所有收听者.

### 配置音频会话

设置音频会话类别,模式和选项,例如用于中断其他应用程序音频的电影回放. 此插件的所有方法仅在 iOS 上可用 :

```typescript
import { AudioSession } from '@capawesome/capacitor-audio-session';

const configure = async () => {
  await AudioSession.configure({
    category: 'playback',
    mode: 'moviePlayback',
    options: {
      mixWithOthers: false,
    },
  });
};
```

### 激活或关闭音频会话

在播放或录制音频前激活音频会话,并在完成后关闭,以便其他应用程序可以恢复播放:

```typescript
import { AudioSession } from '@capawesome/capacitor-audio-session';

const setActive = async () => {
  await AudioSession.setActive({ active: true });
};
```

### 读取当前音频输出

获取当前音频路径的音频输出, 例如检查耳机是否连接 :

```typescript
import { AudioSession } from '@capawesome/capacitor-audio-session';

const getCurrentOutputs = async () => {
  const { outputs } = await AudioSession.getCurrentOutputs();
  return outputs;
};
```

### 回放内置扬声器的路由

覆盖用于回放的音频输出端口, 例如在呼叫时从接收器切换到扬声器 :

```typescript
import { AudioSession } from '@capawesome/capacitor-audio-session';

const overrideOutput = async () => {
  await AudioSession.overrideOutput({ type: 'speaker' });
};
```

### 听中断

音频会话中断时得到通知,例如接到电话。 这个 `shouldResume` 旗子告诉您在中断结束后是否应该恢复播放 :

```typescript
import { AudioSession } from '@capawesome/capacitor-audio-session';

const addInterruptionListener = async () => {
  await AudioSession.addListener('interruption', event => {
    console.log('Interruption:', event.type, event.shouldResume);
  });
};
```

### 路由更改时监听

音频路由改变时得到通知, 例如耳机插入或插出时 :

```typescript
import { AudioSession } from '@capawesome/capacitor-audio-session';

const addRouteChangeListener = async () => {
  await AudioSession.addListener('routeChange', event => {
    console.log('Route change:', event.reason, event.outputs);
  });
};
```

### 删除所有听众

删除所有注册此插件的听众 :

```typescript
import { AudioSession } from '@capawesome/capacitor-audio-session';

const removeAllListeners = async () => {
  await AudioSession.removeAllListeners();
};
```

## API 密码

-   [`configure(...)`](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-configure)
-   [`getCurrentOutputs()`](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-getcurrentoutputs)
-   [`overrideOutput(...)`](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-overrideoutput)
-   [`setActive(...)`](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-setactive)
-   [`addListener('interruption', ...)`](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-addlistenerinterruption-)
-   [`addListener('routeChange', ...)`](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-addlistenerroutechange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-type-aliases)

### 配置(...)

```typescript
configure(options: ConfigureOptions) => Promise<void>
```

配置音频会话类别、模式和选项.

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ConfigureOptions](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-configureoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 获取当前输出( )

```typescript
getCurrentOutputs() => Promise<GetCurrentOutputsResult>
```

获取当前音频路径的音频输出 .

仅在iOS上可用.

**回返情况:** `Promise<[GetCurrentOutputsResult](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-getcurrentoutputsresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 覆盖输出(...)

```typescript
overrideOutput(options: OverrideOutputOptions) => Promise<void>
```

覆盖用于播放的音频输出端口.

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[OverrideOutputOptions](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-overrideoutputoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 设置

```typescript
setActive(options: SetActiveOptions) => Promise<void>
```

启动或关闭音频会话 .

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetActiveOptions](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-setactiveoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ 中断 ” ,...)

```typescript
addListener(eventName: 'interruption', listenerFunc: (event: InterruptionEvent) => void) => Promise<PluginListenerHandle>
```

音频会话中断时打电话,例如通过接通电话.

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'interruption'` |
| **`listenerFunc`** | `(event: [InterruptionEvent](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-interruptionevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ route Change ” ,...)

```typescript
addListener(eventName: 'routeChange', listenerFunc: (event: RouteChangeEvent) => void) => Promise<PluginListenerHandle>
```

当音频路由改变时调用,例如耳机被插入或出时调用.

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'routeChange'` |
| **`listenerFunc`** | `(event: [RouteChangeEvent](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-routechangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

仅在iOS上可用.

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 配置选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`category`** | `[AudioSessionCategory](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-audiosessioncategory)` | 音频会话分类 . |  | 0.1.0 (中文(简体) ) |
| **`mode`** | `[AudioSessionMode](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-audiosessionmode)` | 音频会话模式 . | `'default'` | 0.1.0 (中文(简体) ) |
| **`options`** | `[AudioSessionCategoryOptions](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-audiosessioncategoryoptions)` | 音频会话分类选项 . |  | 0.1.0 (中文(简体) ) |

#### 音响类选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`allowAirPlay`** | `boolean` | AirPlay 设备是否可以用于输出 . | `false` | 0.1.0 (中文(简体) ) |
| **`allowBluetooth`** | `boolean` | 蓝牙无手设备是否可以用于输入和输出. | `false` | 0.1.0 (中文(简体) ) |
| **`allowBluetoothA2DP`** | `boolean` | 蓝牙A2DP设备是否可用于输出. | `false` | 0.1.0 (中文(简体) ) |
| **`defaultToSpeaker`** | `boolean` | 当没有其他音频路由连接时,音频是否被路由到内置扬声器而不是接收器. | `false` | 0.1.0 (中文(简体) ) |
| **`duckOthers`** | `boolean` | 其他会话的音频在播放时是否在音量上减少( ducated) . | `false` | 0.1.0 (中文(简体) ) |
| **`interruptSpokenAudioAndMixWithOthers`** | `boolean` | 是否使用其他会话的音频 `spokenAudio` 模式被中断,来自此会话的音频与所剩音频相混合. | `false` | 0.1.0 (中文(简体) ) |
| **`mixWithOthers`** | `boolean` | 本会话的音频是否与其他活动会话的音频相混合,而不是打断它们. | `false` | 0.1.0 (中文(简体) ) |

#### 获取当前输出结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`outputs`** | `AudioSessionOutput[]` | 当前音频路径的音频输出 . | 0.1.0 (中文(简体) ) |

#### 音频会议产出

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`portName`** | `string` | 音频输出端口的可人读取名. | 0.1.0 (中文(简体) ) |
| **`portType`** | `string` | 音频输出端口的类型 . | 0.1.0 (中文(简体) ) |

#### 取代输出选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `[OverrideOutputType](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-overrideoutputtype)` | 音频输出端口可路径回放到 . | 0.1.0 (中文(简体) ) |

#### 设置动作选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`active`** | `boolean` | 是否应激活音频会话( E)`true`)或已失效(`false`) (中文(简体) ). |  | 0.1.0 (中文(简体) ) |
| **`notifyOthersOnDeactivation`** | `boolean` | 当此会话被关闭时, 是否通知其它音频会话, 以便恢复播放 . | `true` | 0.1.0 (中文(简体) ) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 中断活动

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`shouldResume`** | `boolean` | 中断结束后恢复播放 。 仅 `true` 若为 `type` 实值 `ended`。 。 。 . | 0.1.0 (中文(简体) ) |
| **`type`** | `[InterruptionType](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-interruptiontype)` | 中断的类型. | 0.1.0 (中文(简体) ) |

#### 路由变化事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`outputs`** | `AudioSessionOutput[]` | 更改后音频路径的音频输出 . | 0.1.0 (中文(简体) ) |
| **`reason`** | `[RouteChangeReason](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-routechangereason)` | 音频路线改变的原因. | 0.1.0 (中文(简体) ) |

### 类型异名

#### 音频会议类别

音频会话分类 .

`'ambient' | 'multiRoute' | 'playAndRecord' | 'playback' | 'record' | 'soloAmbient'`

#### 音频会议模式

音频会话模式 .

`'default' | 'gameChat' | 'measurement' | 'moviePlayback' | 'spokenAudio' | 'videoChat' | 'videoRecording' | 'voiceChat' | 'voicePrompt'`

#### 覆盖输出类型

音频输出端口可路径回放到 .

`'default' | 'speaker'`

#### 中断主题

音频会话中断的类型 .

`'began' | 'ended'`

#### 路由变化Reason

音频路线改变的原因.

`'categoryChange' | 'newDeviceAvailable' | 'noSuitableRouteForCategory' | 'oldDeviceUnavailable' | 'override' | 'routeConfigurationChange' | 'unknown' | 'wakeFromSleep'`

## 会话所有权

音频会话由 [`AVAudioSession.sharedInstance()`](https://developer.apple.com/documentation/avfaudio/avaudiosession) 是一个 **单一、全应用** 对象。 此插件给您 **手动** 控制它,但其他与音频相关的插件(例如 [音频播放器](https://capawesome.io/docs/sdks/capacitor/audio-player/), (中文(简体) ), [录音机](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) 和语音识别插件)以及它们使用的基本平台API.

由于会议是共同的 **最后写取胜**: 调用 `configure(...)` 可能覆盖另一个插件设置的类别、模式或选项,反之亦然。 此插件无法阻止 。 如果您将这个插件与其他音频插件结合, 请在调换回放、 录音和其他音频方案时, 确保重新配置会话 .

## 财务问题

### 此插件与其他类似插件有何不同?

它通过一个完全输入的 API 来给您对 iOS 音频会话的精细控制: 设置分类,模式和选项, 激活或关闭会话, 读取当前输出并覆盖输出路径, 观察中断和路由更改事件. 它诚实地记录了音频会话的共享和全应用性质,所以你确切地知道它如何与其他音频代码并列,并且它被积极维护在最新的Capacitor和iOS版本上. 如果只播放一个简单的声音,一个基本设置就足够了;如果需要精确的会话控制,这个插件就是为此设计的.

### 这个插件在Android或Web上可用吗?

不,这个插件只在iOS上可用,因为它控制了iOS的特有性 [音频会话](https://developer.apple.com/documentation/avfaudio/avaudiosession)。在Android和Web上,所有方法都拒绝作为未执行的方法,因此可以安全地将插件包含在跨平台的应用中.

### 为什么我的音频会话设置会被其他插件所压倒?

音频会话是与其他音频相关插件(例如: [音频播放器](https://capawesome.io/docs/sdks/capacitor/audio-player/) 财务报告和审定财务报表 [录音机](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) 插件)和它们使用的基本平台API. 最后的写胜出,所以另一个插件可能会覆盖您设置的类别,模式或选项. 每次在回放,录音和其他音频情景之间切换时,都会重新配置会话. 见 [会话所有权](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-session-ownership) 详细情况.

### 我的应用程序怎么能在不打扰其他应用程序的情况下播放音频?

使用 `mixWithOthers` 调用时的类别选项 `configure(...)` 将音频与其它活动会话的音频相混合,而不是打断它们。 或者,使用 `duckOthers` 选项,以减小音频播放时其他会话的音量.

### 电话中断后我怎么恢复播放?

为您添加一个收听器 `interruption` 活动。 当活动 `type` 实值 `ended` 财务报告和审定财务报表 `shouldResume` 实值 `true`,应该恢复播放。 见 [听中断](https://npmcn.com/package/%40capawesome/capacitor-audio-session/#readme-listen-for-interruptions) 举个例子.

### 我要怎么把音频传送到扩音器?

打电话 `overrideOutput(...)` 类型 `speaker` 以返回到内置扬声器,并使用 `default` 以恢复默认路径。 如果您希望音频在没有其他路径连接时默认被传送到扬声器,请使用 `defaultToSpeaker` 调用时的类别选项 `configure(...)`。 。 。 .

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [音频播放器](https://capawesome.io/docs/sdks/capacitor/audio-player/): 播放有背景支持的音频.
-   [录音机](https://capawesome.io/docs/sdks/capacitor/audio-recorder/):用设备的麦克风记录音频.
-   [媒体会议](https://capawesome.io/docs/sdks/capacitor/media-session/): 与媒体控制器,音量键和媒体按钮进行交互.
-   [数量](https://capawesome.io/docs/sdks/capacitor/volume/):控制音量并观察硬件音量按钮按下.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-session/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-session/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-audio-session 是什么？

用于配置和观察iOS音频会话的电容插件\.

### 如何安装 @capawesome/capacitor-audio-session？

在项目目录运行 npm install @capawesome/capacitor-audio-session，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-audio-session 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/capacitor-audio-session 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-audio-session 可以商用吗？

@capawesome/capacitor-audio-session 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-audio-session 的下载量有多少？

根据 npm 官方下载统计，@capawesome/capacitor-audio-session 在 2026/10/09 – 2026/11/07 这 30 天内被下载 10,254 次，日均约 342 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/capacitor-audio-session 还在维护吗？

最新版本 0\.1\.2 发布于 2026/09/02（2 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/07/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。