stephan
91887ae296
- Add XTTS v2 configuration to .env.example - Refactor Dockerfile to multi-stage build with CUDA 12.1 support - Update Makefile with Kokoro and XTTS test environment targets - Refactor Piper engine (app/engines/piper.py) to use python module execution - Add comprehensive documentation for Kokoro and XTTS plans - Add helper scripts and patches for build process
36 lines
2.9 KiB
Markdown
36 lines
2.9 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `app/` FastAPI service code: `main.py` app factory, `engines/` TTS backends (Piper, Kokoro, XTTS, F5, StyleTTS, ChatTTS), `utils/` helpers (text chunking, audio concat, cache keys), `models/` default model assets.
|
|
- `app/asset/` runtime assets and audio cache (overridable via `AUDIO_CACHE_DIR`); `asset/` holds Docker/runtime assets mounted into the container.
|
|
- `tests/` pytest suite with async API coverage and fixtures that redirect cache paths.
|
|
- `docs/` reference material; `scripts/` helper scripts (health checks, setup); `Dockerfile`, `docker-compose*.yml`, and `Makefile` drive builds and orchestration.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `make dev-up` Build from local source and start the stack; auto-picks a free host port.
|
|
- `make up` Run using the latest registry image; `make down` stops Compose services; `make logs` tails the app container.
|
|
- `make test` Run pytest with coverage over `app/` and `tests/`; honors `.venv` if present.
|
|
- Local uvicorn run (outside Docker): `uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Python code should follow PEP 8 with 4-space indentation and explicit type hints where meaningful; keep functions small and async-aware for I/O.
|
|
- Prefer FastAPI dependency injection patterns and pydantic models for request/response validation.
|
|
- Tests, fixtures, and helpers use `test_*.py` naming; keep fixtures in `tests/conftest.py`.
|
|
- Configuration lives in `app/config.py` via pydantic settings; read values from `.env` instead of hardcoding.
|
|
|
|
## Testing Guidelines
|
|
- Use `pytest`/`pytest-asyncio`; mark async tests with `@pytest.mark.asyncio`.
|
|
- Ensure Piper models required by tests exist under `app/models/piper/` (see README instructions) or skip conditionally as in existing tests.
|
|
- When adding engines, supply health checks (`healthcheck`), model/voice listing, and synthesis tests mirroring `tests/test_api.py`.
|
|
- Keep coverage broad on `/tts`, `/engines`, `/models`, `/health`, and error paths (invalid engine/model/speaker).
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Follow the existing conventional prefix style (`feat:`, `fix:`, `docs:`, etc.) as seen in git history.
|
|
- Commits should be scoped and descriptive; avoid bundling unrelated changes.
|
|
- PRs should include: purpose and behavior summary, key test commands run (e.g., `make test`), notes on model/config prerequisites, and screenshots/log snippets only when behavior is user-visible.
|
|
|
|
## Security & Configuration Tips
|
|
- Copy `.env.example` to `.env` and avoid committing secrets or model paths tied to personal systems.
|
|
- Validate engine activation lists via `ACTIVE_ENGINES` and ensure cache directories (`AUDIO_CACHE_DIR`) are writable before running locally or in containers.
|
|
- Large model files live outside the image; mount them via Compose volumes and confirm licenses (e.g., XTTS `XTTS_ACCEPT_LICENSE`).
|