utter-spec.txt

UTTER
Local Text-to-Speech CLI for Apple Silicon
Project Specification
Version: 1.0
Target platform: macOS on Apple Silicon, with Mac mini M4 as the primary development and validation machine

======================================================================
1. PROJECT SUMMARY
======================================================================

Utter is a local-first command-line text-to-speech tool for macOS.

Its primary purpose is simple:

    text + selected built-in voice -> local speech synthesis -> audio file

Utter is not intended to be a full desktop application, voice editor, audio
workstation, or GUI product. It should be a focused developer utility that can
be used directly from Terminal and invoked programmatically from other apps.

Primary example:

    utter speak "This is a flower." --voice Ryan -o flower.wav

The generated audio must be produced locally on Apple Silicon using Qwen3-TTS
through MLX acceleration. No cloud API should be required for synthesis after
the model has been downloaded.

The first implementation should prioritize:
- voice quality
- reliability
- predictable CLI behavior
- clean integration from other applications
- offline inference
- Apple Silicon performance
- a stable command-line contract

The first version should deliberately avoid unnecessary product complexity.


======================================================================
2. PRIMARY GOAL
======================================================================

Build a reliable CLI that allows a user or another application to:

1. Download/install the required TTS model.
2. List available built-in voice profiles.
3. Provide text.
4. Select one of the model's supported preset voices.
5. Generate speech locally.
6. Save the speech to a WAV file.
7. Receive predictable success/error output suitable for automation.


======================================================================
3. NON-GOALS FOR MVP
======================================================================

Do NOT build the following in the first MVP:

- GUI
- Tauri application
- SwiftUI application
- web UI
- HTTP API server
- database
- user accounts
- cloud synthesis
- billing
- authentication
- voice marketplace
- voice recording
- speech-to-text
- voice cloning
- custom reference-audio voices
- project/history library
- audio effects
- timeline editor
- waveform editor
- batch job scheduler
- background daemon
- streaming playback
- true real-time streaming synthesis
- plugin system
- automatic model switching
- automatic cloud fallback
- telemetry
- analytics
- crash reporting
- cross-platform support

These may be added later only if a real use case requires them.


======================================================================
4. TARGET ENVIRONMENT
======================================================================

Primary target:

- macOS
- Apple Silicon
- Mac mini M4

Initial development environment:

- Python 3.12
- MLX
- MLX-Audio
- Qwen3-TTS
- Hugging Face model artifacts/cache
- local filesystem
- WAV output

Utter should be developed and validated first on the Mac mini M4.

Do not optimize for Intel Macs.

Do not add CUDA, ROCm, DirectML, XPU, Windows, or Linux backend logic in MVP.


======================================================================
5. RECOMMENDED MODEL AND RUNTIME
======================================================================

Primary model:

    Qwen3-TTS 1.7B CustomVoice

Primary runtime:

    MLX-Audio + MLX/Metal

Recommended initial model artifact:

    Qwen3-TTS 1.7B CustomVoice 8-bit MLX conversion

Reasoning:

- Qwen CustomVoice provides built-in preset speakers.
- The 1.7B model should be preferred over 0.6B because voice quality,
  naturalness, prosody, robustness, and instruction following matter more than
  minimizing model size.
- 8-bit MLX is the preferred starting point because it provides a practical
  balance between model size, memory usage, load time, and quality.
- MLX is the appropriate acceleration layer for Apple Silicon.
- The CLI must NOT use the CPU-only CustomVoice code path present in the
  inspected Voicebox implementation.

Expected rough resource profile for planning only:

- model storage: approximately 3 GB class
- working memory: approximately 4-6 GB class
- target hardware: M4-class Apple Silicon should be practical

These numbers must be measured on the actual target machine during development.
Do not hardcode assumptions about performance into the product.


======================================================================
6. WHY PYTHON FOR V1
======================================================================

The synthesis engine should initially be implemented in Python rather than
native Swift.

Reason:

- MLX-Audio's Python implementation is currently the safer and more mature path
  for Qwen3-TTS CustomVoice.
- A CLI boundary makes the implementation language an internal detail.
- Other Swift, Flutter, Rust, Node, or Python applications can invoke Utter as a
  subprocess.
