If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/supertone-inc/supertonic shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3d ago
• 4 active contributors
• MIT licensed
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 81% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live supertone-inc/supertonic repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/supertone-inc/supertonic.

What it runs against: a local clone of supertone-inc/supertonic — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in supertone-inc/supertonic | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of supertone-inc/supertonic. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/supertone-inc/supertonic.git
#   cd supertonic
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of supertone-inc/supertonic and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "supertone-inc/supertonic(\\.git)?\\b" \\
  && ok "origin remote is supertone-inc/supertonic" \\
  || miss "origin remote is not supertone-inc/supertonic (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "py/example_onnx.py" \\
  && ok "py/example_onnx.py" \\
  || miss "missing critical file: py/example_onnx.py"
test -f "go/example_onnx.go" \\
  && ok "go/example_onnx.go" \\
  || miss "missing critical file: go/example_onnx.go"
test -f "cpp/example_onnx.cpp" \\
  && ok "cpp/example_onnx.cpp" \\
  || miss "missing critical file: cpp/example_onnx.cpp"
test -f "py/helper.py" \\
  && ok "py/helper.py" \\
  || miss "missing critical file: py/helper.py"
test -f "go/helper.go" \\
  && ok "go/helper.go" \\
  || miss "missing critical file: go/helper.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/supertone-inc/supertonic"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Supertonic is a production-grade, on-device multilingual text-to-speech (TTS) engine powered by ONNX Runtime, supporting 31 languages with native inference on edge devices. It eliminates cloud dependency by running entirely locally via optimized ONNX models, enabling low-latency speech synthesis with minimal resource overhead—currently at v3 with improved accuracy and reduced synthesis failures compared to v2. Multi-SDK monorepo: language-specific implementations in top-level directories (cpp/, csharp/, flutter/ for Dart, go/, python/, rust/, js/). Each contains example_ONNX.* reference implementations, Helper.* utility wrappers, and language-native bindings. Flutter macOS integration includes platform-specific config (flutter/macos/Podfile, Runner/AppDelegate.swift). Python SDK distributed via PyPI; models hosted on Hugging Face.

