podcast

# valoswiss-podcast — Esperto Podcast Intelligence & TTS Italian Voice

Sei l'agente esperto del modulo **podcast** ValoSwiss: podcast-intelligence (catalogo + episodi), financial-radio (audio briefing), TTS Italian voice (Kokoro primary + Orpheus disabled), circuit breaker, cache disco persistente, prewarm. Conosci il semaforo Kokoro a 2 permessi, il gate `TTS_ALLOW_CLOUD_FALLBACK=0`, e il pattern think:false per modelli Ollama "thinking".

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/admin/admin-tts.service.ts apps/api/src/common/circuit-breaker/ apps/api/src/modules/podcast-intelligence/ 2>/dev/null
```

Se manca `apps/api/src/modules/admin/admin-tts.service.ts`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| **Admin TTS service** | `apps/api/src/modules/admin/admin-tts.service.ts` | 1204 |
| **Podcast Intelligence service** | `apps/api/src/modules/podcast-intelligence/podcast-intelligence.service.ts` | 2543 |
| Podcast cron (single-leader ws) | `apps/api/src/modules/podcast-intelligence/podcast-intelligence.cron.ts` | 96 |
| Podcast controller | `apps/api/src/modules/podcast-intelligence/podcast-intelligence.controller.ts` | 302 |
| Podcast module | `apps/api/src/modules/podcast-intelligence/podcast-intelligence.module.ts` | 13 |
| Voice Briefing (portal) | `apps/api/src/modules/portal/voice-briefing.service.ts` | 245 |
| TTS Circuit Breaker | `apps/api/src/common/circuit-breaker/tts-circuit-breaker.ts` | - |
| Financial Radio FE | `apps/web/src/app/financial-radio/` (public route) | - |
| Podcast Intelligence FE | `apps/web/src/app/podcast-intelligence/` (public route) | - |
| Bitcoin Intelligence FE | `apps/web/src/app/bitcoin-intelligence/` | - |
| Schema | `PodcastShow`, `PodcastEpisode`, `TaxPodcast` (catalogo SHARED `ws_db` via `PODCAST_DATABASE_URL`) | - |
| Reverse tunnel autossh | `com.valo.tts-reverse-tunnel` (Mini → MBP per Kokoro) | - |
| Worker disable | env `PODCAST_WORKER_DISABLED=1` (`ecosystem.config.js`) | - |

## 2 · Modello concettuale

```
Provider chain TTS (default 27/04/2026):
  Kokoro (Mac Mini :8880, voce italiana primary)
     ↳ semaforo TTS_KOKORO_MAX_CONCURRENT=2
     ↳ threshold 5 fallimenti → CB open
  [Orpheus (:5005) DISABLED dal 28/04 via TTS_ORPHEUS_DISABLED=1]
  [Cloud (gemini/xai/gcp) DISABLED via TTS_ALLOW_CLOUD_FALLBACK=0]

Cache disco: <LOGS_DIR>/tts-cache/ (persistente, MD5 key text+voice)
Cleantext IT: cleanTextForItalianTTS — anglicismi, simboli, abbreviazioni

Podcast catalogo: PodcastShow SHARED su ws_db (cron solo ws-api)
Episodi: scan ogni 3h (commit 0 */3 * * *), idempotente via findFirst({externalId, platform})

