@spec input_level() :: {float(), float()} | :silent | {:error, atom()}

Read the current microphone input level as {rms_db, peak_db} (dBFS), :silent when there is no measurable signal, or {:error, reason}.

start_input_metering/1 must be active first, else {:error, :not_metering}. Same {rms, peak} | :silent shape as MobAudioCapture.output_level/0, so the :mic source (here) and the :output source (mob_audio_capture) read uniformly.

@spec output_level(keyword()) :: {float(), float()} | :silent | {:error, atom()}

Read the current output signal level as {rms_db, peak_db} (dBFS, e.g. {-18.0, -6.0}), or :silent when there is no measurable signal.

This is the probe that distinguishes live audio from pushed silence — the one thing output_status/0 and adb dumpsys audio cannot tell you. Metering is instantaneous and only valid while audio plays, so call it as play → sleep a beat → output_level.

Options:

• source: :mob (default) — meters Mob.Audio's own player. Android needs RECORD_AUDIO (runtime-granted); iOS uses AVAudioPlayer metering.
• source: :mix — the global output mix. Unsupported for a normal app on both platforms (see module docs); use the separate capture plugin.

Returns {:error, reason} when unavailable: :not_playing (no active Mob.Audio player), :needs_record_audio (Android, permission not granted at runtime), or :unsupported_on_platform (:mix).

@spec output_status() :: %{
  volume: float(),
  muted: boolean(),
  route: route(),
  other_audio: boolean()
}

Read the current system audio output configuration.

Returns %{volume: float, muted: boolean, route: route(), other_audio: boolean}. Cheap, synchronous, no permission. The first thing to check when verifying sound: a volume of 0.0, muted: true, or a route of :none explains silence regardless of what a player is doing.

volume is normalized 0.0–1.0 (the media stream volume on Android, AVAudioSession.outputVolume on iOS). route is the active output sink. other_audio is true when another app is already playing (iOS isOtherAudioPlaying / Android isMusicActive).

@spec play(Mob.Socket.t(), String.t(), keyword()) :: Mob.Socket.t()

Play an audio file. Stops any currently playing audio first.

Options:

• loop: boolean (default false)
• volume: float 0.0–1.0 (default 1.0)

Result arrives as:

• {:audio, :playback_finished, %{path: path}}
• {:audio, :playback_error, %{reason: reason}}

@spec play_at(Mob.Socket.t(), String.t(), integer(), keyword()) :: Mob.Socket.t()

Schedule path to begin playing at absolute local wall-clock time at_wall_ms (in System.system_time(:millisecond) terms — caller is responsible for translating from a server-supplied target time via their own clock-sync component).

The audio hardware clock — not BEAM's timer wheel — fires playback at the requested instant. Multiple play_at/3 calls accumulate on the player's timeline (call stop_playback/1 to flush). If at_wall_ms is already in the past, the buffer plays as soon as the audio engine can.

Options:

• volume: float 0.0–1.0 (default 1.0)

Result arrives as {:audio, :playback_finished, %{path: path}} when the scheduled buffer drains, or {:audio, :playback_error, %{reason: reason}} if the file fails to open.

iOS: AVAudioEngine + AVAudioPlayerNode.scheduleBuffer(_:at:options:), with the at: AVAudioTime constructed from mach_absolute_time so the buffer starts at the requested host time.

Android: TODO — falls back to immediate playback on Android until the AAudio port lands.

@spec set_volume(Mob.Socket.t(), float()) :: Mob.Socket.t()

Adjust playback volume (0.0–1.0) without stopping playback.

@spec start_input_metering(Mob.Socket.t()) :: Mob.Socket.t()

Start metering the microphone input level — without recording to a file.

The agent-facing "ears" primitive: poll input_level/0 to detect whether the device is producing sound (e.g. an agent loop "keep going until you hear sound"). The mic picks up the device's own speaker, so it registers audio from any source. Shares the mic session with recording — don't run both at once.

Requires :microphone permission (same as recording).

@spec start_recording(
  Mob.Socket.t(),
  keyword()
) :: Mob.Socket.t()

Start recording audio from the microphone.

Options:

• format: :aac | :wav (default :aac)

• quality: :low | :medium | :high (default :medium)

@spec stop_input_metering(Mob.Socket.t()) :: Mob.Socket.t()

Stop microphone input metering.

@spec stop_playback(Mob.Socket.t()) :: Mob.Socket.t()

Stop the currently playing audio.

@spec stop_recording(Mob.Socket.t()) :: Mob.Socket.t()

Stop the in-progress recording and save it to a temp file. Result arrives as {:audio, :recorded, %{path: ..., duration: ...}}.