@mapmap/voice reference (beta)

Generated from the published @mapmap/voice 0.1.0-beta.1 (beta) type declarations by website/scripts/sdk-reference.mjs. Do not edit by hand: change the JSDoc in the package, or the examples in website/content/sdk-reference/voice.examples.md, and regenerate.

Beta. Every public export of the voice guidance phrasebook and registry, at the published beta. The API may change before 0.1.0; the repository is already ahead of this release, and this page describes what npm serves. The guide is in SDKs & installation.

npm install @mapmap/voice@0.1.0-beta.1

Other SDK references: @mapmap/maps, @mapmap/points, @mapmap/core, @mapmap/tile, @mapmap/react-native, MapMapKit, ai.mapmap:core.

67 exports across 1 entry point: 24 functions, 15 interfaces, 18 types, 10 constants.

How to read this page

Each entry gives the declaration as published, the JSDoc description, and a table of parameters or properties with their types. The Default column quotes the default the source states (an @default tag or a "Default ..." sentence in the JSDoc). "required" means the property must be given; "not stated" means the source gives no default, so none is claimed here. Classes, factories and the main entry functions each carry a minimal example; examples marked from the source are the package's own @example.

Contents

• @mapmap/voice: 67 exports

@mapmap/voice

import { /* … */ } from "@mapmap/voice";

Functions (@mapmap/voice)

allowedVoice, bucket, clipKey, defaultGenderFor, definePhrases, enumerateFixed, formatDistance, formatRate, fromValhalla, fromValhallaRoute, gendersFor, headingFromBearing, isRef, ladder, normaliseClipText, normaliseRef, parseRegistry, phrase, providerClass, render, sha256Hex, supportedLocale, voiceById, voiceFor

allowedVoice

Function

function allowedVoice(voice: VoiceEntry, providers: readonly ProviderClass[], from?: Registry): VoiceEntry | undefined;

A voice, or the first voice down its fallback chain whose provider is in providers. undefined when the chain has none.

Options and types: VoiceEntry, ProviderClass, Registry.

bucket

Function

function bucket(units: Units, metres: number): Rung;

The rung a distance is spoken as. Negative and non-finite distances count as zero.

Options and types: Units.

clipKey

Function

function clipKey(voice: VoiceEntry | string, text: string, options: ClipKeyOptions): string;

The content address of one clip, 64 lower-case hex digits.

• Voices with languageCode: null (Amelia) keep the legacy key, so every existing clip stays valid: sha256("<provider>|<voiceId>|<model>|<format>|<rate 2dp>|<text>").
• Voices with a languageCode use v2: sha256("v2|<provider>|<voiceId>|<model>|<languageCode>|<seed or ->|<stability or ->|<dictionary or ->|<format>|<rate 2dp>|<text>").

text is normalised first (see normaliseClipText). Throws when the voice has no provider id yet and none is passed in options.voiceId.

Options and types: VoiceEntry, ClipKeyOptions.

Example

import { clipKey, voiceFor } from "@mapmap/voice";

// The content address of one clip, as the gateway computes it.
const key = clipKey(voiceFor("en-GB"), "Turn left onto Baldwin Street.", { format: "m4a" });
console.log(key.length); // 64

defaultGenderFor

Function

function defaultGenderFor(locale: Locale): Gender;

The gender a locale speaks in when the caller names none.

Options and types: Locale.

definePhrases

Function

function definePhrases(locale: Locale, table: Record<string, Template>): void;

Registers an app's own phrases for a locale (Pacmap's chunk and rig lines, for example). Every slot is closed except at most one "name" slot, which must end the template. Core ids cannot be overridden. Registering an id again replaces it. The object form's byGender gives the text for one speaker gender where it differs (same placeholders); phrase and enumerateFixed pick it by the speaker's gender.

Options and types: Locale, Template.

enumerateFixed

Function

function enumerateFixed(locale: Locale, units: Units, options?: SpeakerOptions): string[];