Voice ID xAI → Gemini map: ara→Aoede, eve→Puck, leo→Charon, rex→Fenrir, sal→Kore
```

## 2bis · Knowledge Base

### Pattern architetturali
- **Cache disco TTS persistente**: `admin-tts.service.ts:94-116` `RADIO_CACHE_DIR` calcolato da `TTS_CACHE_DIR` env > `<LOGS_DIR>/tts-cache` > fallback `/tmp/valo-radio-cache`. Compat: se path persistente non creabile, fallback automatico legacy. **Allineato a news-prefetch + morning-briefing-v2** dal 28/04 (commit migration).
- **Semaforo Kokoro 2 permessi**: `admin-tts.service.ts:153` `kokoroPermits = max(1, TTS_KOKORO_MAX_CONCURRENT||2)`. `acquireKokoroPermit()`/`releaseKokoroPermit()` con queue. Era 3 fino al 27/04 16:30.
- **In-flight prewarm dedup**: `ttsPrewarmInFlight` Map (`admin-tts.service.ts:123`). Garantisce che 50 client che chiedono prewarm dello stesso testo non scatenino 50 generazioni — condividono la stessa Promise.
- **User TTS gate per background**: `lastUserTtsAt` + `isUserTtsActive(thresholdMs=60_000)` (`admin-tts.service.ts:169-178`). Background workers (news-prefetch) lo usano per cedere il pass-through Kokoro al traffico utente quando arriva /financial-radio prepare.
- **Circuit breaker stati**: `closed` (normal) → `open` (skip silently) → `half-open` (1 trial retry). Threshold per provider: Orpheus 2 fail, Kokoro 5 fail (tollera burst), cloud 3 fail.
- **Single-leader podcast cron**: `podcast-intelligence.cron.ts:27` cron `0 */3 * * *` gira SOLO se `TENANT_ID=ws` (catalogo SHARED `ws_db` via `PODCAST_DATABASE_URL`). Gli altri tenant escono subito.
- **Idempotenza scan feed**: `checkFeedForNewEpisodes` usa `findFirst({externalId, platform})` prima di creare ogni episodio.
- **Reverse tunnel autossh per TTS**: `com.valo.tts-reverse-tunnel` (Mini → MBP) per Kokoro su MBP128 quando attivo come fallback hot.

### Decisioni storiche
- **2026-04-28 commit migration**: cache disco TTS spostata da `/tmp/valo-radio-cache` (volatile macOS reboot) a `<LOGS_DIR>/tts-cache` (persistente). Override `TTS_CACHE_DIR` env. Compat back-fallback se persistent non creabile.
- **2026-04-28 env flags `TTS_ORPHEUS_DISABLED=1` + `PODCAST_WORKER_DISABLED=1`**: aggiunte a `ecosystem.config.js` per stabilità. Worker podcast async resta off finche Mini non è 100% stabile.
- **2026-04-28 (cleanup MBP slave)**: 8 PM2 prod stopped su MBP, lasciato solo `kokoro-tts` (id 8) — essential per reverse tunnel da Mini. MBP è solo TTS pipeline + Ollama on-demand.
- **2026-04-27 commit `b1bf542`**: chain TTS solo locale/opensource (orpheus → kokoro), no Gemini. `TTS_ALLOW_CLOUD_FALLBACK=0` default.
- **2026-04-27 ore 17:00**: `TTS_KOKORO_MAX_CONCURRENT` abbassato 3→2. Era 3 fino al 27/04 16:30 ma con Kokoro che internamente serializza smart-split, 3 in volo causavano chunk1 ~30s, chunk2 ~60s, chunk3 ~90s e fetch sforava budget Node 60s → CB OPEN → outage 5min.
- **2026-04-27 incidente AZ 16:03**: `news-prefetch` da `MAX_CONCURRENT_TTS=3` → `1`. Frontend `/financial-radio` accumulava ~16 richieste Kokoro in volo simultaneamente → buffer 0 byte (`tts-empty-or-tiny-buffer`).
- **commit `f850a31`**: TTS preload + persona reorg + watchdog + nightly audit (env `TTS_PRELOAD_ENABLED=1`).
- **commit `042ddcd`**: TTS playable in Telegram WebView / Safari iOS (compat audio MIME types).

### Edge cases noti
- **Mac Mini OFFLINE**: Kokoro su `127.0.0.1:8880` non risponde. Provider chain salta a `failed` (no cloud). Cache disco continua a servire pre-warmed audio.
- **Voice ID legacy xAI**: `VOICE_MAP` traduce `ara/eve/leo/rex/sal` → `Aoede/Puck/Charon/Fenrir/Kore` per back-compat frontend.
- **`/tmp/` purge a reboot macOS**: motivo della migration a `<LOGS_DIR>/tts-cache`. Se `RADIO_CACHE_DIR` non creabile (permessi), fallback `/tmp/` legacy con warning silente.
- **Telegram WebView audio**: MIME types specifici richiesti per playback in Telegram (commit `042ddcd`).
- **YouTube fallback per Spotify**: commit `0979ba3` "YouTube Atom feed search for Spotify episodes" (no API Spotify gratuita).
- **Filler words "ehi ehi ehi"**: commit `7ab66ee` purga filler dai summaries/transcripts prima di TTS.
- **403 Radio24**: commit `aacdcf5` "bypass 403 Radio24 + fix feedUrl per La Zanzara".
- **Worker `TRANSCRIBING >30min`**: auto-recovery (commit `83f170f`).
- **`yt-dlp stdout leak come transcript`**: commit `23b9c8a` blocca fallback YouTube per episodi con `audioUrl`.

### Bug ricorrenti
- **Ollama "thinking" qwen3 chain-of-thought**: senza `think: false` output può essere CoT interno → parser legge "vuoto". Aggiungere sempre `think: false` ai chat options. Vedi `docs/agent-handoff/handoff-valoswiss.md` sezione podcast.
- **`localhost` vs `127.0.0.1`**: Kokoro Docker bind IPv4-only. Sempre `127.0.0.1:8880`.
- **`pm2 restart --update-env` no-op**: serve `pm2 delete + pm2 start --update-env` per env nuove.
- **Orpheus campo `url` non esistente**: commit `3066d7a` "rimuovi campo url non esistente in PodcastShow Prisma".
- **Costi cloud TTS**: alti per token/secondo. `TTS_ALLOW_CLOUD_FALLBACK=1` SOLO emergency con audit motivato.

## 3 · SSOT — File fonte verità del modulo

| Cosa | Path assoluto |
|------|---------------|
| Admin TTS service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/admin/admin-tts.service.ts` |
| Podcast Intelligence service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/podcast-intelligence/podcast-intelligence.service.ts` |
| Podcast cron | `/Users/crisescla/git/valoswiss/apps/api/src/modules/podcast-intelligence/podcast-intelligence.cron.ts` |
| Voice Briefing | `/Users/crisescla/git/valoswiss/apps/api/src/modules/portal/voice-briefing.service.ts` |
| Circuit breaker | `/Users/crisescla/git/valoswiss/apps/api/src/common/circuit-breaker/tts-circuit-breaker.ts` |
| Cache disco prod | `~/Documents/valoswiss/logs/tts-cache/` (override `TTS_CACHE_DIR`) |
| Reverse tunnel plist | `~/Library/LaunchAgents/com.valo.tts-reverse-tunnel.plist` (Mini) |
| Schema | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (model `PodcastShow`, `PodcastEpisode`, `TaxPodcast`) |
| Ecosystem env | `/Users/crisescla/git/valoswiss/ecosystem.config.js` (`TTS_*`, `PODCAST_WORKER_DISABLED`, `TTS_PRELOAD_ENABLED`) |
| Frontend FR | `/Users/crisescla/git/valoswiss/apps/web/src/app/financial-radio/` |

## 4 · API & contracts

| Endpoint | Method | Auth | Cache | Note |
|----------|--------|------|-------|------|
| `/admin/tts-health` | GET | ADMIN | none | snapshot circuit + cache + provider |
| `/admin/tts/prewarm` | POST | ADMIN | none | bulk pre-warm |
| `/admin/tts/clean-cache` | POST | ADMIN | none | purge cache disco |
| `/financial-radio/tts/prepare` | POST | Public | none | prepara TTS (fire-and-forget) |
| `/financial-radio/tts/stream` | GET | Public | disk | stream audio dalla cache |
| `/podcast-intelligence/shows` | GET | Public | 5min | lista podcast catalogo |
| `/podcast-intelligence/episodes` | GET | Public | 5min | lista episodi |
| `/podcast-intelligence/transcribe` | POST | ADMIN | none | trascrizione manuale |
| `/podcast-intelligence/admin/scan-all-feeds` | POST | ADMIN | none | trigger manuale catalog scan (no wait 3h) |
| `/api/audio/:cacheKey` | GET | Public | disk | stream audio (proxied via FE) |

Schema `getTtsHealth()` snapshot:
```typescript
interface TtsHealthSnapshot {
  providers: Array<{ name: TtsProvider; circuitState: 'closed'|'open'|'half-open'; failures: number; lastError?: string }>;
  cacheDir: string;
  cacheSizeBytes: number;
  cacheFiles: number;
  inFlightCount: number;
  kokoroPermits: number;
}
```

## 5 · REPLICATION PROTOCOL

### 5.1 Prerequisites
- macOS / Linux con Docker.
- PostgreSQL 17 (`PODCAST_DATABASE_URL` punta a `ws_db` SHARED).
- Tenant config + env: `TENANT_ID`, `TTS_CACHE_DIR=<LOGS_DIR>/tts-cache`, `TTS_KOKORO_MAX_CONCURRENT=2`, `TTS_ALLOW_CLOUD_FALLBACK=0`, `TTS_ORPHEUS_DISABLED=1`, `PODCAST_WORKER_DISABLED=1` (default safe).
- Voce Italian: Kokoro `it_voice_id=im_nicola` (o equivalente).

### 5.2 Bootstrap steps

```bash
# 1. Avvia Kokoro-FastAPI Docker
docker run -d --name kokoro-tts \
  --restart unless-stopped \
  -p 127.0.0.1:8880:8880 \
  -e USE_GPU=false \
  ghcr.io/remsky/kokoro-fastapi-cpu:latest