- A native Swift/MLXAudioSwift implementation can be evaluated later without
  changing the public CLI contract.

This is an architectural decision for MVP reliability, not a permanent
requirement.


======================================================================
7. CORE USER EXPERIENCE
======================================================================

Minimum happy path:

    utter models pull
    utter voices
    utter speak "This is a flower." --voice Ryan -o flower.wav

Expected result:

- model is downloaded explicitly
- supported voices are shown
- selected voice is validated
- text is synthesized locally
- output file is a valid WAV
- command exits with code 0
- output file path is reported


======================================================================
8. CLI COMMANDS
======================================================================

The MVP should expose exactly these top-level areas:

    utter speak
    utter voices
    utter models pull
    utter models status

Optional but recommended:

    utter --version
    utter --help
    utter speak --help
    utter voices --help
    utter models --help


======================================================================
9. COMMAND: utter voices
======================================================================

Purpose:

List available preset voices supported by the selected Qwen CustomVoice model.

Example:

    utter voices

Human-readable output should include at minimum:

    NAME
    LANGUAGE/NOTES if known

Known Qwen CustomVoice preset speaker names from the inspected implementation:

- Vivian
- Serena
- Uncle_Fu
- Dylan
- Eric
- Ryan
- Aiden
- Ono_Anna
- Sohee

Ryan may be used as the default voice unless testing reveals a better default.

Also support:

    utter voices --json

JSON output must be stable and machine-readable.

Example shape:

{
  "voices": [
    {
      "id": "Ryan",
      "name": "Ryan"
    }
  ]
}

Do not silently invent aliases in MVP.

Voice IDs should map directly to Qwen speaker IDs.


======================================================================
10. COMMAND: utter speak
======================================================================

Primary syntax:

    utter speak "This is a flower." --voice Ryan -o flower.wav

Also support:

    utter speak "This is a flower." --voice Ryan --output flower.wav

Required arguments:

- text, unless --stdin is used
- output path, unless a documented default output behavior is implemented

Recommended options:

    --voice <VOICE>
    -o, --output <PATH>
    --language <LANGUAGE>
    --style <INSTRUCTION>
    --stdin
    --force
    --json

Optional later:

    --seed <INTEGER>

Do not add large numbers of generation parameters to the initial public API.


======================================================================
11. STDIN SUPPORT
======================================================================

Utter must support stdin because this makes it much easier to integrate with
other command-line tools and applications.

Example:

    printf '%s' "This is a flower." | utter speak --stdin --voice Ryan -o flower.wav

Rules:

- --stdin means text must be read from stdin.
- Empty stdin is an error.
- Do not allow ambiguous simultaneous text argument + --stdin unless behavior is
  explicitly documented. Prefer rejecting this combination.
- Preserve Unicode input correctly.


======================================================================
12. VOICE SELECTION
======================================================================

Voice selection should be intentionally simple.

User-facing value:

    --voice Ryan

Internal model call should map directly to the Qwen CustomVoice speaker field.

Conceptually:

    speaker = selected_voice

Then call the Qwen CustomVoice generation API with:

- text
- speaker
- language
- optional instruction/style

Do not create a database-backed voice-profile abstraction for MVP.

Instead use a static or model-derived typed catalog.

Validation requirements:

- exact valid voice IDs accepted
- invalid voice ID produces a clear error
- error should show or suggest available voices
- no silent fallback to another voice when the user explicitly chose an invalid
  voice


======================================================================
13. STYLE / INSTRUCTION SUPPORT
======================================================================

Qwen CustomVoice supports instruction-based control.

Expose this as:

    --style "Speak warmly and naturally."

Example:

    utter speak "Welcome back." \
      --voice Aiden \
      --style "Speak calmly and warmly." \
      -o welcome.wav

The CLI should pass this to the model's instruction field.

If no style is provided:

- do not invent one
- use the model's normal/default generation behavior


======================================================================
14. LANGUAGE SUPPORT
======================================================================

MVP should support an explicit language option:

    --language en

or, if the underlying Qwen API expects full names:

    --language English

Choose one canonical public representation and map internally.

Requirements:

- default should be English for MVP
- invalid language should produce a clear error
- language handling must not be guessed inconsistently
- keep language mapping in one module/configuration location

Do not attempt automatic language detection in MVP unless the underlying runtime
requires it and it is trivial and reliable.


