### Development Setup - Cloning and Dependencies

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Bash commands to clone the Qwen3-TTS repository and install development dependencies using pip.

```bash
# Clone repository
git clone https://github.com/kritsanan1/Qwen3-TTS.git
cd Qwen3-TTS

# Install development dependencies
pip install -r requirements-dev.txt
```

--------------------------------

### Speaker Recording Interface Setup

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Configures and initializes the ProfessionalAudioRecorder with specified audio settings and launches the GUI interface for professional speaker recording.

```python
from professional_recording_system import ProfessionalAudioRecorder, RecordingInterfaceConfig

# Configure recording
config = RecordingInterfaceConfig(
    sample_rate=48000,
    show_waveform=True,
    show_spectrum=True
)

# Create recorder
recorder = ProfessionalAudioRecorder(config)

# Start recording interface
recorder.run_gui_interface()
```

--------------------------------

### Production Deployment Server Setup

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Creates and starts a production-ready REST API server using FastAPI, configured with predefined production settings for the TTS system.

```python
from production_deployment_system import create_production_server, PRODUCTION_CONFIG

# Create and start server
server = create_production_server(PRODUCTION_CONFIG)
server.start_server()
```

--------------------------------

### Installation

Source: https://context7.com/kritsanan1/qwen3-tts/llms.txt

Instructions for installing the qwen-tts package and optional dependencies.

```APIDOC
## Installation

Install the qwen-tts package from PyPI for quick setup.

```bash
# Create a clean Python environment
conda create -n qwen3-tts python=3.12 -y
conda activate qwen3-tts

# Install the package
pip install -U qwen-tts

# Optional: Install FlashAttention 2 for better performance
pip install -U flash-attn --no-build-isolation
```
```

--------------------------------

### Install Qwen3-TTS from Source

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

This snippet shows how to install the Qwen3-TTS package in editable mode from a local Git repository. This is useful for development or modifying the code. It requires cloning the repository first.

```bash
git clone https://github.com/QwenLM/Qwen3-TTS.git
cd Qwen3-TTS
pip install -e .
```

--------------------------------

### Install Dependencies for Thai-Isan TTS

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Installs the necessary Python packages for the Thai-Isan TTS system, including PyTorch with CUDA support for GPU acceleration.

```bash
pip install -r requirements-thai-isan.txt

# For GPU support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

--------------------------------

### Install Qwen3-TTS Package

Source: https://context7.com/kritsanan1/qwen3-tts/llms.txt

Installs the qwen-tts package and optional FlashAttention 2 for improved performance. It includes steps for creating and activating a Conda environment.

```bash
# Create a clean Python environment
conda create -n qwen3-tts python=3.12 -y
conda activate qwen3-tts

# Install the package
pip install -U qwen-tts

# Optional: Install FlashAttention 2 for better performance
pip install -U flash-attn --no-build-isolation
```

--------------------------------

### Install FlashAttention 2 for Qwen3-TTS

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

This snippet demonstrates how to install FlashAttention 2, which can reduce GPU memory usage for Qwen3-TTS. It includes instructions for systems with limited RAM and highlights hardware compatibility requirements.

```bash
pip install -U flash-attn --no-build-isolation
# For systems with less than 96GB RAM and many CPU cores:
MAX_JOBS=4 pip install -U flash-attn --no-build-isolation
```

--------------------------------

### Docker Production Deployment Configuration

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

A Dockerfile for building a production image of the Qwen3-TTS application. It installs dependencies, copies application code, and exposes the necessary port.

```dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements-thai-isan.txt .
RUN pip install -r requirements-thai-isan.txt

COPY . .
EXPOSE 8000

CMD ["python", "production_deployment_system.py"]
```

--------------------------------

### Set up Qwen3-TTS Python Environment

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

This snippet outlines the steps to set up a Python 3.12 environment for Qwen3-TTS using Conda and install the 'qwen-tts' package. It emphasizes using an isolated environment to prevent dependency conflicts.

```bash
conda create -n qwen3-tts python=3.12 -y
conda activate qwen3-tts
pip install -U qwen-tts
```

--------------------------------

### Install Dependencies for Thai-Isan TTS

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_README.md

Installs necessary Python libraries for the Thai-Isan TTS project, including PyTorch, Transformers, Librosa, and Streamlit for the demo interface.

```bash
pip install torch transformers librosa soundfile numpy scipy
pip install streamlit  # For demo interface
pip install jiwer    # For evaluation
```

--------------------------------

### Model Training Pipeline Initialization

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Sets up the ThaiIsanTTSModel and ThaiIsanTrainer with specified training configurations, including epochs, batch size, and learning rate, then initiates the training process.

```python
from enhanced_training_pipeline import ThaiIsanTTSModel, ThaiIsanTrainer, TrainingConfig

