GeminiTtsCli 0.9.4

Gemini TTS CLI

A command-line interface tool for text-to-speech conversion using Google's Gemini TTS API.

Features

• Convert text to speech using Google Gemini TTS API
• Multiple voice options (male and female voices)
• Support for custom instructions
• Output to WAV format or stdout
• Direct playback on Windows and macOS with --sayit
• Single output file from full --file content with --single-output
• Merge multiple WAV files into one with glob pattern support
• Batch processing from text/markdown files
• Concurrency support for batch TTS
• Cross-platform support (Windows, Linux, macOS)

Installation

Via .NET Global Tool (Recommended)

dotnet tool install -g GeminiTtsCli

Via dotnet dnx (No Installation)

dotnet dnx GeminiTtsCli "Text to convert"
dotnet dnx GeminiTtsCli "@input.txt"

The first bare argument is treated as a shortcut for --text. When the value starts with @, it is treated as a file reference, so @input.txt works as a quick shortcut for file-based input.

Windows Installer (.exe)

Download the Windows installer from the releases page and run gemini-tts-cli-<version>-win-x64-setup.exe.

The installer can:

• Install the CLI into Program Files
• Add the installation folder to PATH
• Register an uninstaller in Windows

Manual Installation

Download the appropriate binary for your platform from the releases page.

Prerequisites

1. Google AI Studio API Key: You need to obtain an API key from Google AI Studio
2. Environment Variable: Set the GEMINI_API_KEY environment variable with your API key
3. .NET 10: Required for building from source and for installing/running the .NET global tool or dotnet dnx

Setting up the API Key

Windows (PowerShell)

$env:GEMINI_API_KEY = "your-api-key-here"

Windows (Command Prompt)

set GEMINI_API_KEY=your-api-key-here

Linux/macOS

export GEMINI_API_KEY="your-api-key-here"

To make it permanent, add the export line to your shell profile (.bashrc, .zshrc, etc.).

Usage

Single Text to Speech

gemini-tts -t "Text to convert" [-i "Your instructions"] [-s <voice-name>] [-o output.wav] [--sayit]

Quick Execution via dotnet dnx

dotnet dnx GeminiTtsCli "Text to convert"
dotnet dnx GeminiTtsCli "@input.txt"

Use the usual options after the shortcut argument when needed, for example:

dotnet dnx GeminiTtsCli "Hello world" -s zephyr -o hello.wav
dotnet dnx GeminiTtsCli "@input.txt" --single-output -o full-text.wav

Batch Processing from File

gemini-tts -f "input.txt" [-i "Your instructions"] [-s <voice-name>] [-m] [-c 20] [-o output.wav] [--single-output] [--sayit]

Merge WAV Files

gemini-tts merge <glob-pattern> [-o <output-file>]

List Available Voices

gemini-tts list-voices

Parameters

• -t, --text (optional): Text to convert to speech (required if no -f)
• -f, --file (optional): File path for batch processing (.txt or .md files, required if no -t)
• -i, --instructions (optional): Instructions for the TTS conversion (default: "Read aloud in a warm, professional and friendly tone")
• -s, --speaker1 (optional): Voice name for the speaker (default: random selection from available voices)
• -o, --outputfile (optional): Output WAV filename (default: output.wav). Use "-" for stdout output
• --sayit (optional): Play audio directly on Windows or macOS and skip file output. With --file, the entire file is played as one stream
• --single-output (optional): Output a single WAV from the entire --file content (disables batch mode)
• -v, --version (optional): Show version and exit
• -c, --concurrency (optional): Concurrent API requests for batch processing (default: 1)
• -m, --merge (optional): Merge all outputs into single file for batch processing

Merge Command Parameters

