madcat-tts 0.3.0__tar.gz

madcat_tts-0.3.0/.github/workflows/main.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

madcat_tts-0.3.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv
+.venv/
+venv
+venv/
+.python-version
+
+# uv
+uv.lock
+
+# Editors
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Local state / outputs
+/state.toml
+/tmp/
+*.wav
+*.onnx
+*.onnx.json
+
+# OS
+.DS_Store

madcat_tts-0.3.0/AGENTS.md

@@ -0,0 +1,148 @@
+# madcat-tts Agent Guide
+
+## Workspace Structure
+
+```
+madcat-tts/
+├── src/madcat_tts/
+│   ├── __main__.py         # Entry point: uvicorn launcher, env var parsing
+│   ├── main.py             # FastAPI app, EnginePool, route handlers
+│   ├── schemas.py          # Pydantic models (Voice, Cart, AudioSpeechRequest, …)
+│   ├── registry.py         # Cart catalog loader (TOML) + state persistence
+│   ├── normalize.py        # LLM-based text normalizer (vllm-tts LoRA via httpx)
+│   └── engines/
+│       ├── base.py         # Engine ABC + SynthResult dataclass
+│       ├── chatterbox.py   # ChatterboxMultilingualTTS, GPU-resident
+│       ├── piper.py        # PiperVoice ONNX, CPU-resident, lazy per-path cache
+│       └── xtts_proxy.py   # HTTP proxy to remote Auralis/XTTS-v2 backend
+├── conf/
+│   ├── carts/
+│   │   ├── bt7274.toml     # BT-7274 persona — chatterbox EN/PL + piper + xtts voices
+│   │   └── lessac.toml     # Piper CPU-only fallback voice
+│   └── madcat-tts.service  # systemd user unit (port 14099)
+├── install.sh              # Idempotent deploy script for sinanju
+├── pyproject.toml
+└── README.md
+```
+
+Runtime paths (XDG-based, not in-repo):
+- Cart catalog: `~/.config/madcat-tts/carts/*.toml`
+- Active state: `~/.local/state/madcat-tts/state.toml`
+- Voice refs (chatterbox WAVs): `~/.local/share/bt7274/*.wav`
+- Piper models: `~/piper-voices/*.onnx` (sibling `.onnx.json` required)
+
+## Key Commands
+
+```sh
+# Install / deploy to sinanju (idempotent)
+./install.sh
+
+# Reuse existing CUDA torch venv (for chatterbox on GB10/DGX/aarch64 CUDA 13)
+MADCAT_TTS_VENV=$HOME/cb ./install.sh
+
+# Run directly
+python -m madcat_tts
+# or
+madcat-tts
+
+# Build/sync venv
+uv sync
+
+# Systemd user unit management
+systemctl --user start madcat-tts
+systemctl --user restart madcat-tts
+systemctl --user status madcat-tts
+journalctl --user -u madcat-tts -f
+
+# Health check
+curl http://localhost:14099/health | python3 -m json.tool
+
+# List carts
+curl http://localhost:14099/carts
+
+# Switch active cart
+curl -X POST http://localhost:14099/carts/active -H 'Content-Type: application/json' -d '{"id":"bt7274"}'
+
+# Synthesize
+curl -X POST http://localhost:14099/v1/audio/speech \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Hello world","voice":"bt7274-en","response_format":"wav"}' \
+  --output out.wav
+```
+
+## Critical Implementation Details
+
+**Engine pool serialization:** Each engine is locked per-call (`threading.Lock`). GPU contention from chatterbox makes single-threading correct. Piper also benefits. Never add async synthesis — model init and inference are not async-safe.
+
+**Single worker only:** uvicorn runs `workers=1`. Engines are model-resident and not fork-safe. Do not change this.
+
+**Leading silence padding:** 300ms of zeros is prepended to every response (`MADCAT_TTS_LEADING_SILENCE_MS`, default 300). Compensates for AVAudioPlayer / afplay decode warmup latency on macOS. Override with `MADCAT_TTS_LEADING_SILENCE_MS=0` to disable.
+
+**XTTS proxy pattern:** Coqui XTTS-v2 requires `transformers==5.9.0`, chatterbox requires `transformers==5.2.0` — incompatible. XTTS runs in a separate process (Auralis on junkpile:8020). The `XttsProxyEngine` base64-encodes the local WAV ref, POSTs to the remote, decodes the audio response. Reference WAV is read from the daemon's local filesystem.
+
+**Auralis upstream bug workaround:** `AudioSpeechGenerationRequest.speed` has a trailing-comma tuple default in Auralis 0.2.8.post2 that raises `TypeError` on `<=` comparison when `speed` is absent. The proxy **always** sends `speed` explicitly. This is load-bearing — do not remove.
+
+**Voice resolution priority:**
+1. Exact voice id (e.g. `bt7274-en`)
+2. Cart tag (e.g. `bt7274`) → resolves to that cart's `default_voice`
+3. `null` / omitted → active voice from `state.toml`
+4. `list[str]` → ad-hoc base64 WAV clone (chatterbox only, first element used)
+
+**Engine init failures are non-fatal:** If chatterbox fails to load (CUDA unavailable, model missing), the daemon continues and returns HTTP 503 only for requests targeting that engine. Piper + xtts remain available.
+
+**Text normalization:** `TextNormalizer` calls a vLLM instance at `MADCAT_TTS_NORMALIZER_URL` (default `http://localhost:8002`) with the `qwen25-7b-tts-norm` LoRA model. Any failure falls back to raw text — normalization is best-effort. LRU cache (512 entries, configurable via `MADCAT_TTS_NORMALIZER_CACHE_SIZE`). Disable with `MADCAT_TTS_NORMALIZE=0`.
+
+**Audio formats:** Only `wav`, `flac`, `pcm` are actually supported despite `ResponseFormat` including `mp3`. Format table in `main.py` controls what soundfile gets asked to write.
+
+**State persistence:** `Registry._write_state()` uses atomic write (tmp file + rename). Reads back on daemon restart. If `state.toml` references a no-longer-existing cart/voice, it is ignored and the first cart's default voice is used.
+
+**Chatterbox params:** `cfg_weight` (0–1, default 0.5) and `exaggeration` (0–2, default 0.5). Cross-language references (e.g. EN voice for PL synthesis) often need `cfg_weight` lowered. `t3_model` param selects alternate checkpoint.
+
+**Piper voice caching:** `PiperEngine` caches loaded `PiperVoice` instances keyed by path. Multiple carts can share an ONNX model file without reloading.
+
+## Database / Storage
+
+No database. Two TOML-based stores:
+
+| Path | Purpose | Access |
+|------|---------|--------|
+| `~/.config/madcat-tts/carts/*.toml` | Cart catalog (voices, engine, params) | Read-only at runtime |
+| `~/.local/state/madcat-tts/state.toml` | Active cart + voice selection | Read/write by daemon |
+
+Cart file schema (per-file): `default_voice` string + `[[voices]]` array. Each voice: `id`, `engine`, `lang`, `description`, `voice_path`, `[params]`.
+
+## Development Notes
+
+- **Language:** Python 3.11+, uses `from __future__ import annotations` throughout
+- **Python version in use:** 3.14 (CPython, aarch64, sinanju/GB10)
+- **Framework:** FastAPI + uvicorn (single worker)
+- **Package manager:** uv — `uv sync` for fresh venv, `uv pip install` for reuse path
+- **Key deps:** `chatterbox-tts`, `piper-tts>=1.4.0`, `torch`, `soundfile`, `fastapi`, `httpx`, `pydantic>=2.7`, `tomli-w`
+- **TOML:** Read via stdlib `tomllib` (py3.11+), write via `tomli-w`
+- **Target host:** sinanju (DGX Spark / GB10 / aarch64 / CUDA 13)
+- **Service port:** 14099 (default)
+
+## Conventions
+
+- Engine names are lowercase string literals: `"chatterbox"`, `"piper"`, `"xtts"` — the `EngineName` `Literal` type in schemas.py is the source of truth
+- Voice IDs follow `<persona>-<lang>[-<engine>]` convention: `bt7274-en`, `bt7274-pl-xtts`, `bt7274-en-piper`
+- Cart tag = TOML filename stem: `bt7274.toml` → tag `bt7274`
+- All engine `synth()` calls return `SynthResult(audio: np.ndarray float32 [-1,1], sample_rate: int)` — encoding to WAV/FLAC/PCM happens in the HTTP layer
+- Response headers carry synthesis metadata: `X-Madcat-Cart`, `X-Madcat-Voice`, `X-Madcat-Engine`, `X-Madcat-Sample-Rate`, `X-Madcat-Duration-Sec`, `X-Madcat-Leading-Silence-Ms`
+- No multi-worker, no async synth — model-resident GPU engines are intentionally synchronous
+- Env vars follow `MADCAT_TTS_*` prefix convention
+
+## Entry Points
+
+| Surface | Detail |
+|---------|--------|
+| `python -m madcat_tts` | Main daemon entry (`__main__.py` → uvicorn) |
+| `madcat-tts` | Console script alias (same) |
+| `POST /v1/audio/speech` | OpenAI-compatible synthesis endpoint |
+| `GET /health` | Engine availability + normalizer stats |
+| `GET /carts` | Full cart catalog |
+| `POST /carts/active` | Switch active voice/cart |
+| `GET /docs` | FastAPI Swagger UI |
+| `Engine` ABC | `engines/base.py` — implement for new backends |
+| `Registry` | `registry.py` — cart catalog and state |
+| `EnginePool` | `main.py` — engine lifecycle, lock management |

