// Package voice implements asynchronous speech-to-text and text-to-speech for
// the Cyrene runtime, following DevDocs/design/06-多模态.md §1.
//
// Voice input (STT) is transcribed to text and fed into the same agent pipeline
// as a chat message; the reply is synthesized (TTS) back to audio. Both
// directions degrade through a provider chain — cloud → local → edge-tts/espeak
// → silent — so an unavailable provider falls through to the next rung instead
// of failing the whole turn. The stub default implementations are HTTP-based and
// testable with a stdlib httptest server; real cloud/local providers remain
// adaptation points for later milestones.
package voice

import "context"

// Audio is a piece of audio data plus its encoding.
type Audio struct {
	// Format is the encoding, e.g. "wav", "mp3", "ogg".
	Format string
	// Data is the raw audio bytes.
	Data []byte
}

// STT converts audio to text.
type STT interface {
	// STT transcribes audio and returns the spoken text. ctx controls
	// cancellation and must be honored.
	STT(ctx context.Context, audio Audio) (string, error)
}

// TTS synthesizes speech audio from text.
type TTS interface {
	// TTS synthesizes audio from text. ctx controls cancellation and must be
	// honored.
	TTS(ctx context.Context, text string) (Audio, error)
}