sound - PythonIDE Docs

音效与本地音频播放：短音效、长音频 Player、音量与静音开关控制。

边界：短反馈用 play_effect；本地长音频用 Player。远程视频/流媒体请看 avplayer；文字朗读用 speech。MIDIPlayer 由原生 AVMIDIPlayer 播放本地 MIDI，可选本地 sound bank，不是占位返回值。

R2 增量：本地音频可传项目相对路径、appui.FileResource 或 appui.MediaSource.file/asset。App 不附带内置音效库；请先把音频导入项目。inline data 与需自定义 header 的远程媒体不属于此字符串 bridge。

R7 增量：播放器和 MIDI 资源按 MiniApp owner 注册并在 session 结束时释放；controller_status() 可查看当前 owner 资源数，play_effect_async(..., budget=...) 提供统一任务/错误/预算入口。

严格异步失败抛出 SoundError。

#模块概览

项	说明
导入	`import sound`
适合做什么	点击音效、成功/错误提示音、本地音乐/播客播放
调用时机	放在按钮回调；页面关闭时停止循环音效
推荐顺序	短音 `play_effect` → 保存 handle → 需要时 `stop_effect`
循环音效	`looping=True` 时必须保存 handle，否则无法停止

#快速开始

下面脚本播放短音效并调节全局音量：

python

import sound

handle = sound.play_effect("assets/click.wav", volume=0.8)
print("handle:", handle)

sound.set_volume(0.8)
print("全局音量:", sound.get_volume())

if handle:
    sound.stop_effect(handle)

#AppUI 示例

音效和音量控制放在按钮回调里，状态同步写回界面。

python

import appui
import sound

state = appui.State(
    status="未播放",
    volume=sound.get_volume(),
    handle=None,
)


def play_click():
    handle = sound.play_effect("assets/click.wav", volume=state.volume)
    state.handle = handle
    state.status = "音效已触发" if handle else "音效不可用（检查名称或文件）"


def play_loop():
    if state.handle:
        sound.stop_effect(state.handle)
    handle = sound.play_effect("assets/click.wav", volume=state.volume, looping=True)
    state.handle = handle
    state.status = "循环播放中" if handle else "循环音效不可用"


def stop_current():
    if state.handle:
        sound.stop_effect(state.handle)
        state.handle = None
    state.status = "已停止当前音效"


def stop_all():
    sound.stop_all_effects()
    state.batch_update(handle=None, status="已停止所有音效")


def update_volume(value):
    state.volume = value
    sound.set_volume(value)
    state.status = f"全局音量 {value:.1f}"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("音效", [
                appui.Button("播放点击音", action=play_click)
                .button_style("bordered_prominent"),
                appui.Button("循环播放", action=play_loop),
                appui.Button("停止当前", action=stop_current),
                appui.Button("停止全部", action=stop_all, role="destructive"),
            ]),
            appui.Section("音量", [
                appui.Slider(
                    value=state.volume,
                    minimum=0,
                    maximum=1,
                    step=0.1,
                    label="全局音量",
                    on_change=update_volume,
                ),
                appui.Text(state.status).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("音效")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`play_effect(name, ...)`	播放短音效 → handle
`stop_effect(handle)`	停止指定音效
`stop_all_effects()`	停止全部音效
`set_volume(v)` / `get_volume()`	全局主音量 0.0–1.0
`set_honors_silent_switch(flag)`	是否遵守 iOS 静音开关
`Player(path)`	本地长音频播放器
`MIDIPlayer(path, sound_bank_path="")`	原生 MIDI 播放器
`controller_status()`	当前 owner 的播放器/音效资源状态
`play_effect_async(..., budget=...)`	可取消、可超时的短音效任务

#短音效

play_effect(name, volume=1.0, pitch=1.0, pan=0.0, looping=False)

python

handle = sound.play_effect("assets/click.wav", volume=0.8)
handle = sound.play_effect("assets/loop.wav", looping=True)
sound.stop_effect(handle)
sound.stop_all_effects()

参数	说明
`name`	项目内音频路径、`FileResource` 或受支持的 `MediaSource`
`volume`	0.0–1.0
`pitch`	播放速率 0.5–2.0
`pan`	立体声 -1.0（左）到 1.0（右）
`looping`	循环播放，需保存 handle 才能停止

失败时返回 None。

#长音频 Player

Player(file_path) — 本地音频文件播放器：

python

player = sound.Player("audio.m4a")
player.volume = 0.8
player.number_of_loops = 0  # 0 不循环，-1 无限循环
player.play()

print(player.playing, player.duration, player.current_time)
player.pause()
player.stop()

属性/方法	说明
`play()` / `pause()` / `stop()`	播放控制
`playing`	是否正在播放
`duration` / `current_time`	总时长与当前位置（秒）
`volume` / `rate`	音量与速率
`number_of_loops`	循环次数

#全局设置

python

sound.set_volume(0.7)
sound.set_honors_silent_switch(True)  # 遵守静音开关

set_volume 影响所有音效和 Player。

#选型

需求	API
点击/成功/错误短音	`play_effect`
停止某个循环音效	`stop_effect(handle)`
播放本地长音频	`Player`
远程视频/URL	avplayer
文字朗读	speech

#常见错误

错误写法	后果	修正
循环音效不保存 handle	无法停止	保存 `play_effect` 返回值
用 `sound` 朗读文字	能力不匹配	使用 speech
离开页面不停止循环音	后台继续响	调用 `stop_effect` 或 `stop_all_effects`
改全局音量无 UI 反馈	用户不知当前音量	界面显示音量值

#相关文档

文档	用途
avplayer	远程视频/音频流
speech	文字转语音
haptics	触觉反馈（可配合音效）
原生能力入口	MiniApp 场景配方

#预期效果

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