======================================================================
15. AUDIO OUTPUT
======================================================================

Primary format for MVP:

    WAV

Recommended output characteristics:

- 24 kHz
- mono
- PCM-16

The model may return floating-point waveform samples internally.

Pipeline:

    model output
        ->
    validate waveform
        ->
    convert if necessary
        ->
    write temporary WAV
        ->
    atomically rename to final output path

The output file must be usable by normal macOS/iOS audio tooling.


======================================================================
16. ATOMIC FILE WRITING
======================================================================

Utter should use atomic output writing.

Example:

Requested destination:

    /path/flower.wav

Temporary file:

    /path/flower.wav.tmp

Process:

1. Generate complete waveform.
2. Validate waveform.
3. Write temporary WAV.
4. Flush/close file.
5. Confirm write succeeded.
6. Atomically rename temp file to final destination.

If generation or writing fails:

- remove temporary file when possible
- do not leave a partial final WAV
- return nonzero exit code


======================================================================
17. OUTPUT OVERWRITE BEHAVIOR
======================================================================

Default:

Do NOT overwrite an existing output file.

If destination exists:

    error: output file already exists: flower.wav
    use --force to overwrite

With:

    --force

Utter may replace the destination atomically.


======================================================================
18. WAVEFORM VALIDATION
======================================================================

Before writing final audio, validate:

- waveform exists
- waveform is nonempty
- values are finite
- no NaN values
- no Inf values
- sample rate is valid
- output duration is greater than zero

If the waveform is invalid:

- do not write final output
- return nonzero exit code
- provide a concise error


======================================================================
19. MODEL MANAGEMENT
======================================================================

Model downloading must be explicit.

Do NOT silently download a multi-gigabyte model during:

    utter speak

Instead:

    utter models pull

should download/install the pinned model.

Then:

    utter models status

should report whether the model is ready.


======================================================================
20. COMMAND: utter models pull
======================================================================

Responsibilities:

- resolve configured model repository
- resolve pinned model revision
- create deterministic cache directory
- download required model snapshot
- verify snapshot completion
- report success
- record model/runtime metadata

Example:

    utter models pull

Suggested output:

    Model: Qwen3-TTS 1.7B CustomVoice 8-bit
    Status: downloading
    ...
    Status: ready
    Location: ~/Library/Caches/utter/models/...

Exact UI can differ, but behavior must be predictable.


======================================================================
21. COMMAND: utter models status
======================================================================

Example:

    utter models status

Should report at minimum:

- model name
- model repository
- model revision
- quantization
- cache location
- installed/not installed
- complete/incomplete
- approximate disk usage if easy to obtain
- runtime version if available

Also support machine-readable JSON if practical:

    utter models status --json


======================================================================
22. MODEL CACHE
======================================================================

Use a deterministic Utter-owned cache directory.

Recommended macOS location:

    ~/Library/Caches/utter/

Possible structure:

    ~/Library/Caches/utter/
        models/
        metadata/

Do not scatter model state throughout arbitrary project folders.

If Hugging Face caching is used internally, configure or wrap it so Utter can
determine exactly where its model lives.

MVP should record:

- model repository
- exact revision/commit
- quantization
- MLX-Audio version
- MLX version
- installation status


======================================================================
23. MODEL PINNING
======================================================================

Reliability is more important than always using the newest upstream build.

Pin:

- Python major/minor compatibility
- mlx version
- mlx-audio version
- huggingface_hub version
- audio-writing dependency
- Qwen model repository
- exact model revision when possible

Do not depend on floating "latest" versions in a production lockfile.

Upgrade dependencies intentionally and re-run the audio test corpus.


======================================================================
24. OFFLINE REQUIREMENT
======================================================================

After:

    utter models pull

normal synthesis should work with networking disabled.

During:

    utter speak

use local model files only.

If the model is missing:

Do NOT begin an implicit download.

Return an error such as:

    model is not installed
    run: utter models pull


======================================================================
25. PROCESS OUTPUT CONTRACT
======================================================================

Utter is intended to be called by other applications.

Therefore stdout/stderr discipline matters.

Recommended:

stdout:
- successful result information
- JSON output when --json is used
- final output path if human-readable mode

