stephan/audio-engine-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
audio-engine-hub/AGENTS.md
stephan 91887ae296 feat: Add XTTS v2 support, refactor Docker/GPU infra, and improve Piper engine 
- 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
2025-12-13 11:37:58 +01:00

2.9 KiB
Raw Permalink Blame History

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).