# Voice Tools in God's Eye View: A Complete Technical Guide to Hands-Free Geo-Spatial Control

> Explore hands-free geo-spatial control with God's Eye View voice tools. Discover features like layer management, navigation, and data analysis for seamless geo-spatial operations.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-09-09

---

**God's Eye View (GEV) implements over 15 voice-controlled tools—including layer management, navigation, camera control, and data analysis—through a centralized tool-router in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) that maps natural language commands to concrete JavaScript handlers.**

God's Eye View is an open-source geospatial visualization platform that enables hands-free operation through a sophisticated voice command architecture. According to the **bilawalsidhu/gods-eye-view** repository, the system utilizes OpenAI's Realtime API to capture speech, then dispatches parsed intents to specialized handlers defined across three core files: [`gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevRealtime.js), [`gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevActions.js), and [`voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/voiceCost.js).

## How Voice Command Routing Works

The voice system follows a pipeline architecture that bridges speech recognition and viewport manipulation. The **browser UI** in [`src/voice/gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevRealtime.js) captures microphone input and negotiates the OpenAI Realtime session, exposing the supported tool schema to the language model. When the model generates a tool call, the client forwards the request to the **tool runner**.

The tool runner, exported as `createGevActionRunner` from [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js), contains the central `runGevAction(name, args)` dispatcher. This function executes a large conditional cascade that matches the tool `name` to specific implementation logic, such as adjusting camera positions or toggling data layers. Finally, [`src/voice/voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/voiceCost.js) defines the **tool schema**—including argument specifications and capability caps—that constrains which voice tools the language model can invoke.

## Complete Catalog of Voice Tools

The following voice tools are categorized by function and implemented within [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js). Each tool corresponds to a specific branch in the dispatcher's conditional logic.

### Layer Management

* **`set_layer_visibility`** – Toggles data layers on or off using the `layerId` and `enabled` parameters. For example, commanding "show traffic" activates the traffic overlay. Implemented at **lines 21–45** of [`gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevActions.js).

### Navigation and Camera Control

* **`fly_to_location`** – Animates the camera to a named place, address, or latitude/longitude coordinates. Located at **lines 70–85**.
* **`zoom_to_globe`** – Resets the viewport to a global overview. Found at **lines 96–104**.
* **`adjust_camera_zoom`** – Performs incremental zoom operations while maintaining orbit. Defined at **lines 12–18**.

### UI and Context Management

* **`set_panel_open`** – Opens or closes specific UI panels (data, location, or control panels) via the `panelId` and `open` arguments. See **lines 82–88**.
* **`set_context_mode`** – Switches the application context mode between states like contacts, flights, or default views. Located at **lines 90–106**.
* **`set_hud`** – Modifies the Heads-Up Display layout or visibility. Implemented at **lines 44–57**.

### Visual Styling and Basemaps

* **`set_visual_style`** – Applies aesthetic filters such as retro, noir, or thermal imaging to the viewport. Found at **lines 75–80**.
* **`set_map_stack`** – Switches the underlying basemap between providers like OpenStreetMap, Bing aerial, or Google 3-D. Located at **lines 69–73**.

### Aircraft and Cockpit Integration

* **`control_cockpit`** – Toggles cockpit view mode or navigates between tracked aircraft. Defined at **lines 42–46**.
* **`select_nearest_aircraft`** – Identifies and selects the closest airborne aircraft to a specified location. Implemented at **lines 20–27**.

### CCTV, Radio, and Media Controls

* **`control_cctv`** – Manages CCTV layer visibility, camera selection, rotation, and coverage toggling. See **lines 91–101**.
* **`control_radio`** – Controls internet radio playback, including play, pause, volume adjustment, and station changes. Found at **lines 101–103**.

### Annotation and Scene Tools

