# TalkLabs STT SDK
SDK Python para TalkLabs Speech-to-Text API - Compatível com
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
## Features
- ✅ **REST API** - Transcrição completa de arquivos
- ✅ **WebSocket Streaming** - Transcrição em tempo real
- ✅ **Deepgram Compatible** - API compatível com Deepgram
- ✅ **Múltiplos Modelos** - Suporte a diferentes modelos de transcrição
- ✅ **Async Support** - WebSocket assíncrono
- ✅ **Type Hints** - Totalmente tipado
## Instalação
```bash
pip install talklabs-stt
```
## Quick Start
### REST API (Síncrono)
```python
from talklabs_stt import STTClient
client = STTClient(api_key="tlk_live_xxxxx")
result = client.transcribe_file("audio.wav")
print(result["results"]["channels"][0]["alternatives"][0]["transcript"])
```
### WebSocket Streaming (Assíncrono)
```python
import asyncio
from talklabs_stt import STTClient
async def main():
client = STTClient(api_key="tlk_live_xxxxx")
def on_transcript(data):
if data["is_final"]:
print(data["channel"]["alternatives"][0]["transcript"])
await client.transcribe_stream(
"audio.wav",
on_transcript=on_transcript
)
asyncio.run(main())
```
## Uso Completo
### Inicialização
```python
from talklabs_stt import STTClient, TranscriptionOptions
# Cliente (sempre usa api.talklabs.com.br)
client = STTClient(api_key="tlk_live_xxxxx")
# Cliente com timeout customizado
client = STTClient(
api_key="tlk_live_xxxxx",
timeout=600 # 10 minutos
)
```
### Opções de Transcrição
```python
from talklabs_stt import TranscriptionOptions
options = TranscriptionOptions(
model="large-v3", # large-v3, medium, small
language="pt", # pt, en, es, etc.
punctuate=True, # Adicionar pontuação
smart_format=True, # Formatação inteligente
detect_language=False, # Detecção automática
vad_filter=False, # Filtro VAD
interim_results=True # Resultados intermediários (WebSocket)
)
result = client.transcribe_file("audio.wav", options=options)
```
### Com kwargs diretos
```python
result = client.transcribe_file(
"audio.wav",
model="large-v3",
language="pt",
punctuate=True,
smart_format=True
)
```
## API Reference
### STTClient
#### `transcribe_file(audio_path, options=None, **kwargs)`
Transcreve arquivo completo via REST API.
**Args:**
- `audio_path` (str): Caminho do arquivo de áudio
- `options` (TranscriptionOptions, optional): Opções de transcrição
- `**kwargs`: Parâmetros adicionais
**Returns:** dict - Resultado -compatible
#### `transcribe_stream(audio_path, options=None, on_transcript=None, on_metadata=None, **kwargs)`
Transcreve via WebSocket streaming (async).
**Args:**
- `audio_path` (str): Caminho do arquivo
- `options` (TranscriptionOptions, optional): Opções
- `on_transcript` (callable, optional): Callback para transcrições
- `on_metadata` (callable, optional): Callback para metadata
- `**kwargs`: Parâmetros adicionais
#### `list_models()`
Lista modelos disponíveis.
**Returns:** dict - Lista de modelos disponíveis
## Migração do Deepgram
O SDK é 100% compatível com Deepgram. Para migrar:
```python
# Deepgram
from deepgram import DeepgramClient
dg = DeepgramClient(api_key)
# TalkLabs
from talklabs_stt import STTClient
client = STTClient(api_key)
# Mesma interface!
result = client.transcribe_file("audio.wav", language="pt")
```
## Exemplos
Ver pasta `examples/`:
- `transcribe_simple.py` - REST API básico
- `transcribe_stream.py` - WebSocket streaming
- `list_models.py` - Listar modelos
- `quick_start.py` - Exemplo rápido de uso
## Desenvolvimento
### Benchmark de Modelos
O projeto inclui um script de benchmark completo para testar todos os modelos:
```bash
# Instalar dependências de desenvolvimento
pip install -e ".[dev]"
# Executar benchmark
python benchmark_models.py <arquivo_audio>
# Testar modelos específicos
python benchmark_models.py audio.wav --models tiny base medium
# Salvar relatório customizado
python benchmark_models.py audio.wav --output meu_relatorio.json
```
O benchmark testa:
- ✅ Velocidade de processamento (REST API e WebSocket)
- ✅ RTF (Real-Time Factor) de cada modelo
- ✅ Verifica se o servidor está **trocando os modelos corretamente**
- ✅ Gera relatórios visuais e JSON completo
Ver documentação completa em [BENCHMARK.md](BENCHMARK.md).
### Usando Makefile
O projeto inclui um Makefile para facilitar tarefas comuns:
```bash
# Verificação de código
make lint # Verificar com flake8
# Build e publicação
make publish-test # Publicar no TestPyPI
make publish # Publicar no PyPI oficial
# Utilitários
make clean # Limpar arquivos temporários
make help # Ver todos os comandos
```
Para mais detalhes sobre desenvolvimento, ver [CONTRIBUTING.md](CONTRIBUTING.md).
## Troubleshooting
### Erro de autenticação
Verifique se a API key está correta e ativa.
### Timeout
Aumente o timeout:
```python
client = STTClient(api_key="...", timeout=600)
```
### Formato de áudio
Formatos suportados: WAV, MP3, FLAC, OGG, M4A
## License
MIT License - Ver LICENSE
## Support
- Documentação: https://docs.talklabs.com.br/stt
- Issues: https://github.com/talklabs/talklabs-stt/issues
- Email: support@talklabs.com.br
Raw data
{
"_id": null,
"home_page": "https://talklabs.com.br",
"name": "talklabs-stt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Francisco Lima <franciscorllima@gmail.com>",
"keywords": "speech-to-text, stt, transcription, audio, deepgram, talklabs",
"author": "Francisco Lima",
"author_email": "Francisco Lima <franciscorllima@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/df/21/60a7f6f9aad293c0b21f42ccda81aa38deb3c632da1094ebafa065f1f8a3/talklabs_stt-1.0.2.tar.gz",
"platform": null,
"description": "# TalkLabs STT SDK\n\nSDK Python para TalkLabs Speech-to-Text API - Compat\u00edvel com \n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\n## Features\n\n- \u2705 **REST API** - Transcri\u00e7\u00e3o completa de arquivos\n- \u2705 **WebSocket Streaming** - Transcri\u00e7\u00e3o em tempo real\n- \u2705 **Deepgram Compatible** - API compat\u00edvel com Deepgram\n- \u2705 **M\u00faltiplos Modelos** - Suporte a diferentes modelos de transcri\u00e7\u00e3o\n- \u2705 **Async Support** - WebSocket ass\u00edncrono\n- \u2705 **Type Hints** - Totalmente tipado\n\n## Instala\u00e7\u00e3o\n\n```bash\npip install talklabs-stt\n```\n\n## Quick Start\n\n### REST API (S\u00edncrono)\n\n```python\nfrom talklabs_stt import STTClient\n\nclient = STTClient(api_key=\"tlk_live_xxxxx\")\n\nresult = client.transcribe_file(\"audio.wav\")\nprint(result[\"results\"][\"channels\"][0][\"alternatives\"][0][\"transcript\"])\n```\n\n### WebSocket Streaming (Ass\u00edncrono)\n\n```python\nimport asyncio\nfrom talklabs_stt import STTClient\n\nasync def main():\n client = STTClient(api_key=\"tlk_live_xxxxx\")\n \n def on_transcript(data):\n if data[\"is_final\"]:\n print(data[\"channel\"][\"alternatives\"][0][\"transcript\"])\n \n await client.transcribe_stream(\n \"audio.wav\",\n on_transcript=on_transcript\n )\n\nasyncio.run(main())\n```\n\n## Uso Completo\n\n### Inicializa\u00e7\u00e3o\n\n```python\nfrom talklabs_stt import STTClient, TranscriptionOptions\n\n# Cliente (sempre usa api.talklabs.com.br)\nclient = STTClient(api_key=\"tlk_live_xxxxx\")\n\n# Cliente com timeout customizado\nclient = STTClient(\n api_key=\"tlk_live_xxxxx\",\n timeout=600 # 10 minutos\n)\n```\n\n### Op\u00e7\u00f5es de Transcri\u00e7\u00e3o\n\n```python\nfrom talklabs_stt import TranscriptionOptions\n\noptions = TranscriptionOptions(\n model=\"large-v3\", # large-v3, medium, small\n language=\"pt\", # pt, en, es, etc.\n punctuate=True, # Adicionar pontua\u00e7\u00e3o\n smart_format=True, # Formata\u00e7\u00e3o inteligente\n detect_language=False, # Detec\u00e7\u00e3o autom\u00e1tica\n vad_filter=False, # Filtro VAD\n interim_results=True # Resultados intermedi\u00e1rios (WebSocket)\n)\n\nresult = client.transcribe_file(\"audio.wav\", options=options)\n```\n\n### Com kwargs diretos\n\n```python\nresult = client.transcribe_file(\n \"audio.wav\",\n model=\"large-v3\",\n language=\"pt\",\n punctuate=True,\n smart_format=True\n)\n```\n\n## API Reference\n\n### STTClient\n\n#### `transcribe_file(audio_path, options=None, **kwargs)`\n\nTranscreve arquivo completo via REST API.\n\n**Args:**\n- `audio_path` (str): Caminho do arquivo de \u00e1udio\n- `options` (TranscriptionOptions, optional): Op\u00e7\u00f5es de transcri\u00e7\u00e3o\n- `**kwargs`: Par\u00e2metros adicionais\n\n**Returns:** dict - Resultado -compatible\n\n#### `transcribe_stream(audio_path, options=None, on_transcript=None, on_metadata=None, **kwargs)`\n\nTranscreve via WebSocket streaming (async).\n\n**Args:**\n- `audio_path` (str): Caminho do arquivo\n- `options` (TranscriptionOptions, optional): Op\u00e7\u00f5es\n- `on_transcript` (callable, optional): Callback para transcri\u00e7\u00f5es\n- `on_metadata` (callable, optional): Callback para metadata\n- `**kwargs`: Par\u00e2metros adicionais\n\n#### `list_models()`\n\nLista modelos dispon\u00edveis.\n\n**Returns:** dict - Lista de modelos dispon\u00edveis\n\n## Migra\u00e7\u00e3o do Deepgram\n\nO SDK \u00e9 100% compat\u00edvel com Deepgram. Para migrar:\n\n```python\n# Deepgram\nfrom deepgram import DeepgramClient\ndg = DeepgramClient(api_key)\n\n# TalkLabs\nfrom talklabs_stt import STTClient\nclient = STTClient(api_key)\n\n# Mesma interface!\nresult = client.transcribe_file(\"audio.wav\", language=\"pt\")\n```\n\n## Exemplos\n\nVer pasta `examples/`:\n- `transcribe_simple.py` - REST API b\u00e1sico\n- `transcribe_stream.py` - WebSocket streaming\n- `list_models.py` - Listar modelos\n- `quick_start.py` - Exemplo r\u00e1pido de uso\n\n## Desenvolvimento\n\n### Benchmark de Modelos\n\nO projeto inclui um script de benchmark completo para testar todos os modelos:\n\n```bash\n# Instalar depend\u00eancias de desenvolvimento\npip install -e \".[dev]\"\n\n# Executar benchmark\npython benchmark_models.py <arquivo_audio>\n\n# Testar modelos espec\u00edficos\npython benchmark_models.py audio.wav --models tiny base medium\n\n# Salvar relat\u00f3rio customizado\npython benchmark_models.py audio.wav --output meu_relatorio.json\n```\n\nO benchmark testa:\n- \u2705 Velocidade de processamento (REST API e WebSocket)\n- \u2705 RTF (Real-Time Factor) de cada modelo\n- \u2705 Verifica se o servidor est\u00e1 **trocando os modelos corretamente**\n- \u2705 Gera relat\u00f3rios visuais e JSON completo\n\nVer documenta\u00e7\u00e3o completa em [BENCHMARK.md](BENCHMARK.md).\n\n### Usando Makefile\n\nO projeto inclui um Makefile para facilitar tarefas comuns:\n\n```bash\n# Verifica\u00e7\u00e3o de c\u00f3digo\nmake lint # Verificar com flake8\n\n# Build e publica\u00e7\u00e3o\nmake publish-test # Publicar no TestPyPI\nmake publish # Publicar no PyPI oficial\n\n# Utilit\u00e1rios\nmake clean # Limpar arquivos tempor\u00e1rios\nmake help # Ver todos os comandos\n```\n\nPara mais detalhes sobre desenvolvimento, ver [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Troubleshooting\n\n### Erro de autentica\u00e7\u00e3o\n\nVerifique se a API key est\u00e1 correta e ativa.\n\n### Timeout\n\nAumente o timeout:\n```python\nclient = STTClient(api_key=\"...\", timeout=600)\n```\n\n### Formato de \u00e1udio\n\nFormatos suportados: WAV, MP3, FLAC, OGG, M4A\n\n## License\n\nMIT License - Ver LICENSE\n\n## Support\n\n- Documenta\u00e7\u00e3o: https://docs.talklabs.com.br/stt\n- Issues: https://github.com/talklabs/talklabs-stt/issues\n- Email: support@talklabs.com.br\n",
"bugtrack_url": null,
"license": null,
"summary": "TalkLabs STT SDK - Speech-to-Text API compatible with Deepgram",
"version": "1.0.2",
"project_urls": {
"Bug Reports": "https://github.com/talklabs/talklabs-stt/issues",
"Documentation": "https://docs.talklabs.com.br/stt",
"Homepage": "https://talklabs.com.br",
"Repository": "https://github.com/talklabs/talklabs-stt"
},
"split_keywords": [
"speech-to-text",
" stt",
" transcription",
" audio",
" deepgram",
" talklabs"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3346fbd7c19a12c0cc1f91353d3a549e6370e0b33456ba5a3cb09514a993d23b",
"md5": "2f34a986896709ca8500c41cdb7d01d5",
"sha256": "0ad767b65c60b48387765b6476c9f0a613306e1d6b4a35777c590880c37d6b7b"
},
"downloads": -1,
"filename": "talklabs_stt-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f34a986896709ca8500c41cdb7d01d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10258,
"upload_time": "2025-11-05T16:31:41",
"upload_time_iso_8601": "2025-11-05T16:31:41.574635Z",
"url": "https://files.pythonhosted.org/packages/33/46/fbd7c19a12c0cc1f91353d3a549e6370e0b33456ba5a3cb09514a993d23b/talklabs_stt-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "df2160a7f6f9aad293c0b21f42ccda81aa38deb3c632da1094ebafa065f1f8a3",
"md5": "1747d2af08d6a2be59c5521eab07fbbb",
"sha256": "ba70488987154e4703ea1401adc11f4c15bc61d3d87cb50f607b4ae2a875a300"
},
"downloads": -1,
"filename": "talklabs_stt-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1747d2af08d6a2be59c5521eab07fbbb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 18149,
"upload_time": "2025-11-05T16:31:42",
"upload_time_iso_8601": "2025-11-05T16:31:42.995848Z",
"url": "https://files.pythonhosted.org/packages/df/21/60a7f6f9aad293c0b21f42ccda81aa38deb3c632da1094ebafa065f1f8a3/talklabs_stt-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 16:31:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "talklabs",
"github_project": "talklabs-stt",
"github_not_found": true,
"lcname": "talklabs-stt"
}
JSON
