Audio Object

class Audio extends Object

Plays sounds from files or memory, discovers and operates audio devices, controls what other applications are playing, observes levels, and records from a microphone or from what an output device is playing.

This class is exported by the KS module:

#Import "Ks" { Audio }

Note: This class is experimental: it and its nested types may change or be removed without deprecation. See #Warn Experimental.

Note: This class has no instances; its members are used directly on the class. Calling Audio() throws an Error.

The related types below, such as Audio.Clip, are nested in Audio, and importing Audio introduces no other names.

The Sound functions are the AutoHotkey-compatible surface. This class adds to them.

Table of Contents

• Conventions
• Audio — probes, clips, one-line playback, devices, applications, events
• Audio.Clip
• Audio.Device
• Audio.Output
• Audio.Playback
• Audio.Session
• Audio.Meter
• Audio.Recorder
• Audio.Recording
• Platform Support
• Examples
• Related

Conventions

These hold for every member on this page.

Selecting a device

Everywhere a device is accepted it may be an Audio.Device, an exact Id, an exact and unique Name, or an empty string for the platform's current default. A name matching several devices throws a ValueError listing their ids; a selector matching none throws an OSError.

Error handling

Where a script must not throw, check the matching probe first.

Audio

Capability probes

Each of these is a read-only true or false. Reading one never opens a device or prompts for permission.

IsFormatSupported

Supported := Audio.IsFormatSupported(Format)

Returns 1 (true) if Load can decode that container, or 0 (false) otherwise. Format is a token or an extension, with or without the leading dot, such as "wav" or ".WAV". This never inspects a file.

Note: WAV is supported on every platform. Other containers depend on the host's decoders: Windows reports mp3, m4a, aac, wma and flac; Linux requires libsndfile, or ffmpeg on PATH; Ogg and Opus are not supported on Windows or macOS. Where a container is unsupported, convert the file to WAV or pass its samples to FromPcm.

Load

Clip := Audio.Load(Path)

Decodes a file into a reusable, immutable Audio.Clip. A relative path resolves once, against the current A_WorkingDir, at the moment of the call.

An empty path, a path containing a NUL, or a syntactically invalid path throws a ValueError before any I/O. A missing or unreadable file, an invalid container, and a format this host cannot decode each throw an OSError naming the file.

FromPcm

Clip := Audio.FromPcm(Data, SampleRate , Channels, SampleFormat)

Copies headerless PCM out of a Buffer into an immutable clip. The copy is synchronous and complete, so Data may be reused or freed as soon as this returns.

Channels defaults to 1 and SampleFormat to "Signed16". The buffer must hold a whole number of frames — one frame being Channels samples — and must not be empty. A clip may hold at most 512 MiB of decoded samples.

Play

Playback := Audio.Play(Source , Volume, Loop, Pan, StartMilliseconds, Device)

Plays a clip or a file path and returns an Audio.Playback controlling that sound. Source is an Audio.Clip or a path, which is loaded through Load. Volume defaults to 100, Loop to false, Pan to 0, StartMilliseconds to 0 and Device to the current default output.

The sound plays through a private output of the script. Where Audio.Output.Play would return an empty string, this throws an OSError.

A starting point at or past the clip's duration is a ValueError.

To stop the sound, call Stop on the returned playback. To stop several sounds at once, play them through an Audio.Output and call its StopAll.

Devices

List := Audio.Devices(Kind)

Returns an Array of every present, usable Audio.Device. Kind is "Output", "Input" or "All" (the default), and any other token is a ValueError. "All" lists outputs before inputs.

A host with no audio at all returns an empty Array.

DefaultDevice

Device := Audio.DefaultDevice(Kind)

Returns the current default Audio.Device of one kind, or an empty string when the host has none. Kind is "Output" (the default) or "Input"; "All" is a ValueError.

Sessions

List := Audio.Sessions(PIDOrName, Device)

Returns an Array of every live application audio session, optionally narrowed to one process and one device.

PIDOrName is a process id, or an executable name with or without its .exe suffix. It is not a path: a value containing a slash or backslash is a ValueError. Omitted, it matches every session.

A host with no per-application audio model returns an empty Array.

SetApplicationVolume

Changed := Audio.SetApplicationVolume(PIDOrName, Volume , Device)

Sets one absolute volume on every session of a process and returns how many sessions were changed, which is 0 when nothing matched. Volume is an absolute level from 0 through 100; relative strings such as "+5" are not accepted here.

If a session which still exists refuses the change, an OSError is thrown after the other sessions are changed.

SetApplicationMute

Changed := Audio.SetApplicationMute(PIDOrName, Mute , Device)