Every fixed part text the locale can produce in units: the bake list for a splice voice, and the closed half of every sentence. Includes the core phrases and the app phrases registered so far with definePhrases (their closed slots expanded). Sorted, no duplicates. The list is for one speaker: options.gender (default: the locale's defaultGender), because a voice only ever says its own gender's text.

Options and types: Locale, Units, SpeakerOptions.

formatDistance

Function

function formatDistance(locale: Locale, units: Units, metres: number): Utterance;

The spoken words for a distance, as the preview would say it without "In": "four hundred yards".

Options and types: Locale, Units.

formatRate

Function

function formatRate(rate: number): string;

The rate at two decimals, as the key spells it. Pass rates that are already at two decimals (1, 0.95, 1.1): an exact binary tie such as 1.125 rounds up here and half-to-even in Rust's {:.2}.

fromValhalla

Function

function fromValhalla(m: ValhallaManeuver, context?: ValhallaContext): GuidanceIntent;

Builds the intent for one Valhalla manoeuvre. Pass context for the two facts a single manoeuvre does not carry (see ValhallaContext).

Options and types: ValhallaManeuver, ValhallaContext.

Example

import { fromValhalla, render } from "@mapmap/voice";

// One manoeuvre from a Valhalla route response (type 15 is a left turn).
const intent = fromValhalla({ type: 15, street_names: ["Baldwin Street"] });
console.log(render("en-GB", { intent, stage: "imperative", units: "metric" })?.text);

fromValhallaRoute

Function

function fromValhallaRoute(maneuvers: readonly ValhallaManeuver[]): GuidanceIntent[];

Intents for a whole manoeuvre list, with each manoeuvre's neighbours passed as context.

Options and types: ValhallaManeuver.

Example

import { fromValhallaRoute, render, type ValhallaManeuver } from "@mapmap/voice";

declare const maneuvers: ValhallaManeuver[]; // trip.legs[0].maneuvers from a Valhalla /route response
for (const intent of fromValhallaRoute(maneuvers)) {
  console.log(render("en-GB", { intent, stage: "imperative", units: "imperial_uk" })?.text);
}

gendersFor

Function

function gendersFor(locale: Locale): Gender[];

The genders a locale has a default voice for, in GENDERS order.

Options and types: Locale.

headingFromBearing

Function

function headingFromBearing(bearing: number): Heading;

Bearing in degrees to the nearest of eight compass points.

isRef

Function

function isRef(text: string): boolean;

True when text (after normaliseRef) reads as a road reference.

ladder

Function

function ladder(units: Units): readonly Rung[];

Every rung of a ladder, shortest first.

Options and types: Units.

normaliseClipText

Function

function normaliseClipText(text: string): string;

The gateway's text normalisation: trim, collapse whitespace runs to one space, Unicode NFC. Nothing else (no case folding, no lexicon).

normaliseRef

Function

function normaliseRef(text: string): string;

Removes the spaces inside a ref: "B 2" -> "B2", "A 1 (M)" -> "A1(M)".

parseRegistry

Function

function parseRegistry(raw: unknown): Registry;

Validates a registry document (version 3): every voice has a gender and a known provider; every default names a voice of that locale and gender; every locale has a defaultGender with a default voice; every fallback is an open-source voice of the same locale and gender, with no cycles. Exported for tests and for tools that load an override file.

phrase

Function

function phrase(locale: Locale, id: PhraseId, params?: Record<string, string | number>, options?: SpeakerOptions): Utterance;

A fixed phrase by id: a core id, or one registered with definePhrases for this locale. Throws on an unknown id or a value outside a closed slot. options.gender is the speaker's gender (default: the locale's defaultGender).

Options and types: Locale, PhraseId, SpeakerOptions.

providerClass

Function

function providerClass(provider: VoiceProvider): ProviderClass;

The class a provider belongs to.

Options and types: VoiceProvider.

render

Function

function render(locale: Locale, input: RenderInput, options?: SpeakerOptions): Utterance | null;

Renders one prompt. Returns null when there is nothing to say (for example a depart with neither a heading nor a road).

• preview with distanceM: "In four hundred yards," + the clause. A continue preview is the post-manoeuvre confirmation instead: "Continue for two miles on York Street." A preview without a distance is the imperative.
• imperative: the clause on its own.
• then: the clause as a stand-alone follow-up ("Then turn left.").
• then in the input chains a second clause (", then turn left"). The chained clause carries a name only when the first clause has none, so an utterance never has more than one open slot.

options.gender is the speaker's gender (default: the locale's defaultGender). No v1 locale changes its words with it; the argument exists for languages that do, and so that the text a voice hashes is the text that voice would say.

Options and types: Locale, RenderInput, SpeakerOptions.

Example

import { render } from "@mapmap/voice";

const utterance = render("en-GB", {
  intent: { kind: "turn", side: "right", target: { kind: "name", text: "York Street" } },
  stage: "preview",
  units: "imperial_uk",
  distanceM: 370,
});
console.log(utterance?.text);

sha256Hex

Function

function sha256Hex(str: string): string;

SHA-256 of the UTF-8 encoding of str, as 64 lower-case hex digits.

supportedLocale

Function

function supportedLocale(deviceLocale: string): {
    locale: Locale;
    fallback: boolean;
};

The phrasebook locale for a device locale ("de_AT", "fr-CA", "en-AU", "pt-BR"). A device in a supported language gets that language, with fallback: false. Anything else gets en-GB with fallback: true, and because the numbers are words from the en-GB ladder the old "In 1,5 kilometres" defect cannot recur.

voiceById

Function

function voiceById(id: string): VoiceEntry | undefined;

A registry voice by id, or undefined.

voiceFor

