132 lines
5.1 KiB
Markdown
132 lines
5.1 KiB
Markdown
# Kira ✨
|
|
|
|
AI body double — a girly-pop focus companion with real-time voice conversation, lo-fi music, ADHD tools, and a customizable avatar.
|
|
|
|
Your wife's very own focus bestie who's always there when her real body double isn't available.
|
|
|
|
## Features
|
|
|
|
- **🎙️ Voice conversation** — Push-to-talk microphone → STT (Whisper) → LLM (DeepSeek) → TTS (OpenAI Nova voice)
|
|
- **💬 Text chat fallback** — Type when you don't want to speak
|
|
- **🎶 Lo-fi music** — Streaming from Lofi Girl YouTube channel
|
|
- **🍅 Timer** — Pomodoro, countdown, stopwatch modes
|
|
- **📝 Notes** — Quick task list / check-in notes
|
|
- **🎨 10 background scenes** — Cozy room, coffee shop, garden, rainy window, starry night, sakura, ocean, autumn, winter cabin, sunset
|
|
- **✨ Particle effects** — Rain, stars, cherry petals, snow per scene
|
|
- **👘 Wardrobe** — 5 outfits + 5 accessories (bow, glasses, flower crown, earrings, scarf)
|
|
- **🐱 Pet zone** — Two cats: Mochi (orange fluffy) and Luna (sleepy black)
|
|
- **🕐 Live clock** — Time + date
|
|
- **🌸 Animated avatar** — Blinking, speaking mouth, waving, outfit colors (Live2D-ready)
|
|
|
|
## Quick Start
|
|
|
|
### 1. Get API keys
|
|
|
|
| Service | What for | Where |
|
|
|---------|----------|-------|
|
|
| OpenAI | Whisper STT + TTS (Nova voice) | https://platform.openai.com/api-keys |
|
|
| DeepSeek | LLM brain | https://platform.deepseek.com/api_keys |
|
|
|
|
### 2. Configure
|
|
|
|
```bash
|
|
cd ~/Projects/ai-body-double
|
|
cp .env.example .env
|
|
# Edit .env with your API keys:
|
|
# OPENAI_API_KEY=sk-...
|
|
# HONCHO_API_KEY=...
|
|
```
|
|
|
|
### 3. Run
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Open **http://kira.hobokenchicken.com:3000** (or wherever you deploy it).
|
|
|
|
### 4. Add a Caddy entry (homelab)
|
|
|
|
```
|
|
kira.hobokenchicken.com {
|
|
reverse_proxy 172.20.0.X:3000
|
|
}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser (React + Live2D + WhiteNoise + Notes) ──WebSocket──▶ Backend (FastAPI)
|
|
│ │
|
|
├─ Mic (MediaRecorder full webm on stop) ────────────────────▶ ├─ gpt-4o-transcribe (REST STT, emits delta)
|
|
│ ├─ gpt-5.4-nano + Honcho memory context
|
|
│ ◀── Incremental Opus chunks (play on arrival) ─────────────── ├─ OpenAI TTS streaming (sage)
|
|
│ │
|
|
├─ YouTube lofi + Web Audio noise (independent) │
|
|
├─ Timer / Notes / Pets / Wardrobe / Scenes │
|
|
└─ Live2D (or fallback) avatar │
|
|
```
|
|
|
|
Note: Realtime WebSocket STT (gpt-realtime-whisper) was attempted for true streaming but blocked by model access — current REST path is stable and cheap.
|
|
|
|
## Live2D Model Setup
|
|
|
|
Kira currently uses a CSS/SVG animated placeholder avatar. To add a Live2D model:
|
|
|
|
1. Commission or obtain a `.model3.json` (Cubism 4.x format) model
|
|
2. Place the model directory in `frontend/public/live2d/models/`
|
|
3. Rename the model entry point to `kira.model3.json`
|
|
4. The WebGL renderer will auto-detect and switch
|
|
|
|
Required model files:
|
|
- `kira.model3.json` — model definition
|
|
- `kira.moc3` — mesh/deformer data
|
|
- `kira.cdi3.json` — display info (optional)
|
|
- `textures/` — PNG texture files
|
|
- `motions/` — animation files (optional)
|
|
- `expressions/` — face expression files (optional)
|
|
|
|
Recommended creators for custom Live2D models: search VGen, VTube Studio model artists, or Fiverr.
|
|
|
|
## Color Palette
|
|
|
|
| Token | Hex | Usage |
|
|
|-------|-----|-------|
|
|
| Kira Pink | `#FFB6C1` | Primary accent |
|
|
| Kira Lavender | `#D8B4FE` | Secondary accent |
|
|
| Kira Mint | `#A7F3D0` | Success/status |
|
|
| Background | `#FFF5F5` | Card/comfy bg |
|
|
| Text Plum | `#4A1942` | Body text |
|
|
| Text Violet | `#7C3AED` | Soft text |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
ai-body-double/
|
|
├── docker-compose.yml
|
|
├── .env
|
|
├── backend/ # FastAPI + WebSocket
|
|
│ ├── main.py # WS handler (STT→LLM→TTS pipeline)
|
|
│ ├── services/
|
|
│ │ ├── stt.py # OpenAI Whisper
|
|
│ │ ├── llm.py # DeepSeek
|
|
│ │ └── tts.py # OpenAI TTS
|
|
│ └── config.py # Env config
|
|
├── frontend/ # React + Vite + TailwindCSS
|
|
│ ├── src/
|
|
│ │ ├── App.tsx # Main layout
|
|
│ │ ├── components/
|
|
│ │ │ ├── AnimatedAvatar.tsx # SVG animated character
|
|
│ │ │ ├── KiraAvatar.tsx # Live2D loader + fallback
|
|
│ │ │ ├── ChatBubble.tsx # Conversation display
|
|
│ │ │ ├── Timer.tsx # Pomodoro/stopwatch
|
|
│ │ │ ├── MusicPlayer.tsx # Lofi Girl embed
|
|
│ │ │ ├── PetZone.tsx # Two CSS cats
|
|
│ │ │ ├── Wardrobe.tsx # Outfit + accessories
|
|
│ │ │ └── Particles.tsx # Rain/stars/petals/snow
|
|
│ │ └── hooks/
|
|
│ │ └── useConversation.ts # WS + audio management
|
|
│ └── public/live2d/ # Cubism SDK + model slot
|
|
└── README.md
|
|
```
|