Skip to main content

​
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.
Search the codebase for TODO comments to find features yet to be built.

​
Getting Started

​
Fork and Clone

1

Fork the repository

Fork WhisperKit to your personal GitHub account.
2

Clone your fork

git clone https://github.com/[your-username]/whisperkit.git
cd whisperkit
3

Create a feature branch

git checkout -b my-feature-branch

​
Development Environment Setup

​
Install Dependencies

Use the provided Makefile to set up your environment: 
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: 
make download-model MODEL=tiny
Ensure git-lfs is installed before downloading models.

​
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

# Build the project
make build

# Run tests
make test

​
Testing Changes

Run the test suite:
make test
Or in Xcode: ⌘U to run all tests
Run performance benchmarks:
make benchmark-devices DEBUG=true
See Benchmarks for details.
Test with the provided example applications:
  • WhisperAX: Main demo app with full features
  • TTSKitExample: Text-to-speech examples
  • ServeCLIClient: Local server client examples

​
Code Guidelines

​
Coding Style

  • Swift Style: Follow Swift 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: 
Add support for custom model repositories

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

​
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

​
Create a Pull Request

1

Commit your changes

git add .
git commit -m "Add a new feature"
2

Push to your fork

git push origin my-feature-branch
3

Open a Pull Request

  1. Go to the WhisperKit repository
  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
4

Respond to feedback

Be responsive to maintainer feedback and make requested changes promptly.

​
Pull Request Template

## 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

Bug Fixes

Found a bug? Submit a fix with:
  • Clear bug description
  • Steps to reproduce
  • Test case demonstrating the fix

New Features

Adding functionality? Include:
  • Feature description and use case
  • Tests and documentation
  • Examples of usage

Documentation

Improving docs:
  • Fix typos and errors
  • Add examples and clarifications
  • Improve organization

Performance

Performance improvements:
  • Benchmark before and after
  • Explain the optimization
  • Ensure functionality preserved

​
Working with Models

​
Creating Custom Models

WhisperKit supports fine-tuned models via whisperkittools:
  1. Fine-tune Whisper using the tools repo
  2. Convert to CoreML format
  3. Upload to HuggingFace
  4. Load in WhisperKit:
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
See Benchmarks for detailed instructions.

​
Roadmap & Feature Requests

​
Public Roadmap

Check our roadmap for planned features:

​
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

Discord Community

Join our Discord for questions and discussions

GitHub Issues

Report bugs or request features

Documentation

Browse the documentation

Email Support

Contact the team directly

​
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
Thank you for making WhisperKit better for everyone!

​
Next Steps

View Benchmarks

Learn about running benchmarks

FAQ

Common questions answered

Model Catalog

Explore available models

API Reference

Detailed API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us