Function

function voiceFor(locale: Locale, gender?: Gender, options?: VoiceForOptions): VoiceEntry;

The default voice for a locale and gender. With no gender, the locale's defaultGender (female for every locale today), so voiceFor(locale) means what it meant before voices had a gender. With options.providers, a default outside those provider classes is replaced by its fallback (voiceFor("en-GB", "female", { providers: ["open"] }) is the open-source female voice). Throws when the locale has no voice of that gender (see gendersFor), or none the providers allow.

This is the voice a request asks for. The gateway can still answer a clip with the fallback voice (when ElevenLabs fails), so a client takes each clip's hash and url from the response, never from clipKey of the voice it asked for.

Options and types: Locale, Gender, VoiceForOptions.

Example

import { voiceFor } from "@mapmap/voice";

const voice = voiceFor("en-GB");                                      // the locale's default voice
const open = voiceFor("en-GB", "female", { providers: ["open"] });    // only open-source models
console.log(voice.id, open.provider);

Interfaces (@mapmap/voice)

ClipKeyOptions, GuidanceIntent, Part, Registry, RenderInput, Rung, SpeakerOptions, Target, Utterance, ValhallaContext, ValhallaManeuver, ValhallaSign, ValhallaSignElement, VoiceEntry, VoiceForOptions

ClipKeyOptions

Interface

interface ClipKeyOptions

GuidanceIntent

Interface

interface GuidanceIntent

A locale-neutral description of one manoeuvre. It contains no words except the target's bare name.

Part

Interface

interface Part

One clip's worth of an utterance. fixed parts come from the closed phrasebook (see enumerateFixed); a name part is the open slot, the bare target text, and is synthesised once per name and locale.

Registry

Interface

interface Registry

RenderInput

Interface

interface RenderInput

Rung

Interface

interface Rung

SpeakerOptions

Interface

interface SpeakerOptions

Who is speaking. Some languages change the words with the speaker's gender (a Thai polite particle, Hebrew or Hindi verb agreement), so the text of a sentence can depend on the voice that will say it. Absent, the gender is the locale's defaultGender from the registry.

Target

Interface

interface Target

The one open slot. text is the bare form as signed: no article, no case ending, no contraction. A ref is normalised by removing spaces ("B 2" -> "B2", "A 1 (M)" -> "A1(M)"); hyphens stay ("A-6", "I-95").

Utterance

Interface

interface Utterance

A rendered sentence. text is the whole utterance, the string a sentence-mode voice synthesises and hashes. parts is the same sentence cut at clip boundaries for a splice-mode voice; parts carry no joining whitespace and the name part carries no terminal punctuation.

ValhallaContext

Interface

interface ValhallaContext

Neighbouring manoeuvres. Contract addition, optional: a roundabout's own street_names is the roundabout, so the road it is left onto comes from the following exit manoeuvre (next); "to stay on" needs the road being driven before the manoeuvre (previous).

ValhallaManeuver

Interface

interface ValhallaManeuver

The fields of a Valhalla manoeuvre this package reads. Others may be present and are ignored.

ValhallaSign

Interface

interface ValhallaSign

ValhallaSignElement

Interface

interface ValhallaSignElement

Valhalla manoeuvre -> GuidanceIntent, from STRUCTURED fields only.

Read: type, street_names, begin_street_names, sign.*_elements, roundabout_exit_count, bearing_after, highway. Never read: instruction and every verbal_* string. Those are English (or whatever language the route was requested in), and pattern-matching them is what broke the moment a route came back in another language.

Field reference: Valhalla turn-by-turn API, "Maneuvers" and "Sign" (https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/).

VoiceEntry

Interface

interface VoiceEntry

VoiceForOptions

Interface

interface VoiceForOptions

Options for voiceFor.

Types (@mapmap/voice)

ComposeMode, CorePhraseId, DistanceUnit, Gender, GenderDefaults, Heading, Kind, Locale, PhraseId, ProviderClass, Sharpness, Side, SlotSpec, Stage, Template, Units, VoiceProvider, VoiceStatus

ComposeMode

Type

type ComposeMode = "sentence" | "splice";

CorePhraseId

Type

type CorePhraseId = "off_route" | "rerouting" | "back_on_route" | "arrived" | "arrive_left" | "arrive_right" | "gps_lost" | "gps_back" | "level_crossing" | "speed_camera" | "ferry_ahead" | "toll_ahead" | "faster_route" | "average_speed";

The phrase ids every locale defines.

DistanceUnit

Type

type DistanceUnit = "m" | "km" | "yd" | "ft" | "mi";

The closed distance ladders. A spoken distance is always one rung of a ladder, so the set of distance phrases is finite and can be baked.