# Configure training
config = TrainingConfig(
    num_epochs=100,
    batch_size=32,
    learning_rate=2e-5
)

# Create model and trainer
model = ThaiIsanTTSModel(config)
trainer = ThaiIsanTrainer(model, config)

# Train model
trainer.train(train_dataloader, val_dataloader)
```

--------------------------------

### Download Qwen3-TTS Models via HuggingFace CLI

Source: https://context7.com/kritsanan1/qwen3-tts/llms.txt

This bash script demonstrates how to download Qwen3-TTS models and tokenizer using the HuggingFace CLI. It covers downloading the tokenizer, 1.7B parameter models (CustomVoice, VoiceDesign, Base), 0.6B parameter models (CustomVoice, Base), and provides instructions for installation.

```bash
# Download via HuggingFace CLI
pip install -U "huggingface_hub[cli]"

# Tokenizer
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz --local-dir ./Qwen3-TTS-Tokenizer-12Hz

# 1.7B Models
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local-dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir ./Qwen3-TTS-12Hz-1.7B-Base

# 0.6B Models (smaller, faster)
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-Base --local-dir ./Qwen3-TTS-12Hz-0.6B-Base
```

--------------------------------

### Download Qwen3-TTS Models using Hugging Face CLI

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

This snippet shows how to download Qwen3-TTS model weights locally using the Hugging Face CLI. It requires the 'huggingface_hub' package to be installed. The commands specify the model name and the local directory for download.

```bash
pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz --local-dir ./Qwen3-TTS-Tokenizer-12Hz
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local-dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir ./Qwen3-TTS-12Hz-1.7B-Base
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-Base --local-dir ./Qwen3-TTS-12Hz-0.6B-Base
```

--------------------------------

### Download Qwen3-TTS Models using ModelScope

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

This snippet demonstrates how to download Qwen3-TTS model weights locally using the ModelScope CLI. It requires the 'modelscope' package to be installed. The commands specify the model name and the local directory for download.

```bash
pip install -U modelscope
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz  --local_dir ./Qwen3-TTS-Tokenizer-12Hz 
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local_dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-Base --local_dir ./Qwen3-TTS-12Hz-1.7B-Base
modelscope download --model Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-12Hz-0.6B-Base --local_dir ./Qwen3-TTS-12Hz-0.6B-Base
```

--------------------------------

### API Documentation Access

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Provides links to access the interactive API documentation.

```APIDOC
## API Documentation Access

### Description
Access interactive API documentation for detailed endpoint information and testing.

### Swagger UI
- **URL:** `http://localhost:8000/docs`

### ReDoc
- **URL:** `http://localhost:8000/redoc`
```

--------------------------------

### AWS ECS Docker Image Build and Push

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Bash commands to build a Docker image for the Qwen3-TTS application and push it to AWS Elastic Container Registry (ECR).

```bash
# Build and push to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ECR_REPO
docker build -t thai-isn-tts .
docker tag thai-isn-tts:latest $ECR_REPO/thai-isn-tts:latest
docker push $ECR_REPO/thai-isn-tts:latest
```

--------------------------------

### Start Production Thai-Isan TTS API Server (Bash)

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/IMPLEMENTATION_COMPLETE.md

Initiates the production-ready REST API server for the Thai-Isan TTS system. It uses FastAPI and provides access to API documentation via a '/docs' endpoint.

```bash
# Start production API server
python production_deployment_system.py

# Access API documentation
# Open browser to: http://localhost:8000/docs
```

--------------------------------

### Generate Voice Design TTS with Qwen3 TTS Model (Python)

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

Shows how to utilize the `generate_voice_design` function from `Qwen3TTSModel` for text-to-speech with specific voice characteristics. This function requires the `qwen_tts` and `soundfile` libraries. It accepts text, language, and a natural language instruction to guide the voice style, producing audio waveforms and sample rate.

```python
import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