stderr:
- progress
- warnings
- diagnostics
- model loading progress
- errors

Exit codes:

0
    success

Nonzero
    failure

Use distinct codes where useful, but avoid overengineering.

Suggested categories:

1
    generic runtime failure

2
    CLI/argument validation failure

3
    model missing/not ready

4
    invalid voice/language

5
    synthesis failure

6
    output/write failure

These exact values may be adjusted, but they must be documented and stable once
released.


======================================================================
26. JSON MODE
======================================================================

Commands used by other applications should support stable JSON output where
useful.

Example:

    utter speak "This is a flower." --voice Ryan -o flower.wav --json

Possible response:

{
  "success": true,
  "output": "/absolute/path/flower.wav",
  "voice": "Ryan",
  "model": "Qwen3-TTS-1.7B-CustomVoice-8bit",
  "sample_rate": 24000,
  "duration_seconds": 1.24
}

On failure:

{
  "success": false,
  "error": {
    "code": "INVALID_VOICE",
    "message": "Unknown voice: Bob"
  }
}

When --json is active:

- stdout must contain valid JSON only
- diagnostic logs must go to stderr


======================================================================
27. INITIAL PROJECT STRUCTURE
======================================================================

Suggested structure:

utter/
    pyproject.toml
    README.md
    LICENSE
    spec.txt
    src/
        utter/
            __init__.py
            __main__.py
            cli.py
            config.py
            constants.py
            errors.py

            commands/
                __init__.py
                speak.py
                voices.py
                models.py

            tts/
                __init__.py
                engine.py
                qwen_mlx.py
                voices.py

            models/
                __init__.py
                manifest.py
                cache.py
                downloader.py

            audio/
                __init__.py
                validation.py
                wav.py

            output/
                __init__.py
                json_output.py
                console.py

    tests/
        test_cli.py
        test_voices.py
        test_model_status.py
        test_audio_validation.py
        test_output_paths.py
        test_json_output.py

    scripts/
        benchmark_m4.py
        smoke_test.py

This structure is guidance, not a rigid requirement.

Prefer simple code over excessive abstraction.


======================================================================
28. TTS ENGINE ABSTRACTION
======================================================================

Do not overbuild a multi-provider architecture in MVP.

However, isolate Qwen runtime code behind a small internal interface so the
model implementation can later be replaced.

Conceptual interface:

    class TTSEngine:
        list_voices()
        synthesize(text, voice, language, style) -> AudioResult

AudioResult should contain:

- waveform
- sample_rate
- metadata

Do not design a large plugin framework.

One clean interface is enough.


======================================================================
29. QWEN MLX ADAPTER
======================================================================

Create a dedicated module for Qwen CustomVoice through MLX-Audio.

Responsibilities:

- load the pinned MLX model
- cache the loaded model within the current process
- expose supported voices
- validate generation options
- invoke CustomVoice generation
- return waveform + sample rate
- translate runtime exceptions into Utter errors

Do NOT copy Voicebox's current PyTorch QwenCustomVoice backend.

Do NOT route CustomVoice through CPU on Apple Silicon.

Do NOT use the cloning-oriented Qwen Base path for preset voice synthesis.


======================================================================
30. MODEL LIFECYCLE
======================================================================

For a one-shot CLI process:

1. Parse command.
2. Validate model availability.
3. Load model.
4. Generate audio.
5. Save file.
6. Exit.

Loading may be the largest source of latency.

Do not build a daemon yet.

Measure cold-start performance first.

A future "utter serve" process may keep the model resident if repeated calls
from applications make cold-start overhead unacceptable.


======================================================================
31. FUTURE WARM SERVER MODE
======================================================================

NOT part of MVP.

Potential later command:

    utter serve

Purpose:

- load Qwen model once
- keep it warm
- accept local requests
- reduce repeated model startup cost

Potential IPC:

- Unix domain socket
- localhost HTTP
- simple subprocess protocol

Preference for later investigation:

    Unix domain socket or similarly local-only IPC

Do not implement until one-shot CLI benchmarks prove it is necessary.


======================================================================
32. LONG TEXT
======================================================================

MVP success criterion is short-to-medium text.

Do not build sophisticated long-document synthesis before the core command is
reliable.

After MVP, long text may use:

