Voice server

Overview

The voice server is started with moorcheh-edge voice serve. It runs on Linux edge hardware (for example Arduino UNO Q) and exposes mic, speaker, and RAG endpoints over HTTP. It is not part of the Moorcheh Edge Docker container (:8080). RAG calls are proxied to Moorcheh Edge on the same device (default http://127.0.0.1:8080).


Default URL	`http://<device-ip>:8766`
Start command	`moorcheh-edge voice serve --port 8766`
Platform	Linux with ALSA (not Windows/macOS)

Run moorcheh-edge voice setup once before starting the server.

GET /health

Check that the voice server is running.

curl -X GET "http://192.168.1.50:8766/health"

{
  "status": "ok",
  "service": "moorcheh-edge-voice"
}

POST /listen

Record from the device mic and return transcribed text.

number

Fixed recording length in seconds. When set, disables silence detection.

boolean

default:"true"

When true (and seconds is omitted), stop recording after a pause in speech.

number

default:"30"

Maximum recording length when using silence detection (3–60).

curl -X POST "http://192.168.1.50:8766/listen" \
  -H "Content-Type: application/json" \
  -d '{"until_silence": true, "max_seconds": 30}'

{
  "heard": "Do you have oat milk?"
}

POST /speak

Synthesize and play text on the device speaker.

string

required

Text to speak.

curl -X POST "http://192.168.1.50:8766/speak" \
  -H "Content-Type: application/json" \
  -d '{"text": "Welcome to The Brew Corner."}'

{
  "spoke": true
}

POST /ask/stream

Stream a RAG answer as Server-Sent Events. Embeds the query on the edge device when query_vector is omitted; otherwise uses the vector you supply. Proxies POST /answer/stream on Moorcheh Edge. When speak: true, streams answer tokens to the remote UI immediately and starts TTS after the full answer is ready (one Piper pass on the device speaker).

string

required

Question text.

array

Optional precomputed embedding. When omitted, the server embeds locally with BGE-small-en-v1.5 (384-dim).

number

default:"5"

Passages to retrieve for context.

boolean

default:"true"

When true, filters passages below threshold.

number

default:"0.25"

Minimum search score when kiosk_mode is true.

string

Optional system instruction for RAG.

string

Optional instruction before the question.

array

Prior turns: [{"role": "user"|"assistant", "content": "..."}].

boolean

default:"false"

When true, speak the full answer on the device after streaming completes.

boolean

default:"true"

When speak is true, play the cached kiosk holding welcome audio in parallel with RAG. Pre-generate with moorcheh-edge voice cache-holding - see Retail Kiosk: kiosk audio cache.

boolean

default:"true"

When speak is true, loop the ambient thinking WAV until answer tokens arrive (after holding). Pre-generate with moorcheh-edge voice cache-thinking - see Retail Kiosk: kiosk audio cache. Disable globally with MOORCHEH_THINKING_SOUND=0.

curl -N -X POST "http://192.168.1.50:8766/ask/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Do you have oat milk?",
    "top_k": 2,
    "kiosk_mode": true,
    "threshold": 0.3,
    "speak": true
  }'

SSE events

Inherits Moorcheh Edge events from Answer stream:

Event	Description
`meta`	Model, sources, and context count
`token`	Answer text delta (`{"delta": "..."}`)
`done`	Full answer and metadata
`error`	LLM or upstream failure

Additional events when speak: true:

Event	Description
`holding`	Kiosk welcome audio started (`{"text": "...", "playing": true}`)
`thinking`	Ambient thinking loop started (`{"text": "Thinking…", "playing": true}`)
`sentence`	Full answer text sent before TTS starts (`{"text": "..."}`)

TTS continues in the background after the HTTP stream closes; the connection does not wait for playback to finish.

POST /ask and POST /ask/voice

Full voice loop: record from mic (unless query is provided), embed locally, call POST /answer on Moorcheh Edge, and speak the reply on the device. /ask/voice is an alias for /ask.

string

When set, skip mic capture and use this text as the question.

number

Fixed recording length when query is omitted.

boolean

default:"true"

Stop recording after a pause when seconds is omitted.

number

default:"30"

Maximum recording length for silence detection.

number

default:"5"

Passages to retrieve for context.

boolean

default:"true"

Filter low-scoring passages when true.

number

default:"0.25"

Minimum score when kiosk_mode is true.

string

Optional system instruction.

string

Optional instruction before the question.

array

Prior conversation turns.

boolean

default:"true"

When true, play the answer on the device speaker.

curl -X POST "http://192.168.1.50:8766/ask" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are your hours?",
    "top_k": 2,
    "kiosk_mode": true,
    "threshold": 0.3,
    "speak": true
  }'

{
  "heard": "What are your hours?",
  "query": "What are your hours?",
  "answer": "We are open Monday through Friday, 7am to 6pm.",
  "model": "qwen2.5:0.5b-instruct",
  "context_count": 1,
  "spoke": true
}

POST /catalog/document

Chunk a catalog document, embed on the device, and upload vectors to Moorcheh Edge on the same board. Used by the retail kiosk Admin when saving documents (MOORCHEH_VOICE_PROXY_URL).

string

required

Stable document id (used in chunk ids and [meta] headers).

string

required

Document category (e.g. menu, policy).

string

required

Display title for the document.

string

required

Full document body to chunk and embed. Alias: body.

array | string

Tags as a JSON array or comma-separated string.

array

Edge item ids to delete before upload (replaced chunks after an edit). Alias: orphan_ids.

curl -X POST "http://192.168.1.50:8766/catalog/document" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "hours",
    "category": "store-info",
    "title": "Store hours",
    "tags": ["hours"],
    "text": "We are open Monday through Friday, 7am to 6pm."
  }'

{
  "doc_id": "hours",
  "chunks_uploaded": 1,
  "chunks_deleted": 0,
  "chunk_ids": ["hours:0"],
  "chunks": [
    {
      "chunk_id": "hours:0",
      "doc_id": "hours",
      "chunk_index": 0,
      "category": "store-info",
      "title": "Store hours",
      "tags": "hours",
      "text": "[meta]\ndoc_id: hours\ncategory: store-info\ntitle: Store hours\ntags: hours\nchunk: 0\n[/meta]\n\nWe are open Monday through Friday, 7am to 6pm."
    }
  ]
}

Errors

Condition	Status	Body
Invalid JSON	`400`	`{"error": "invalid JSON body"}`
Missing `query` on `/ask/stream`	`400`	`{"error": "query is required"}`
Unknown route	`404`	`{"error": "not found"}`
Voice runtime / audio failure	`503`	`{"error": "..."}`
Unexpected server error	`500`	`{"error": "..."}`

System

Search

AI Generation

Data Operations

Delete

Overview

GET /health

POST /listen

POST /speak

POST /ask/stream

SSE events

POST /ask and POST /ask/voice

POST /catalog/document

Errors

​Overview

​GET /health

​POST /listen

​POST /speak

​POST /ask/stream

​SSE events

​POST /ask and POST /ask/voice

​POST /catalog/document

​Errors

​Related

Overview

GET /health

POST /listen

POST /speak

POST /ask/stream

SSE events

POST /ask and POST /ask/voice

POST /catalog/document

Errors

Related