madcat_tts-0.3.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: madcat-tts
+Version: 0.3.0
+Summary: TTS daemon (Chatterbox + Piper in-process; XTTS proxied) for the MADCAT OS substrate.
+Author: chi
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: chatterbox-tts
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy
+Requires-Dist: piper-tts>=1.4.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: setproctitle>=1.3
+Requires-Dist: soundfile
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: torch
+Requires-Dist: torchaudio
+Requires-Dist: uvicorn[standard]>=0.30

madcat_tts-0.3.0/README.md

@@ -0,0 +1,157 @@
+# madcat-tts
+
+Single TTS daemon fronting four engines behind one OpenAI-compatible HTTP
+endpoint.
+
+| engine             | location           | strengths                                    |
+| ------------------ | ------------------ | -------------------------------------------- |
+| `chatterbox`       | in-process, GPU    | Voice cloning, EN + PL, multilingual         |
+| `chatterbox-turbo` | in-process, GPU    | Fast single-step, paralinguistic tags (EN)   |
+| `piper`            | in-process, CPU    | Fast, deterministic, no GPU                  |
+| `xtts`             | HTTP-proxied       | XTTS-v2 zero-shot clone via remote backend   |
+
+## Install
+
+```sh
+pip install madcat-tts
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv pip install madcat-tts
+```
+
+## Quick start
+
+```sh
+# Start the daemon
+madcat-tts
+
+# Health check
+curl http://localhost:14099/health
+
+# Synthesize
+curl -X POST http://localhost:14099/v1/audio/speech \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Hello world","voice":"bt7274-en","response_format":"wav"}' \
+  --output out.wav
+```
+
+## Configuration
+
+Config lives in `~/.config/madcat/config.toml`:
+
+```toml
+[tts]
+host = "0.0.0.0"
+port = 14099
+log_level = "info"
+leading_silence_ms = 300
+
+[tts.normalizer]
+url = "http://localhost:8002"
+model = "qwen3-4b-tts-norm"
+enabled = true
+
+[tts.chunking]
+chunk_size = 250
+chunk_gap_ms = 200
+trim_silence = true
+max_silence_ms = 400
+```
+
+All settings have env var overrides (`MADCAT_TTS_HOST`, `MADCAT_TTS_PORT`,
+etc.) and sensible defaults. The daemon runs without a config file.
+
+## Endpoints
+
+| route                   | method | purpose                                                         |
+| ----------------------- | ------ | --------------------------------------------------------------- |
+| `/v1/audio/speech`      | POST   | OpenAI-compat synthesis. `voice` = cart/voice id or base64 WAVs |
+| `/carts`                | GET    | List cart catalog with active marker                            |
+| `/carts/active`         | GET    | Current active cart + voice                                     |
+| `/carts/active`         | POST   | Switch active cart/voice                                        |
+| `/health`               | GET    | Liveness + per-engine availability + normalizer stats           |
+| `/docs`                 | GET    | Swagger UI                                                      |
+
+## Carts
+
+A **cart** maps a persona to one or more voices. Each voice binds an engine,
+language, reference audio, and engine-specific params. Catalog lives at
+`~/.config/madcat/carts/*.toml` (one file per cart).
+
+Example cart (`bt7274.toml`):
+
+```toml
+default_voice = "bt7274-en-piper"
+
+[[voices]]
+id = "bt7274-en"
+engine = "chatterbox"
+lang = "en"
+description = "English voice — Chatterbox GPU cloning"
+voice_path = "/path/to/english.wav"
+
+[voices.params]
+cfg_weight = 0.5
+exaggeration = 0.5
+
+[[voices]]
+id = "bt7274-en-piper"
+engine = "piper"
+lang = "en"
+description = "English voice — Piper CPU fallback"
+voice_path = "/path/to/english.onnx"
+
+[voices.params]
+length_scale = 1.0
+```
+
+Active selection persists to `~/.local/share/madcat/tts-state.toml`.
+
+## Text normalization
+
+Optional LLM-based preprocessor that expands numbers, acronyms, and symbols
+before synthesis. Calls any OpenAI-compatible `/v1/chat/completions` endpoint.
+Disable with `MADCAT_TTS_NORMALIZE=0` or per-request `"normalize": false`.
+
+## Engine notes
+
+- **chatterbox**: Multilingual voice cloning. Requires CUDA GPU. 10s mono
+  reference WAV. Params: `cfg_weight` (0-1), `exaggeration` (0-2).
+- **chatterbox-turbo**: 350M parameter English-only model. Supports
+  paralinguistic tags: `[laugh]`, `[chuckle]`, `[cough]`, `[sigh]`,
+  `[gasp]`, `[groan]`. Single-step decoder, lighter VRAM.
+- **piper**: CPU ONNX inference. Deterministic. Voice = `.onnx` file with
+  sibling `.onnx.json` config. Params: `length_scale`, `noise_scale`.
+- **xtts**: HTTP proxy to a remote XTTS-v2 backend (e.g. Auralis). Configure
+  via `MADCAT_TTS_XTTS_URL` (default `http://localhost:8020`).
+
+Engine init failures are non-fatal — the daemon stays up and returns 503
+only for requests targeting unavailable engines.
+
+## Layout
+
+```
+src/madcat_tts/
+├── __main__.py           # uvicorn launcher
+├── main.py               # FastAPI app, EnginePool, routes
+├── schemas.py            # Pydantic models
+├── registry.py           # Cart catalog + state persistence
+├── config.py             # Config reader (~/.config/madcat/config.toml)
+├── normalize.py          # LLM text normalizer
+├── chunker.py            # Sentence-boundary chunking
+├── postprocess.py        # Audio post-processing (silence trim/compress)
+├── pcart.py              # Cart format utilities
+└── engines/
+    ├── base.py           # Engine ABC + SynthResult
+    ├── chatterbox.py     # ChatterboxMultilingualTTS
+    ├── chatterbox_turbo.py # ChatterboxTurboTTS (paralinguistic)
+    ├── piper.py          # PiperVoice ONNX
+    └── xtts_proxy.py     # HTTP proxy to remote backend
+```
+
+## License
+
+MIT

