---
license: openrail
language:
- en
library_name: coreml
pipeline_tag: text-to-speech
tags:
- tts
- text-to-speech
- coreml
- mlprogram
- supertonic
- ios
- macos
- on-device
---

# Supertonic v1 Core ML

Core ML ML Program exports of **Supertonic v1 English** for iOS and macOS.

This repository hosts the heavy binary artifacts for the
[`eborges78/supertonic-1-coreml`](https://github.com/eborges78/supertonic-1-coreml)
GitHub project. The GitHub repo holds the code, conversion scripts, runtime
contract, Swift package, tests, and CI. This Hugging Face repo holds the
weights.

## What Is Included

Core ML packages (fixed-shape, ML Program, iOS 16+):

- `models/supertonic-v1/coreml/duration_predictor_mlprogram.mlpackage`
- `models/supertonic-v1/coreml/text_encoder_mlprogram.mlpackage`
- `models/supertonic-v1/coreml/vector_estimator_mlprogram.mlpackage`
- `models/supertonic-v1/coreml/vocoder_mlprogram.mlpackage`

Source ONNX models (for reconverting or inspection):

- `resources/supertonic-v1/onnx/duration_predictor.onnx`
- `resources/supertonic-v1/onnx/text_encoder.onnx`
- `resources/supertonic-v1/onnx/vector_estimator.onnx`
- `resources/supertonic-v1/onnx/vocoder.onnx`

The small runtime files (voice styles, embedding tables, `tts.json`,
`unicode_indexer.bin`) live in the GitHub repository.

## Export Configuration

```text
format=mlprogram
minimum_deployment_target=iOS16
max_text_len=300
max_seconds=20
latent_length=288
sample_rate=44100
```

## Quick Download

From Python, using the `huggingface_hub` CLI:

```sh
pip install -U huggingface_hub
huggingface-cli download eborges78/supertonic-v1-coreml \
    --local-dir ./supertonic-v1-coreml
```

Or use the helper script in the GitHub repo:

```sh
git clone https://github.com/eborges78/supertonic-1-coreml.git
cd supertonic-1-coreml
python scripts/download_models.py
```

## Runtime Contract

The four packages are fixed-shape and expect externalized text embeddings.
See [`docs/runtime-contract.md`](https://github.com/eborges78/supertonic-1-coreml/blob/main/docs/runtime-contract.md)
in the GitHub repo for the exact tensor shapes and the integration steps.

A minimal Swift integration reference is shipped as a SwiftPM library:
[`Sources/SupertonicV1CoreML/SupertonicV1CoreMLPipeline.swift`](https://github.com/eborges78/supertonic-1-coreml/blob/main/Sources/SupertonicV1CoreML/SupertonicV1CoreMLPipeline.swift).

## Provenance and License

- Upstream model: [`Supertone/supertonic`](https://huggingface.co/Supertone/supertonic) — OpenRAIL-M.
- Upstream project: [`supertone-inc/supertonic`](https://github.com/supertone-inc/supertonic).
- Core ML conversion reference: [`Nooder/supertonic-2-coreml`](https://github.com/Nooder/supertonic-2-coreml).

The weights in this repository are redistributed under the upstream OpenRAIL-M
license. Use-based restrictions from the upstream license are preserved. See
the [GitHub repo's `MODEL_LICENSE.md`](https://github.com/eborges78/supertonic-1-coreml/blob/main/MODEL_LICENSE.md)
for details.

The conversion scripts and sample integration code on GitHub are MIT-licensed.

## Acknowledgements

- Supertone for releasing Supertonic v1.
- The Supertonic 2 Core ML community work that informed parts of this
  conversion approach.