Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
201 lines (144 loc) · 5.82 KB

CONTRIBUTING.md

File metadata and controls

201 lines (144 loc) · 5.82 KB

Contributing to OmniVoice Studio

Thanks for your interest in improving OmniVoice Studio! This guide covers everything you need to get started.

Quick Links
💬 Chat Discord
🐛 Bugs GitHub Issues
🏷️ Good First Issues Filtered list
📋 Roadmap README → Roadmap

Development Setup

Prerequisites

  • Git
  • Bun (frontend package manager)
  • uv (Python environment manager)
  • ffmpeg (audio/video processing)
  • Python 3.10+ (managed automatically by uv)

Clone & Run

git clone https://github.com/debpalash/OmniVoice-Studio.git
cd OmniVoice-Studio
bun install
bun run dev

This starts both services:

Service URL What it does
Backend localhost:3900 FastAPI server — TTS, ASR, diarization, dubbing pipeline
Frontend localhost:3901 React + Vite UI

Desktop App (Tauri)

bun run desktop

Requires Rust and platform-specific Tauri dependencies — see the Tauri prerequisites.

Project Structure

OmniVoice-Studio/
├── backend/                 # Python FastAPI server
│   ├── api/                 # Route handlers
│   ├── core/                # Config, prefs, constants
│   └── services/            # TTS engines, ASR, dubbing, audio DSP
│       └── tts_backend.py   # ← Multi-engine TTS registry
├── frontend/                # React + Vite
│   ├── src/
│   │   ├── components/      # UI components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── stores/          # Zustand state slices
│   │   └── utils/           # Shared utilities
│   └── src-tauri/           # Rust/Tauri desktop shell
├── deploy/                  # Docker, CI configs
├── docs/                    # Screenshots, MCP config
└── scripts/                 # Build & release scripts

How to Contribute

Bug Reports

Open an issue with:

  1. What happened vs what you expected
  2. Steps to reproduce
  3. OS, GPU, and Python version (find in Settings → Logs)
  4. Error logs (Settings → Logs → copy relevant lines)

Pull Requests

  1. Fork the repo and create a branch from main
  2. Keep PRs focused — one feature or fix per PR
  3. Run tests before pushing: 
    # Backend tests
uv run pytest backend/ -x -q

# Frontend build check
cd frontend && npx vite build --mode development
  4. Write a clear PR title — it becomes the squash-merge commit message
  5. Don't include local machine stats, file paths, or private system info in PR descriptions

Adding a New TTS Engine

OmniVoice's TTS backend is a plugin registry. Adding a new engine takes ~50 lines:

  1. Open backend/services/tts_backend.py
  2. Create a class extending TTSBackend:
class MyEngineBackend(TTSBackend):
    id = "my-engine"
    display_name = "My Engine (description)"

    @classmethod
    def is_available(cls) -> tuple[bool, str]:
        try:
            import my_engine  # noqa: F401
            return True, "ready"
        except ImportError:
            return False, "my_engine not installed. pip install my-engine"

    @property
    def sample_rate(self) -> int:
        return 24000

    @property
    def supported_languages(self) -> list[str]:
        return ["en", "zh"]

    def generate(self, text: str, **kw) -> torch.Tensor:
        # ... call your engine, return [1, num_samples] tensor
  1. Register it in _REGISTRY at the bottom of the file
  2. That's it — it auto-appears in Settings → TTS Engine

Code Style

Python (Backend)

  • Formatter: We don't enforce one globally — match the style of the file you're editing
  • Logging: Use logger.warning() / logger.error(), never bare print()
  • Exceptions: Avoid bare except: pass — catch specific exceptions
  • Type hints: Use them for public API functions and class methods

JavaScript/React (Frontend)

  • Components: Functional components with hooks
  • State: Zustand stores in src/stores/, organized by slice
  • CSS: Vanilla CSS in component-level files — no Tailwind
  • Naming: PascalCase for components, camelCase for hooks and utils

Rust (Tauri)

  • Format: cargo fmt before committing
  • Modules: One concern per file (bootstrap.rs, tools.rs, config.rs, commands.rs)

Commit Messages

Write clear, concise messages. The PR title becomes the squash-merge commit.

good: fix: prevent CUDA OOM during concurrent transcription + TTS
good: feat: add CosyVoice 3 TTS backend adapter
good: docs: add platform compatibility matrix to README

bad:  fixed stuff
bad:  update
bad:  WIP

Testing

# Run all backend tests
uv run pytest backend/ -x -q

# Run a specific test file
uv run pytest backend/tests/test_api.py -x -q

# Frontend build validation (no test suite yet)
cd frontend && npx vite build --mode development

# Tauri shell check (requires Rust)
cd frontend/src-tauri && cargo check

Need Help?

Thank you for contributing! 🎙️