• <glob-pattern> (required): Pattern to match WAV files (e.g., *.wav, trial03-*.wav, **/*.wav)
• -o, --outputfile (optional): Output WAV filename

Available Voices

Female Voices

• achernar, aoede, autonoe, callirrhoe, despina, erinome, gacrux, kore
• laomedeia, leda, sulafat, zephyr, pulcherrima, vindemiatrix

Male Voices

• achird, algenib, algieba, alnilam, charon, enceladus, fenrir, iapetus
• orus, puck, rasalgethi, sadachbia, sadaltager, schedar, umbriel, zubenelgenubi

Examples

With custom instructions and specific voice:

gemini-tts -i "Read aloud in a warm, professional and friendly tone" -s achird -t "大家好，我是 Will 保哥。" -o my-name-is-will.wav

With minimal required parameters (uses defaults):

gemini-tts -t "Hello, this is a test of the Gemini TTS system"

Run directly with dotnet dnx (no prior installation):

dotnet dnx GeminiTtsCli "Hello, this is a test of the Gemini TTS system"

Use a file reference shortcut with dotnet dnx:

dotnet dnx GeminiTtsCli "@test.txt"

With specific voice but default instructions:

gemini-tts -s zephyr -t "Hello, this is a test of the Gemini TTS system" -o greeting.wav

Play audio directly on Windows or macOS (no output file):

gemini-tts -t "Hello, this is a test of the Gemini TTS system" --sayit

Play an entire text file directly on Windows or macOS (no output file):

gemini-tts -f "test.txt" -s zephyr --sayit

Batch processing from file, with merge and concurrency:

gemini-tts -f "test.txt" -s zephyr -m -c 5 -o batch-merged.wav

Single output from entire file content (no batch):

gemini-tts -f "test.txt" -s zephyr --single-output -o full-text.wav

Batch processing from file, without merge (outputs numbered files):

gemini-tts -f "test.txt" -s zephyr -c 3
# Output: test-01.wav, test-02.wav, ...

List all available voices:

gemini-tts list-voices

Show version:

gemini-tts --version

Merge all WAV files in current directory:

gemini-tts merge '*.wav'
# Creates: merged.wav

Merge specific pattern with custom output:

gemini-tts merge 'trial03-*.wav' -o trial03-merged.wav
# Creates: trial03-merged.wav

Merge all WAV files recursively:

gemini-tts merge '**/*.wav' -o all-merged.wav
# Creates: all-merged.wav

Output to stdout (pipe to file or other processes):

gemini-tts -t "Hello world" -o - > output.wav
# or pipe to another command
gemini-tts -t "Hello world" -o - | aplay

Notes

• All input files for batch must have .txt or .md extension
• All input files for merge must have .wav extension
• Files with different audio formats will be converted to match the first file's format
• The pattern must include *.wav to ensure only WAV files are processed
• Recursive patterns (**/*.wav) will search subdirectories
• Either --text or --file must be provided, but not both
• --sayit is supported on Windows and macOS
• On macOS, --sayit uses the built-in afplay command for playback
• --sayit with --file plays the full file as a single stream instead of batch-generating WAV files
• --single-output cannot be used with --merge
• --sayit cannot be used with --merge
• API key must be set in the GEMINI_API_KEY environment variable

Development

Building from Source

1. Clone the repository
2. Restore dependencies: dotnet restore
3. Build: dotnet build
4. Run: dotnet run -- --text "Hello world"

Versioning (SemVer)

The project version is centralized in Directory.Build.props and validated by Directory.Build.targets.

Use the helper script to bump versions instead of editing project files manually:

./scripts/bump-version.ps1 -Part patch
./scripts/bump-version.ps1 -Part minor
./scripts/bump-version.ps1 -Part major
./scripts/bump-version.ps1 -Part prerelease -PrereleaseLabel rc
./scripts/bump-version.ps1 -Part release
./scripts/bump-version.ps1 -SetVersion 1.2.3

Publishing

The project supports two types of builds:

1. Global Tool (for NuGet distribution)

dotnet pack --configuration Release

This creates a .NET global tool package that can be installed via dotnet tool install -g GeminiTtsCli.

2. Self-Contained Executables (for standalone distribution)

For Windows x64:

dotnet publish --configuration Release --self-contained true --runtime win-x64 -p:PublishSelfContained=true

For Linux x64:

dotnet publish --configuration Release --self-contained true --runtime linux-x64 -p:PublishSelfContained=true

For macOS x64:

dotnet publish --configuration Release --self-contained true --runtime osx-x64 -p:PublishSelfContained=true

For macOS ARM64:

dotnet publish --configuration Release --self-contained true --runtime osx-arm64 -p:PublishSelfContained=true

The project includes automated GitHub Actions workflows for:

• Building cross-platform binaries
• Building a Windows installer (.exe) via Inno Setup
• Publishing to NuGet Gallery
• Creating GitHub releases

3. Windows Installer (Inno Setup)

Prerequisite:

• Install Inno Setup 6

Build installer locally (PowerShell):

./scripts/build-windows-installer.ps1

Specify a version explicitly (optional):

./scripts/build-windows-installer.ps1 -Version 0.7.2

Outputs:

• Published app files: artifacts/windows-installer/app/
• Installer executable: artifacts/windows-installer/out/

To trigger a release, create and push a git tag:

git tag v0.7.0
git push origin v0.7.0

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Acknowledgments

Google Cloud credits are provided for this project. #AISprint

We thank Google Cloud for supporting this project with credits that help make development and testing possible.