D03 — The audio guide in the visitor's language

A museum wants its audio guide in five languages. The obvious workflow makes all five for every visitor and throws four away. This one makes the one the visitor asked for: the visitor’s choice decides which branch runs, the other four branches are skipped before they cost anything, and the result comes back through one door — whatever the language.

Johannes Vermeer, Girl with a Pearl Earring, about 1665, Mauritshuis, The Hague (public domain, via Wikimedia Commons), detail — the whole painting. The stop of the reference runs:

The visitor typed	Language	Listen	Credits
Italiano	Italian	MP3, 73 s	2.9
DEUTSCH	German	MP3, 78 s	3.3
日本語	English — not offered, so the fallback	MP3, 66 s	2.9

The narrations are in the runs’ outputs.

The case

The curator has written one text for the room, in English: the date, the size and the museum; that the painting is a tronie and not a portrait; the ultramarine of the turban; the pearl that is two strokes of paint; what a 2018 study found under the surface. The museum offers the guide in English, Italian, French, German and Spanish, on a kiosk and in its app — where visitors choose their language in all sorts of ways: IT, Italiano, italian, DEUTSCH, or a language the museum does not offer yet.

Input	Who provides it	Example
Visitor’s language	the kiosk or the app, as the visitor chose it	Italiano
Curator’s text	the museum, once per room	saved in the workflow

What it shows

• Normalise the key before routing on it. The first Select by Key maps sixteen spellings (it, italiano, italian, DEUTSCH, français, francais…) to five codes, ignoring case, and falls back to English for anything else — 日本語 included, with used_default: true so the app can say so. Its cases are constants: it costs nothing, and everything after it compares exact codes. See Choosing.
• Route, then rejoin. Each language has its own branch, opened by a Predicate (equals the code) and a Filter. Exactly one Filter passes; the four others reject, and their narration and voice are skipped — the paid steps of four languages never run. A second pair of Select by Key, fed with the same code and caseSensitive: true, rejoins the branches: it accepts the rejected cases, so only the chosen one has to arrive. See Choosing.
• Adapt, do not translate. Each branch has its own writer: the curator’s facts, rewritten for listening in that language — short sentences, spoken to one visitor in front of the painting, every date and size kept, nothing added. The German narration says “Sie sehen es im Mauritshuis”; the Italian one “Si trova al Mauritshuis, all’Aia”.
• One voice for the museum. The same narrator reads every language (a multilingual voice model), so the guide sounds like one institution, not five vendors.

The workflow

The figure tells the workflow as stages, with the reference runs’ results on the cards; the exact graph is the workflow (as a diagram), node by node in the table.

Node	Type	Why
Visitor’s language / Curator’s text	input/text	The key as the visitor chose it; the room’s text
English, Italian, French, German, Spanish	utility/constant	The five codes, as values to choose from
Supported language	utility/select_by_key, 16 cases, case-insensitive, use_default English	Any spelling to one code; unknown languages fall back
Is … / Only …	utility/predicate (equals the code) and utility/filter, one pair per language	Only the chosen branch receives the curator’s text
Narration in …	ai/text_generation, low reasoning effort	The text for listening, in that language
Voice in …	ai/text_to_speech, one multilingual voice	The narration read aloud
Narration / Audio	utility/select_by_key, five cases, caseSensitive: true, onNoMatch: fail	The chosen branch’s text and audio, whatever the language
Outputs	output/audio, output/text ×2, output/json	The MP3, the narration, the language, whether it fell back

Reading a run: Language says which guide was made and Fell back to English whether the visitor’s language was not offered. In the trace, four of the five narration and voice steps are skipped with branch_rejected.

Cost: about 3 credits a visitor — the narration a few hundredths, the voice about 3 credits for a thousand characters. Making all five languages every time would cost five times as much. The estimate before the run cannot know which language the visitor will choose: it counts the five narrations as a ceiling and reports the voice as deferred, because the length of a spoken text is measured and admitted just before the voice is ordered.

A note on the writers: a narration is a writing task, so each writer runs with low reasoning effort (a model parameter). Left at the default, the model sometimes spent its whole token budget deliberating over how to rewrite an English text in English, and returned nothing. For writing, ask the model to write.

Install it

The example installs into your workspace with an API key, through the public API only — see Installing an example:

node madoo-install-example.mjs d03-audio-guide --api <your Madoo API URL> --key <key.json> --run

--run makes the Italian guide (about 3 credits). The other two runs are in run-inputs-deutsch.json and run-inputs-japanese.json.

Change it

• Another room: replace the curator’s text; the workflow does not know it is about Vermeer.
• Another language: add a constant, its spellings in Supported language, a branch of four nodes, and a case in each of the two rejoins.
• Another fallback: the default of Supported language is the museum’s first language.
• Another voice: the narrator is a parameter of the voice steps; a museum can use its own cloned voice.
• A family version: a second key (adults, children) routed the same way gives each visitor the right tone.

Files

manifest · workflow · the complete graph