madcat_tts-0.3.0/conf/carts/bt7274.toml

@@ -0,0 +1,60 @@
+# BT-7274 — Vanguard-class Titan AI
+# Voices across multiple TTS engines for the canonical persona.
+
+default_voice = "bt7274-en-piper"
+
+[[voices]]
+id = "bt7274-pl"
+engine = "chatterbox"
+lang = "pl"
+description = "Canonical Polish voice — Chatterbox GPU cloning, 10s reference"
+voice_path = "/home/madcat/.local/share/bt7274/canonical_pl_ref_22k_mono.wav"
+
+[voices.params]
+cfg_weight = 0.5
+exaggeration = 0.5
+
+
+[[voices]]
+id = "bt7274-en"
+engine = "chatterbox"
+lang = "en"
+description = "Canonical English voice — Chatterbox GPU cloning, 10s reference"
+voice_path = "/home/madcat/.local/share/bt7274/canonical_en_ref_22k_mono.wav"
+
+[voices.params]
+cfg_weight = 0.5
+exaggeration = 0.5
+
+
+[[voices]]
+id = "bt7274-en-xtts"
+engine = "xtts"
+lang = "en"
+description = "English via XTTS-v2 zero-shot clone — proxied to Auralis on junkpile"
+voice_path = "/home/madcat/.local/share/bt7274/canonical_en_ref_22k_mono.wav"
+
+[voices.params]
+speed = 1.0
+
+
+[[voices]]
+id = "bt7274-pl-xtts"
+engine = "xtts"
+lang = "pl"
+description = "Polish via XTTS-v2 zero-shot clone — proxied to Auralis on junkpile"
+voice_path = "/home/madcat/.local/share/bt7274/canonical_pl_ref_22k_mono.wav"
+
+[voices.params]
+speed = 1.0
+
+
+[[voices]]
+id = "bt7274-en-piper"
+engine = "piper"
+lang = "en"
+description = "English via Piper ONNX — fast CPU fallback, custom trained"
+voice_path = "/home/madcat/piper-voices/bt7274.onnx"
+
+[voices.params]
+length_scale = 1.0

