# Snapshots decoder /opt/Kazeia/kazeia-tts-decoder-ggml/src/

Le repo decoder est externe (mono-repo /opt/Kazeia, fichiers untracked en
pratique). Ces snapshots gardent une trace des modifications apportées pour
Phase 2 du chantier BigVGAN HMX.

## Modifications par fichier

### decoder.h
- Ajout `std::vector<ggml_backend_t> backends` + `ggml_backend_sched_t sched`
  dans `struct Decoder`.
- Ajout `bool owns_backends` pour la libération.
- Nouvelle méthode `load_with_backends(path, devs)` : variante de
  `load_with_buft` qui prend une liste de backends et crée optionnellement
  un sched (gated par env `KZTTS_DECODER_SCHED`).
- Nouvelle méthode `compute_graph(ctx, gf, n_threads)` qui dispatche vers
  `sched_compute` si sched actif, sinon `ggml_graph_compute_with_ctx` legacy.

### gguf_loader.cpp
- Impl de `load_with_backends` : alloue les poids sur le buft du backend[0]
  (HTP si présent) via `load_with_buft`. Sched créé seulement si
  `KZTTS_DECODER_SCHED=1` (le sched complet nécessite refactor des stages).
- Impl de `compute_graph` : sched path ou compute_with_ctx legacy.
- `unload()` libère sched + backends si `owns_backends`.

### decoder.cpp
- Ajout du timing par stage dans `Decoder::forward` (gated par
  `KZTTS_DECODER_PROFILE=1`). Imprime quant/preconv/pretr/upsample/bigvgan.
- (pas d'autres modifs structurelles : le refactor stage_bigvgan en pattern
  sched-friendly reste à faire dans la session suivante)

## Modes de fonctionnement

| Env | Effet |
|---|---|
| (rien) | path CPU pur historique, poids CPU buffer (default) |
| `KZTTS_DECODER_HTP=1` | poids alloués sur HTP buffer, compute CPU pur via `opt_hostbuf=1` (HTP buffer CPU-mappable). Pas de gain HMX mais valide la chaîne. |
| `KZTTS_DECODER_HTP=1 KZTTS_DECODER_SCHED=1` | sched créé, mais stages encore en compute_with_ctx → assertion `buffer_id >= 0` au premier compute. **NE FONCTIONNE PAS** sans refactor stages. |

## Reste à faire (Phase 2 session suivante)

Refactor de `stage_bigvgan` (et causal_conv1d_TC, apply_snake_TC,
precompute_snake) pour le pattern sched :

1. `ggml_init(no_alloc=true)` avec mem_size réduit (metadata only)
2. `ggml_set_input(input_tensor)` sur l'input host
3. `ggml_set_output(output_tensor)` sur l'output final
4. Remplacer `memset(zeros->data)` + `ggml_concat` par `ggml_pad_ext`
5. Remplacer `precompute_snake` host (exp, 1/x) par ops in-graph
   `ggml_exp + ggml_div`
6. Wrapping `sched_reset` + `sched_alloc_graph` +
   `ggml_backend_tensor_set(input)` + `sched_graph_compute` +
   `ggml_backend_tensor_get(output)`

Snake `sin` n'est pas supporté HTP → sched fallback automatique vers CPU
pour cette op. Le ping-pong est borné (snake = 0.4 Gops total sur 115).

Estimation : ~70 lignes propres, ~1 session focalisée. Cibles : decoder
3.2s → ~0.5-0.8s (gain ×4-6 réaliste avec HMX sur MUL_MAT).

## Rebuild

```
cd /opt/Kazeia/kazeia-tts-decoder-ggml/build-android-engine && \
  make qwen3tts-decoder -j$(nproc)
# puis côté Kazeia-engine
cd /opt/Kazeia-engine/dist && ./build_tts_pipeline.sh
```