Rungs (phrasing research §3.1, shared by every locale): metric 50, 100, 150, 200, 250, 300, 400, 500, 600, 700, 800 m; 1, 1.5, 2, 2.5, 3 km; 4 to 10 km; 15 to 100 km in fives imperial_uk 50 to 400 yd in fifties; a quarter, half, three quarters of a mile; 1, 1.5, 2, 2.5, 3 mi; 4 to 10 mi; 15 to 100 mi imperial_us 100, 200, 300, 400, 500, 600, 800, 1000 ft; then the same miles as imperial_uk. Never yards.

A distance goes to the NEAREST rung (linear), clamped to the ends.

Gender

Type

type Gender = "female" | "male";

A voice's gender. Every locale has a default gender (defaultGender in the registry) and may have one voice of each.

GenderDefaults

Type

type GenderDefaults = Readonly<Partial<Record<Gender, string>>>;

A locale's default voice ids by gender. A gender is absent until a voice exists for it.

Heading

Type

type Heading = "n" | "ne" | "e" | "se" | "s" | "sw" | "w" | "nw";

Eight-point compass heading, used by depart only. Contract addition.

Kind

Type

type Kind = "depart" | "continue" | "name_change" | "turn" | "uturn" | "keep" | "merge" | "ramp_on" | "exit" | "roundabout_enter" | "roundabout_exit" | "ferry_enter" | "ferry_exit" | "arrive";

What kind of manoeuvre is being described. Closed set.

Locale

Type

type Locale = "en-GB" | "en-US" | "fr-FR" | "de-DE" | "es-ES" | "it-IT" | "nl-NL";

The locales the phrasebook speaks in v1.

PhraseId

Type

type PhraseId = CorePhraseId | (string & {});

A core id, or an id an app registered with definePhrases. The string & {} keeps editor completion for the core ids.

ProviderClass

Type

type ProviderClass = "elevenlabs" | "open";

The provider classes a caller can allow or forbid (providers on POST /v1/voice/clips, and on voiceFor): elevenlabs, or open for every self-hosted open-source model.

Sharpness

Type

type Sharpness = "slight" | "normal" | "sharp";

Side

Type

type Side = "left" | "right" | "straight";

SlotSpec

Type

type SlotSpec = readonly (string | number)[] | {
    cardinal: readonly [number, number];
} | "name";

A closed slot in an app template: a list of allowed values, or a cardinal range the locale spells out in words. "name" marks the single open slot, which must be the template's last placeholder.

Stage

Type

type Stage = "preview" | "imperative" | "then";

preview: the early prompt, led by a distance when one is given ("In four hundred yards, turn right onto York Street."). imperative: the prompt at the manoeuvre ("Turn right onto York Street."). then: the intent spoken as a follow-up on its own ("Then turn left.").

Template

Type

type Template = string | {
    text: string;
    slots?: Readonly<Record<string, SlotSpec>>;
    byGender?: Readonly<Partial<Record<Gender, string>>>;
};

An app phrase. A plain string has no placeholders. The object form names each {slot} in text. Contract addition: the contract names the type without defining it.

Units

Type

type Units = "metric" | "imperial_uk" | "imperial_us";

The distance system the driver chose. It is a setting of its own, not a property of the language: a French driver in the UK can hear miles. imperial_uk speaks yards below a quarter of a mile; imperial_us speaks feet and never yards.

VoiceProvider

Type

type VoiceProvider = "elevenlabs" | "kokoro" | "supertonic";

Who synthesises a voice. elevenlabs is the hosted provider; kokoro (Kokoro-82M) and supertonic (Supertonic 3) are open-source models the gateway runs itself.

VoiceStatus

Type

type VoiceStatus = "live" | "candidate";

Constants (@mapmap/voice)

CORE_PHRASE_IDS, GENDERS, HEADINGS, KINDS, LOCALES, PROVIDER_CLASSES, registry, REGISTRY_VERSION, UNITS, VOICE_PROVIDERS

CORE_PHRASE_IDS

Constant

const CORE_PHRASE_IDS: readonly CorePhraseId[];

GENDERS

Constant

const GENDERS: readonly Gender[];

Every voice gender.

HEADINGS

Constant

const HEADINGS: readonly Heading[];

KINDS

Constant

const KINDS: readonly Kind[];

LOCALES

Constant

const LOCALES: readonly Locale[];

Every supported locale, in registry order.

PROVIDER_CLASSES

Constant

const PROVIDER_CLASSES: readonly ProviderClass[];

Every provider class.

registry

Constant

const registry: Registry;

The shared voice registry (voices.json), validated.

REGISTRY_VERSION

Constant

const REGISTRY_VERSION = 3;

Registry format this package reads. Version 3 added open-source providers and fallback.

UNITS

Constant

const UNITS: readonly Units[];

VOICE_PROVIDERS

Constant

const VOICE_PROVIDERS: readonly VoiceProvider[];

Every provider a registry voice may name.