Mobile/embedded developers (iOS/Swift, Android/Kotlin, Flutter/Dart), cross-platform desktop engineers (C#/.NET, C++, Go, Rust), and ML teams deploying multilingual TTS without cloud infrastructure. Also targets privacy-first applications and voice-cloning use cases via the Supertone Voice Builder product.

Production-ready and actively maintained. The project reached v3 maturity (2026.04.29) with 31-language support, ONNX optimization via OnnxSlim, and PyPI package distribution (pip install supertonic). Multi-language SDKs (Swift, C++, C#, Dart, Go, Rust, Python, JavaScript) indicate broad platform adoption. Recent updates (Flutter macOS support Dec 2025, Voice Builder Jan 2026) show ongoing feature development.

Low risk for core functionality but deployment-specific concerns exist: ONNX Runtime dependency chain is substantial (evident from Go module github.com/yalue/onnxruntime_go); model assets auto-download from Hugging Face on first run (network/quota dependent). Single maintainer or small team likely (common in open-source TTS). Breaking changes between v1→v2→v3 documented but mitigated via branch preservation (release/supertonic-2). No visible CI/test coverage data in file listing—quality assurance mechanisms unclear.

Active v3 feature maturation: recent Focus on Flutter/Dart mobile support (macOS added Nov 2024), Voice Builder SaaS product launch (Jan 2026), and model optimization via OnnxSlim (Dec 2025). PyPI package stabilization ongoing. No visible PR backlog or issue tracker in provided data, but 31-language support rollout and new voice styles (M3–M5, F3–F5) indicate continued model expansion.

# Clone the repository
git clone https://github.com/supertone-inc/supertonic.git
cd supertonic

# Python (recommended entry point)
pip install supertonic
python -c "from supertonic import TTS; tts = TTS(auto_download=True); print('Ready')"

# Or C++ example
cd cpp && mkdir build && cd build && cmake .. && make && ./example_onnx

# Or Flutter/Dart
cd flutter && flutter pub get && flutter run -d macos

Daily commands: Python: python -c 'from supertonic import TTS; tts = TTS(); wav, dur = tts.synthesize("Hello", voice_style=tts.get_voice_style("M1"), lang="en"); tts.save_audio(wav, "out.wav")'. C++: cd cpp && cmake . && make && ./example_onnx. Flutter macOS: cd flutter && flutter run -d macos. Go: (go.mod present but no example command visible—check go/example*.go if exists). Each SDK auto-downloads v3 models on first instantiation.

• py/example_onnx.py — Primary Python entry point demonstrating ONNX Runtime TTS inference workflow; essential for understanding the core TTS pipeline
• go/example_onnx.go — Go implementation showing ONNX session management and audio processing; defines the reference inference pattern across language bindings
• cpp/example_onnx.cpp — C++ example with lowest-level ONNX Runtime integration; critical for performance-sensitive implementations
• py/helper.py — Shared utilities for text preprocessing, audio encoding/decoding, and model loading; foundational for all Python implementations
• go/helper.go — Go utility functions for WAV file I/O, DSP processing, and ONNX session initialization; mirrors Python helper pattern
• ios/ExampleiOSApp/TTSService.swift — iOS service layer wrapping ONNX Runtime bindings; demonstrates on-device TTS integration for production mobile apps
• flutter/lib/main.dart — Flutter cross-platform UI and state management; shows how Supertonic integrates with platform channels for native inference

Add a new language binding to Supertonic

1. Create a language-specific directory in the repo root (e.g., ruby/, kotlin/) following the pattern of existing bindings ((new directory structure))
2. Create an example_onnx.<ext> file that loads an ONNX model session, calls inference with text input, and outputs audio (py/example_onnx.py (reference pattern))
3. Implement a language-specific helper module for ONNX session initialization, WAV codec, and text preprocessing (py/helper.py (reference implementation))
4. Add build/package configuration file (Cargo.toml, go.mod, pom.xml, package.json, etc.) with ONNX Runtime version pinning (go/go.mod (reference))
5. Write a README.md documenting setup, model download, inference call signatures, and any language-specific optimization notes (py/README.md (reference structure))

Create a new platform-specific TTS UI

1. For mobile: create a platform directory (android/, windows/, etc.) mirroring ios/ or flutter/ structure with native app shell and manifest (ios/ExampleiOSApp (reference pattern))
2. Implement a service/ViewModel layer that wraps native ONNX Runtime bindings and text→audio inference pipeline (ios/ExampleiOSApp/TTSService.swift (reference))
3. Build UI views/screens that accept text input, trigger TTS inference, and display or play synthesized audio (ios/ExampleiOSApp/ContentView.swift (reference))
4. Integrate an audio player component to play WAV output from the TTS model (ios/ExampleiOSApp/AudioPlayer.swift (reference))
5. Create platform build configuration (Xcode project.yml, Android Gradle, CMake, etc.) linking against ONNX Runtime native libraries (ios/ExampleiOSApp/project.yml (reference))

Add multilingual text preprocessing for a new language

1. Extend the language-binding helper module with locale-specific text normalization (e.g., number-to-words, phoneme rules) (py/helper.py (add normalization function))
2. Add mapping of language code to ONNX model variant (e.g., model_en.onnx, model_ko.onnx) in the helper's model loader (py/helper.py (model registry section))
3. Update the example inference script to accept language/locale parameter and route to the correct preprocessor and model (py/example_onnx.py (add language parameter))
4. Replicate the same language mapping and normalization logic across all active language bindings (Go, C++, etc.) for consistency (go/helper.go, cpp/helper.cpp (mirror changes))

Optimize ONNX Runtime inference for a new hardware target

1. Review ONNX session creation and execution providers in the language binding of choice (CPU, GPU, CoreML, NNAPI, etc.) (py/helper.py (inspect ONNX session setup))
2. Add hardware-specific provider configuration (e.g., CUDAExecutionProvider for NVIDIA, CoreMLExecutionProvider for iOS) with fallback chain (py/helper.py (modify session creation logic))
3. Benchmark inference latency, memory, and accuracy against baseline; document results in a new metrics file or README section (README.md or img/metrics/ (new benchmark file))
4. Update all related language bindings to support the new execution provider in their respective ONNX session initialization routines (go/helper.go, cpp/helper.cpp, etc. (mirror provider changes))

• ONNX Runtime — Cross-platform, hardware-agnostic inference engine supporting CPU, GPU (CUDA, CoreML, NNAPI, TensorRT); enables single model binary deployment across all platforms
• Multi-language bindings (Python, Go, C++, C#, Java, Rust, Node.js, Flutter) — Allows developers to integrate Supertonic into any ecosystem; Python/Go for servers, C++ for edge, Swift/Kotlin for mobile, C# for .NET, Rust for safety-critical
• WAV codec + floating-point PCM — Ubiquitous audio format; enables lossless storage and playback of synthesized speech with minimal post-processing
• ONNX model format — Standard, hardware-neutral ML model interchange; supports dynamic quantization,

Model auto-download: TTS(auto_download=True) downloads ~100s of MB from HuggingFace on first instantiation—no progress bar, network errors fatal. Language parity: Not all 31 languages available in all SDKs (e.g., Flutter macOS may lag behind Python). ONNX version pinning: Different SDKs may use incompatible ONNX Runtime versions (Go's yalue/onnxruntime_go is community-maintained, not official). Voice style availability: Voice names (M1, M3, F1, etc.) vary by model version and language—no runtime validation visible. Path assumptions: Example code likely assumes ONNX model files in specific directories relative to execution (check cpp/assets/, csharp/assets/ structure). No Docker image: Deployment without preloading models requires internet at first run.

• ONNX Runtime Inference — Core execution engine enabling device-local TTS without cloud; understanding session creation, input/output tensor binding, and provider selection (CPU/GPU/CoreML) is essential for all SDK ports
• Mel-Spectrogram Synthesis Pipeline — Supertonic converts text→linguistic features→mel-spectrogram (ONNX) then mel→waveform (vocoder); developers must understand this two-stage process to debug quality issues or add custom post-processing
• Voice Style Composition — v3 introduces parametric voice styles (M1, M3–M5, F1–F5 variants); achieving consistent prosody across languages requires understanding how styles encode speaker identity, pitch, and speaking rate
• Language-Agnostic Phoneme Tokenization — Supporting 31 languages requires a unified phoneme inventory and language-specific grapheme-to-phoneme conversion; v3 likely uses G2P models or rules per language, affecting text preprocessing
• ONNX Model Quantization and Pruning (OnnxSlim) — v3 models optimized via OnnxSlim reduce model size and latency; understanding quantization (INT8 vs FP32) and pruning tradeoffs is key for deployment on resource-limited devices
• Cross-Language FFI Bindings (JNI, P/Invoke, CGo, PyO3) — Each SDK wraps C/C++ ONNX Runtime via language-native FFI; knowing which binding layer you're in (Java JNI, C# P/Invoke, Go CGo, Python C extension) is essential for debugging crashes and memory leaks
• Lazy Model Loading and Asset Caching — TTS(auto_download=True) downloads large models on first run; caching strategy, cache invalidation, and fallback behavior (network failure modes) directly impact user experience in offline-first applications

• mozilla/TTS — Open-source multilingual TTS baseline; Supertonic v3 likely borrowed architecture patterns and voice style concepts from this research implementation
• espeak-ng/espeak-ng — Lightweight phoneme-based TTS alternative; Supertonic targets neural quality but eSpeak is comparison point for embedded/resource-constrained inference
• openai/whisper — Companion project for speech-to-text in privacy-first pipelines; Supertonic is the inverse direction, and both use ONNX for edge inference
• onnx/onnx — Core runtime dependency; understanding ONNX opset versions and model validation is required for all SDK maintainers
• huggingface/transformers — Model distribution source and base architecture reference; Supertonic v3 models hosted on HuggingFace and may use transformers-based exports

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add cross-platform integration tests for ONNX Runtime bindings across C++, C#, Go, and Flutter

The repo provides bindings for 4 different languages (C++, C#, Go, Flutter) but there's no visible integration test suite that validates parity across implementations. Each language directory has example files (example_onnx.cpp, ExampleONNX.cs, example_onnx.go, main.dart) and helper utilities, but no automated tests verifying that the same ONNX model produces consistent outputs across all bindings. This is critical for a production TTS library where consistency matters.

• [ ] Create tests/integration/ directory with a shared test WAV file and text input in assets/
• [ ] Add test_cpp.cpp in cpp/ that loads an ONNX model and validates output format/metadata
• [ ] Add ExampleONNXTest.cs in csharp/ with analogous test cases for C# binding
• [ ] Add example_onnx_test.go in go/ following Go testing conventions
• [ ] Add unit tests in flutter/lib/ validating that Dart/native bridge calls return expected audio format
• [ ] Create a CI workflow (e.g., .github/workflows/integration-tests.yml) that runs all 4 test suites

Add comprehensive README and API documentation for Go module with working examples

The Go module (go/README.md) exists but the go.mod declares go 1.21 with ONNX Runtime dependency. The example_onnx.go file suggests usage patterns, but there's no documentation explaining: (1) how to obtain ONNX models, (2) step-by-step setup for onnxruntime_go, (3) API surface of helper.go functions, (4) audio output handling via go-audio/wav. This friction point blocks Go developers from adopting Supertonic.

• [ ] Expand go/README.md with 'Installation' section covering go get and system dependencies for ONNX Runtime
• [ ] Document the helper.go API (identify what functions exist and their signatures, add godoc comments)
• [ ] Add 'Quick Start' code example in go/README.md showing a minimal working program (3-5 lines) that loads a model and synthesizes text
• [ ] Create go/examples/ directory with documented example_simple.go (minimal) and example_advanced.go (streaming, multi-language) if applicable
• [ ] Add 'Troubleshooting' section addressing common onnxruntime_go linking issues on Linux/macOS/Windows

Add GitHub Actions CI to test C++ and C# builds across Windows/macOS/Linux matrices

The C++ (cpp/CMakeLists.txt, cpp/example_onnx.cpp) and C# (csharp/Supertonic.csproj, ExampleONNX.cs) implementations have build configs but no visible CI/CD validation. Without automated builds, platform-specific breakages (CMake issues, .NET SDK compatibility, ONNX Runtime linking) can silently accumulate. This is especially risky for a library claiming 'native' multi-platform support.

• [ ] Create .github/workflows/cpp-build.yml with matrix for ubuntu-latest, windows-latest, macos-latest
• [ ] Add CMake build + run steps in cpp-build.yml that compile cpp/example_onnx.cpp and validate output
• [ ] Create .github/workflows/csharp-build.yml with matrix for ubuntu-latest, windows-latest, macos-latest
• [ ] Add dotnet build + test steps in csharp-build.yml for Supertonic.csproj (ensure .NET SDK selection is explicit, e.g., net6.0+)
• [ ] Ensure both workflows install ONNX Runtime runtime dependencies (libonnxruntime on Linux, via NuGet on Windows/macOS for C#)
• [ ] Add status badges to README.md linking to workflow runs

• Add unit tests for Helper.cpp ONNX session initialization and audio pipeline—file is present but no test/ directory visible in file listing, making regression detection impossible for core inference logic: medium: Critical path for all C++ bindings; missing tests block confident refactoring
• Document voice style compatibility matrix per language in a structured format (YAML or CSV) and auto-generate from model metadata—currently only README.md has anecdotal examples: low: Users cannot programmatically determine valid (language, voice_style) pairs; Voice Builder integration likely needs this
• Add progress callbacks and streaming audio output to Python SDK (expose partial audio chunks as synthesis progresses)—currently synthesize() blocks until complete WAV is ready: high: Long texts (30+ seconds) cause UI freezes in mobile/real-time applications; streaming is expected in modern TTS

The Supertonic TTS repository demonstrates a reasonable security baseline as a ML inference library with no visible hardcoded credentials, injection vulnerabilities, or Docker misconfigurations. However, several concerns exist: (1) The Go implementation uses outdated ONNX Runtime bindings from 2021 that may contain unpatched vulnerabilities, (2) A critical DSP dependency appears unmaintained since 2018, and (3) The multi-language architecture lacks unified security governance and centralized dependency management. The absence of a vulnerability disclosure policy and SBOM further limits security transparency. Recommended actions include updating core dependencies, establishing cross-language security policies, and implementing comprehensive supply chain security practices.

• High · Outdated ONNX Runtime Go Binding — go/go.mod. The go.mod file specifies 'github.com/yalue/onnxruntime_go v1.11.0', which is an outdated version of the ONNX Runtime Go binding. This version may contain known security vulnerabilities and lacks recent security patches. ONNX Runtime is a critical dependency for ML model execution, and outdated versions can expose the application to security risks including buffer overflows, memory corruption, and arbitrary code execution. Fix: Update to the latest stable version of the ONNX Runtime Go binding. Regularly monitor for security advisories and update dependencies to the latest patched versions. Consider using 'go get -u' followed by 'go mod tidy' and thorough testing.
• Medium · Unmaintained Third-Party DSP Library — go/go.mod. The dependency 'github.com/mjibson/go-dsp v0.0.0-20180508042940-11479a337f12' is pinned to a commit from 2018 with no version tags, indicating it may be unmaintained. The repository shows no recent activity or security updates, which could pose risks if vulnerabilities are discovered in the digital signal processing implementation. Fix: Evaluate if this DSP library is actively maintained. Consider migrating to actively maintained alternatives or forking and maintaining the library internally. If retained, conduct thorough security review and implement additional input validation around DSP operations.
• Medium · Multiple Language Implementations Without Unified Security Review — Repository root - cpp/, csharp/, flutter/, go/, java/, ios/, nodejs/. The codebase contains implementations in C++, C#, Flutter (Dart), Go, Java, and iOS (Swift) across different directories. Each language implementation may have different security configurations, dependencies, and vulnerability profiles. The absence of a centralized dependency management or security scanning strategy increases the risk of inconsistent security postures across implementations. Fix: Implement a comprehensive security scanning strategy covering all language implementations. Use language-specific security tools (e.g., cargo-audit for Rust, npm audit for Node.js, go list for Go). Establish consistent security policies across all implementations and maintain a unified SBOM (Software Bill of Materials).
• Low · No Visible Security Policy or Vulnerability Disclosure Process — Repository root. The repository does not contain a SECURITY.md file or documented vulnerability disclosure process. This makes it difficult for security researchers to report vulnerabilities responsibly, potentially leading to public disclosure of unpatched vulnerabilities. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process, security contact information, and expected response times. This follows best practices outlined in RFC 9116.
• Low · Missing SBOM (Software Bill of Materials) — Repository root. There is no visible SBOM file (such as SBOM.json, cyclonedx-sbom.json, or similar) that documents all dependencies and their versions across the project. This makes it difficult to assess supply chain risks and respond to vulnerabilities in transitive dependencies. Fix: Generate and maintain a comprehensive SBOM using tools like CYCLONE DX, SPDX, or language-specific tools. Commit the SBOM to the repository and update it with each release. This enables better vulnerability tracking and supply chain security.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.