Metadata-Version: 2.1
Name: tsclient
Version: 1.0.1
Summary: Python client library for Talkscriber Live Transcription and Text-to-Speech services
Home-page: https://github.com/Talkscriber/ts-client
Author: Talkscriber
Author-email: Talkscriber <support@talkscriber.com>
Maintainer-email: Talkscriber <support@talkscriber.com>
License: MIT License
        
        Copyright (c) 2024 Talkscriber
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://talkscriber.com
Project-URL: Documentation, https://docs.talkscriber.com
Project-URL: Repository, https://github.com/Talkscriber/ts-client
Project-URL: Bug Tracker, https://github.com/Talkscriber/ts-client/issues
Project-URL: Dashboard, https://app.talkscriber.com
Keywords: talkscriber,speech-to-text,text-to-speech,transcription,tts,stt,websocket,real-time,audio,speech
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: ffmpeg-python>=0.2.0
Requires-Dist: PyAudio>=0.2.11
Requires-Dist: websocket-client>=1.6.0
Requires-Dist: websockets>=11.0.0
Requires-Dist: loguru>=0.7.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"

# TSClient - Talkscriber Python Client

[![PyPI version](https://badge.fury.io/py/tsclient.svg)](https://badge.fury.io/py/tsclient)
[![Python Support](https://img.shields.io/pypi/pyversions/tsclient.svg)](https://pypi.org/project/tsclient/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://pepy.tech/badge/tsclient)](https://pepy.tech/project/tsclient)
[![GitHub stars](https://img.shields.io/github/stars/Talkscriber/ts-client.svg)](https://github.com/Talkscriber/ts-client)

A comprehensive Python client library for Talkscriber's Live Transcription and Text-to-Speech services. This package provides easy-to-use APIs for real-time speech-to-text transcription and ultra-low latency text-to-speech conversion.

## Features

### Live Transcription
- Real-time speech-to-text transcription via WebSocket
- Support for 50+ languages
- Smart turn detection using ML models
- Translation capabilities
- File and microphone input support

### Text-to-Speech
- Ultra-low latency streaming (speech starts in <0.1 seconds)
- Real-time audio playback
- Multiple voice options
- Audio file saving
- Configurable buffering for optimal performance

## Installation

### Quick Install

```bash
pip install tsclient
```

### System Dependencies

The package requires some system-level dependencies for audio processing:

**macOS:**
```bash
# Install PortAudio (required for PyAudio)
brew install portaudio

# Then install the package
pip install tsclient
```

**Ubuntu/Debian:**
```bash
# Install system dependencies
sudo apt-get update
sudo apt-get install libasound2-dev portaudio19-dev python3-dev

# Then install the package
pip install tsclient
```

**Windows:**
```bash
# No additional setup required - just install the package
pip install tsclient
```

**CentOS/RHEL/Fedora:**
```bash
# Install system dependencies
sudo yum install portaudio-devel python3-devel
# or for newer versions:
sudo dnf install portaudio-devel python3-devel

# Then install the package
pip install tsclient
```

### Development Install

For development or to run examples:

```bash
git clone https://github.com/Talkscriber/ts-client.git
cd ts-client
pip install -e .
```

## Quick Start

### Get Your API Key

1. Visit [Talkscriber Dashboard](https://app.talkscriber.com)
2. Sign up or log in
3. Generate an API key
4. Set it as an environment variable:

```bash
export TALKSCRIBER_API_KEY="your_api_key_here"
```

### Live Transcription

```python
from talkscriber.stt import TranscriptionClient

# Initialize client
client = TranscriptionClient(
    host="wss://api.talkscriber.com",
    port=9090,
    api_key="your_api_key",
    language="en"
)

# Start live transcription from microphone
client()

# Or transcribe from file
client("audio_file.wav")
```

### Text-to-Speech

```python
from talkscriber.tts import TalkScriberTTSClient

# Initialize TTS client
tts_client = TalkScriberTTSClient(
    api_key="your_api_key",
    text="Hello, world!",
    speaker_name="tara"
)

# Generate and play speech
tts_client.run_simple_test()
```

## Command Line Interface

The package includes convenient CLI tools:

### Live Transcription CLI

```bash
# Transcribe from microphone
talkscriber-stt --api-key YOUR_KEY --language en

# Transcribe from file
talkscriber-stt --api-key YOUR_KEY --file audio.wav

# Enable multilingual detection
talkscriber-stt --api-key YOUR_KEY --multilingual
```

### Text-to-Speech CLI

```bash
# Basic TTS
talkscriber-tts --api-key YOUR_KEY --text "Hello, world!"

# Save to file
talkscriber-tts --api-key YOUR_KEY --text "Hello" --save output.wav

# Use specific voice
talkscriber-tts --api-key YOUR_KEY --text "Hello" --speaker tara
```

## API Reference

### Live Transcription

#### TranscriptionClient

```python
TranscriptionClient(
    host: str,
    port: int,
    api_key: str,
    multilingual: bool = False,
    language: str = None,
    translate: bool = False,
    enable_turn_detection: bool = False,
    turn_detection_timeout: float = 0.6
)
```

**Parameters:**
- `host`: WebSocket host URL
- `port`: WebSocket port number
- `api_key`: Your Talkscriber API key
- `multilingual`: Enable auto language detection
- `language`: Language code (e.g., "en", "es", "fr")
- `translate`: Enable translation
- `enable_turn_detection`: Enable ML-based turn detection
- `turn_detection_timeout`: Timeout for turn detection

### Text-to-Speech

#### TalkScriberTTSClient

```python
TalkScriberTTSClient(
    host: str = "api.talkscriber.com",
    port: int = 9099,
    text: str,
    speaker_name: str = "tara",
    api_key: str,
    enable_playback: bool = True,
    save_audio_path: str = None
)
```

**Parameters:**
- `host`: TTS server hostname
- `port`: TTS server port
- `text`: Text to convert to speech
- `speaker_name`: Voice to use
- `api_key`: Your Talkscriber API key
- `enable_playback`: Enable real-time audio playback
- `save_audio_path`: Optional path to save audio file

## Supported Languages

The client supports 50+ languages including English, Spanish, French, German, Chinese, Japanese, and many more. See the [full language list](https://docs.talkscriber.com/languages) in our documentation.

## Examples

Check out the `examples/` directory for comprehensive examples organized by category:

### Quick Start
```bash
# First, install the package
pip install tsclient

# Then run examples
# Interactive demo (recommended for beginners)
python examples/integration/comprehensive_demo.py

# Basic STT (microphone)
python examples/stt/basic.py

# Basic TTS (text-to-speech)
python examples/tts/basic.py
```

### Example Categories

**Speech-to-Text (STT):**
- **`stt/basic.py`** - Real-time microphone transcription
- **`stt/file.py`** - Transcribe audio files
- **`stt/multilingual.py`** - Automatic language detection

**Text-to-Speech (TTS):**
- **`tts/basic.py`** - Basic TTS with real-time playback
- **`tts/save_file.py`** - Generate and save audio files
- **`tts/silent.py`** - Silent TTS generation
- **`tts/different_voices.py`** - Multiple voice comparison
- **`tts/batch.py`** - Batch processing from text files

**Integration:**
- **`integration/stt_to_tts.py`** - Complete voice processing pipeline
- **`integration/comprehensive_demo.py`** - Interactive demo

**Configuration:**
- **`configuration/config_patterns.py`** - Configuration patterns and best practices

See the [examples README](examples/README.md) for detailed usage instructions and the complete directory structure.

## Documentation

- [Full Documentation](https://docs.talkscriber.com)
- [API Reference](https://docs.talkscriber.com/api)
- [Language Support](https://docs.talkscriber.com/languages)

## Links

- [Talkscriber Dashboard](https://app.talkscriber.com) - Get your API key
- [Official Website](https://talkscriber.com)
- [GitHub Repository](https://github.com/Talkscriber/ts-client)

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

