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).
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.
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.
# 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
Slide the reference sample over this snapshot and return the best similarity. Uses 64 normalized amplitude-mel bands and averages similarity across active reference frames; missing sound reduces the score. Silent windows are not matches. No speech recognition, speed or pitch correction is performed. A sample longer than the clip is an error. Recalibrate thresholds after a matcher update using independent recordings.
# 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
Listen for this reference in new audio for timeout_ms milliseconds and return the first AudioMatch, or None when no match is found. Starts configured capture if needed and keeps it active until Audio.stop() or macro completion. Only audio received after this call subscribes is eligible. Scans continuous overlapping candidates on a 10 ms grid, reusing spectra across chunk boundaries; this prevents polling gaps but does not guarantee recognition. For a sample of at least 100 ms with substantial sound, a near-perfect match (score at least 0.9999) returns as soon as the full sample arrives. Other strong matches (score at least 0.98) may refine their position for up to 20 ms; weaker matches use a 50 ms window. If a candidate first becomes strong near that window's end, one 20 ms refinement follows. Every match must meet the requested threshold. Timeout limits the recording window; processing eligible audio may add latency. Zero returns None without starting capture. Macro Pause discards pending audio and suspends the timeout; Resume searches a fresh segment. Lost capture, data overrun and corrupt audio are errors, never None.
Syntax
audio.find(timeout_ms, threshold)
Parameters
Name
Description
timeout_msNumber (0..2147483647)
Required whole recording-window duration in milliseconds, from 0 to 2147483647. Macro pause time is excluded. Window boundaries are approximated from recorder read-completion times, not hardware timestamps.
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.
# 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()
