AI Voice Address Capture: Resolve Spoken Addresses with Swiftcomplete

ffmpeg -i input.wav -ac 1 -ar 16000 -c:a pcm_s16le address.wav

wss://voice.swiftcomplete.com/v1/address/stream

x-api-key: YOUR_API_KEY

{
  "parameter": "key",
  "description": "Your credits have expired. Please sign in to your account and purchase credits to continue using the service.",
  "resolutionExamples": []
}

{
  "type": "start_utterance",
  "audio_format": { "encoding": "mulaw", "sample_rate_hz": 8000 },
  "idempotency_key": "5f0c2a8e-7d1b-4c3e-9a2f-1b6d8e4c0a7f"
}

{ "type": "commit_utterance" }

{"type":"transcript_interim","transcript":"ten downing"}
{"type":"transcript_interim","transcript":"ten downing street"}
{"type":"transcript_final","transcript":"ten downing street london"}

{
  "type": "validation_completed",
  "turn_id": "9fb7c1e2-4d0a-4c55-a0f3-2b8e6d1f7a90",
  "response": {
    "validation": { "result": "match", "resolution": "premise" },
    "address": {
      "singleLine": "65 Alfred Road, London, W2 5EU, United Kingdom",
      "multiLine": {
        "line1": "65 Alfred Road",
        "primaryLocality": "London",
        "postalCode": "W2 5EU"
      }
    },
    "associatedRecords": null
  }
}

{"type":"not_resolved","turn_id":"9fb7c1e2-4d0a-4c55-a0f3-2b8e6d1f7a90"}

{"type":"error","turn_id":"9fb7c1e2-4d0a-4c55-a0f3-2b8e6d1f7a90","code":"service_busy","retry_after_ms":1000}

{"type":"error","turn_id":"9fb7c1e2-4d0a-4c55-a0f3-2b8e6d1f7a90","code":"api_key_rejected","description":"Your free trial has expired. Please sign in to your account and purchase credits to continue using the service."}

"""Resolve a spoken UK address from a WAV file with Swiftcomplete.

Usage:
    pip install "websockets>=14"
    export SWIFTCOMPLETE_API_KEY=your-key
    python resolve_address.py address.wav
"""

import asyncio
import json
import os
import sys
import uuid
import wave

import websockets

URL = "wss://voice.swiftcomplete.com/v1/address/stream"
SAMPLE_RATES = (8_000, 16_000, 48_000)
FRAME_MS = 20
RESULT_TIMEOUT_S = 15


def read_pcm(path):
    with wave.open(path, "rb") as wav:
        rate = wav.getframerate()
        if wav.getnchannels() != 1 or wav.getsampwidth() != 2 or rate not in SAMPLE_RATES:
            sys.exit("The WAV file must be 16-bit mono PCM at 8, 16 or 48 kHz")
        return wav.readframes(wav.getnframes()), rate


async def stream_audio(ws, pcm, rate):
    """Send the audio at real-time pace, as a live call would, then commit."""
    frame_bytes = rate * 2 * FRAME_MS // 1000  # 20 ms of 16-bit mono audio
    try:
        for offset in range(0, len(pcm), frame_bytes):
            await ws.send(pcm[offset:offset + frame_bytes])
            await asyncio.sleep(FRAME_MS / 1000)
        await ws.send(json.dumps({"type": "commit_utterance"}))
    except websockets.ConnectionClosed:
        pass  # The server ended the request early; its result explains why.


async def resolve(pcm, rate):
    headers = {"X-API-Key": os.environ["SWIFTCOMPLETE_API_KEY"]}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "type": "start_utterance",
            "idempotency_key": str(uuid.uuid4()),
            "audio_format": {"encoding": "pcm_s16le", "sample_rate_hz": rate},
        }))
        sender = asyncio.create_task(stream_audio(ws, pcm, rate))
        try:
            async for message in ws:
                event = json.loads(message)
                if event["type"] == "transcript_interim":
                    print("Heard so far:", event["transcript"])
                elif event["type"] == "transcript_final":
                    print("Heard:", event["transcript"])
                else:
                    return event  # The one result; the server then closes the connection.
        finally:
            sender.cancel()
    return None


def describe(result):
    if result is None:
        return "The connection closed without a result"
    if result["type"] == "validation_completed":
        response = result["response"]
        address = (response.get("address") or {}).get("singleLine")
        return f"{response['validation']['result']}: {address}"
    if result["type"] == "not_resolved":
        return "No address identified; ask the caller again"
    detail = ""
    if "retry_after_ms" in result:
        detail += f", retry after {result['retry_after_ms']} ms"
    if "error_ref" in result:
        detail += f", ref {result['error_ref']}"
    if "description" in result:
        detail += f": {result['description']}"
    return f"Error: {result['code']}{detail} (turn {result['turn_id']})"


def refusal(error):
    """Why the connection was refused, with Swiftcomplete's description when it gave one."""
    try:
        description = json.loads(error.response.body)["description"]
    except (TypeError, ValueError, KeyError):
        description = None
    status = error.response.status_code
    return f"Connection refused: HTTP {status}" + (f": {description}" if description else "")