Sets one absolute mute state on every session of a process and returns how many changed. Mute is a state, not a toggle.

OnDeviceChange

Hook := Audio.OnDeviceChange(Callback , Kind)
Hooks := Audio.Hooks

Calls Callback when a device arrives, is removed, is renamed, or becomes the default, and returns a running hook controlling the subscription.

Callback is a function object, called as Callback(Hook, Change, Device), where Change is "Added", "Removed", "Changed" or "DefaultChanged" and Device is the Audio.Device the change concerns; for "Removed" its Status is "Missing". A_EventInfo is not set. Kind filters the devices reported: "Output", "Input" or "All" (the default).

A notification which changes nothing observable does not call back.

The returned hook is an Audio.DeviceHook, an EventHook with no additional members. Audio.Hooks is an Array of the running hooks.

The hook does not keep the script running; a script which only waits for device changes calls Persistent.

An unknown Kind is a ValueError, and subscribing where IsDeviceChangeSupported is false raises an OSError.

Audio.Clip

class Audio.Clip extends Object

One decoded sound: immutable, reusable, and safe to play many times at once. A clip is produced by Audio.Load or Audio.FromPcm; calling Audio.Clip() throws an Error naming those two.

Every property is read-only.

Audio.Device

class Audio.Device extends Object

A snapshot of one audio endpoint, plus the controls that endpoint owns. A device is produced by Audio.Devices and Audio.DefaultDevice, and returned by several other members; calling Audio.Device() throws an Error.

Id is the durable identity: Refresh() never adopts a same-named replacement.

Operating a device whose Status is "Missing" raises an OSError telling the caller to Refresh() first. Reading or writing Volume or Mute on a host without endpoint volume control raises an OSError.

Note: What ToClr returns depends on the platform; on Windows it is a Core Audio interface. On Linux, ToClr throws an OSError. See also SoundGetInterface.

Audio.Output

class Audio.Output extends Object

Output := Audio.Output(Device, VoiceLimit, VoicePolicy, LatencyMilliseconds)

An explicit mixer and the one native stream behind it.

Construction opens nothing; call Open or TryOpen to open the stream. Device defaults to the current default output and is followed as that default changes; naming a device pins the output to it. VoiceLimit is 1 through 256 and defaults to 16. VoicePolicy defaults to "Oldest". LatencyMilliseconds is 5 through 500 and defaults to 20; it is a scheduling target, not a promised floor.

A script may hold at most 16 open outputs at once, counting the private one Audio.Play uses. It may likewise hold 8 running recorders and 16 running meters. Exceeding a cap throws an OSError.

Voice policy

A voice is one sound in flight. When every voice is taken, VoicePolicy decides what a new play does:

Members

While an output is "Transitioning" after a default change, IsAvailable is false, nothing is prepared, and Play returns an empty string; nothing is played through the stale stream. An output pinned to a specific device which goes away becomes "Unavailable" and waits for that same id to return.

Volume and Mute belong to the open stream: a closed output reports 100 and false, and a value assigned to either while it is closed is discarded. VoicePolicy is held on the output itself, so it survives a Close and applies to the next Open.

Audio.Playback

class Audio.Playback extends Object

One sound in flight. A playback is produced by Audio.Play and Audio.Output.Play; calling Audio.Playback() throws an Error.

A playback controls only its own sound; after its voice is stolen, it controls nothing.

Audio.Session

class Audio.Session extends Object

One application's audio on one device. Sessions are produced by Audio.Sessions; calling Audio.Session() throws an Error.

On Linux, retitling a live audio stream keeps its session identity. This correction is source-reviewed and awaits Linux verification.

A session object is bound to that exact session; a later session of the same application needs a new object from Audio.Sessions.

Operating an expired session raises an OSError telling the caller to Refresh() first. On a platform with no per-application audio model, every member which reaches the platform raises an OSError explaining what to use instead.

Audio.Meter

class Audio.Meter extends Object

Meter := Audio.Meter(Target, IntervalMilliseconds)

An explicit observation of a device's or a session's level.

Target is an Audio.Device, an Audio.Session, a device selector, or an empty string for the current default output. IntervalMilliseconds is 20 through 1000 and defaults to 50. Construction snapshots the target and opens nothing.

Read Peak whenever a value is wanted, for instance from a timer.

Audio.Recorder

class Audio.Recorder extends Object

Recorder := Audio.Recorder(Source, Path, Device, SampleRate, Channels, SampleFormat, ChunkMilliseconds, MaximumDurationMilliseconds)

One capture, from a microphone or from what an output device is playing. Construction checks every option and opens nothing.

