app.audio - Audio Control API

System volume, sound effects playback, text-to-speech, and audio device information.

Volume Control

app.audio.volume()

Get the system output volume.

Returns: number|nil, error - 0.0 to 1.0

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

app.audio.setVolume(value)

Set the system output volume.

Parameters:

• value (number) - volume value (0.0-1.0, automatically clamped)

Returns: boolean, error

app.audio.setVolume(0.5)  -- Set to 50%

app.audio.isMuted()

Check if the system is muted.

Returns: boolean

if app.audio.isMuted() then
    app.log.info("System is muted")
end

app.audio.setMuted(muted)

Set the mute state.

Parameters:

• muted (boolean) - whether to mute

Returns: boolean, error

app.audio.setMuted(true)   -- Mute
app.audio.setMuted(false)  -- Unmute

Playback

app.audio.playSound(name)

Play a system alert sound.

Parameters:

• name (string) - alert sound name (e.g., “Ping”, “Funk”, “Glass”, “Basso”)

Returns: boolean, error

app.audio.playSound("Ping")

app.audio.playFile(path)

Play an audio file.

Parameters:

• path (string) - audio file path

Returns: boolean, error

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

Text-to-Speech

app.audio.speak(text, options?)

Speak text aloud (blocks until speech completes).

Parameters:

• text (string) - text to speak
• options (table, optional):
  • voice (string) - voice ID
  • rate (number) - speech rate
  • volume (number) - volume (0.0-1.0)

Returns: boolean, error

-- Default voice
app.audio.speak("Hello World")

-- Specify Chinese voice
app.audio.speak("Hello World", {voice = "com.apple.voice.compact.zh-CN.Tingting"})

app.audio.stopSpeaking()

Stop the current speech.

Returns: boolean

app.audio.stopSpeaking()

app.audio.voices()

Get the list of available voices.

Returns: array<table> - each item contains:

• id (string) - voice ID
• name (string) - voice name
• language (string) - language code

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

Device Information

app.audio.outputDevices()

Get the list of audio output devices.

Returns: array<table> - each item: {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()

Get the list of audio input devices.

Returns: array<table> - each item: {id, name, isDefault}

local devices = app.audio.inputDevices()

app.audio.setDefaultOutputDevice(id)

Set the system default audio output device.

Parameters:

• id (string) - device ID (obtained from outputDevices())

Returns: 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)

Set the system default audio input device.

Parameters:

• id (string) - device ID (obtained from inputDevices())

Returns: 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

Event Watching

app.audio.watch(event, callback)

Watch for audio device change events.

Parameters:

• event (string) - event name (currently only "defaultDeviceChanged" is supported)
• callback (function) - callback function, receives an event table:
  • scope (string) - which device type changed: "output" or "input"
  • deviceId (string) - new default device ID
  • deviceName (string) - new default device name

Returns: string, error - watcher handle ID

app.audio.watch("defaultDeviceChanged", function(e)
    app.log.info(string.format("Default %s device changed to: %s",
        e.scope,
        e.deviceName
    ))
end)

app.audio.stopAllWatchers()

Stop all audio event watchers registered by the current plugin.

Returns: boolean

app.audio.stopAllWatchers()

app.audio.listWatchers()

List all audio event watchers registered by the current plugin.

Returns: array<table> - each item contains:

• id (string) - watcher handle ID
• event (string) - event name being watched

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

Examples

Read Selected File Content Aloud

function MyPlugin:handleReadAloud(context)
    local file = context.selectedFiles[1]
    local content, err = app.file.read(file)
    if not content then
        app.dialog.alert("Error", err or "Failed to read file")
        return
    end

    -- Truncate to first 1000 characters
    if #content > 1000 then
        content = content:sub(1, 1000) .. "..."
    end

    app.audio.speak(content)
end