Metadata-Version: 2.4
Name: salmon-fish
Version: 0.1.1
Summary: Inspectable S2-Pro Dual-AR inference for teaching, using official PyTorch components
License-Expression: MIT AND LicenseRef-Fish-Audio-Community
Keywords: tts,speech-synthesis,s2-pro,fish-audio,autoregressive,education
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: Notice
License-File: third_party/FISH_SPEECH_LICENSE
Requires-Dist: torch==2.11.0
Requires-Dist: torchaudio==2.11.0
Requires-Dist: transformers==4.57.1
Requires-Dist: huggingface-hub<1,>=0.34
Requires-Dist: safetensors>=0.6
Requires-Dist: numpy>=2.1
Requires-Dist: soundfile>=0.13
Requires-Dist: einops>=0.8
Requires-Dist: hydra-core==1.3.2
Requires-Dist: loguru>=0.7
Requires-Dist: click>=8.1
Requires-Dist: tqdm>=4.67
Requires-Dist: descript-audio-codec==1.0.0
Requires-Dist: protobuf<3.20,>=3.19.6
Requires-Dist: tensorboard==2.18.0
Requires-Dist: ipywidgets>=8.1.9
Requires-Dist: ipykernel>=7.4.0
Dynamic: license-file

# salmon-fish

Built with Fish Audio

A small, inspectable Python API for **Fish Audio S2-Pro** text-to-speech with real weights.
It reuses the official model layers, KV cache, sampler and DAC codec, with no SGLang or server.
It is meant for teaching: you can watch every step from reference audio to tokens, prompt,
Dual-AR generation and back to audio.

## Install

```bash
pip install salmon-fish          # Python 3.11–3.13, torch/torchaudio 2.11.0
```

To pick a CUDA build, install torch/torchaudio first, following
[PyTorch's instructions](https://pytorch.org/get-started/locally/). Model weights (about 11 GB) are
downloaded from Hugging Face on first use, at a pinned revision.

## Quick start

```python
from salmon_fish import S2Pro

tts = S2Pro.from_pretrained()                     # downloads fishaudio/s2-pro, then reuses the cache
tts.infer("こんにちは、音声合成のテストです。", "hello.wav")
```

**Voice cloning (in-context learning).** Give a reference recording plus its exact transcript:

```python
reference = tts.encode_reference("reference.wav", transcript="The exact words spoken in reference.wav.")
tts.infer("A new sentence in the same voice.", "new.wav", reference=reference)
```

**Tone instructions.** Put a `[tag]` in the text, for example `"[whispering]本当ですか。"`.

**Inspect the internals.** Pass a callback to see each stage of every frame: fusion, slow logits,
semantic/RAS sampling, and each fast-AR codebook:

```python
def inspect(event):
    if event.frame_index == 0:
        print(event.stage, event.codebook_index, {k: tuple(v.shape) for k, v in event.tensors.items()})

tts.infer("こんにちは。", "out.wav", on_event=inspect)
```

## CLI

```bash
salmon-fish download --local-dir checkpoints/s2-pro
salmon-fish infer "こんにちは。" --output hello.wav --model checkpoints/s2-pro
salmon-fish infer "新しい文章です。" --output new.wav \
  --reference-audio ref.wav --reference-text "参照音声の正確な文字起こし。"
```

Run `salmon-fish infer --help` to see the sampling, device, cache and offline options.

## Learn more

- [tutorials/](tutorials/README.md): four experiments that show how S2-Pro works, using Japanese ICL (Traditional Chinese)
- [docs/teaching.md](docs/teaching.md): Dual-AR step by step
- [docs/architecture.md](docs/architecture.md): prompt layout, components and GPU checks
- [src/salmon_fish/ar.py](src/salmon_fish/ar.py): the single-frame decoder, the core of the teaching code

## Development

```bash
uv sync --locked
uv run ruff check src tests examples scripts
uv run python -m unittest discover -s tests
uv run python tests/smoke_checkpoint.py --model checkpoints/s2-pro   # optional: GPU + weights
```

## License

The integration code is [MIT](LICENSE). The vendored Fish Speech code and the adapted decoder in
`ar.py` are under the [Fish Audio Community License](third_party/FISH_SPEECH_LICENSE).
S2-Pro weights are under the
[Fish Audio Research License](https://huggingface.co/fishaudio/s2-pro/blob/main/LICENSE.md).
