# Model Manager

`tools/model_manager_v2.py` downloads supported model packages into the
framework's expected `models/` layout. It reads package metadata from
`model_specs/*.json`, which is the current source of truth for default download
links.

When a family has a ready-to-use GGUF package, the default install should be that
GGUF package. The old safetensors/converter catalog is still available as
`tools/model_manager_deprecated.py`, but it is a legacy path for models that have
not migrated to spec-backed packages.

## GGUF Downloads

Ready-to-use GGUF packages are published here:

- Core released models: [audio-cpp/audio.cpp-gguf](https://huggingface.co/audio-cpp/audio.cpp-gguf)
- Fun-ASR-Nano: [FunAudioLLM/Fun-ASR-Nano-2512-GGUF](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512-GGUF)
- Community OuteTTS package: [mirek190/audio.cpp](https://huggingface.co/mirek190/audio.cpp/tree/main/Text%20to%20audio%20(TTS))

For support status and tested precision coverage, see the [GGUF guide](gguf.md).
For measured 16-bit vs Q8 speed and peak-VRAM results, see the
[Q8 performance report](reports/gguf_q8_performance.md).

## Dependencies

- Python 3
- Network access to the upstream model source

Legacy converter installs through `tools/model_manager_deprecated.py` may also
need `torch`, `safetensors`, `PyYAML`, or model-specific conversion inputs.

## Commands

- `list` shows the available package ids
- `list --json` prints a machine-readable package catalog
- `info` shows the target layout, required files, and install source for one package
- `info <package> --json` prints machine-readable package details
- `install` downloads or converts one package into a models root

The runtime loader catalog is also available from:

```bash
audiocpp_cli --list-loaders --json
```

## Quick Start

List installable packages:

```bash
python3 tools/model_manager_v2.py list
```

Inspect one package:

```bash
python3 tools/model_manager_v2.py info qwen3_tts
```

Install into the default `models/` directory:

```bash
python3 tools/model_manager_v2.py install qwen3_tts
```

Install into a custom models root:

```bash
python3 tools/model_manager_v2.py install vevo2 --models-root /path/to/models
```

Overwrite an existing install:

```bash
python3 tools/model_manager_v2.py install pocket_tts --overwrite
```

Install a converter-style package that needs a source file:

```bash
python3 tools/model_manager_deprecated.py info voxcpm2_audiovae
python3 tools/model_manager_deprecated.py install voxcpm2_audiovae --source-file models/VoxCPM2/audiovae.pth --models-root models --overwrite
```

Kroko Community defaults to the ready-to-use GGUF package:

```bash
python3 tools/model_manager_v2.py install kroko_asr_community_q8_0 --models-root models --overwrite
```

The original Kroko `.data` conversion workflow remains documented in the
community model guide for users who want to build from the upstream source
package themselves.

## Package Notes

For shared audio.cpp GGUF packages, the v2 model manager installs the default GGUF.
That is usually `q8_0`; FP32-only packages such as Inflect Micro v2 use
original dtype instead. Other precision variants can be downloaded directly from
[audio-cpp/audio.cpp-gguf](https://huggingface.co/audio-cpp/audio.cpp-gguf).

Use `python3 tools/model_manager_v2.py list --json` for the current package
ids and defaults. The legacy loader/catalog sync notes are maintained only for
the deprecated catalog path.