Nara'Korrin

Nara'Korrin is a desktop companion: a voiced, animated 3D quarian that lives in a transparent Tauri window. Talk to her by microphone or text; she responds in English or Latin American Spanish, remembers useful details between sessions, and speaks through a configurable helmet-style voice effect.

Features

• Text chat and push-to-talk microphone input, with optional voice activity detection.
• OpenAI speech-to-text and text-to-speech, with selectable STT and TTS models.
• DeepSeek-powered conversational responses with the Nara'Korrin persona.
• Three.js GLB avatar with idle, talking, waving, and dance animations synchronized to playback.
• SQLite-backed conversation sessions, recall, and a persistent user profile.
• Adjustable quarian helmet audio effect: dry/wet mix, pitch, filters, and saturation.
• Transparent, frameless, always-on-top Tauri desktop window with drag support.

Stack

• TypeScript, Vite, and Three.js
• Tauri 2 and Rust
• SQLite through rusqlite
• OpenAI APIs for transcription and speech
• DeepSeek API for chat and memory extraction
• Web Audio API and the in-repository quarian-dsp Rust crate for audio processing

Prerequisites

• Node.js and pnpm
• Rust toolchain 1.96 or later
• The platform dependencies required by Tauri 2
• An OpenAI API key for transcription and speech
• A DeepSeek API key for chat and memory features

The desktop app is configured and packaged for Windows. Development is also supported wherever the Tauri prerequisites are available.

Getting started

Install dependencies:

pnpm install

Create a local .env file for development:

VITE_OPENAI_API_KEY=your_openai_api_key
VITE_DEEPSEEK_API_KEY=your_deepseek_api_key

Start the desktop app:

pnpm tauri:dev

VITE_* variables are a development fallback. In the desktop application, credentials are retrieved from the operating system keyring under the com.nara.desktop service. Do not commit API keys or put them in client-side storage.

Scripts

Command	Purpose
pnpm dev	Run the Vite frontend development server.
pnpm build	Type-check and build the frontend.
pnpm tauri:dev	Run the Tauri desktop app in development.
pnpm tauri:build	Create a desktop application bundle.
pnpm test	Run the Vitest suite.
pnpm bounds:generate	Generate 3D model bounds metadata.

Using Nara

• Switch between chat and microphone modes from the controls. Enable VAD to begin recording automatically when speech is detected.
• Drag the avatar area to reposition the transparent window.
• Press e or Escape to show or hide the text input.
• Press d to toggle the debug panel and v to open the helmet FX controls.
• Send a short greeting to trigger a wave, or ask Nara to dance.

Chat commands

Command	Action
/help	Show the command reference.
/history	Browse saved conversation sessions.
/new	Start a new session.
/debug	Toggle the debug panel.
/session	Show the current session details.
/recall	Load the most recent saved session.
/clearprofile	Remove Nara's saved profile details about you.
/exit	Close the application.

Architecture

Microphone or text
  -> OpenAI transcription (voice input)
  -> memory retrieval and context assembly
  -> DeepSeek chat response
  -> OpenAI TTS
  -> quarian DSP and Web Audio playback
  -> synchronized 3D animation
  -> SQLite session and profile persistence

The frontend in src/ owns the UI, audio capture, voice playback, chat orchestration, memory context, and Three.js scene. The Tauri shell in shell/ owns the transparent window, OS keyring access, SQLite commands, and the Rust DSP bridge. Avatar assets live in src/assets/models/; generated model-bound metadata is served from build/bounds/.

Project layout

src/
  3d/          Avatar loading, animation, and bounds
  audio/       Playback and helmet FX parameters
  components/  Application UI and chat controls
  memory/      Sessions, profile, context, and LLM integration
  modules/     Audio capture, VAD, STT, TTS, and keyring access
shell/         Tauri application and Rust commands
quarian-dsp/   Rust audio processing crate

Privacy and data

Conversation sessions and profile facts are stored locally in SQLite by the Tauri backend. Audio, messages, and relevant memory context are sent to OpenAI and DeepSeek to provide transcription, speech, and chat responses. API credentials are read from the OS keyring when available; environment variables are intended only for local development.