# single inference
wavs, sr = model.generate_voice_design(
    text="哥哥，你回来啦，人家等了你好久好久了，要抱抱！",
    language="Chinese",
    instruct="体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显，营造出黏人、做作又刻意卖萌的听觉效果。",
)
sf.write("output_voice_design.wav", wavs[0], sr)

# batch inference
wavs, sr = model.generate_voice_design(
    text=[
      "哥哥，你回来啦，人家等了你好久好久了，要抱抱！",
      "It's in the top drawer... wait, it's empty? No way, that's impossible! I'm sure I put it there!"
    ],
    language=["Chinese", "English"],
    instruct=[
      "体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显，营造出黏人、做作又刻意卖萌的听觉效果。",
      "Speak in an incredulous tone, but with a hint of panic beginning to creep into your voice."
    ]
)
sf.write("output_voice_design_1.wav", wavs[0], sr)
sf.write("output_voice_design_2.wav", wavs[1], sr)
```

--------------------------------

### Launch Qwen3-TTS Local Web UI Demo

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

Provides commands to launch the Qwen3-TTS web UI demo locally. The demo can be run with different models (CustomVoice, VoiceDesign, Base) and accessed via a web browser. Requires the 'qwen-tts' package.

```bash
qwen-tts-demo --help
```

```bash
# CustomVoice model
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000
# VoiceDesign model
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --ip 0.0.0.0 --port 8000
# Base model
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base --ip 0.0.0.0 --port 8000
```

--------------------------------

### Batch Synthesis API Request

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Example of a curl command to synthesize multiple text requests in a batch using the TTS API, including priority.

```bash
curl -X POST "http://localhost:8000/synthesize/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"text": "สวัสดีครับ", "language": "th"},
      {"text": "สบายดีบ่", "language": "tts"}
    ],
    "priority": "high"
  }'
```

--------------------------------

### Launch Qwen3-TTS Web UI Demo (Bash)

Source: https://context7.com/kritsanan1/qwen3-tts/llms.txt

Launches an interactive Gradio web interface for testing Qwen3-TTS models. This command allows users to select different model types (CustomVoice, VoiceDesign, Base) and configure parameters like IP address, port, and device settings. HTTPS is required for microphone access with the Base model for voice cloning.

```bash
# Launch CustomVoice demo
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000

# Launch VoiceDesign demo
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --ip 0.0.0.0 --port 8000

# Launch Base model demo (voice cloning)
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base --ip 0.0.0.0 --port 8000

# With custom settings
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
    --device cuda:0 \
    --dtype bfloat16 \
    --flash-attn \
    --ip 0.0.0.0 \
    --port 8000 \
    --max-new-tokens 2048 \
    --temperature 0.9

# With HTTPS for microphone access (required for Base model voice cloning)
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base \
    --ip 0.0.0.0 --port 8000 \
    --ssl-certfile cert.pem \
    --ssl-keyfile key.pem \
    --no-ssl-verify
```

--------------------------------

### Enable HTTPS for Qwen3-TTS Base Model Demo

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

Shows how to generate SSL certificates and launch the Qwen3-TTS Base model demo with HTTPS enabled. This is recommended to avoid browser microphone permission issues. Requires 'openssl'.

```bash
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost"
```

```bash
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base \
  --ip 0.0.0.0 --port 8000 \
  --ssl-certfile cert.pem \
  --ssl-keyfile key.pem \
  --no-ssl-verify
```

--------------------------------

### Single Text Synthesis API Request

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Example of a curl command to synthesize a single piece of text using the TTS API, specifying text, language, speed, and quality.

```bash
curl -X POST "http://localhost:8000/synthesize" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "สวัสดีครับ",
    "language": "th",
    "speed": 1.0,
    "quality": "high"
  }'
```

--------------------------------

### Encode and Decode Audio with Qwen3TTSTokenizer

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/README.md

Demonstrates how to use the Qwen3TTSTokenizer to encode audio from a URL and decode it back into a waveform. Requires the 'soundfile' and 'qwen-tts' libraries. Outputs a WAV file.

```python
import soundfile as sf
from qwen_tts import Qwen3TTSTokenizer

tokenizer = Qwen3TTSTokenizer.from_pretrained(
    "Qwen/Qwen3-TTS-Tokenizer-12Hz",
    device_map="cuda:0",
)

enc = tokenizer.encode("https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/tokenizer_demo_1.wav")
wavs, sr = tokenizer.decode(enc)
sf.write("decode_output.wav", wavs[0], sr)
```

--------------------------------

### GET /languages

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_README.md

Retrieves a list of all languages supported by the Qwen3-TTS model.

```APIDOC
## GET /languages