def main():
    pcm, rate = read_pcm(sys.argv[1])
    audio_seconds = len(pcm) / (rate * 2)
    try:
        result = asyncio.run(asyncio.wait_for(resolve(pcm, rate), audio_seconds + RESULT_TIMEOUT_S))
    except websockets.InvalidStatus as error:
        sys.exit(refusal(error))
    except asyncio.TimeoutError:
        sys.exit("No result in time")
    print(describe(result))


if __name__ == "__main__":
    main()

// Resolve a spoken UK address from a WAV file with Swiftcomplete.
//
// Usage (Node.js 18 or later):
//   npm install ws
//   SWIFTCOMPLETE_API_KEY=your-key node resolve-address.mjs address.wav

import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
import { setTimeout as sleep } from "node:timers/promises";
import WebSocket from "ws";

const URL = "wss://voice.swiftcomplete.com/v1/address/stream";
const SAMPLE_RATES = [8000, 16000, 48000];
const FRAME_MS = 20;
const RESULT_TIMEOUT_MS = 15000;

function readPcm(path) {
  const wav = readFileSync(path);
  if (wav.toString("ascii", 0, 4) !== "RIFF" || wav.toString("ascii", 8, 12) !== "WAVE") {
    throw new Error("Not a WAV file");
  }
  let format;
  for (let offset = 12; offset + 8 <= wav.length; ) {
    const id = wav.toString("ascii", offset, offset + 4);
    const size = wav.readUInt32LE(offset + 4);
    const body = wav.subarray(offset + 8, offset + 8 + size);
    if (id === "fmt ") {
      format = {
        encoding: body.readUInt16LE(0),
        channels: body.readUInt16LE(2),
        sampleRate: body.readUInt32LE(4),
        bits: body.readUInt16LE(14),
      };
    } else if (id === "data") {
      const ok = format?.encoding === 1 && format.channels === 1 &&
        SAMPLE_RATES.includes(format.sampleRate) && format.bits === 16;
      if (!ok) throw new Error("The WAV file must be 16-bit mono PCM at 8, 16 or 48 kHz");
      return { pcm: body, rate: format.sampleRate };
    }
    offset += 8 + size + (size % 2);
  }
  throw new Error("The WAV file has no audio data");
}

function describe(result) {
  if (!result) return "The connection closed without a result";
  if (result.type === "validation_completed") {
    const { validation, address } = result.response;
    return `${validation.result}: ${address?.singleLine}`;
  }
  if (result.type === "not_resolved") return "No address identified; ask the caller again";
  const retry = result.retry_after_ms ? `, retry after ${result.retry_after_ms} ms` : "";
  const ref = result.error_ref ? `, ref ${result.error_ref}` : "";
  const why = result.description ? `: ${result.description}` : "";
  return `Error: ${result.code}${retry}${ref}${why} (turn ${result.turn_id})`;
}

const { pcm, rate } = readPcm(process.argv[2]);
const frameBytes = (rate * 2 * FRAME_MS) / 1000; // 20 ms of 16-bit mono audio
const audioMs = (pcm.length / (rate * 2)) * 1000;
const ws = new WebSocket(URL, { headers: { "X-API-Key": process.env.SWIFTCOMPLETE_API_KEY } });
const timer = setTimeout(() => ws.terminate(), audioMs + RESULT_TIMEOUT_MS);
let result;

ws.on("open", async () => {
  ws.send(JSON.stringify({
    type: "start_utterance",
    idempotency_key: randomUUID(),
    audio_format: { encoding: "pcm_s16le", sample_rate_hz: rate },
  }));
  // Send the audio at real-time pace, as a live call would, then commit.
  for (let offset = 0; offset < pcm.length; offset += frameBytes) {
    if (ws.readyState !== WebSocket.OPEN) return; // The server ended the request early.
    ws.send(pcm.subarray(offset, offset + frameBytes));
    await sleep(FRAME_MS);
  }
  if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "commit_utterance" }));
});

ws.on("message", (data, isBinary) => {
  if (isBinary) return;
  const event = JSON.parse(data.toString());
  if (event.type === "transcript_interim") console.log("Heard so far:", event.transcript);
  else if (event.type === "transcript_final") console.log("Heard:", event.transcript);
  else result = event; // The one result; the server then closes the connection.
});

// A refused connection: the HTTP status, with Swiftcomplete's description when it gave one.
ws.on("unexpected-response", (_request, response) => {
  let body = "";
  response.on("data", (chunk) => { body += chunk; });
  response.on("end", () => {
    let description;
    try { description = JSON.parse(body).description; } catch { /* no JSON body */ }
    console.error(`Connection refused: HTTP ${response.statusCode}${description ? `: ${description}` : ""}`);
    clearTimeout(timer);
    process.exit(1);
  });
});

ws.on("error", (error) => console.error(error.message));

ws.on("close", () => {
  clearTimeout(timer);
  console.log(describe(result));
});