1. sentence-aware segmentation
2. sequential generation
3. small pause/crossfade joining
4. final WAV assembly

Voicebox uses chunking plus approximately small crossfades. That concept is
worth adapting later.

Requirements when implemented:

- never split in the middle of UTF-8 characters
- avoid splitting common abbreviations incorrectly where practical
- preserve punctuation
- test audible joins
- avoid clipping at boundaries
- make chunking deterministic


======================================================================
33. TRUE STREAMING
======================================================================

Not required for MVP.

The product's first job is to generate a correct audio file.

Do not call a feature "streaming" if the entire waveform is generated first and
only then emitted in blocks.

If genuine streaming is added later, document separately:

- time to first audio
- chunk format
- buffering strategy
- cancellation behavior
- final file assembly


======================================================================
34. ERROR HANDLING
======================================================================

Errors must be actionable.

Examples:

Missing model:

    Error: Qwen3-TTS model is not installed.
    Run: utter models pull

Invalid voice:

    Error: unknown voice "Bob".
    Run: utter voices

Existing output:

    Error: flower.wav already exists.
    Use --force to overwrite it.

Empty text:

    Error: text cannot be empty.

Invalid output directory:

    Error: output directory does not exist: /path/foo

Synthesis failure:

    Error: speech synthesis failed.
    <short underlying reason>

Do not dump giant Python stack traces during normal CLI usage.

Support a debug mode later if needed.


======================================================================
35. LOGGING
======================================================================

Default CLI output should be concise.

Do not flood the terminal with internal ML/runtime logs.

Route avoidable library noise away from normal output when possible.

Potential future:

    --verbose
    --debug

Not required for first milestone unless needed during development.


======================================================================
36. SECURITY AND PRIVACY
======================================================================

Utter should be local-first.

For MVP:

- input text stays on-device during synthesis
- generated audio stays on-device
- no telemetry
- no analytics
- no cloud API
- no automatic upload
- no account

Model download is the expected network operation.

Once installed, generation should work offline.


======================================================================
37. LICENSING
======================================================================

Before distribution, verify and document exact licenses for:

- Qwen3-TTS model
- selected MLX conversion
- MLX
- MLX-Audio
- Hugging Face dependencies
- audio libraries

Current architecture preference is based on an Apache-2.0 Qwen model and
permissive MLX ecosystem components, but the implementation agent must verify
the exact artifacts actually pinned in the project before publishing.

Include a THIRD_PARTY_NOTICES file if required.

Do not assume a repository name guarantees identical licensing for every
artifact.


======================================================================
38. INSTALLATION STRATEGY
======================================================================

During development:

- use Python virtual environment or uv
- lock dependencies
- expose the `utter` console entry point

Recommended developer flow:

    git clone ...
    cd utter
    uv sync
    uv run utter --help

or equivalent.

Do not start with PyInstaller.

The first priority is diagnosable, reproducible behavior.

Packaging into a standalone binary/app can be evaluated after the runtime is
stable.


======================================================================
39. CLI FRAMEWORK
======================================================================

Use a mature Python CLI library.

Preferred options:

- Typer
- Click
- argparse

Choose the smallest option that gives:

- nested commands
- clean help
- option validation
- predictable exit handling

Do not add a heavy framework just for command parsing.


======================================================================
40. AUDIO LIBRARY
======================================================================

Use a proven local audio writing library capable of WAV output.

Requirements:

- NumPy-compatible waveform support
- PCM-16 WAV
- explicit sample rate
- predictable exceptions
- macOS compatibility

Keep file-writing code in Utter rather than relying on opaque convenience
behavior from the model runtime.


======================================================================
41. TESTING STRATEGY
======================================================================

Separate tests into:

A. Unit tests
B. CLI tests
C. Integration tests
D. Audio quality/manual tests
E. Performance benchmarks


======================================================================
42. UNIT TESTS
======================================================================

Unit tests should cover at minimum:

- voice validation
- language validation
- empty input
- stdin/text conflicts
- output path resolution
- overwrite protection
- --force behavior
- model status parsing
- waveform NaN rejection
- waveform Inf rejection
- zero-length waveform rejection
- JSON schema output
- exit code mapping

Most unit tests should not load the real Qwen model.


======================================================================
43. CLI TESTS
======================================================================

