Skip to content
Log inGet an API key
Documentation menu
docs / voice-copilot · raw .md

Voice copilot

The voice copilot is a browser demo you talk to. A voice model on OpenAI Realtime listens and answers, and every route, place, restriction and detour it states comes from a call to MapMap's hosted MCP server, shown on screen as it happens. Ask it to drive and MapMap's guidance engine, compiled to WebAssembly, runs the route in the page with a banner, an ETA and spoken turn instructions. It is for anyone who wants to hear what a voice interface on MapMap's tools sounds like, and for teams building one of their own.

Availability: a live demo at mapmap.ai/copilot, free to try with no signup, in sessions of up to five minutes. It is not a product or an API: there is no hosted voice API for customers. What you can build on is the hosted MCP server, which is live, and the guidance and voice packages below.

Using it

  1. Press Start talking and allow the microphone. The page asks its own server for a short-lived session key (it expires in about a minute and is only used to open the session), then connects to OpenAI Realtime over WebRTC.
  2. Speak. Interrupt it mid-sentence and it stops. The Try saying chips send a prompt as text once the MCP tool list has loaded.
  3. Routes and places are drawn on the map. The Tool calls list shows every tool the model calls, with its arguments and its result: nothing is mocked.
  4. Once there is a route, Drive the route plays a simulated drive along it: the guidance engine is fed position fixes synthesised along the route, and turns them into the banner, the ETA, the speed limit and the spoken prompts.

A route change goes through two steps: the page computes the new route and the time difference, the copilot reads the difference back, and only a clear yes confirms it. A proposal not confirmed within about 25 seconds expires.

Two voices. The turn instructions are spoken in a different voice from the copilot's, so the engine and the assistant never sound alike. The engine's words are spoken verbatim, never reworded by a model. Guidance always wins: critical guidance, then an imminent manoeuvre or warning, then you, then the copilot, which is turned down while guidance speaks and holds non-urgent speech within 150 metres or 12 seconds of a manoeuvre, whichever is further.

Modes

?mode= picks the persona; the control at the top of the page switches it while no session is running. Anything else opens in fleet mode.

modePersonaTry saying
fleet (default)A businesslike copilot for commercial drivers, with a vehicle chip for the declared truck and load"Take my tanker from Dover to Birmingham, tunnel code C"; "Can I take this load through a category D tunnel?"; "Why are we going this way?"
consumerPlain English for someone walking, cycling or driving a car; prefers walking or cycling routes when they fit"Walk me home on lit streets"; "Where's the nearest EV charger?"; "Where's the nearest late-night pharmacy?"
codriverMapMap Co-driver: short, characterful lines and a full-width map; volunteers at most one remark, and only at session start, drive start or arrival"Take me to Birmingham"; "Why this way?"; "What's near me?"

?fixture=1 is a test affordance: it loads a recorded 1.2 km route in Cambridge so Drive the route works with no voice session at all.

What it calls

PartWhat it is
VoiceOpenAI Realtime over WebRTC (model gpt-realtime by default). Speech is transcribed in English, and turn-taking uses semantic voice activity detection, so a cough is less likely to count as a turn.
ToolsMapMap's hosted MCP server, https://mcp.mapmap.ai/mcp, attached to the session by the page's server so the browser cannot change it
Page toolsTen tools the model calls in the browser, because they need the page's own state: get_navigation_context, set_vehicle_profile, preview_route_change, confirm_route_change, cancel_route_change, start_drive, stop_drive, repeat_last_instruction, set_guidance_muted and clear_map
Route previewsThe hosted MapMap routing API through this site's demo key, car or truck, 2 to 4 locations
GuidanceMapMap's guidance engine (GuidanceSession, the engine in @mapmap/core), compiled to WebAssembly and run in the page
Guidance speechOpenAI text-to-speech for each engine phrase, cached; the browser's own speech when that is not available