madcat_tts-0.3.0/conf/carts/lessac.toml

@@ -0,0 +1,14 @@
+# Lessac — Piper CPU fallback voice
+# No cloning, fast deterministic synthesis. CPU-only baseline.
+
+default_voice = "lessac"
+
+[[voices]]
+id = "lessac"
+engine = "piper"
+lang = "en"
+description = "Piper lessac medium — fast EN fallback, no GPU required"
+voice_path = "/home/madcat/piper-voices/en_US-lessac-medium.onnx"
+
+[voices.params]
+length_scale = 1.0

madcat_tts-0.3.0/conf/madcat-tts.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=madcat-tts — MADCAT OS TTS daemon (Chatterbox + Piper in-process)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/Projects/madcat-tts
+Environment=PYTHONUNBUFFERED=1
+Environment=MADCAT_TTS_HOST=0.0.0.0
+Environment=MADCAT_TTS_PORT=14099
+Environment=MADCAT_TTS_LOG=info
+# XTTS proxy target. Sin runs Auralis locally on :8020.
+Environment=MADCAT_TTS_XTTS_URL=http://localhost:8020
+# LLM text normalizer (vllm-tts LoRA). Set MADCAT_TTS_NORMALIZE=0 to bypass.
+Environment=MADCAT_TTS_NORMALIZER_URL=http://localhost:8002
+# uv-managed venv at $WorkingDirectory/.venv
+ExecStart=%h/Projects/madcat-tts/.venv/bin/python -m madcat_tts
+Restart=on-failure
+RestartSec=5s
+
+[Install]
+WantedBy=default.target