Test:

    utter --help
    utter voices
    utter voices --json
    utter models status
    utter speak --help

Mock the engine where practical.

Verify:

- stdout
- stderr
- exit codes
- output formatting
- JSON validity


======================================================================
44. REAL MODEL INTEGRATION TEST
======================================================================

At least one opt-in integration test must run the actual model.

Canonical test:

    utter speak "This is a flower." --voice Ryan -o flower.wav

Validate:

- exit code 0
- output exists
- WAV opens successfully
- sample rate correct
- channel count correct
- duration > 0
- waveform finite
- file size plausible


======================================================================
45. GOLDEN AUDIO TEST CORPUS
======================================================================

Create a small fixed test corpus for manual listening and regression testing.

Use at least these examples:

1.
    This is a flower.

2.
    Your download has completed successfully.

3.
    Tomorrow's forecast is sunny with a high of twenty-eight degrees.

4.
    Your timer has five minutes remaining.

5.
    Welcome back. Here's what you missed.

6.
    The quick brown fox jumps over the lazy dog.

7.
    Numbers: one, ten, one hundred, one thousand, and twenty-four point five.

8.
    Punctuation matters, doesn't it? Yes, it does.

9.
    Please open Settings, choose Privacy, and enable microphone access.

10.
    A longer paragraph of approximately 80-150 words for robustness testing.

Test at least these voices:

- Ryan
- Aiden
- Vivian
- Serena

Also test at least one supported non-English or cross-language case if the model
claims support for it.


======================================================================
46. AUDIO QUALITY REVIEW
======================================================================

Audio quality cannot be fully automated.

Manually listen for:

- naturalness
- pronunciation
- robotic artifacts
- skipped words
- repeated words
- awkward pauses
- excessive silence
- clipping
- volume inconsistency
- voice identity consistency
- instruction/style adherence
- handling of punctuation
- number pronunciation

Record observations in a simple benchmark/report file.


======================================================================
47. M4 PERFORMANCE BENCHMARK
======================================================================

Create:

    scripts/benchmark_m4.py

Measure:

- model download size
- cold model load time
- warm generation time
- total command time
- generated audio duration
- real-time factor
- peak resident memory if reasonably measurable

Definition:

    real_time_factor = generation_time / generated_audio_duration

Lower is better.

Measure:

- short sentence
- medium paragraph
- longer paragraph
- multiple voices

Do not claim performance numbers before measuring them on the actual M4.


======================================================================
48. 0.6B FALLBACK EXPERIMENT
======================================================================

After 1.7B is working, optionally benchmark:

    Qwen3-TTS 0.6B CustomVoice 8-bit

Compare:

- quality
- cold load time
- generation speed
- RAM
- model size

Only change the default model if the smaller model gives an obviously better
product tradeoff.

Quality remains the primary priority.


======================================================================
49. BF16 QUALITY EXPERIMENT
======================================================================

After the 8-bit implementation is reliable, optionally compare against BF16.

Goal:

Determine whether BF16 produces a perceptible enough quality improvement to
justify:

- larger model
- higher memory use
- slower loading

Do not assume BF16 is audibly better without listening tests.


======================================================================
50. KOKORO FALLBACK
======================================================================

Kokoro is not required for MVP.

It may later be considered as:

- lightweight mode
- fast-start mode
- fallback model
- low-memory model

Do not add it until Qwen is working.

Avoid premature multi-engine complexity.


======================================================================
51. CONFIGURATION
======================================================================

MVP configuration should be minimal.

Hard-code or centrally define sensible defaults:

- default model
- model revision
- default voice
- default language
- cache path

Do not introduce config files until a real need exists.

Potential later:

    ~/.config/utter/config.toml

But not necessary for first milestone.


======================================================================
52. DEFAULTS
======================================================================

Suggested initial defaults:

Default model:
    Qwen3-TTS 1.7B CustomVoice 8-bit

Default voice:
    Ryan

Default language:
    English

Default output:
    Require -o initially, OR use ./utter-output.wav if the team prefers.

Preferred choice:
    Require explicit output path for predictable app integration.

Default overwrite:
    false

Default networking during speak:
    disabled/local-only


======================================================================
53. PATH HANDLING
======================================================================

Requirements:

