google-api-server 0.1.0
Streaming audio processor for Google Cloud Speech-to-Text, Text-to-Speech, and Translation APIs
License: MIT
Requires Python: >=3.8
Keywords: google-cloud, speech-to-text, text-to-speech, translation, streaming, audio-processing

# google-api-server

Comprehensive Google Cloud API server supporting Speech-to-Text, Text-to-Speech, and Translation services

## Features

- Stream-based audio processing and conversion
- Google Cloud Speech-to-Text integration
- Google Cloud Text-to-Speech integration
- **Google Cloud Translation with concurrent multi-language support (fastest speed)**
- Support for multiple audio formats (WEBM, WAV, FLAC, MP3)
- Real-time streaming recognition with interim and final results
- Domain-Driven Design (DDD) architecture with clean separation of concerns

## Installation

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

## Usage

### CLI Usage

The CLI provides easy access to Speech-to-Text and Text-to-Speech functionality:

```bash
# Speech to Text - Convert audio to transcript
python main.py stt audio.webm --lang zh-CN --output transcript.txt

# Text to Speech - Convert text to audio
python main.py tts "Hello world" --lang en --output speech.mp3 --format mp3

# List available voices
python main.py list-voices --lang zh-CN

# Get help
python main.py --help
```

### Python API Usage

```python
from google_api_server import StreamingAudioProcessor

processor = StreamingAudioProcessor(
    credentials_path="path/to/credentials.json",
    language_code="zh-CN"
)

# Process audio from callback
results = processor.process_stream_from_callback(chunk_callback, input_format="webm")

# Or process audio bytes directly
results = processor.process_audio_bytes_stream(audio_bytes, input_format="webm")
```

## Requirements

- Python >= 3.8
- ffmpeg (for audio conversion)
- Google Cloud credentials JSON file
- Google Cloud Translation API enabled in your Google Cloud project

## Testing

### Using Pytest (Recommended)

```bash
# Run all pytest-based tests
pytest tests/

# Run specific test file
pytest tests/test_translation_pytest.py

# Run with verbose output
pytest -v tests/

# Run performance tests only
pytest -m performance tests/
```

### HTTP Integration Tests (Real Server)

Test using real HTTP requests against a running server:

```bash
# Automatic: Start server + run tests + stop server
python run_http_tests.py

# Manual: Run tests against running server
pytest tests/test_translation_http.py -v
```

HTTP tests verify:
- ✅ Real HTTP request/response cycle
- ✅ Full API stack integration
- ✅ Server lifecycle management
- ✅ End-to-end functionality

### Integration Tests

Run integration tests for the translation API:

```bash
# Run translation integration tests
python tests/test_translation_integration.py

# Or use pytest
pytest tests/test_translation_pytest.py -v
```

The integration tests verify:
- Single language translation
- Multi-language concurrent translation
- Language detection
- Performance benchmarks (concurrent vs sequential)
- Error handling

### Testing Translation API

```bash
# Using the test script
python test_translation_api.py
```

### Quick Test Commands

```bash
# Fast pytest run
python run_pytest.py

# Custom pytest options
pytest tests/test_translation_pytest.py -k test_single -v
```

## Docker Usage

**Note:** The `google.json` credentials file is already included in the Docker image.

### Using Docker Compose (Recommended)

1. Build and run the container:

```bash
docker-compose up -d
```

2. The API will be available at `http://localhost:8000`

3. Stop the container:

```bash
docker-compose down
```

### Using Docker

1. Build the Docker image:

```bash
docker build -t google-api-server .
```

2. Run the container:

```bash
docker run -d -p 8000:8000 google-api-server
```

3. The API will be available at `http://localhost:8000`

**Note:** The credentials file (`google.json`) is already bundled in the Docker image, so no volume mounting is required.

### Docker Health Check

The container includes a health check that monitors the API:

```bash
# Check container health
docker ps  # Look for "healthy" status

# View health check logs
docker inspect --format='{{json .State.Health}}' google-api-server
```

### Testing the API

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

# Text-to-Speech
curl --form 'text="你好世界"' --form 'language_code="zh-CN"' http://localhost:8000/tts

# Translation - Single language
curl --form 'text="Hello World"' --form 'source_language="en"' --form 'target_language="zh-CN"' http://localhost:8000/translation/translate

# Translation - Multiple languages (concurrent, fastest speed)
curl --form 'text="Hello World"' --form 'source_language="en"' --form 'target_languages="zh-CN,ja,es,fr,de,ru"' http://localhost:8000/translation/translate-multiple

# Language Detection
curl --form 'text="Hello World"' http://localhost:8000/translation/detect-language
```

## Translation API

The translation API supports:
- **Single language translation**: Translate text from one language to another
- **Multi-language translation**: Translate to multiple languages simultaneously using concurrent API calls for fastest speed
- **Language detection**: Automatically detect the language of input text

### Translation Endpoints

#### POST `/translation/translate`
Translate text to a single target language.

**Parameters:**
- `text`: Text to translate
- `source_language`: Source language code (e.g., 'en')
- `target_language`: Target language code (e.g., 'zh-CN')

#### POST `/translation/translate-multiple`
Translate text to multiple target languages concurrently (fastest speed).

**Parameters:**
- `text`: Text to translate
- `source_language`: Source language code (e.g., 'en')
- `target_languages`: Comma-separated list of target language codes (e.g., 'zh-CN,ja,es,fr,de')

**Features:**
- Uses concurrent API calls for maximum speed
- All translations happen simultaneously
- Returns a dictionary mapping target languages to translated texts

#### POST `/translation/detect-language`
Detect the language of input text.

**Parameters:**
- `text`: Text to detect language for

### Supported Language Codes

Common language codes include:
- `en` - English
- `zh-CN` - Simplified Chinese
- `ja` - Japanese
- `es` - Spanish
- `fr` - French
- `de` - German
- `ru` - Russian
- `ko` - Korean
- And many more...

For a complete list of supported languages, refer to the [Google Cloud Translation API documentation](https://cloud.google.com/translate/docs/languages).