audio_session - PythonIDE Docs

配置共享 AVAudioSession：设置音频类别、激活会话、查询当前输入/输出路由。

边界：影响全 App 的音频行为，通常在播放/录音之前配置。与 sound、avplayer、audio_recorder 配合使用。不需要单独权限，但会改变其他模块的音频路由；配置放在按钮回调或启动流程，不要在 body() 里反复切换。

#模块概览

项	说明
导入	`import audio_session`
适合做什么	后台播放、录音+外放、语音通话模式、查耳机/扬声器路由
调用时机	播放/录音前 `set_category` → `set_active(True)`
推荐顺序	设类别 → 激活 → 使用音频模块 → 可选 `set_active(False)`
全局影响	改类别会影响其他正在播放的音频

#快速开始

下面脚本切换到播放模式并查看当前路由：

python

import audio_session

try:
    audio_session.set_category("playback")
    audio_session.set_active(True)
    route = audio_session.current_route()
    print("输出:", route.get("outputs"))
    print("输入:", route.get("inputs"))
except audio_session.AudioSessionError as exc:
    print("配置失败:", exc, f"code={exc.code}")

录音场景常用 playAndRecord + defaultToSpeaker：

python

import audio_session

audio_session.set_category(
    "playAndRecord",
    mode="voiceChat",
    options=["defaultToSpeaker", "mixWithOthers"],
)
audio_session.set_active(True)

#AppUI 示例

类别切换和路由查询放在按钮回调。

python

import appui
import audio_session

state = appui.State(
    category="未设置",
    outputs="—",
    status="点击按钮配置音频会话",
)


def refresh_route():
    try:
        route = audio_session.current_route() or {}
        outs = route.get("outputs") or []
        if outs:
            names = [o.get("name", "?") for o in outs]
            state.outputs = " · ".join(names)
        else:
            state.outputs = "无输出设备"
    except audio_session.AudioSessionError as exc:
        state.outputs = f"查询失败: {exc}"


def use_playback():
    try:
        audio_session.set_category("playback", options=["mixWithOthers"])
        audio_session.set_active(True)
        state.batch_update(category="playback", status="已切换为播放模式")
        refresh_route()
    except audio_session.AudioSessionError as exc:
        state.status = f"失败: {exc}"


def use_record():
    try:
        audio_session.set_category(
            "playAndRecord",
            options=["defaultToSpeaker"],
        )
        audio_session.set_active(True)
        state.batch_update(category="playAndRecord", status="已切换为录音模式")
        refresh_route()
    except audio_session.AudioSessionError as exc:
        state.status = f"失败: {exc}"


def deactivate():
    try:
        audio_session.set_active(False)
        state.status = "会话已停用"
    except audio_session.AudioSessionError as exc:
        state.status = f"停用失败: {exc}"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("当前状态", [
                appui.LabeledContent("类别", value=state.category),
                appui.LabeledContent("输出路由", value=state.outputs),
            ]),
            appui.Section("操作", [
                appui.Button("播放模式", action=use_playback)
                .button_style("bordered_prominent"),
                appui.Button("录音模式", action=use_record),
                appui.Button("刷新路由", action=refresh_route),
                appui.Button("停用会话", action=deactivate, role="destructive"),
                appui.Text(state.status).foreground_color("secondaryLabel"),
            ], footer="切换类别会影响其他正在播放的音频。"),
        ]).navigation_title("音频会话")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`set_category(category, mode, options)`	设置音频类别
`set_active(active)`	激活 / 停用会话
`current_route()`	当前输入/输出路由
`AudioSessionError`	配置失败时抛出

#set_category

set_category(category, mode=None, options=None)

category	说明
`playback`	后台播放（默认回退值）
`record`	仅录音
`playAndRecord` / `play_and_record`	播放 + 录音
`ambient`	与其他 App 混音
`soloAmbient` / `solo_ambient`	独占环境音
`multiRoute`	多路由

mode	说明
`voiceChat` / `voice_chat`	语音通话
`videoChat` / `video_chat`	视频通话
`spokenAudio` / `spoken_audio`	有声内容
`measurement`	测量
`default`	默认

options	说明
`mixWithOthers`	与其他 App 混音
`duckOthers`	压低其他 App 音量
`defaultToSpeaker`	默认外放扬声器
`bluetooth`	允许蓝牙
`airplay`	允许 AirPlay

#set_active

set_active(active=True) — 激活或停用共享音频会话。

#current_route

current_route() 返回：

python

{
    "inputs": [{"name": "...", "type": "..."}],
    "outputs": [{"name": "...", "type": "..."}],
}

#常见错误

错误写法	后果	修正
在 `body()` 里反复 `set_category`	每次刷新都改全局音频	放进按钮或启动回调
录音前不设 `playAndRecord`	录音无声或路由错误	录音前配置类别
与 audio_recorder 类别冲突	启动失败或无声	统一在录音前设好类别
忘记 `set_active(True)`	配置不生效	类别后激活会话

#相关文档

文档	用途
sound	播放音效
avplayer	音视频播放
audio_recorder	麦克风录音
speech	语音合成

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。