pikku-ai-voice

name

pikku-ai-voice

description

Use when adding voice input (speech-to-text) or voice output (text-to-speech) to AI agents in a Pikku app. Covers voiceInput/voiceOutput middleware hooks and STT/TTS service interfaces. TRIGGER when: code uses voiceInput, voiceOutput, STTService, TTSService, or user asks about voice, speech-to-text, text-to-speech, or @pikku/ai-voice. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or Vercel AI SDK (use pikku-ai-vercel).

Pikku AI Voice (Speech I/O)

Agent Operating Procedure

Use this skill as an execution checklist, not reference material.

1. Discover before editing. Prefer OpenCode tools such as pikku-meta when available; otherwise run the relevant pikku meta ... --json command and inspect only the focused output you need.
2. Identify the source files that own the behavior. Do not start by reading generated output, .pikku, node_modules, vendored packages, or broad build artifacts.
3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
4. Validate with the narrowest relevant command first, then run pikku-verify or pikku all when functions, wirings, schemas, or generated clients may have changed.
5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.

@pikku/ai-voice provides speech-to-text and text-to-speech middleware hooks for Pikku AI agents.

Installation

yarn add @pikku/ai-voice

API Reference

Service Interfaces

interface STTService {
  transcribe(
    audio: Uint8Array,
    options?: { language?: string; format?: string }
  ): Promise<string>
}

interface TTSService {
  synthesize(
    text: string,
    options?: { voice?: string; format?: string }
  ): Promise<Uint8Array>
  synthesizeStream?(
    text: string,
    options?: { voice?: string; format?: string }
  ): AsyncIterable<Uint8Array>
}

Middleware Hooks

import { voiceInput, voiceOutput } from '@pikku/ai-voice'

voiceInput(config?: { language?: string }): PikkuAIMiddlewareHooks
voiceOutput(config?: { format?: string; voice?: string }): PikkuAIMiddlewareHooks

These return middleware hooks that can be attached to AI agent wirings to automatically transcribe audio input and synthesize audio output.

Usage Patterns

Voice-Enabled Agent

import { voiceInput, voiceOutput } from '@pikku/ai-voice'
import { wireAIAgent } from '@pikku/core/ai-agent'

wireAIAgent({
  name: 'voice-assistant',
  model: 'openai:gpt-4o',
  systemPrompt: 'You are a voice assistant.',
  middlewareHooks: [
    voiceInput({ language: 'en' }),
    voiceOutput({ voice: 'alloy', format: 'mp3' }),
  ],
  func: myAgentFunc,
})

Custom STT/TTS Services

Implement the STTService and TTSService interfaces with your provider (OpenAI Whisper, ElevenLabs, etc.) and register them as singleton services.