madcat_tts-0.3.0/conf/personas/bt7274.pcart/cart.toml

@@ -0,0 +1,40 @@
+schema_version = 1
+
+[persona]
+slug = "bt7274"
+name = "bt7274"
+type = "assistant"
+tagline = ""
+prompt = "prompt.md"
+default_lang = "pl"
+
+[theme]
+palette = "default"
+typography = "sans"
+mode = "dark"
+accent = ""
+
+[sink]
+default = ""
+
+[voices.pl]
+id = "bt7274-pl"
+backend = "chatterbox"
+lang = "pl"
+voice_path = "/home/madcat/.local/share/bt7274/canonical_pl_ref_22k_mono.wav"
+description = "Canonical Polish voice — Chatterbox GPU cloning, 10s reference"
+
+[voices.pl.params]
+cfg_weight = 0.5
+exaggeration = 0.5
+
+[voices.en]
+id = "bt7274-en"
+backend = "chatterbox"
+lang = "en"
+voice_path = "/home/madcat/.local/share/bt7274/canonical_en_ref_22k_mono.wav"
+description = "Canonical English voice — Chatterbox GPU cloning, 10s reference"
+
+[voices.en.params]
+cfg_weight = 0.5
+exaggeration = 0.5

madcat_tts-0.3.0/conf/personas/lessac.pcart/cart.toml

