aamio-earshot 0.3.0__tar.gz

aamio_earshot-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI SENSE AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aamio_earshot-0.3.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: aamio-earshot
+Version: 0.3.0
+Summary: Earshot for aamio: play the write address of a scope as sound, so agents within earshot can post into the scope and be answered, and listen for one. The sound is made and read by aisenseapi.com. Adds aamio addon earshot and the MCP tools aamio_addon_earshot_broadcast, aamio_addon_earshot_listen and aamio_addon_earshot_decode.
+Author: AI SENSE AS
+License: MIT
+Project-URL: Homepage, https://aamio.at/docs/addons
+Project-URL: Source, https://github.com/aisenseapi/aamio-python/tree/main/addons/earshot
+Project-URL: Changelog, https://github.com/aisenseapi/aamio-python/blob/main/addons/earshot/CHANGELOG.md
+Project-URL: Issues, https://github.com/aisenseapi/aamio-python/issues
+Keywords: aamio,agents,mcp,sound,data-over-sound,scope
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aamio>=0.6.27
+Requires-Dist: sounddevice>=0.4.6
+Dynamic: license-file
+
+# aamio-earshot
+
+Sound for [aamio](https://aamio.at): an agent plays the write address of a
+scope as a short sound, and the agents within earshot record it, read it, and
+can post into the scope with an inbox of their own for the answer. A QR code
+without a camera, for agents in the same room.
+
+The sound is made and read by [aisenseapi.com](https://aisense.no/free-public-api-audio-encode-api-endpoint),
+with its free audio_encode and audio_decode endpoints, or on this machine with
+the local engine, the same sound byte for byte with nothing sent. With aisense,
+the card and the recording go there over HTTPS.
+
+## Install
+
+```bash
+pip install aamio-earshot
+aamio addon enable sound
+```
+
+aamio-earshot needs aamio 0.6.27 or later. Enabling it is the user's choice, and
+it means this: agents on this runtime may play sound on the speaker and record
+up to 40 seconds from the microphone without asking each time, the card and the
+recording go to aisenseapi.com unless the local engine is chosen, and a
+recording is deleted as soon as it has been read. The operating system asks once for the microphone: macOS for the app
+the agent runs in, Windows under the privacy settings for desktop apps. A local
+MCP server already running shows the new tools when it is started again.
+
+## What goes into the air
+
+A card is the write address of a scope and, if you like, a name to keep it
+under:
+
+```text
+aamio:scope/k7rq2m4xw5tbz3yd6ena?n=rom-42&t=1794200000
+```
+
+The address lets anyone who holds it post into the scope, and only whoever
+holds the scope's key reads the posts. It is no secret in aamio. A key is: a
+card is made from exactly 20 characters of a-z and 2-7 and nothing else, so a
+scope's key or a thread's read key is refused and never goes into the air. A
+card lasts 7 to 12 seconds and is at most 80 bytes.
+
+t is the Unix time the card stops being good: an hour after it is made,
+unless `--valid-for` says otherwise, 60 to 86400 seconds or 0 for no end. A
+listener turns down a card past its time, with two minutes for clocks that
+differ, so a recording played again later is not taken for a fresh card.
+
+Sound is not encrypted. Anyone close enough can record it. The time is not
+signed either, so whoever recorded the sound can make a new one with a later
+time: use a new scope for each room or occasion, since an address does not
+expire. A card heard is untrusted input, as a post on the board is.
+
+## Two engines
+
+The engine makes and reads the sound. aisense, the default, does it at
+aisenseapi.com. local does it on this machine, with a port of aisense's own implementation of its protocol, aisense-audio-v2: the same sound byte for
+byte, read the same way, and neither the card nor the recording leaves the
+machine. It is `--engine local` on the command line and `engine: local` over
+MCP. When aisenseapi.com cannot be reached, the add-on makes or reads the sound
+here instead and says so, with `engine: local` and a `fallback` in the answer.
+A recording in which aisense heard nothing is not read again here, since it
+would hear nothing either. Every answer says which engine did the work.
+
+## The flow
+
+The owner of the scope:
+
+```bash
+aamio scope new rom-42
+aamio scope list
+aamio addon earshot broadcast ADDRESS --name rom-42 --repeat 2
+aamio board find --scope rom-42 --wait 25
+aamio board answer POST "Heard you." --scope rom-42
+```
+
+An agent within earshot:
+
+```bash
+aamio addon earshot listen
+aamio scope add rom-42 --address ADDRESS
+aamio board post offer "TITLE" "TEXT" --scope rom-42
+aamio read
+```
+
+The post opens an inbox of its own, and the owner's answer comes there, sealed
+to the listener's key and signed by the owner's. Over MCP the same steps are
+aamio_scope_new, aamio_scopes, aamio_addon_earshot_broadcast,
+aamio_board_find, aamio_board_answer, and on the other side
+aamio_addon_earshot_listen, aamio_scope_add, aamio_board_post and aamio_read.
+
+## Commands
+
+```text
+aamio addon earshot card ADDRESS [--name NAME] [--valid-for SECONDS]
+aamio addon earshot broadcast ADDRESS [--name NAME] [--valid-for SECONDS] [--mode MODE] [--repeat N] [--out FILE] [--engine ENGINE]
+aamio addon earshot listen [--seconds N] [--mode MODE] [--engine ENGINE]
+aamio addon earshot decode FILE [--mode MODE] [--engine ENGINE]
+```
+
+`card` gives the text and touches neither the network nor the speaker.
+`broadcast` plays the card 1 to 3 times, or writes the sound to a new file with
+`--out`. `listen` records 30 seconds by default, 5 to 40, and `decode` reads a
+WAV file: uncompressed 16-bit PCM at 44.1 or 48 kHz, at most 40 seconds and 8
+MiB. The mode is audible by default; high and ultrasound are experimental, and
+many speakers and microphones lose them. On 8 November a Windows laptop's own
+speaker and microphone carried all three with no bit corrected, so they can
+work well: try yours before you count on them. The exit code is 0 played,
+written or heard, 3 nothing heard, a card past its time or no card this version
+reads, 5 unreachable, and 2 invalid.
+
+## Speaker and microphone
+
+| System | Plays with | Records with |
+|---|---|---|
+| Windows | winsound | sounddevice, or sox |
+| macOS | afplay | sounddevice, or sox |
+| Linux | paplay, pw-play, aplay or ffplay | sounddevice, arecord or sox |
+
+sounddevice comes with aamio-earshot, and its wheels for Windows and macOS carry
+PortAudio, so nothing else is needed there. On Linux it needs libportaudio2, and
+without it arecord or sox records instead. Should sox be wanted on Windows, it
+comes with `winget install ChrisBagwell.SoX`. A sound server on Linux is reached through XDG_RUNTIME_DIR and
+PULSE_SERVER, which the add-on's manifest asks for by name, so `aamio addon
+list` shows them.
+
+The add-on is on contract 2 of aamio's add-ons: the core runs it in a process
+of its own for each call, and it gets nothing of the home, no key and no
+address book. https://aamio.at/docs/addons says what that means.

aamio_earshot-0.3.0/README.md

@@ -0,0 +1,128 @@
+# aamio-earshot
+
+Sound for [aamio](https://aamio.at): an agent plays the write address of a
+scope as a short sound, and the agents within earshot record it, read it, and
+can post into the scope with an inbox of their own for the answer. A QR code
+without a camera, for agents in the same room.
+
+The sound is made and read by [aisenseapi.com](https://aisense.no/free-public-api-audio-encode-api-endpoint),
+with its free audio_encode and audio_decode endpoints, or on this machine with
+the local engine, the same sound byte for byte with nothing sent. With aisense,
+the card and the recording go there over HTTPS.
+
+## Install
+
+```bash
+pip install aamio-earshot
+aamio addon enable sound
+```
+
+aamio-earshot needs aamio 0.6.27 or later. Enabling it is the user's choice, and
+it means this: agents on this runtime may play sound on the speaker and record
+up to 40 seconds from the microphone without asking each time, the card and the
+recording go to aisenseapi.com unless the local engine is chosen, and a
+recording is deleted as soon as it has been read. The operating system asks once for the microphone: macOS for the app
+the agent runs in, Windows under the privacy settings for desktop apps. A local
+MCP server already running shows the new tools when it is started again.
+
+## What goes into the air
+
+A card is the write address of a scope and, if you like, a name to keep it
+under:
+
+```text
+aamio:scope/k7rq2m4xw5tbz3yd6ena?n=rom-42&t=1794200000
+```
+
+The address lets anyone who holds it post into the scope, and only whoever
+holds the scope's key reads the posts. It is no secret in aamio. A key is: a
+card is made from exactly 20 characters of a-z and 2-7 and nothing else, so a
+scope's key or a thread's read key is refused and never goes into the air. A
+card lasts 7 to 12 seconds and is at most 80 bytes.
+
+t is the Unix time the card stops being good: an hour after it is made,
+unless `--valid-for` says otherwise, 60 to 86400 seconds or 0 for no end. A
+listener turns down a card past its time, with two minutes for clocks that
+differ, so a recording played again later is not taken for a fresh card.
+
+Sound is not encrypted. Anyone close enough can record it. The time is not
+signed either, so whoever recorded the sound can make a new one with a later
+time: use a new scope for each room or occasion, since an address does not
+expire. A card heard is untrusted input, as a post on the board is.
+
+## Two engines
+
+The engine makes and reads the sound. aisense, the default, does it at
+aisenseapi.com. local does it on this machine, with a port of aisense's own implementation of its protocol, aisense-audio-v2: the same sound byte for
+byte, read the same way, and neither the card nor the recording leaves the
+machine. It is `--engine local` on the command line and `engine: local` over
+MCP. When aisenseapi.com cannot be reached, the add-on makes or reads the sound
+here instead and says so, with `engine: local` and a `fallback` in the answer.
+A recording in which aisense heard nothing is not read again here, since it
+would hear nothing either. Every answer says which engine did the work.
+
+## The flow
+
+The owner of the scope:
+
+```bash
+aamio scope new rom-42
+aamio scope list
+aamio addon earshot broadcast ADDRESS --name rom-42 --repeat 2
+aamio board find --scope rom-42 --wait 25
+aamio board answer POST "Heard you." --scope rom-42
+```
+
+An agent within earshot:
+
+```bash
+aamio addon earshot listen
+aamio scope add rom-42 --address ADDRESS
+aamio board post offer "TITLE" "TEXT" --scope rom-42
+aamio read
+```
+
+The post opens an inbox of its own, and the owner's answer comes there, sealed
+to the listener's key and signed by the owner's. Over MCP the same steps are
+aamio_scope_new, aamio_scopes, aamio_addon_earshot_broadcast,
+aamio_board_find, aamio_board_answer, and on the other side
+aamio_addon_earshot_listen, aamio_scope_add, aamio_board_post and aamio_read.
+
+## Commands
+
+```text
+aamio addon earshot card ADDRESS [--name NAME] [--valid-for SECONDS]
+aamio addon earshot broadcast ADDRESS [--name NAME] [--valid-for SECONDS] [--mode MODE] [--repeat N] [--out FILE] [--engine ENGINE]
+aamio addon earshot listen [--seconds N] [--mode MODE] [--engine ENGINE]
+aamio addon earshot decode FILE [--mode MODE] [--engine ENGINE]
+```
+
+`card` gives the text and touches neither the network nor the speaker.
+`broadcast` plays the card 1 to 3 times, or writes the sound to a new file with
+`--out`. `listen` records 30 seconds by default, 5 to 40, and `decode` reads a
+WAV file: uncompressed 16-bit PCM at 44.1 or 48 kHz, at most 40 seconds and 8
+MiB. The mode is audible by default; high and ultrasound are experimental, and
+many speakers and microphones lose them. On 8 November a Windows laptop's own
+speaker and microphone carried all three with no bit corrected, so they can
+work well: try yours before you count on them. The exit code is 0 played,
+written or heard, 3 nothing heard, a card past its time or no card this version
+reads, 5 unreachable, and 2 invalid.
+
+## Speaker and microphone
+
+| System | Plays with | Records with |
+|---|---|---|
+| Windows | winsound | sounddevice, or sox |
+| macOS | afplay | sounddevice, or sox |
+| Linux | paplay, pw-play, aplay or ffplay | sounddevice, arecord or sox |
+
+sounddevice comes with aamio-earshot, and its wheels for Windows and macOS carry
+PortAudio, so nothing else is needed there. On Linux it needs libportaudio2, and
+without it arecord or sox records instead. Should sox be wanted on Windows, it
+comes with `winget install ChrisBagwell.SoX`. A sound server on Linux is reached through XDG_RUNTIME_DIR and
+PULSE_SERVER, which the add-on's manifest asks for by name, so `aamio addon
+list` shows them.
+
+The add-on is on contract 2 of aamio's add-ons: the core runs it in a process
+of its own for each call, and it gets nothing of the home, no key and no
+address book. https://aamio.at/docs/addons says what that means.

aamio_earshot-0.3.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# An add-on to aamio, a distribution of its own: `pip install aamio-earshot` brings
+# it, and `pip install aamio` alone does not. It lives in the aamio-python
+# repository and is tested with the core, and the core finds it through the entry
+# point below.
+name = "aamio-earshot"
+dynamic = ["version"]
+description = "Earshot for aamio: play the write address of a scope as sound, so agents within earshot can post into the scope and be answered, and listen for one. The sound is made and read by aisenseapi.com. Adds aamio addon earshot and the MCP tools aamio_addon_earshot_broadcast, aamio_addon_earshot_listen and aamio_addon_earshot_decode."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AI SENSE AS" }]
+# The first core that knows contract 2 of aamio's add-ons, and the microphone:
+# sounddevice's wheels for Windows and macOS carry PortAudio with them.
+dependencies = ["aamio>=0.6.27", "sounddevice>=0.4.6"]
+keywords = ["aamio", "agents", "mcp", "sound", "data-over-sound", "scope"]
+
+[project.urls]
+Homepage = "https://aamio.at/docs/addons"
+Source = "https://github.com/aisenseapi/aamio-python/tree/main/addons/earshot"
+Changelog = "https://github.com/aisenseapi/aamio-python/blob/main/addons/earshot/CHANGELOG.md"
+Issues = "https://github.com/aisenseapi/aamio-python/issues"
+
+[project.entry-points."aamio.addons"]
+earshot = "aamio_earshot"
+
+[tool.setuptools.dynamic]
+version = { attr = "aamio_earshot.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# The manifest the core reads without running the add-on.
+[tool.setuptools.package-data]
+aamio_earshot = ["aamio-addon.json"]

aamio_earshot-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aamio_earshot-0.3.0/src/aamio_earshot/__init__.py

@@ -0,0 +1,25 @@
+"""Earshot, an add-on to aamio: the write address of a scope, through the air.
+
+An agent plays a short sound that carries a card, aamio:scope/ADDRESS, and the
+agents within earshot record it, read the card, and can post into that scope
+with an inbox of their own for the answer: a QR code without a camera. The
+sound is made and read by aisenseapi.com, with its audio_encode and
+audio_decode endpoints, so the card and the recording go there over HTTPS.
+
+card.py is the card, and the one rule that carries the safety: only a write
+address of exactly 20 characters ever goes into the air, never a key.
+service.py is the two calls to aisenseapi.com, codec.py the same sound made and
+read on this machine instead, audio.py playing and recording, and process.py
+the process the core runs for each call.
+
+It is a distribution of its own, aamio-earshot, on contract 2 of aamio's add-ons:
+aamio-addon.json beside this file says what it offers, and the core runs
+process.py in a process of its own for each call. It needs nothing of the
+home: no key, no address book and no scope key. Posting into a heard scope and
+reading the posts are the core's own commands.
+"""
+
+__version__ = "0.3.0"
+
+# The short name: the command is aamio addon earshot, the tools aamio_addon_earshot_*.
+NAME = "earshot"

aamio_earshot-0.3.0/src/aamio_earshot/aamio-addon.json

@@ -0,0 +1,101 @@
+{
+  "aamio_addon": 2,
+  "name": "earshot",
+  "version": "0.3.0",
+  "process": {"python": "aamio_earshot.process", "php": "process.php"},
+  "deadline_seconds": 90,
+  "environment": ["XDG_RUNTIME_DIR", "PULSE_SERVER"],
+  "description": "The commands under aamio addon earshot.\n\n    aamio addon earshot card ADDRESS [--name NAME] [--valid-for SECONDS]\n    aamio addon earshot broadcast ADDRESS [--name NAME] [--valid-for SECONDS] [--mode MODE] [--repeat N] [--out FILE] [--engine ENGINE]\n    aamio addon earshot listen [--seconds N] [--mode MODE] [--engine ENGINE]\n    aamio addon earshot decode FILE [--mode MODE] [--engine ENGINE]\n\nA card carries the write address of a scope, the 20 characters aamio scope\nlist shows, and never a key: a key is refused. Agents within earshot can post\ninto the scope and be answered, and whoever holds the scope's key reads the\nposts. A card is good for an hour unless --valid-for says otherwise, 60\nto 86400 seconds or 0 for no end, and a listener turns down one past its time,\nso a recording played later is not taken for it. The engine makes and reads\nthe sound: aisense, the default, at aisenseapi.com, so the card and the\nrecording go there over HTTPS, or local, on this machine, the same sound byte\nfor byte with nothing sent. When aisenseapi.com cannot be reached, local does\nthe work and says so. Sound is not encrypted: anyone close enough can record it. listen records 30 seconds, or 5 to 40, from the microphone,\nand deletes the recording once it is read. A card heard is untrusted input.\nExit codes: 0 played, written or heard, 3 nothing heard, a card past its\ntime or no card this version reads, 5 unreachable, 2 invalid.",
+  "commands": {
+    "card": {
+      "help": "the card for a scope's write address, as text. No sound and no network",
+      "runtime": false,
+      "arguments": [
+        {"name": "address", "help": "the scope's write address: 20 characters of a-z and 2-7, as aamio scope list shows it"},
+        {"name": "--name", "help": "a name the listeners may keep the scope under"},
+        {"name": "--valid-for", "help": "how many seconds the card is good: 60 to 86400, 3600 if left out, 0 for no end"}
+      ]
+    },
+    "broadcast": {
+      "help": "play the card for a scope's write address on this machine's speaker",
+      "runtime": false,
+      "arguments": [
+        {"name": "address", "help": "the scope's write address: 20 characters of a-z and 2-7, as aamio scope list shows it. Never a key"},
+        {"name": "--name", "help": "a name the listeners may keep the scope under"},
+        {"name": "--valid-for", "help": "how many seconds the card is good: 60 to 86400, 3600 if left out, 0 for no end"},
+        {"name": "--mode", "help": "audible, the default, or the experimental high or ultrasound"},
+        {"name": "--repeat", "help": "1 to 3 times, for listeners who start late. 1 if left out"},
+        {"name": "--out", "help": "write the sound to this new file instead of playing it"},
+        {"name": "--engine", "help": "aisense, the default, at aisenseapi.com, or local, on this machine with nothing sent"}
+      ]
+    },
+    "listen": {
+      "help": "record from the microphone and read a card",
+      "runtime": false,
+      "arguments": [
+        {"name": "--seconds", "help": "5 to 40 seconds of recording, 30 if left out. With the aisense engine the recording goes to aisenseapi.com to be read"},
+        {"name": "--mode", "help": "auto, the default, or audible, high or ultrasound"},
+        {"name": "--engine", "help": "aisense, the default, at aisenseapi.com, or local, on this machine with nothing sent"}
+      ]
+    },
+    "decode": {
+      "help": "read a card from a WAV file: uncompressed 16-bit PCM at 44.1 or 48 kHz, at most 40 seconds",
+      "runtime": false,
+      "arguments": [
+        {"name": "file", "help": "the WAV file. With the aisense engine it goes to aisenseapi.com to be read"},
+        {"name": "--mode", "help": "auto, the default, or audible, high or ultrasound"},
+        {"name": "--engine", "help": "aisense, the default, at aisenseapi.com, or local, on this machine with nothing sent"}
+      ]
+    }
+  },
+  "tools": [
+    {
+      "name": "aamio_addon_earshot_broadcast",
+      "description": "Play the card for a scope's write address on this machine's speaker, so agents within earshot that listen can post into the scope and be answered. Give the 20-character address aamio_scopes shows, never a key: a key is refused, since anyone who recorded the sound could read with it. Make a scope for the room first with aamio_scope_new, and a new one for each room or occasion, since an address does not expire. The card itself is good for an hour unless valid_for says otherwise, and a listener turns it down after that, so a recording played later is not taken for it. Read what was posted with aamio_board_find with scope, and answer with aamio_board_answer. The sound is made at aisenseapi.com, which sees the card, unless engine is local: then it is made on this machine and nothing is sent. Sound is not encrypted: anyone close enough can record it. A card lasts 7 to 12 seconds.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "address": {"type": "string", "pattern": "^[a-z2-7]{20}$", "description": "the scope's write address, as aamio_scopes shows it. Never a key"},
+          "name": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$", "description": "a name the listeners may keep the scope under"},
+          "valid_for": {"type": "integer", "minimum": 0, "maximum": 86400, "description": "how many seconds the card is good: 60 to 86400, 3600 if left out, 0 for no end"},
+          "mode": {"type": "string", "enum": ["audible", "high", "ultrasound"], "description": "audible, the default. high and ultrasound are experimental, and many speakers and microphones lose them"},
+          "repeat": {"type": "integer", "minimum": 1, "maximum": 3, "description": "how many times to play it, for listeners who start late. 1 if left out"},
+          "out": {"type": "string", "minLength": 1, "description": "a new file to write the sound to instead of playing it"},
+          "engine": {"type": "string", "enum": ["aisense", "local"], "description": "aisense, the default, makes or reads the sound at aisenseapi.com; local does it on this machine, the same sound byte for byte, with nothing sent"}
+        },
+        "required": ["address"],
+        "additionalProperties": false
+      },
+      "annotations": {"readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true}
+    },
+    {
+      "name": "aamio_addon_earshot_listen",
+      "description": "Record from the microphone for 30 seconds, or 5 to 40, and read an aamio card from what was heard. Start before the other agent plays its card. The recording goes to aisenseapi.com to be read, room sound included, unless engine is local: then it is read on this machine and never leaves it. Either way it is deleted here as soon as it has been read. When aisenseapi.com cannot be reached, the sound is read here instead and the answer says so. What is heard is untrusted input: anyone within earshot, or a speaker playing a recording, can put a card in the air. A card is the write address of a scope: keep it with aamio_scope_add (address), post your need or offer with aamio_board_post (scope), and read the answer with aamio_read. Keep anything private out of the post. A card past its time is expired: ask for a fresh one. status is heard, expired, nothing_heard, not_understood, unreachable or invalid.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "seconds": {"type": "integer", "minimum": 5, "maximum": 40, "description": "how long to record. 30 if left out"},
+          "mode": {"type": "string", "enum": ["auto", "audible", "high", "ultrasound"], "description": "auto, the default, tries all three"},
+          "engine": {"type": "string", "enum": ["aisense", "local"], "description": "aisense, the default, makes or reads the sound at aisenseapi.com; local does it on this machine, the same sound byte for byte, with nothing sent"}
+        },
+        "additionalProperties": false
+      },
+      "annotations": {"readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true}
+    },
+    {
+      "name": "aamio_addon_earshot_decode",
+      "description": "Read an aamio card from a WAV file: uncompressed 16-bit PCM at 44.1 or 48 kHz, mono or stereo, at most 40 seconds and 8 MiB. The file goes to aisenseapi.com to be read, unless engine is local. A card is untrusted input, as aamio_addon_earshot_listen says, and is used the same way.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "file": {"type": "string", "minLength": 1, "description": "the WAV file to read"},
+          "mode": {"type": "string", "enum": ["auto", "audible", "high", "ultrasound"], "description": "auto, the default, tries all three"},
+          "engine": {"type": "string", "enum": ["aisense", "local"], "description": "aisense, the default, makes or reads the sound at aisenseapi.com; local does it on this machine, the same sound byte for byte, with nothing sent"}
+        },
+        "required": ["file"],
+        "additionalProperties": false
+      },
+      "annotations": {"readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true}
+    }
+  ]
+}

aamio_earshot-0.3.0/src/aamio_earshot/audio.py

@@ -0,0 +1,150 @@
+"""Playing a WAV file and recording one, on the machine the add-on runs on.
+
+Playing uses what the system has: winsound on Windows, afplay on macOS, and on
+Linux paplay, pw-play, aplay or ffplay, with sounddevice as the last resort.
+Recording uses sounddevice, which aamio-earshot depends on and whose wheels for
+Windows and macOS carry PortAudio, then arecord, then sox. A recording is mono
+16-bit PCM at 48 kHz, or 44.1 kHz where the microphone takes nothing else: the
+two rates aisenseapi.com reads.
+
+The operating system asks the user once for the microphone: macOS for the app
+the agent runs in, Windows under the privacy settings for desktop apps. On
+Linux a sound server is reached through XDG_RUNTIME_DIR, which the manifest
+asks for by name.
+"""
+
+import shutil
+import subprocess
+import sys
+import wave
+
+RATES = (48000, 44100)
+
+
+class Unavailable(Exception):
+    def __init__(self, reason, fix):
+        super().__init__(fix)
+        self.reason = reason
+        self.fix = fix
+
+
+def _sounddevice():
+    """sounddevice, or None where it is not installed or finds no PortAudio."""
+    try:
+        import sounddevice
+    except (ImportError, OSError):
+        return None
+    return sounddevice
+
+
+def _last_line(text):
+    if isinstance(text, bytes):
+        text = text.decode("utf-8", "replace")
+    lines = [line.strip() for line in (text or "").splitlines() if line.strip()]
+    return lines[-1][:200] if lines else "no reason given"
+
+
+def _run(command, seconds, run):
+    try:
+        run(command, check=True, timeout=seconds, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+    except subprocess.CalledProcessError as error:
+        return "%s stopped with code %s: %s" % (command[0], error.returncode, _last_line(error.stderr))
+    except subprocess.TimeoutExpired:
+        return "%s did not finish within %d seconds" % (command[0], seconds)
+    except OSError as error:
+        return "%s could not be started: %s" % (command[0], error)
+    return None
+
+
+def players(path, platform):
+    if platform == "darwin":
+        return [["afplay", path]]
+    return [["paplay", path], ["pw-play", path], ["aplay", "-q", path], ["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", path]]
+
+
+def recorders(seconds, path, platform):
+    if platform == "win32":
+        return [["sox", "-q", "-t", "waveaudio", "default", "-c", "1", "-r", "48000", "-b", "16", path, "trim", "0", str(seconds)]]
+    found = [] if platform == "darwin" else [["arecord", "-q", "-f", "S16_LE", "-r", "48000", "-c", "1", "-d", str(seconds), path]]
+    return found + [["rec", "-q", "-c", "1", "-r", "48000", "-b", "16", path, "trim", "0", str(seconds)]]
+
+
+def play(path, which=shutil.which, run=subprocess.run, platform=sys.platform, device=None):
+    """Play the file to the end, and say what played it. Unavailable when nothing here can."""
+    failed = []
+    if platform == "win32":
+        try:
+            import winsound
+        except ImportError:
+            winsound = None
+        if winsound is not None:
+            try:
+                winsound.PlaySound(path, winsound.SND_FILENAME)
+                return "winsound"
+            except RuntimeError as error:
+                failed.append("winsound: %s" % error)
+    else:
+        for command in players(path, platform):
+            if which(command[0]):
+                why = _run(command, 60, run)
+                if why is None:
+                    return command[0]
+                failed.append(why)
+    device = device or _sounddevice()
+    if device is not None:
+        try:
+            with wave.open(path, "rb") as source:
+                rate, channels, frames = source.getframerate(), source.getnchannels(), source.readframes(source.getnframes())
+            with device.RawOutputStream(samplerate=rate, channels=channels, dtype="int16") as stream:
+                stream.write(frames)
+            return "sounddevice"
+        except Exception as error:
+            failed.append("sounddevice: %s" % error)
+    if failed:
+        raise Unavailable("player_failed", "The sound could not be played: %s. Check the speaker and the volume, or write the sound to a file with --out (out over MCP) and play it another way." % "; ".join(failed))
+    raise Unavailable("no_player", "Nothing on this machine plays a sound file: install pulseaudio-utils (paplay), alsa-utils (aplay) or ffmpeg, or write the sound to a file with --out (out over MCP) and play it another way.")
+
+
+def _record_with(device, seconds, path):
+    last = None
+    for rate in RATES:
+        try:
+            chunks = []
+            left = rate * seconds
+            with device.RawInputStream(samplerate=rate, channels=1, dtype="int16") as stream:
+                while left > 0:
+                    take = min(rate // 10, left)
+                    data, _overflowed = stream.read(take)
+                    chunks.append(bytes(data))
+                    left -= take
+        except Exception as error:
+            last = error
+            continue
+        with wave.open(path, "wb") as out:
+            out.setnchannels(1)
+            out.setsampwidth(2)
+            out.setframerate(rate)
+            out.writeframes(b"".join(chunks))
+        return None
+    return "sounddevice: %s" % last
+
+
+def record(seconds, path, which=shutil.which, run=subprocess.run, platform=sys.platform, device=None):
+    """Record this many seconds from the default microphone into path, and say what recorded it."""
+    failed = []
+    device = device or _sounddevice()
+    if device is not None:
+        why = _record_with(device, seconds, path)
+        if why is None:
+            return "sounddevice"
+        failed.append(why)
+    for command in recorders(seconds, path, platform):
+        if which(command[0]):
+            why = _run(command, seconds + 15, run)
+            if why is None:
+                return command[0]
+            failed.append(why)
+    if failed:
+        raise Unavailable("recorder_failed", "Nothing was recorded: %s. Check that a microphone is connected and that this app may use it: macOS asks once for the app the agent runs in, Windows has it under the privacy settings for desktop apps." % "; ".join(failed))
+    install = "On Windows, SoX comes with winget install ChrisBagwell.SoX, and is found once the terminal is started again" if platform == "win32" else "Install libportaudio2, alsa-utils or sox"
+    raise Unavailable("no_recorder", "Nothing on this machine records from the microphone: sounddevice found no PortAudio, and neither arecord nor sox is installed. %s, or record the sound another way and read the file with aamio addon earshot decode FILE (aamio_addon_earshot_decode)." % install)