Base Soundscape App Function Service
Exposes Soundscape's actions to Gemini and other agents.
Every function is a thin wrapper over SoundscapeActionExecutor, the same shared vocabulary the iOS App Intents run on, so the two platforms cannot drift into describing different capabilities.
The KDoc on each function below is not decoration: with isDescribedByKDoc = true it becomes the natural-language description the agent reads to decide when to call it, and the agent sees each one on its own. So each says for itself whether Soundscape must be open and whether the answer is spoken by the app, even where that repeats. The app-wide context (who the app is for, how it answers) is in res/xml/app_functions_app_metadata.xml.
Requires API 36, well above the app's minSdk of 30. Nothing else references this class, so on older devices the service simply never starts.
Properties
Functions
Answers "what's ahead of me?": Soundscape calls out the roads, junctions and places lying ahead in the direction the user is facing or walking.
Answers "what's around me?": Soundscape calls out points of interest on every side of the user, each positioned in spatial audio so it sounds from its real direction. For the street the user is on, use myLocation; for only what is in front, aheadOfMe.
Answers "what is the beacon on?" or "where is my beacon?": Soundscape says the beacon's name, distance, direction and street address. For just the distance, use calloutBeacon.
A quick "how far is it?" for the audio beacon: Soundscape says the distance, heard from the beacon's direction. For the beacon's name and address as well, use beaconInfo.
Lists the names of the places the user has saved as markers in Soundscape, for choosing one to pass to startBeacon. Works whether or not Soundscape is open, because it only reads saved data. Read the message to the user, or use it to pick the marker they meant.
Lists the names of the routes the user has saved in Soundscape, for choosing one to pass to startRoute. Works whether or not Soundscape is open, because it only reads saved data. Read the message to the user, or use it to pick the route they meant.
Answers "where am I?": Soundscape says the street the user is on or the junction they are at, and the nearest landmarks. For points of interest all around, use aroundMe; for what is in front, aheadOfMe.
Calls out the user's own saved markers (places they saved in Soundscape) that are close by, each from its direction. To hear all saved markers by name wherever they are, use listMarkers.
Skips forward to the next waypoint on the route that is playing, moving the beacon there.
Goes back to the previous waypoint on the route that is playing, moving the beacon there.
Silences or restores the audio beacon's repeating tone, without stopping the beacon or route: it keeps its place and can be unmuted later. Asking for the state it is already in changes nothing. To remove the beacon altogether, use stopBeacon or stopRoute.
Sets how much Soundscape says automatically as the user walks: Silent turns automatic callouts off altogether, leaving beacons, routes and on-demand callouts; Essential calls out only streets, junctions and landmarks; Simplified skips minor paths and repeats itself less; Detailed calls out everything nearby. Useful when a busy street is too noisy, or a quiet one too sparse. The change is saved, the same as choosing it in Settings.
Sets an audio beacon on one of the user's saved markers: a repeating tone that sounds from the marker's direction, so the user can walk towards it, until it is stopped. Only places the user has already saved as markers in Soundscape can be used; it cannot search for a shop, address or other new place. If unsure of the name, call listMarkers first.
Starts playing one of the user's saved routes: an audio beacon guides them to each waypoint in turn. Only routes the user has already saved in Soundscape can be started; it cannot plan a route to a new place. If unsure of the name, call listRoutes first.
Switches the audio beacon off. To only silence it for a while, use setBeaconMuted. Read the message to the user: it confirms the beacon stopped. Soundscape must be open.
Stops the route that is playing, and its beacon. Read the message to the user: it confirms the route stopped. Soundscape must be open.