### Description
Retrieves a list of all languages supported by the Qwen3-TTS model.

### Method
GET

### Endpoint
`/languages`

### Response

#### Success Response (200)
- **languages** (array) - A list of supported language codes.

### Response Example
```json
{
  "languages": [
    "th",
    "tts"
  ]
}
```
```

--------------------------------

### GET /speakers

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_README.md

Retrieves a list of available speakers for a specified language.

```APIDOC
## GET /speakers

### Description
Retrieves a list of available speakers for a specified language.

### Method
GET

### Endpoint
`/speakers`

### Query Parameters

- **language** (string) - Required - The language to get speakers for (e.g., 'th', 'tts').

### Response

#### Success Response (200)
- **speakers** (array) - A list of speaker IDs available for the specified language.

### Response Example
```json
{
  "speakers": [
    "speaker_001",
    "speaker_002",
    "speaker_003"
  ]
}
```
```

--------------------------------

### Batch Synthesis

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Synthesizes speech from multiple text requests in a batch.

```APIDOC
## POST /synthesize/batch

### Description
Synthesizes speech from multiple text requests in a batch, allowing for a priority setting.

### Method
POST

### Endpoint
`/synthesize/batch`

### Parameters
#### Request Body
- **requests** (array) - Required - A list of synthesis requests.
  - Each request object should have:
    - **text** (string) - Required - The text to synthesize.
    - **language** (string) - Required - The language of the text.
- **priority** (string) - Optional - The priority of the batch request (e.g., 'high').

### Request Example
```json
{
  "requests": [
    {"text": "สวัสดีครับ", "language": "th"},
    {"text": "สบายดีบ่", "language": "tts"}
  ],
  "priority": "high"
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of synthesis results corresponding to the requests.
  - Each result object may contain:
    - **audio_content** (string) - The synthesized audio content.
    - **error** (string) - An error message if synthesis failed for this request.

#### Response Example
```json
{
  "results": [
    {"audio_content": "/9j/4AAQSkZJRgABAQ..."},
    {"error": "Language not supported"}
  ]
}
```
```

--------------------------------

### Single Text Synthesis

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Synthesizes speech from a single piece of text.

```APIDOC
## POST /synthesize

### Description
Synthesizes speech from a single piece of text with specified language, speed, and quality.

### Method
POST

### Endpoint
`/synthesize`

### Parameters
#### Request Body
- **text** (string) - Required - The text to synthesize.
- **language** (string) - Required - The language of the text (e.g., 'th').
- **speed** (float) - Optional - The speech speed (default: 1.0).
- **quality** (string) - Optional - The audio quality (e.g., 'high', default: 'high').

### Request Example
```json
{
  "text": "สวัสดีครับ",
  "language": "th",
  "speed": 1.0,
  "quality": "high"
}
```

### Response
#### Success Response (200)
- **audio_content** (string) - The synthesized audio content (e.g., base64 encoded).

#### Response Example
```json
{
  "audio_content": "/9j/4AAQSkZJRgABAQ...")
}
```
```

--------------------------------

### Prepare Training Data for Qwen3-TTS

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/finetuning/README.md

This script prepares the training data by converting a raw JSONL file into a format that includes audio codes, which are necessary for fine-tuning the Qwen3-TTS model. It requires the input JSONL file, a tokenizer model path, and specifies the output JSONL file and the CUDA device to use.

```bash
python prepare_data.py \
  --device cuda:0 \
  --tokenizer_model_path Qwen/Qwen3-TTS-Tokenizer-12Hz \
  --input_jsonl train_raw.jsonl \
  --output_jsonl train_with_codes.jsonl
```

--------------------------------

### Monitoring and Observability

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

This section details the available Prometheus metrics for monitoring the TTS service and the health check endpoints.

```APIDOC
## Monitoring and Observability

### Prometheus Metrics

- `thai_isan_tts_requests_total` - Total API requests
- `thai_isan_tts_request_duration_seconds` - Request latency
- `thai_isan_tts_active_connections` - Active connections
- `thai_isan_tts_cache_hit_rate` - Cache performance
- `thai_isan_tts_model_load_time` - Model loading time

### Health Checks

- **Endpoint:** `/health`
- **Method:** GET
- **Description:** Checks the health status of the TTS service.

- **Endpoint:** `/metrics`
- **Method:** GET
- **Description:** Retrieves Prometheus metrics for monitoring.
```

