sayna: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Sayna is a real-time voice processing server built in Rust that provides unified Speech-to-Text (STT) and Text-to-Speech (TTS) services through WebSocket and REST APIs. It integrates with LiveKit for real-time audio streaming and includes advanced noise filtering using DeepFilterNet.

Development Commands

cargo run                    # Run development server
cargo run -- -c config.yaml  # Run with YAML config file
cargo test                   # Run all tests
cargo test test_name         # Run specific test
cargo build --release        # Build for release
cargo check                  # Check without building
cargo fmt                    # Format code
cargo clippy                 # Run linter
docker build -t saynaai/sayna .      # Build Docker image

Feature Flags

By default, no optional features are enabled.

• stt-vad (disabled by default): Silero-VAD voice activity detection with integrated ONNX-based turn detection. When enabled, VAD monitors audio for silence and triggers the turn detection model to confirm if the speaker's turn is complete.
• noise-filter (disabled by default): DeepFilterNet noise suppression. Disable to reduce dependencies.
• openapi (disabled by default): OpenAPI 3.1 specification generation using utoipa crate.

cargo check                                        # Default build, no optional features
cargo check --no-default-features                  # Explicitly disable optional features
cargo build --features stt-vad                     # Enable VAD with turn detection
cargo build --features stt-vad,openapi             # Enable specific features
cargo run --features openapi -- openapi -o docs/openapi.yaml  # Generate OpenAPI spec

High-Level Architecture

Development Rules

The codebase includes detailed development rules in .cursor/rules/:

• rust.mdc: Rust best practices, design patterns, performance, security, testing
• core.mdc: STT/TTS provider abstractions (BaseSTT, TTSProvider traits)
• axum.mdc: Axum framework patterns for WebSocket and REST APIs
• livekit.mdc: LiveKit integration patterns and WebSocket API details
• openapi.mdc: OpenAPI 3.1 documentation guidelines using utoipa