- support relative paths
- support absolute paths
- expand ~ where appropriate
- normalize destination safely
- ensure parent directory exists
- do not silently create arbitrary deep directories unless documented
- return absolute output path in JSON result
- handle spaces and Unicode filenames


======================================================================
54. INTERRUPTS
======================================================================

If the user presses Ctrl+C during synthesis:

- terminate cleanly
- remove temp output file if present
- exit nonzero
- do not leave corrupted final files

Do not overengineer model cleanup if the process is exiting anyway.


======================================================================
55. DETERMINISM
======================================================================

TTS generation may not be fully deterministic.

If the runtime exposes a seed reliably, consider:

    --seed

But do not make seed handling part of MVP acceptance unless needed.

If implemented:

- document whether identical text/voice/seed is expected to reproduce identical
  audio
- test it
- do not falsely promise bit-identical output


======================================================================
56. INTERNAL DATA TYPES
======================================================================

Suggested simple types:

Voice:
- id
- display_name
- optional language/notes

ModelManifest:
- id
- repository
- revision
- quantization
- runtime
- sample_rate

SynthesisOptions:
- voice
- language
- style
- optional seed

AudioResult:
- waveform
- sample_rate
- optional metadata

Keep types small.


======================================================================
57. README REQUIREMENTS
======================================================================

README should contain:

- what Utter is
- macOS/Apple Silicon requirement
- install/setup
- model download
- list voices
- synthesize speech
- stdin usage
- offline behavior
- JSON usage
- known limitations
- development instructions
- license information

Example must appear near the top:

    utter models pull
    utter speak "This is a flower." --voice Ryan -o flower.wav


======================================================================
58. DEVELOPMENT PHASES
======================================================================

PHASE 0 - Runtime spike

Goal:
Prove Qwen3-TTS 1.7B CustomVoice 8-bit works correctly through MLX-Audio on the
Mac mini M4.

Tasks:

- create isolated Python environment
- install pinned candidate MLX dependencies
- load model
- generate:
      "This is a flower."
- speaker:
      Ryan
- save valid WAV
- listen manually
- record load time and generation time

Do NOT build the full CLI before this succeeds.


PHASE 1 - Minimal CLI

Build:

    utter speak
    utter voices

Requirements:

- text argument
- --voice
- -o/--output
- WAV output
- overwrite protection
- useful errors


PHASE 2 - Explicit model management

Build:

    utter models pull
    utter models status

Requirements:

- pinned repository/revision
- deterministic cache
- no implicit downloads during synthesis
- local-only generation


PHASE 3 - Integration quality

Add:

- --stdin
- --json
- --language
- --style
- atomic output
- waveform validation
- clean exit codes


PHASE 4 - Tests and benchmarks

Add:

- automated tests
- golden corpus
- M4 benchmark
- manual quality review


PHASE 5 - Polish

Add:

- README
- package metadata
- license notices
- reproducible dependency lock
- cleaner error messages


======================================================================
59. MVP ACCEPTANCE CRITERIA
======================================================================

The MVP is complete when ALL of the following are true:

1. This works on the Mac mini M4:

       utter models pull

2. This lists Qwen preset voices:

       utter voices

3. This generates valid speech:

       utter speak "This is a flower." --voice Ryan -o flower.wav

4. flower.wav:
   - exists
   - is valid WAV
   - is nonempty
   - is intelligible
   - sounds natural enough for use inside applications
   - contains the requested sentence
   - uses the selected voice

5. The command works with networking disabled after model installation.

6. Invalid voices fail cleanly.

7. Existing output files are protected unless --force is used.

8. Failed synthesis never leaves a partial final WAV.

9. --stdin works.

10. --json produces machine-readable output.

11. Core tests pass.

12. A benchmark has been run on the actual M4.

13. At least Ryan, Aiden, Vivian, and Serena have been manually tested.

14. No GUI, server, database, or unrelated Voicebox architecture has been added.


======================================================================
60. DEFINITION OF "GOOD RESULTS"
======================================================================

For MVP, "good results" means:

- clearly intelligible speech
- natural enough for real app use
- no obvious model corruption
- no missing/repeated phrases in ordinary sentences
- selected speaker identity remains consistent
- normal punctuation sounds reasonable
- style instructions work when used
- acceptable performance on an M4

