# dtelecom-stt

Python SDK for dTelecom real-time speech-to-text with [x402](https://www.x402.org/) micropayments.

Pay-per-minute STT powered by Whisper and Parakeet, with automatic blockchain payments on Base.

## Install

```bash
pip install dtelecom-stt
```

## Quick Start

```python
import asyncio
from dtelecom_stt import STTClient

async def main():
    client = STTClient(private_key="0x...")

    async with client.session(minutes=5, language="en") as stream:
        async for t in stream.transcribe_file("meeting.wav"):
            print(f"[{t.start:.1f}s] {t.text}")

asyncio.run(main())
```

## Real-Time Streaming

```python
import asyncio
from dtelecom_stt import STTClient

async def main():
    client = STTClient(private_key="0x...")

    async with client.session(minutes=5, language="en") as stream:
        # Callback-based
        stream.on_transcription(lambda t: print(t.text))

        # Send audio chunks (PCM16, 16kHz, mono)
        await stream.send_audio(pcm_bytes)

        # Or iterate asynchronously
        async for t in stream.transcriptions():
            print(t.text)

asyncio.run(main())
```

## Auto-Extend Sessions

Sessions automatically buy more time when running low (enabled by default):

```python
# 30-minute session that auto-extends
async with client.session(minutes=30, language="en") as stream:
    # When <60s remaining, SDK buys 5 more minutes automatically
    async for t in stream.transcriptions():
        print(t.text)

# Disable auto-extend
async with client.session(minutes=5, auto_extend=False) as stream:
    ...
```

## Audio Format

The server expects **PCM16, 16kHz, mono** audio. Convert with ffmpeg:

```bash
ffmpeg -i input.mp3 -ar 16000 -ac 1 -acodec pcm_s16le output.wav
```

## Pricing

```python
info = await client.pricing()
print(f"${info.price_per_minute_usd}/min ({info.currency} on {info.network})")
```

Current pricing: **$0.005/min** (USDC on Base Sepolia testnet).

## API Reference

### `STTClient(private_key, url=None)`

Main client. Default URL: `https://x402stt.dtelecom.org`.

- `session(minutes=5, language="en", auto_extend=True)` — Create a paid session (async context manager)
- `pricing()` — Get pricing info
- `health()` — Check server health

### `Stream`

Returned by `client.session()`. Async context manager.

- `send_audio(data: bytes)` — Send raw PCM16 audio
- `transcriptions()` — Async iterator of `Transcription` objects
- `transcribe_file(path)` — Stream a WAV file and yield transcriptions
- `on_transcription(callback)` — Register callback for transcriptions
- `close()` — Close the stream

### `Transcription`

- `text: str` — Transcribed text
- `start: float | None` — Start time in seconds
- `end: float | None` — End time in seconds
- `confidence: float | None` — Confidence score
- `is_final: bool` — Whether this is a final transcription

## Supported Languages

25 languages via Parakeet-TDT (fast) with Whisper fallback:

English, Russian, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Czech, Romanian, Hungarian, Greek, Turkish, Ukrainian, Swedish, Norwegian, Danish, Finnish, Catalan, Croatian, Lithuanian, Slovenian, Latvian, Estonian.

## Error Handling

```python
from dtelecom_stt import PaymentError, SessionExpiredError, ConnectionError

try:
    async with client.session(minutes=5) as stream:
        async for t in stream.transcriptions():
            print(t.text)
except PaymentError:
    print("Payment failed — check wallet balance")
except SessionExpiredError:
    print("Session time ran out")
except ConnectionError:
    print("Cannot connect to server")
```

## License

MIT