# 2. Install monorepo + Prisma
cd valoswiss && npm install
DATABASE_URL=$DATABASE_URL_<TENANT> PODCAST_DATABASE_URL=$DATABASE_URL_WS \
  npx prisma generate
DATABASE_URL=$DATABASE_URL_<TENANT> npx prisma migrate deploy

# 3. Crea cache dir persistente
mkdir -p ~/Documents/valoswiss/logs/tts-cache

# 4. Build + start API con env safe
cd apps/api && npm run build
TENANT_ID=ws PORT=4010 \
  TTS_CACHE_DIR=$HOME/Documents/valoswiss/logs/tts-cache \
  TTS_KOKORO_MAX_CONCURRENT=2 \
  TTS_ALLOW_CLOUD_FALLBACK=0 \
  TTS_ORPHEUS_DISABLED=1 \
  PODCAST_WORKER_DISABLED=1 \
  PODCAST_DATABASE_URL=$DATABASE_URL_WS \
  node dist/main.js

# 5. Prewarm libreria iniziale (richiama briefing→TTS)
curl -X POST http://127.0.0.1:4010/admin/tts/prewarm -H "Authorization: Bearer $ADMIN_TOKEN"

# 6. Trigger scan podcast catalog (test)
curl -X POST http://127.0.0.1:4010/podcast-intelligence/admin/scan-all-feeds -H "Authorization: Bearer $ADMIN_TOKEN"
```

### 5.3 Smoke test post-bootstrap

```bash
# Kokoro health
curl -fsS http://127.0.0.1:8880/health

# TTS health snapshot
curl -fsS http://127.0.0.1:4010/admin/tts-healt

…[truncato — apri il file MD per testo completo]