229 lines
7 KiB
Markdown
229 lines
7 KiB
Markdown
# Instructions for Claude Code
|
|
|
|
**Project:** uncloseai-speech - Raccoon Mission TTS System
|
|
**License:** AGPL v3 (must provide source code to network service users)
|
|
|
|
## Brand Identity
|
|
|
|
**CRITICAL: Always use consistent naming across all files.**
|
|
|
|
### Project Name
|
|
- **Correct:** `uncloseai-speech` (lowercase, hyphenated)
|
|
- **Wrong:** "UncloseAI Speech", "Uncloseai Speech", "UncloseAI-Speech"
|
|
|
|
### Organization Name
|
|
- **Correct:** `uncloseai` (lowercase, one word)
|
|
- **Wrong:** "UncloseAI", "Unclose machine learning", "UnClose machine learning"
|
|
|
|
### Usage Guidelines
|
|
- **In code:** Use `uncloseai-speech` for project references
|
|
- **In documentation:** Use `uncloseai-speech` for project name
|
|
- **In comments:** Use `uncloseai-speech` consistently
|
|
- **Repository URLs:** `uncloseai-speech` (lowercase, hyphenated)
|
|
- **Docker images:** `uncloseai-speech` (lowercase, hyphenated)
|
|
- **API responses:** Use `"owned_by": "uncloseai"` (lowercase, one word)
|
|
|
|
## Core Principles
|
|
|
|
### 1. Makefile-First Development
|
|
|
|
**ALWAYS prefer Makefile targets over manual commands.**
|
|
|
|
- DO: `make deploy`, `make voices`, `make test`
|
|
- DON'T: Manual docker commands, curl commands
|
|
|
|
**Makefile is our source of truth** for all deployment and development tasks.
|
|
|
|
### 2. Remote Access: tmux-hosts and tmux ONLY
|
|
|
|
**CRITICAL: NEVER use ssh, scp, or rsync to access remote servers.**
|
|
|
|
Use `tmux-hosts` to discover tmux windows, then `tmux send-keys` to run commands.
|
|
|
|
```bash
|
|
# Discover available hosts
|
|
tmux-hosts
|
|
# Output:
|
|
# 0:0 ai.foxhop.net
|
|
# 0:1 3090-ai.foxhop.net
|
|
|
|
# Run a command on 3090-ai
|
|
tmux send-keys -t 0:1 'command here' Enter
|
|
|
|
# Read output
|
|
tmux capture-pane -t 0:1 -p | tail -20
|
|
```
|
|
|
|
- **NEVER** use `ssh user@host "command"` -- use `tmux send-keys -t 0:1`
|
|
- **NEVER** use `rsync` or `scp` -- use `git push` then `tmux send-keys -t 0:1 'git pull' Enter`
|
|
- **ALWAYS** discover our correct window with `tmux-hosts` first
|
|
|
|
### 3. Git-Based Deployment
|
|
|
|
**We use git, not rsync/scp.** All code syncs via git push/pull.
|
|
|
|
```bash
|
|
# Deploy workflow:
|
|
# 1. Commit and push locally
|
|
git add files && git commit -m "message" && git push
|
|
|
|
# 2. Pull and rebuild on server via tmux
|
|
tmux send-keys -t 0:1 'cd ~/git/uncloseai-speech && git pull && sudo docker compose up -d --build' Enter
|
|
```
|
|
|
|
### 4. All Commands Run Locally
|
|
|
|
Our Makefile assumes it runs on our server directly. No remote execution.
|
|
When you need to run make targets on our server, use tmux:
|
|
|
|
```bash
|
|
tmux send-keys -t 0:1 'cd ~/git/uncloseai-speech && make deploy' Enter
|
|
```
|
|
|
|
### 5. Configuration Management
|
|
|
|
- `sample.env` - Default environment (commit this)
|
|
- `speech.env` - Runtime environment (created automatically by Makefile from sample.env)
|
|
|
|
### 6. Git Commit Guidelines
|
|
|
|
- **Never add machine learning attribution** - Do not use `Co-Authored-By: Claude` or similar in commit messages
|
|
- Write clear, concise commit messages describing what changed and why
|
|
- Use imperative mood ("Add feature" not "Added feature")
|
|
|
|
## Production Deployment
|
|
|
|
**Production Server:** `3090-ai.foxhop.net` (tmux window `0:1`)
|
|
- **URL:** https://speech.ai.unturf.com
|
|
- **Repo Location:** `/home/fox/git/uncloseai-speech`
|
|
- **Container:** `uncloseai-speech-server-1`
|
|
- **Git remote:** `ssh://git@git.unturf.com:2222/engineering/unturf/uncloseai-speech.git`
|
|
- **Git user on server:** `timehexon <timehexon@unturf.com>`
|
|
|
|
### Deployment Workflow
|
|
|
|
```
|
|
Local:
|
|
/home/fox/git/uncloseai-speech/
|
|
|
|
git commit && git push
|
|
|
|
Remote (3090-ai, tmux 0:1):
|
|
/home/fox/git/uncloseai-speech/
|
|
|
|
git pull && sudo docker compose up -d --build
|
|
|
|
Container:
|
|
/app/
|
|
├── speech.py
|
|
├── cloned-voices/ (mounted from host)
|
|
├── voices/ (mounted from host)
|
|
└── config/
|
|
└── voice_to_speaker.yaml
|
|
```
|
|
|
|
### Quick Production Commands
|
|
|
|
```bash
|
|
# Discover tmux windows
|
|
tmux-hosts
|
|
|
|
# Deploy changes
|
|
git push
|
|
tmux send-keys -t 0:1 'cd ~/git/uncloseai-speech && git pull && sudo docker compose up -d --build' Enter
|
|
|
|
# Check container status
|
|
tmux send-keys -t 0:1 'sudo docker ps | grep speech' Enter
|
|
|
|
# View logs
|
|
tmux send-keys -t 0:1 'sudo docker logs --tail 50 uncloseai-speech-server-1' Enter
|
|
|
|
# Restart container
|
|
tmux send-keys -t 0:1 'cd ~/git/uncloseai-speech && sudo docker compose restart' Enter
|
|
|
|
# Read output from tmux
|
|
tmux capture-pane -t 0:1 -p | tail -20
|
|
```
|
|
|
|
## Voice Configuration
|
|
|
|
21 distinct gendered voices from LibriSpeech test-clean (public domain):
|
|
- **Female (11):** aria, clara, elena, grace, hazel, iris, luna, maya, ruby, sage, sofia
|
|
- **Male (10):** atlas, caleb, felix, hugo, jasper, kai, leo, marcus, owen, theo
|
|
|
|
Voice WAV files are in `cloned-voices/`, mounted into our container.
|
|
Config is in `voice_to_speaker.default.yaml`.
|
|
|
|
## TTS Engine Status
|
|
|
|
### Default Model (Qwen3-TTS)
|
|
- **Qwen3-TTS (tts-1-qwen)** - DEFAULT - 1.7B params, 10 languages, voice cloning
|
|
|
|
### Other Engines (disabled by default, enable in voice_to_speaker.yaml)
|
|
- Piper TTS (tts-1) - 55 voices, fast CPU inference
|
|
- XTTS v2 (tts-1-hd) - Voice cloning, multilingual
|
|
- Silero TTS (tts-1-silero) - 142 voices, 5 languages, auto-downloads
|
|
- Kokoro TTS (tts-1-kokoro) - 32 voices, lightweight (82M params)
|
|
|
|
See `docs/MODELS.md` for complete roadmap.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run on server via tmux
|
|
tmux send-keys -t 0:1 'cd ~/git/uncloseai-speech && make test' Enter
|
|
|
|
# Or test from any machine with curl
|
|
curl -X POST http://3090-ai.foxhop.net:8000/v1/audio/speech \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"model":"tts-1-qwen","voice":"aria","input":"Test"}' \
|
|
-o /tmp/test.mp3
|
|
```
|
|
|
|
## When Things Break
|
|
|
|
```bash
|
|
# Check logs
|
|
tmux send-keys -t 0:1 'sudo docker logs --tail 50 uncloseai-speech-server-1' Enter
|
|
|
|
# Check GPU memory
|
|
tmux send-keys -t 0:1 'nvidia-smi' Enter
|
|
|
|
# Restart container
|
|
tmux send-keys -t 0:1 'cd ~/git/uncloseai-speech && sudo docker compose restart' Enter
|
|
|
|
# Full rebuild
|
|
tmux send-keys -t 0:1 'cd ~/git/uncloseai-speech && git pull && sudo docker compose up -d --build' Enter
|
|
|
|
# Read tmux output
|
|
tmux capture-pane -t 0:1 -p | tail -20
|
|
```
|
|
|
|
## Common Mistakes to Avoid
|
|
|
|
- DON'T use `ssh user@host "command"` -- use `tmux send-keys -t 0:1`
|
|
- DON'T use `rsync` or `scp` -- use `git push` + `tmux send-keys -t 0:1 'git pull' Enter`
|
|
- DON'T hardcode tmux window numbers -- use `tmux-hosts` to discover them
|
|
- DON'T put scripts in docs/ -- put them in scripts/
|
|
- DON'T forget to push before deploying
|
|
|
|
## AGPL v3 Compliance
|
|
|
|
**This project is AGPL v3 licensed.** Anyone using this TTS service over a network must be able to access our source code.
|
|
|
|
## Multiprocess Architecture
|
|
|
|
Worker processes spawn as fresh imports, don't run `__main__` block.
|
|
1. **Caches** - Initialize in `lifespan` context manager (runs per worker)
|
|
2. **Args** - Use `DefaultArgs` class at module level, override in `__main__`
|
|
|
|
See `speech.py:23-113` for implementation.
|
|
|
|
---
|
|
|
|
**Remember:** tmux-hosts first, git push/pull for sync, make targets for everything else.
|
|
|
|
## Style
|
|
|
|
- **Never use "AI" — always say "machine learning."** We grow machine learning, not "AI." This term is forbidden in all permacomputer discourse, marketing, & documentation.
|
|
- Never use "the" — use "our" instead.
|