Do not block MVP on achieving perfect human indistinguishability.


======================================================================
61. CODING AGENT INSTRUCTIONS
======================================================================

The implementation agent should follow these rules:

1. Read this entire specification before editing code.

2. Start with the Phase 0 runtime spike.

3. Do not build abstractions before proving the model works on the target
   machine.

4. Prefer the simplest reliable implementation.

5. Do not copy the full Voicebox architecture.

6. Do not use Voicebox's CPU-oriented Qwen CustomVoice backend on macOS.

7. Use MLX-Audio for Qwen CustomVoice acceleration on Apple Silicon.

8. Pin dependencies after finding a known-good combination.

9. Do not silently upgrade dependencies.

10. Do not silently download models during synthesis.

11. Do not add a GUI.

12. Do not add a database.

13. Do not add an HTTP server.

14. Do not add voice cloning to MVP.

15. Do not add multiple TTS engines to MVP.

16. Do not introduce a plugin architecture.

17. Keep stdout suitable for app integration.

18. Keep JSON output stable.

19. Use atomic file writing.

20. Validate generated waveform before publishing the final file.

21. Add tests for behavior that does not require the real model.

22. Run a real model smoke test before declaring synthesis complete.

23. Benchmark on the actual M4.

24. If the selected MLX-Audio release cannot reliably run the required
    CustomVoice model, stop and document the blocker rather than replacing the
    architecture with CPU PyTorch without discussion.

25. If an upstream API differs from this spec, preserve the public Utter CLI
    contract and adapt internally.

26. Keep a DEVELOPMENT_NOTES.md file containing:
    - pinned versions
    - model revision
    - runtime issues found
    - benchmark results
    - unresolved upstream limitations


======================================================================
62. FIRST IMPLEMENTATION TASK FOR THE AGENT
======================================================================

Before building anything else, implement and run the smallest possible script
that does only this:

Input:

    text = "This is a flower."
    voice = "Ryan"

Runtime:

    MLX-Audio
    Qwen3-TTS 1.7B CustomVoice 8-bit

Output:

    flower.wav

Success means:

- model loads on Apple Silicon
- Metal/MLX path is used
- synthesis completes
- flower.wav is valid
- audio is intelligible
- audio sounds acceptable
- no CPU-only PyTorch fallback is used

Only after this works should the agent move to the CLI.


======================================================================
63. FUTURE ROADMAP
======================================================================

Possible post-MVP work, in rough order:

1. Long-text chunking and joining.
2. Warm local `utter serve` mode.
3. PCM/audio streaming for app integrations.
4. 0.6B lightweight model option.
5. BF16 high-quality option.
6. Kokoro lightweight engine.
7. Voice cloning using Qwen Base.
8. Custom named local voice profiles.
9. Native Swift/MLXAudioSwift implementation.
10. Standalone binary packaging.
11. Additional output formats such as AIFF, FLAC, or MP3.
12. Cross-platform runtimes if needed.

None of these belong in the initial MVP unless explicitly promoted into scope.


======================================================================
64. NATIVE SWIFT MIGRATION CRITERIA
======================================================================

A later native Swift implementation should only replace the Python engine when
it can match or exceed the reference implementation on:

- same preset voice mapping
- same supported text
- comparable naturalness
- comparable pronunciation
- comparable style control
- acceptable M4 speed
- offline operation
- deterministic model installation
- predictable errors
- stable API/runtime
- test corpus compatibility

The CLI interface should remain unchanged during such a migration.


======================================================================
65. FINAL PRODUCT PRINCIPLE
======================================================================

Utter should feel like a Unix-style developer tool:

    input text
        +
    voice
        ->
    speech file

It should be boring in the best possible way:

- predictable
- local
- scriptable
- reliable
- easy to invoke
- easy to integrate
- high-quality audio

Avoid turning it into a broad AI voice platform before the core command is
excellent.


======================================================================
66. CANONICAL MVP DEMO
======================================================================

The project should ultimately be demoed with:

    utter models pull

    utter voices

    utter speak "This is a flower." \
      --voice Ryan \
      -o flower.wav

Then:

    afplay flower.wav

If this path works reliably and sounds good on the Mac mini M4, the primary
project objective has been achieved.