* **`annotate_map`** – Places whiteboard-style annotations (points, routes, labels) directly onto the 3-D globe. Located at **lines 71–76**.
* **`clear_annotations`** – Removes all previously placed map annotations. Implemented at **lines 37–42**.
* **`control_scene`** – Manages scripted scene playback, including listing, starting, stopping, and stepping through sequences. See **lines 55–70**.

### Analytics and Query

* **`analyst_query`** – Executes custom analytical queries against currently loaded data layers. Defined at **lines 16–20**.

## Implementing Voice Tools in the Source Code

Voice tool invocations follow a structured JSON schema defined in [`src/voice/voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/voiceCost.js). When the language model decides to activate a tool, it generates a request object such as:

```json
{
  "name": "set_layer_visibility",
  "arguments": { "layerId": "traffic", "enabled": true }
}

```

The realtime client receives this payload and forwards it to the action runner. The following example demonstrates internal invocation from [`gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevRealtime.js):

```javascript
// Inside gevRealtime.js – after the model decides on a tool call
const runAction = createGevActionRunner({ viewer, styleManager, dataManager });
const result = await runAction('set_layer_visibility', {
  layerId: 'traffic',
  enabled: true,
});
console.log(result);
// → { ok: true, action: 'set_layer_visibility', layerId: 'traffic', … }

```

The dispatcher returns a structured result object containing the action name, execution status, and affected parameters, which the realtime client feeds back to the language model to maintain conversational context.

## Adding Custom Voice Tools

Extending the voice system requires modifying two files. First, add the implementation logic to [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) by inserting a new conditional branch in the dispatcher:

```javascript
// In src/voice/gevActions.js – add a new branch
if (name === 'toggle_satellite_view') {
  const layerId = 'satellites';
  const current = await dataManager.isEnabled(layerId);
  await dataManager.setEnabled(layerId, !current, { origin: 'voice' });
  return { ok: true, action: 'toggle_satellite_view', enabled: !current };
}

```

Second, update the tool schema in [`src/voice/voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/voiceCost.js) to register the new tool name and its argument structure. Without this schema update, the language model cannot generate requests for the new capability, even if the handler code exists.

## Summary

- **God's Eye View voice tools** are centralized in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js), where the `createGevActionRunner` factory dispatches spoken commands to specific viewport and data manipulations.
- The system supports **17 distinct voice operations** across layer management, navigation, styling, aircraft tracking, CCTV control, and scene playback, with line-level implementations traceable in the source.
- **Schema definition** in [`voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/voiceCost.js) and **session management** in [`gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevRealtime.js) create a complete pipeline from speech recognition to geo-spatial action, enabling rapid extension of voice-controlled features.

## Frequently Asked Questions

### How do I enable voice commands in God's Eye View?

Voice interaction requires a browser environment with microphone access. The system initializes automatically upon loading the GEV interface, establishing an OpenAI Realtime session via [`src/voice/gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevRealtime.js). Ensure your browser permissions allow audio input, then speak naturally to invoke any registered tool.

### What speech recognition engine does God's Eye View use?

The platform utilizes the **OpenAI Realtime API** for speech-to-text processing and intent recognition. This engine processes audio locally in the browser before streaming to OpenAI's servers, which return structured tool calls rather than raw text, enabling precise command mapping to the handlers in [`gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevActions.js).

### Can I add custom voice commands to God's Eye View?

Yes. Create a new handler in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) following the existing conditional pattern (e.g., `if (name === 'your_command')`), then register the tool name and arguments in [`src/voice/voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/voiceCost.js). The language model will detect the new capability in subsequent sessions without requiring changes to the realtime client code.

### How does the system handle ambiguous voice commands?

Ambiguity is resolved at the language model level using the tool schema constraints defined in [`voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/voiceCost.js). The model selects the most appropriate tool based on the available names and required arguments. If multiple interpretations remain possible, the system typically defaults to the first matching handler in the [`gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevActions.js) cascade or requests clarification through the conversational interface.