Bouw een transcriptie-app met utt

Spraakherkenning aan een app toevoegen is meer dan alleen een model draaien. Je moet ook microfoontoestemming, audioformaten, achtergrondthreads, wisselende apparaten en sluimerstand afhandelen.

utt regelt dat werk al. Het draait Parakeet en Whisper op de Mac, houdt audio op de Mac en past de vervangingen, opschoning en opmaak van de gebruiker toe.

Je programma kan op twee manieren verbinden. Gebruik de HTTP-API voor audio uit een ander proces of apparaat. Gebruik een extensie voor een lokaal programma dat transcripties, filters, instellingen of statusinformatie nodig heeft.

Audio versturen via HTTP

Zet de API aan in Settings en stuur vervolgens een audiobestand naar POST /transcribe. utt geeft JSON terug. De requestbody is het bestand zelf, dus je hebt geen SDK of multipart-formulier nodig.

curl -X POST http://mac.local:8756/transcribe \
  -H "Authorization: Bearer $UTT_TOKEN" \
  -H "Content-Type: audio/wav" \
  --data-binary @clip.wav

De teruggestuurde tekst heeft dezelfde pipeline doorlopen als bij de sneltoets, inclusief de eigen vervangingen en opmaakregels van de gebruiker. Je app krijgt precies wat utt anders zou hebben geplakt.

Elk programma dat een HTTP-request kan doen, kan de API gebruiken. Denk aan shellscripts, Raycast-commando's, Opdrachten en apps op je lokale netwerk. De developerhandleiding bevat werkende voorbeelden in Swift, Python en JavaScript.

Een lokale extensie verbinden

Een lokaal programma kan een eigen pagina aan utt toevoegen door één JSON-manifest te schrijven. utt tekent de instellingen en acties op de pagina en bewaart de keuzes van de gebruiker vervolgens in een waardenbestand dat het programma kan lezen.

Extensies wisselen via bestanden audio en transcripties uit met utt. Ze hoeven geen poort te openen of API-token op te slaan.

Elke nieuwe extensie begint als in afwachting. utt deelt niets totdat de gebruiker de aanvragen heeft bekeken en goedgekeurd.

Het voorbeeld hieronder schrijft een lokale opname naar de jobs-map van de extensie. utt schrijft de transcriptie ernaast.

jobs = Path.home() / "Library/Application Support/dev.jurrejan.utt/extensions/deckhand.jobs"
part = jobs / "clip-1.wav.part"
part.write_bytes(wav)
part.rename(jobs / "clip-1.wav")  # now utt sees it

answer = jobs / "clip-1.json"
while not answer.exists():
    time.sleep(0.2)
result = json.loads(answer.read_text())
answer.unlink()
print(result.get("text") or result["error"])

Gebruik de jobs-map wanneer een programma op dezelfde Mac transcriptie nodig heeft zonder server, token of netwerktoegang.

Wat je met een extensie kunt maken

Met het manifest kan een programma één onderdeel van utt gebruiken of meerdere combineren:

• Een audiobron plaatst lokale opnames in een jobs-map en leest de voltooide tekst.
• Een transcriptie-ontvanger ontvangt elke voltooide transcriptie om die op te slaan, door te sturen of te verwerken.
• Een live companion volgt voorlopige woorden zolang de toets is ingedrukt en ontvangt later de definitieve transcriptie.
• Een tekstfilter herschrijft, vertaalt, formatteert of stopt een transcriptie voordat utt die aflevert.
• Een bedieningspaneel voegt instellingen, acties, status, daemonstatus en eventueel een submenu aan utt toe.

Een companion die ook de HTTP-API nodig heeft, kan utt vragen om na goedkeuring het token in het waardenbestand te zetten. De developerhandleiding koppelt elk type aan de bijbehorende manifestsleutels en bestanden.

Bouw het met een LLM

De pagina's API en Extensions in utt hebben allebei een knop Copy guide. Die kopieert het exacte protocol, de audio-instellingen, een werkend voorbeeld en veelgemaakte fouten naar een briefing voor coding assistants.

Plak de briefing in Claude, Cursor, Codex of een andere coding assistant. Beschrijf daarna het programma dat je wilt:

Bouw een kleine app die mijn map met Dictafoon-opnames in de gaten houdt. Stuur elke nieuwe opname naar utt en sla de transcriptie ernaast op als tekstbestand.

De briefing geeft het model het exacte utt-protocol, zodat jij je kunt richten op wat je programma moet doen.

In de API-handleiding staat een placeholder voor het token. Kopieer het token pas vanuit de API-instellingen van utt als de code klaar is, in plaats van het geheim in een chat te plakken.

Deckhand

Met Deckhand bedien je vanaf een iPhone Claude Code-sessies op je Mac. Kies een sessie, lees het nieuwste antwoord en houd ingedrukt om te praten. utt transcribeert de opname op je Mac, waarna Deckhand de tekst naar die sessie stuurt.

Waar je begint

1. Installeer utt en dicteer iets, zodat je weet wat het doet.
2. Open Settings. Zet onder Connect de API aan of open de pagina Extensions.
3. Klik op Copy guide en plak die in je model, of lees zelf de developerhandleiding.
4. Bouw je app.

Publiceer je een extensie, open dan een GitHub-issue met de link naar de repository om die aan de pagina Extensies toe te laten voegen.