@@ -0,0 +1,28 @@
+schema_version = 1
+
+[persona]
+slug = "lessac"
+name = "lessac"
+type = "assistant"
+tagline = ""
+prompt = "prompt.md"
+default_lang = "en"
+
+[theme]
+palette = "default"
+typography = "sans"
+mode = "dark"
+accent = ""
+
+[sink]
+default = ""
+
+[voices.en]
+id = "lessac"
+backend = "piper-remote"
+lang = "en"
+voice_path = "/home/madcat/piper-voices/en_US-lessac-medium.onnx"
+description = "Piper lessac medium — fast EN fallback, no GPU required"
+
+[voices.en.params]
+length_scale = 1.0

madcat_tts-0.3.0/conf/vllm-tts.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=vLLM TTS Normalizer (Qwen3-4B-Instruct-2507)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=madcat
+Group=sudo
+ExecStart=/usr/local/bin/vllm serve --config /etc/vllm/tts.yaml
+Restart=on-failure
+RestartSec=5
+Environment="HF_HOME=/home/madcat/.cache/huggingface"
+Environment="HF_TOKEN=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"
+Environment="CUDA_VISIBLE_DEVICES=0"
+Environment="VLLM_USAGE_SOURCE=production"
+
+[Install]
+WantedBy=multi-user.target

madcat_tts-0.3.0/conf/vllm-tts.yaml

@@ -0,0 +1,30 @@
+# vLLM config — TTS text normalizer (Qwen3-4B-Instruct-2507)
+# Replaces Qwen2.5-1.5B: stronger multilingual (119 langs, incl. Polish),
+# no LoRA needed — base instruct model handles TTS normalization via prompting.
+# Non-thinking-only variant: no CoT overhead, fast inference for text transforms.
+
+# ── Model ────────────────────────────────────────────────────
+model: Qwen/Qwen3-4B-Instruct-2507
+served-model-name: qwen3-4b-tts-norm
+dtype: auto
+
+# ── Context & Batching ───────────────────────────────────────
+# Normalization is short-form: inputs rarely exceed 200 tokens.
+max-model-len: 1024
+max-num-seqs: 4
+max-num-batched-tokens: 1024
+
+# ── Memory Management ───────────────────────────────────────
+# 4B model is ~8GiB in bf16. On GB10's 128GB unified memory,
+# 0.15 = ~19GiB — enough for weights + KV cache + activations.
+# Old value 0.08 (10GiB) left barely 2GiB for KV cache.
+gpu-memory-utilization: 0.15
+
+# ── Performance ──────────────────────────────────────────────
+# Prefix caching helps when the same system prompt is reused
+# across all normalization calls (which it is).
+enable-prefix-caching: true
+
+# ── Network ──────────────────────────────────────────────────
+host: 0.0.0.0
+port: 8002