Source is "Microphone" (the default) or "SystemOutput". Path is a .wav file to write; left empty, the recording is kept in memory instead. Device is a device selector of the kind that source implies, defaulting to the current default. SampleRate defaults to 48000, Channels to 1, SampleFormat to "Signed16", and ChunkMilliseconds to 100 within 10 through 1000 — the buffer size the capture device is asked for, which a backend may deliver more often than. MaximumDurationMilliseconds is 0 for unbounded, or 1 through 86400000.

A recorder is single-use: construct another for a second recording.

Recording captures whatever the device carries, which can include other people and other applications. Microphone capture requires the script's AudioCapture capability, granted at build time or through RequestCapabilities, and on platforms which ask, the operating system's own microphone permission. A denial raises an OSError naming the privacy setting to change, and no frames are captured.

An in-memory recording stops at 10 minutes or 256 MiB, whichever arrives first; a file recording is bounded only by MaximumDurationMilliseconds. The destination's parent directory must already exist — no directory is created. The device is opened before the file is created or truncated, so a failed start leaves no empty file behind; a failure after frames have arrived keeps the partial file and finalizes a valid WAV header where it can.

Audio.Recording

class Audio.Recording extends Object

What a finished capture produced: an in-memory clip or a file path. A recording is produced by Audio.Recorder.Stop; calling Audio.Recording() throws an Error.

Every property is read-only.

Platform Support

Playback, clips, device discovery, endpoint volume and mute, and device-change events are part of every backend. What varies is application sessions, metering and capture.

Note: The Windows backend is verified on hardware, apart from recording. On Linux, device enumeration, playback and system-output recording are verified, and the rest is unverified. The macOS backend is unverified.

Linux

Works on X11 and Wayland alike, and requires a reachable PulseAudio or pipewire-pulse server. An application's process name and display name are available only when it publishes them.

Audio.Device.Volume uses the system mixer's slider percentage, so 50 means 50% in the mixer. Endpoint and session volume writes preserve channel balance; readings above 100 are clamped to 100. Session volume retains the linear-gain scale described above.

Note: A recording can include about 100 ms of audio buffered before it started, and a capture opened immediately after another on the same source can lose a similar amount. Use DurationMilliseconds for a recording's length, and leave a short gap between back-to-back captures.

macOS

Device volume and mute use the selected input or output direction. If the device only exposes channel controls, writes cover every channel. This channel fallback is unverified on hardware.

Audio.Sessions returns an empty Array, and SetApplicationVolume and SetApplicationMute throw an OSError. Use Audio.Device.Volume and Mute instead.

Audio.Meter.Start throws an OSError. Audio.Output.Peak, Audio.Playback.Peak and Audio.Recorder.Peak are supported.

To record system output, install a loopback device such as BlackHole and record it as an input device.

Examples

These examples were verified on Windows, except the recording example.

#Import "Ks" { Audio }

Sound := Audio.Play(A_WinDir "\Media\notify.wav")
while Sound.IsPlaying
    Sleep 50

#Import "Ks" { Audio }

Click := Audio.Load(A_ScriptDir "\click.wav")
Out := Audio.Output("", 8, "Oldest")
Out.Open()
Out.Prepare(Click)

F3::Out.Play(Click, 70)
F4::Out.StopAll()

#Import "Ks" { Audio }

Music := Audio.Play(A_ScriptDir "\theme.wav", 40, true)

Sleep 5000
Level := Music.Volume
while (Level > 0) {
    Music.Volume := Level := Max(0, Level - 2)
    Sleep 50
}
Music.Stop()

#Import "Ks" { Audio }

Text := ""
for D in Audio.Devices("Output")
    Text .= D.Name " " Round(D.Volume) (D.IsDefault ? " (default)" : "") "`n"
MsgBox Text

#Import "Ks" { Audio }

if Audio.IsSessionControlSupported
    MsgBox Audio.SetApplicationMute("chrome", true) " sessions muted"

#Import "Ks" { Audio }

Rec := Audio.Recorder("Microphone", A_Desktop "\memo.wav")
Rec.Start()
Sleep 5000
if (Result := Rec.Stop())
    MsgBox "Wrote " Result.Path ", " Round(Result.DurationMilliseconds) " ms"

#Import "Ks" { Audio }

Hook := Audio.OnDeviceChange(DeviceChanged, "Output")
Persistent

DeviceChanged(ThisHook, Change, Device)
{
    ToolTip Change ": " Device.Name
    SetTimer () => ToolTip(), -2000
}

Related

Sound functions, SoundPlay, SoundBeep, SoundSetVolume, SoundGetInterface, EventHook, Buffer, KS module, Platform Support