gcp-chirp 0.1.0
A premium CLI tool for Google Cloud Text-to-Speech Chirp 3 HD voices
Requires Python: >=3.13
Keywords: ai, chirp, chirp-3-hd, cli, google-cloud, text-to-speech, tts

# 🎙️ gcp-chirp

A premium CLI tool for working with **Google Cloud Text-to-Speech Chirp 3 HD** voices. Chirp 3 HD is a new generation of expressive, high-fidelity voices powered by Google's latest LLMs.

## 📋 Prerequisites

Before you begin, ensure you have the following installed and configured:

1.  **FFmpeg**: Required for audio processing.
    ```bash
    # macOS
    brew install ffmpeg
    ```
2.  **Google Cloud Project**:
    - Enable the **Text-to-Speech API**.
    - Set up **Application Default Credentials (ADC)**. Follow the [official documentation](https://docs.cloud.google.com/docs/authentication/application-default-credentials).
    - *Note*: You may need to perform a one-time setup for the `gcloud` CLI:
      ```bash
      gcloud auth application-default login
      ```

## 🚀 Features

- **Expressive Synthesis**: High-fidelity audio with natural intonation.
- **Voice Listing**: Easily list available Chirp 3 HD voices across languages.
- **Modern CLI**: Beautiful output powered by `rich` and `typer`.
- **Managed by uv**: Lightning fast dependency management.

## 📦 Installation

### Via PyPI (Recommended)
This is the easiest way to install the tool globally:
```bash
uv tool install gcp-chirp
```

### From Source
If you are developing or want to run it locally:
```bash
git clone https://github.com/msampathkumar/gcp-chirp
cd gcp-chirp
uv sync
```

## 🗑 Uninstallation
To remove the tool and its local data:

1. **Clean local configuration**:
   ```bash
   gcp-chirp uninstall
   ```
2. **Remove the global tool**:
   ```bash
   uv tool uninstall gcp-chirp
   ```

## 🔑 Authentication

The tool uses Google Cloud **Application Default Credentials (ADC)** by default.

1.  **ADC (Recommended)**: Run the following command if you haven't already:
    ```bash
    gcloud auth application-default login
    ```
2.  **Service Account Key**: If using a service account JSON:
    ```bash
    export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/key.json"
    ```
3.  **CLI Option**: Alternatively, pass the path directly via the `--creds` option in the `say` command.

## 🛠 Usage

### 🚀 Quick Start (One-time Setup)
Run the setup wizard to check dependencies (FFmpeg, gcloud), configure authentication, and set initial defaults:
```bash
uv run gcp-chirp setup
```

### Configuration Precedence
The tool follows a strict precedence for settings:
1.  **CLI Flags**: (e.g., `--project`, `--voice`, `--play`) always win.
2.  **Config File**: (`~/.gcp-chirp/settings.yaml`).
3.  **Environment Variables**: (e.g., `GOOGLE_CLOUD_PROJECT`).

### ⚙️ Configuration Commands

#### Interactive Setup
Set your default project, voice, and output preferences:
```bash
uv run gcp-chirp config
```

#### View Current Configuration
```bash
uv run gcp-chirp config --show
```

#### Reset Configuration
Reset all settings to factory defaults:
```bash
uv run gcp-chirp config-reset
```

### 📋 Action Commands

#### List Voices
List available voices for a language (uses default language if omitted):
```bash
uv run gcp-chirp list --project my-temporary-project
```

#### Synthesize Speech
Convert text to audio with overrides:
```bash
uv run gcp-chirp say "Hello, I am synthesized using a specific project and voice!" --voice en-US-Chirp3-HD-Charon --project my-project --play
```

*Note: Files are saved in the configured `output_dir` with a timestamped filename unless `--output` is provided.*

## 🏗 Track Status

Managed via `conductor/tracks.md`.

---
*Built with ❤️ for the Empire.*