app.audio - 音频控制 API

系统音量、播放音效、文字转语音和音频设备信息。

音量控制

app.audio.volume()

获取系统输出音量。

返回值: number|nil, error - 0.0 到 1.0

local vol = app.audio.volume()
app.log.info("音量: " .. math.floor(vol * 100) .. "%")

app.audio.setVolume(value)

设置系统输出音量。

参数:

• value (number) - 音量值（0.0-1.0，自动裁剪）

返回值: boolean, error

app.audio.setVolume(0.5)  -- 设为 50%

app.audio.isMuted()

检查是否静音。

返回值: boolean

if app.audio.isMuted() then
    app.log.info("系统已静音")
end

app.audio.setMuted(muted)

设置静音状态。

参数:

• muted (boolean) - 是否静音

返回值: boolean, error

app.audio.setMuted(true)   -- 静音
app.audio.setMuted(false)  -- 取消静音

播放

app.audio.playSound(name)

播放系统提示音。

参数:

• name (string) - 提示音名称（如 “Ping”, “Funk”, “Glass”, “Basso”）

返回值: boolean, error

app.audio.playSound("Ping")

app.audio.playFile(path)

播放音频文件。

参数:

• path (string) - 音频文件路径

返回值: boolean, error

app.audio.playFile("/path/to/sound.mp3")

文字转语音

app.audio.speak(text, opts?)

朗读文本（阻塞直到朗读完成）。

参数:

• text (string) - 要朗读的文本
• opts (table, 可选):
  • voice (string) - 语音 ID
  • rate (number) - 语速
  • volume (number) - 音量（0.0-1.0）

返回值: boolean, error

-- 默认语音
app.audio.speak("Hello World")

-- 指定中文语音
app.audio.speak("你好世界", {voice = "com.apple.voice.compact.zh-CN.Tingting"})

app.audio.stopSpeaking()

停止当前朗读。

返回值: boolean

app.audio.stopSpeaking()

app.audio.voices()

获取可用语音列表。

返回值: array<table> - 每项包含:

• id (string) - 语音 ID
• name (string) - 语音名称
• language (string) - 语言代码

local voices = app.audio.voices()
for _, v in ipairs(voices) do
    if v.language:find("zh") then
        app.log.info(v.name .. " (" .. v.id .. ")")
    end
end

设备信息

app.audio.outputDevices()

获取音频输出设备列表。

返回值: array<table> - 每项: {id, name, isDefault}

local devices = app.audio.outputDevices()
for _, d in ipairs(devices) do
    local mark = d.isDefault and " ✓" or ""
    app.log.info(d.name .. mark)
end

app.audio.inputDevices()

获取音频输入设备列表。

返回值: array<table> - 每项: {id, name, isDefault}

local devices = app.audio.inputDevices()

app.audio.setDefaultOutputDevice(id)

设置系统默认音频输出设备。

参数:

• id (string) - 设备 ID（从 outputDevices() 获取）

返回值: boolean, error

local devices = app.audio.outputDevices()
for _, d in ipairs(devices) do
    if d.name:find("AirPods") then
        local ok, err = app.audio.setDefaultOutputDevice(d.id)
        break
    end
end

app.audio.setDefaultInputDevice(id)

设置系统默认音频输入设备。

参数:

• id (string) - 设备 ID（从 inputDevices() 获取）

返回值: boolean, error

local devices = app.audio.inputDevices()
for _, d in ipairs(devices) do
    if d.name == "MacBook Pro Microphone" then
        app.audio.setDefaultInputDevice(d.id)
        break
    end
end

事件监听

app.audio.watch(event, callback)

监听音频设备变化事件。

参数:

• event (string) - 事件名称（目前仅支持 "defaultDeviceChanged"）
• callback (function) - 回调函数，接收事件表:
  • scope (string) - 变化的设备类型: "output" 或 "input"
  • deviceId (string) - 新默认设备 ID
  • deviceName (string) - 新默认设备名称

返回值: string, error - watcher 句柄 ID

app.audio.watch("defaultDeviceChanged", function(e)
    app.log.info(string.format("默认%s设备已变更为: %s",
        e.scope == "output" and "输出" or "输入",
        e.deviceName
    ))
end)

app.audio.stopAllWatchers()

停止当前插件注册的所有音频事件监听器。

返回值: boolean

app.audio.stopAllWatchers()

app.audio.listWatchers()

列出当前插件已注册的音频事件监听器。

返回值: array<table> - 每项包含:

• id (string) - watcher 句柄 ID
• event (string) - 监听的事件名称

local watchers = app.audio.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

示例

朗读选中文件内容

function MyPlugin:handleReadAloud(context)
    local file = context.selectedFiles[1]
    local content, err = app.file.read(file)
    if not content then
        app.dialog.alert("错误", err or "无法读取文件")
        return
    end

    -- 截取前 1000 字符
    if #content > 1000 then
        content = content:sub(1, 1000) .. "..."
    end

    app.audio.speak(content)
end