--------------------------------

### Load Qwen3 TTS Models with from_pretrained

Source: https://context7.com/kritsanan1/qwen3-tts/llms.txt

Loads Qwen3 TTS models using HuggingFace-style initialization. Supports CustomVoice, VoiceDesign, and Base models, automatically loading configuration, weights, processor, and generation defaults. Requires PyTorch and the qwen-tts package.

```python
import torch
from qwen_tts import Qwen3TTSModel

# Load CustomVoice model
model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

# Load VoiceDesign model
voice_design_model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

# Load Base model for voice cloning
base_model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)
```

--------------------------------

### Health and Metrics Endpoint Checks

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Demonstrates how to check the health and retrieve metrics from the running TTS service using curl commands.

```bash
# Health check endpoint
curl http://localhost:8000/health

# Metrics endpoint
curl http://localhost:8000/metrics
```

--------------------------------

### Initialize Thai-Isan Data Collector in Python

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/TESTING_REFACTORING_REPORT.md

This Python code snippet shows how to import and use the refactored data collection modules. It demonstrates initializing the `ThaiIsanDataCollector` with a `DataCollectionConfig` object, highlighting the system's ability to handle optional dependencies.

```python
from data_collection_pipeline_refactored import ThaiIsanDataCollector, DataCollectionConfig

# Create configuration
config = DataCollectionConfig(
    target_hours_thai=100,
    target_hours_isan=100,
    min_speakers_per_language=50
)

# Initialize collector
collector = ThaiIsanDataCollector(config)

# The system will work with or without optional dependencies

```

--------------------------------

### Google Cloud Run Deployment

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

gcloud command to deploy the Qwen3-TTS application to Google Cloud Run, configuring memory, CPU, and maximum instances.

```bash
# Deploy to Cloud Run
gcloud run deploy thai-isn-tts \
  --image gcr.io/PROJECT_ID/thai-isn-tts \
  --platform managed \
  --region us-central1 \
  --memory 4Gi \
  --cpu 2 \
  --max-instances 10
```

--------------------------------

### Download Qwen3-TTS Models via ModelScope

Source: https://context7.com/kritsanan1/qwen3-tts/llms.txt

This bash script shows how to download Qwen3-TTS models using the ModelScope library, which is recommended for users in China. It demonstrates downloading the tokenizer and a 1.7B CustomVoice model.

```bash
# Download via ModelScope (recommended for China)
pip install -U modelscope
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz --local_dir ./Qwen3-TTS-Tokenizer-12Hz
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
```

--------------------------------

### Run Thai-Isan TTS Demo Interface

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_README.md

Provides the command to launch the interactive Streamlit demo interface for the Thai-Isan TTS system.

```bash
streamlit run thai_isan_demo.py
```

--------------------------------

### Kubernetes Deployment Manifest

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

A Kubernetes Deployment manifest to manage the Qwen3-TTS application. It specifies the number of replicas, container image, port, and resource requests/limits.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: thai-isn-tts
spec:
  replicas: 3
  selector:
    matchLabels:
      app: thai-isn-tts
  template:
    metadata:
      labels:
        app: thai-isn-tts
    spec:
      containers:
      - name: thai-isn-tts
        image: thai-isn-tts:latest
        ports:
        - containerPort: 8000
        resources:
          requests:
            memory: "2Gi"
            cpu: "1"
          limits:
            memory: "4Gi"
            cpu: "2"
```

--------------------------------

### Run Tests with Python Script

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/TESTING_REFACTORING_REPORT.md

This bash script demonstrates how to execute various test suites for the project using the `run_tests.py` script. It supports running all tests, specific test types (unit, integration, performance), or individual test files.

```bash
# Run all tests
python run_tests.py

# Run specific test types
python run_tests.py --unit          # Unit tests only
python run_tests.py --integration   # Integration tests only
python run_tests.py --performance   # Performance tests only

# Run specific test
python run_tests.py --specific tests/unit/test_data_collection.py
```

--------------------------------

### Python Integration Test Execution

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Commands to execute integration tests for the TTS API, model inference, and quality evaluation using Python scripts.

```bash
# Test API endpoints
python tests/test_api.py

# Test model inference
python tests/test_model.py