The MCP tools a session may call are read-only: route, geocode, plan_day, reachable_area, matrix, check_adr_tunnel, search_along_route, verify_places, elevation, reverse_geocode, nearby_places and cheapest_fuel_along_route. The style-publishing and feedback tools on the same server are never attached to a voice session. What each tool does is in MCP server.

What it will not say

The copilot's instructions put one set of rules first in every mode, and no persona can override them:

  • Every route, ETA, restriction, place, price or detour figure must come from a tool result or the drive's own state. If it has not looked something up, it does not know it. It reads place names, never coordinates.
  • It speaks British English, and treats a transcript in another language as a mis-hearing. Places are assumed to be in the UK unless you say otherwise.
  • A tunnel code means a dangerous-goods load. It never tells a driver a route is clear of tunnels or that a load is cleared to run; for a dangerous-goods route it says tunnels must be verified independently before dispatch.
  • It never claims a traffic-aware ETA or that a route avoids incidents, and it has no camera and no view of the road.
  • It changes the route only through a preview you agree to.

Build your own

The copilot is a thin layer: a voice model, MapMap's MCP server as its tools, and a few page tools for the state only your app holds. To build the same thing:

1. Give your voice model the MCP server. Any model or agent framework that takes a remote MCP server can call MapMap's tools: point it at https://mcp.mapmap.ai/mcp (recipes). This is the tool entry the demo's server attaches to each Realtime session, with an API key in place of the demo's own credential:

json
{
  "type": "mcp",
  "server_label": "mapmap",
  "server_url": "https://mcp.mapmap.ai/mcp",
  "require_approval": "never",
  "authorization": "snk_…",
  "allowed_tools": [
    "route", "geocode", "plan_day", "reachable_area", "matrix",
    "check_adr_tunnel", "search_along_route", "verify_places", "elevation",
    "reverse_geocode", "nearby_places", "cheapest_fuel_along_route"
  ]
}

With your snk_ key on the MCP connection, every metered call bills to your account (how); without one, the hosted server answers for evaluation under fair use. Mint the model's session on your server, as the demo does, so your OpenAI key never reaches the browser.

2. Keep state-changing actions in your app. The demo's route changes are page tools that return a proposal with the real time difference, and only a separate confirm call commits one. The model never edits the route itself.

3. Guide the drive on the device. The guidance engine is published:

  • @mapmap/core has GuidanceSession: build it from a route response and feed it location fixes. Version 0.4.0 on npm ships a browser build as well as the Node one.
  • @mapmap/maps turns a route's voice and banner instructions into steps, a banner and spoken prompts.
  • @mapmap/voice (beta) is a fixed, multilingual phrasebook for turn-by-turn prompts, played from recorded clips. The copilot demo does not use it; it speaks the engine's own phrases.

Run the demo itself. The demo's source is available by email (hello@mapmap.ai); it is not on npm. It needs OPENAI_API_KEY (server-side only), and optionally OPENAI_REALTIME_MODEL and MAPMAP_MCP_URL to point it at your own self-hosted MCP server.

When it is not configured

A deployment without OPENAI_API_KEY shows "Demo not configured", the prompts you would be able to say, and the self-hosting recipe, and its session endpoint answers 503 with not_configured. The guidance voice falls back to the browser's speech. Without the demo routing key, Drive the route says driving is not available on that deployment rather than drawing anything.

Limits

  • A demo, not an API. There is no hosted voice API, voice SDK or copilot package for customers. The page's own session endpoint serves this page; it is not a published API.
  • Your speech goes to OpenAI. Voice runs on OpenAI Realtime, and the page says so under the controls. Routing, geocoding and ADR answers come from MapMap's MCP server.
  • English, in the UK. Transcription is pinned to English, and places are assumed to be in the UK.
  • The drive is simulated. Positions are synthesised along the route in the browser; the page does not read your device's location.
  • No live traffic. ETAs and route times are not traffic-aware.
  • Short sessions. A session ends after five minutes; start another to carry on. How many sessions can start from one address in an hour is limited.
  • Along-route searches are not among the suggested prompts. You can still ask; the chips leave them out for now.