> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argmaxinc/WhisperKit/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Guidelines for contributing to WhisperKit

## Overview

We welcome and encourage contributions to WhisperKit! Whether you're fixing bugs, improving documentation, or adding new features from the roadmap, your help is appreciated.

<Info>
  Search the codebase for `TODO` comments to find features yet to be built.
</Info>

## Getting Started

### Fork and Clone

<Steps>
  <Step title="Fork the repository">
    [Fork WhisperKit](https://github.com/argmaxinc/WhisperKit/fork) to your personal GitHub account.
  </Step>

  <Step title="Clone your fork">
    ```bash theme={null}
    git clone https://github.com/[your-username]/whisperkit.git
    cd whisperkit
    ```
  </Step>

  <Step title="Create a feature branch">
    ```bash theme={null}
    git checkout -b my-feature-branch
    ```
  </Step>
</Steps>

## Development Environment Setup

### Install Dependencies

Use the provided `Makefile` to set up your environment:

```bash theme={null}
make setup
```

This installs:

* Python dependencies for model tools
* Fastlane for testing automation
* Git LFS for large file support
* Pre-commit hooks

### Download Models

Download models for local testing:

<CodeGroup>
  ```bash Single Model theme={null}
  make download-model MODEL=tiny
  ```

  ```bash All Models theme={null}
  make download-models
  ```
</CodeGroup>

<Note>
  Ensure [git-lfs](https://git-lfs.com) is installed before downloading models.
</Note>

## Making Changes

### Development Workflow

1. **Implement your changes** - Follow the existing coding style and patterns
2. **Update documentation** - Add or update docs for new features
3. **Add tests** - Include unit tests for bug fixes and new features
4. **Test your changes** - Build and test before committing

### Building WhisperKit

<Tabs>
  <Tab title="Command Line">
    ```bash theme={null}
    # Build the project
    make build

    # Run tests
    make test
    ```
  </Tab>

  <Tab title="Xcode">
    Open the example app in Xcode:

    ```bash theme={null}
    xed Examples/WhisperAX/WhisperAX.xcodeproj
    ```

    Run the app to test various use cases.
  </Tab>
</Tabs>

### Testing Changes

<AccordionGroup>
  <Accordion title="Unit Tests">
    Run the test suite:

    ```bash theme={null}
    make test
    ```

    Or in Xcode: `⌘U` to run all tests
  </Accordion>

  <Accordion title="Benchmark Tests">
    Run performance benchmarks:

    ```bash theme={null}
    make benchmark-devices DEBUG=true
    ```

    See [Benchmarks](/resources/benchmarks) for details.
  </Accordion>

  <Accordion title="Example Apps">
    Test with the provided example applications:

    * **WhisperAX**: Main demo app with full features
    * **TTSKitExample**: Text-to-speech examples
    * **ServeCLIClient**: Local server client examples
  </Accordion>
</AccordionGroup>

## Code Guidelines

### Coding Style

* **Swift Style**: Follow [Swift API Design Guidelines](https://swift.org/documentation/api-design-guidelines/)
* **Naming**: Use clear, descriptive names for functions and variables
* **Comments**: Add comments for complex logic and public APIs
* **Documentation**: Use Swift DocC-style documentation comments

### Code Organization

```
Sources/
  WhisperKit/
    - Core transcription functionality
  TTSKit/
    - Text-to-speech functionality
Tests/
  WhisperKitTests/
    - Unit tests
Examples/
  - Example applications
```

### Commit Messages

Write clear, meaningful commit messages:

<CodeGroup>
  ```text Good theme={null}
  Add support for custom model repositories

  - Allow users to specify custom HuggingFace repos
  - Update model loading logic
  - Add tests for custom repo loading
  ```

  ```text Bad theme={null}
  Update code
  ```
</CodeGroup>

### Documentation Requirements

When adding new features:

* ✅ Add inline code documentation
* ✅ Update relevant markdown documentation
* ✅ Include usage examples
* ✅ Update API references if applicable

## Submitting Changes

### Before Submitting

<Checklist>
  * [ ] Code builds without errors or warnings
  * [ ] All tests pass
  * [ ] New tests added for new functionality
  * [ ] Documentation updated
  * [ ] Code follows project style guidelines
  * [ ] Commit messages are clear and descriptive
</Checklist>

### Create a Pull Request

<Steps>
  <Step title="Commit your changes">
    ```bash theme={null}
    git add .
    git commit -m "Add a new feature"
    ```
  </Step>

  <Step title="Push to your fork">
    ```bash theme={null}
    git push origin my-feature-branch
    ```
  </Step>

  <Step title="Open a Pull Request">
    1. Go to the [WhisperKit repository](https://github.com/argmaxinc/WhisperKit)
    2. Click "New Pull Request"
    3. Select your fork and branch
    4. Fill out the PR template with:
       * Clear title
       * Description of changes
       * Related issue numbers
       * Testing performed
  </Step>

  <Step title="Respond to feedback">
    Be responsive to maintainer feedback and make requested changes promptly.
  </Step>
</Steps>

### Pull Request Template

```markdown theme={null}
## Description
[Brief description of the changes]

## Related Issue
Closes #[issue number]

## Changes Made
- [List of changes]

## Testing
- [How you tested the changes]

## Checklist
- [ ] Code builds without errors
- [ ] Tests pass
- [ ] Documentation updated
```

## Types of Contributions

<CardGroup cols={2}>
  <Card title="Bug Fixes" icon="bug">
    Found a bug? Submit a fix with:

    * Clear bug description
    * Steps to reproduce
    * Test case demonstrating the fix
  </Card>

  <Card title="New Features" icon="sparkles">
    Adding functionality? Include:

    * Feature description and use case
    * Tests and documentation
    * Examples of usage
  </Card>

  <Card title="Documentation" icon="book">
    Improving docs:

    * Fix typos and errors
    * Add examples and clarifications
    * Improve organization
  </Card>

  <Card title="Performance" icon="gauge">
    Performance improvements:

    * Benchmark before and after
    * Explain the optimization
    * Ensure functionality preserved
  </Card>
</CardGroup>

## Working with Models

### Creating Custom Models

WhisperKit supports fine-tuned models via [whisperkittools](https://github.com/argmaxinc/whisperkittools):

1. Fine-tune Whisper using the tools repo
2. Convert to CoreML format
3. Upload to HuggingFace
4. Load in WhisperKit:

```swift theme={null}
let config = WhisperKitConfig(
    model: "large-v3",
    modelRepo: "username/your-model-repo"
)
let pipe = try await WhisperKit(config)
```

### Contributing Benchmark Results

Help expand device coverage:

1. Run benchmarks on your devices
2. Results saved to `fastlane/upload_folder/benchmark_data`
3. Submit results to [whisperkit-evals-dataset](https://huggingface.co/datasets/argmaxinc/whisperkit-evals-dataset)

See [Benchmarks](/resources/benchmarks) for detailed instructions.

## Roadmap & Feature Requests

### Public Roadmap

Check our roadmap for planned features:

* View [open issues](https://github.com/argmaxinc/WhisperKit/issues)
* Search code for `TODO` comments
* Join [Discord](https://discord.gg/G5F5GZGecC) discussions

### Requesting Features

To request a new feature:

1. Check if it already exists in issues
2. Create a new issue with:
   * Clear description
   * Use case and motivation
   * Proposed implementation (if applicable)
3. Label as `enhancement`

## Getting Help

<CardGroup cols={2}>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/G5F5GZGecC">
    Join our Discord for questions and discussions
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/argmaxinc/WhisperKit/issues">
    Report bugs or request features
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Browse the documentation
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:info@argmaxinc.com">
    Contact the team directly
  </Card>
</CardGroup>

## Recognition

After your pull request is merged:

* Your contribution will be listed in the project
* You'll be added to the contributors list
* Major contributions may be highlighted in release notes

<Note>
  Thank you for making WhisperKit better for everyone!
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="View Benchmarks" icon="chart-line" href="/resources/benchmarks">
    Learn about running benchmarks
  </Card>

  <Card title="FAQ" icon="question" href="/resources/faq">
    Common questions answered
  </Card>

  <Card title="Model Catalog" icon="book" href="/resources/model-catalog">
    Explore available models
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Detailed API documentation
  </Card>
</CardGroup>