Audio

Class

A read-only audio value for recognizing sounds in an app or game. Use Audio(name) to load a saved sample, or Audio.recent(duration_ms) to copy recently captured audio. Capture and matching run on the device; continuous listening buffers are never uploaded and scripts cannot access raw audio (PCM).

Syntax

Audio(name)

Constructor parameters

Name Description

Name	Description
`nameString`	Required non-empty name of a sample created in this macro's Template Manager, not a file path. Loads immediately, including restored samples and samples in encrypted protected packages; missing or corrupt samples are errors. Backup/Store saves the selected source package and saved samples with the macro: at most 32 PCM16 mono 48 kHz WAV samples, each up to 10 seconds, and 4 MiB of WAV data in total. Required · Positional or named No default

nameString

Required non-empty name of a sample created in this macro's Template Manager, not a file path. Loads immediately, including restored samples and samples in encrypted protected packages; missing or corrupt samples are errors. Backup/Store saves the selected source package and saved samples with the macro: at most 32 PCM16 mono 48 kHz WAV samples, each up to 10 seconds, and 4 MiB of WAV data in total.

Required · Positional or named

No default

Returns

Audio

Example

# Recognize a local audio sample after listening starts
sample = Audio("alert")
Audio.start()
wait(2000)
clip = Audio.recent(duration_ms=2000)
result = clip.match(sample, threshold=0.85)
if result.matched:
    print(result.score, result.start_ms, result.end_ms)
Audio.stop()

Fields

Name	Description
`nameString \| None`	Saved sample name, or None for a recent snapshot.
`duration_msNumber`	Snapshot length in milliseconds.
`start_msNumber`	Start time in milliseconds; zero for a named sample, session-relative for a recent snapshot.
`end_msNumber`	Exclusive end time in milliseconds on the same timeline as start_ms.

Constructor example

# Load a sample saved in this macro
audio = Audio("alert")

Methods

5 methods

Audio.start

Static Method

Start listening to the selected app, never the microphone. Requires Android 10+, recording permission, MediaProjection consent and a source that allows capture. Calling again while listening preserves the buffer. Starting again after stop resets the session timestamps; reset any saved detection timestamp too. Pause clears history, but Resume keeps the original session time origin and includes the paused interval. Missing permission, configuration or capture session is an error.

Syntax

Audio.start()

Returns

None

Example

# Start configured app audio capture after permission and consent
Audio.start()

Audio.stop

Static Method

Stop audio capture and clear its buffer. Previously returned audio values remain usable; screen capture used elsewhere keeps running. Macro completion also releases audio capture.

Syntax

Audio.stop()

Returns

None

Example

# Release the configured audio recorder
Audio.stop()

Audio.recent

Static Method

Copy the most recent audio into an independent snapshot without waiting for more data. Only the latest 10 seconds are available; audio played before listening started cannot be recovered. Insufficient history or an unavailable recorder is an error. Silence alone does not prove the source app blocks capture.

Syntax

Audio.recent(duration_ms)

Parameters

Name	Description
`duration_msNumber (1..10000)`	Required whole duration from 1 to 10000 milliseconds. Required · Positional or named No default

Returns

Audio

Example

# Source app must be playing; keep at least 500 ms of history
Audio.start()
wait(600)
clip = Audio.recent(500)
print(clip.duration_ms)

Audio.match

Method

Find the best match for sample inside this audio and return its similarity score. Silence is not a match; missing parts of the sound lower the score. A sample longer than this audio is an error. This does not recognize speech or correct speed or pitch. Choose thresholds using separate recordings and check them again after matcher updates.

Syntax

audio.match(sample, threshold)

Parameters

Name	Description
`sampleAudio`	Reference audio value to locate inside this audio value. Required · Positional or named No default
`thresholdNumber (0..1)`	Required finite number from 0 to 1. Calibrate with independent recordings; 0.85 is an example, not a recommended universal threshold. Required · Positional or named No default

Returns

AudioMatch

Example

# Save an alert sample in Template Manager before running this example
sample = Audio("alert")
Audio.start()
wait(1500)
clip = Audio.recent(1500)
result = clip.match(sample, 0.85)
print(result)
Audio.stop()

Audio.find

Method

Wait for this sample in new audio and return a matching AudioMatch, or None if the recording window ends without a match. Only audio received after the call starts is searched; recognition is not guaranteed. Starts listening if needed, with the same requirements as Audio.start(), and keeps listening until Audio.stop() or macro completion. Processing may finish after timeout_ms. A timeout of 0 returns None without starting capture. Macro Pause discards pending audio and pauses the timeout; Resume searches new audio. Lost capture, data overrun or corrupt audio raises an error, not None.

Syntax

audio.find(timeout_ms, threshold)

Parameters

Name	Description
`timeout_msNumber (0..2147483647)`	Required whole duration from 0 to 2147483647 milliseconds. Macro pause time is excluded. The recording window is approximate; processing can finish later. Required · Positional or named No default
`thresholdNumber (0..1)`	Required finite number from 0 to 1. Calibrate with independent recordings; 0.85 is an example, not a recommended universal threshold. Required · Positional or named No default

Returns

AudioMatch | None

Example

# Wait for a new sound and handle timeout
audio = Audio("alert")
result = audio.find(timeout_ms=5000, threshold=0.85)
if result is not None:
    print(result.score, result.start_ms, result.end_ms)
Audio.stop()