# Test quality evaluation
python tests/test_quality.py
```

--------------------------------

### Create Reusable Voice Clone Prompts

Source: https://context7.com/kritsanan1/qwen3-tts/llms.txt

Builds reusable voice clone prompts from reference audio to avoid recomputing features, enabling efficient generation of multiple utterances with a consistent cloned voice. This involves creating a prompt once and then using it for subsequent voice cloning tasks.

```python
import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

ref_audio = "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/clone.wav"
ref_text = "Okay. Yeah. I resent you. I love you. I respect you. But you know what? You blew it!"

# Create reusable voice clone prompt (extracts features once)
prompt_items = model.create_voice_clone_prompt(
    ref_audio=ref_audio,
    ref_text=ref_text,
    x_vector_only_mode=False,
)

# Generate multiple utterances with the same voice
sentences = [
    "No problem! I actually finished those already. Want to compare answers?",
    "What? No! I mean yes but not like... I just think your technique is really precise!",
    "This is amazing! I can't believe how well this works.",
]

for i, sentence in enumerate(sentences):
    wavs, sr = model.generate_voice_clone(
        text=sentence,
        language="English",
        voice_clone_prompt=prompt_items,  # Reuse the prompt
    )
    sf.write(f"reusable_clone_{i}.wav", wavs[0], sr)

# Batch generation with reusable prompt
wavs, sr = model.generate_voice_clone(
    text=sentences,
    language=["English", "English", "English"],
    voice_clone_prompt=prompt_items,
)
for i, w in enumerate(wavs):
    sf.write(f"batch_clone_{i}.wav", w, sr)
```

--------------------------------

### Data Collection with ThaiIsanDataCollector

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Initializes the ThaiIsanDataCollector and collects speech data from a specified number of Thai and Isan speakers. Outputs the total hours of collected data.

```python
from enhanced_data_collection import ThaiIsanDataCollector

# Initialize collector
collector = ThaiIsanDataCollector()

# Collect data from speakers
results = collector.collect_data_from_speakers(
    num_speakers_thai=50,  # 50 Thai speakers
    num_speakers_isan=50   # 50 Isan speakers
)

print(f"Collected {results['total_hours']:.2f} hours of speech data")
```

--------------------------------

### Speech Quality Evaluation

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/THAI_ISAN_COMPLETE_GUIDE.md

Utilizes the ThaiIsanQualityEvaluator to assess the quality of synthesized speech against reference audio, providing objective metrics like overall quality and tone accuracy.

```python
from comprehensive_quality_assurance import ThaiIsanQualityEvaluator

# Initialize evaluator
evaluator = ThaiIsanQualityEvaluator()

# Evaluate speech
result = evaluator.evaluate_speech(
    synthesized_audio=audio_data,
    reference_audio=reference_audio,
    text="สวัสดีครับ",
    language="th"
)

print(f"Quality Score: {result.objective_metrics.overall_quality_score:.3f}")
print(f"Tone Accuracy: {result.objective_metrics.tone_accuracy:.3f}")
```

--------------------------------

### Quick Inference Test with Qwen3-TTS

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/finetuning/README.md

This Python script demonstrates how to perform a quick inference test after fine-tuning the Qwen3-TTS model. It loads the fine-tuned model from a specified checkpoint, generates audio for a given text and speaker, and saves the output to a WAV file. Dependencies include PyTorch and SoundFile.

```python
import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

device = "cuda:0"
tts = Qwen3TTSModel.from_pretrained(
    "output/checkpoint-epoch-2",
    device_map=device,
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

wavs, sr = tts.generate_custom_voice(
    text="She said she would be here by noon.",
    speaker="speaker_test",
)
sf.write("output.wav", wavs[0], sr)
```

--------------------------------

### Fine-tune Qwen3-TTS Model (SFT)

Source: https://github.com/kritsanan1/qwen3-tts/blob/main/finetuning/README.md

This script performs supervised fine-tuning (SFT) on the Qwen3-TTS model using the prepared training data. It requires the path to the initial model, an output directory for checkpoints, the path to the training JSONL file, batch size, learning rate, number of epochs, and a speaker name.

```bash
python sft_12hz.py \
  --init_model_path Qwen/Qwen3-TTS-12Hz-1.7B-Base \
  --output_model_path output \
  --train_jsonl train_with_codes.jsonl \
  --batch_size 2 \
  --lr 2e-5 \
  --num_epochs 3 \
  --speaker_name speaker_test
```