A read-only audio value for recognizing sounds in an app or game.
Syntax
Audio(name)
Constructor parameters
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
Returns
Audio
Behavior / side effects
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).
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
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()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Related APIs
None
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.
Syntax
Audio.start()
Parameters
None
Returns
None
Behavior / side effects
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.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Example
# Start configured app audio capture after permission and consent
Audio.start()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
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.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Example
# Release the configured audio recorder
Audio.stop()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Copy the most recent audio into an independent snapshot without waiting for more data.
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
Behavior / side effects
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.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
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)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Slide the reference sample over this snapshot and return the best similarity.
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
Behavior / side effects
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.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
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()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Listen for this reference in new audio for timeout_ms milliseconds and return the first AudioMatch, or None when no match is found.
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.
Required · Positional or named
No default
Returns
AudioMatch | None
Behavior / side effects
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.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
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()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
