talklabs 2.1.0

TalkLabs SDK - Ultra-low latency Text-to-Speech with intelligent streaming and persistent sessions (ElevenLabs compatible)

🐍 TalkLabs Python SDK

SDK oficial da TalkLabs para síntese de voz com streaming ultra-baixa latência

🚀 Quick Start • 📚 Documentação • 💡 Exemplos • 🆘 Suporte

---

🚀 v2.1.0: Streaming com latência de ~200-500ms + Sessões Persistentes!

Características

• ✅ Compatível com ElevenLabs: Drop-in replacement para APIs existentes
• ⚡ Ultra-Low Latency: ~200-500ms até primeiro áudio (vs 5-10s tradicional)
• 🧠 Processamento Inteligente: Segmentação natural avançada
• 📡 Streaming Otimizado: Sistema paralelo com 3 níveis de prioridade
• 🎧 Real-time Playback: Chunks de áudio prontos para reprodução imediata
• 🔄 Incremental Streaming: Envio palavra-por-palavra para máxima responsividade

Instalação

pip install talklabs

Uso Rápido

1. Geração Simples (Síncrona)

from talklabs import TalkLabsClient

client = TalkLabsClient(api_key="tlk_live_xxxxx")

audio = client.generate(
    text="Olá! Bem-vindo ao TalkLabs.",
    voice="yasmin_alves"
)

with open("output.wav", "wb") as f:
    f.write(audio)

2. 🚀 Ultra-Low Latency Streaming (NOVO!)

import asyncio
from talklabs import TalkLabsClient

async def stream_example():
    client = TalkLabsClient(api_key="tlk_live_xxxxx")

    # Streaming otimizado (latência ~200-500ms)
    async for audio_chunk in client.stream_redis(
        text="Este é um teste de ultra baixa latência!",
        voice="yasmin_alves",
        language="pt"
    ):
        # Reproduzir audio_chunk imediatamente
        # Ex: play_audio(audio_chunk) ou salvar em arquivo
        print(f"Chunk recebido: {len(audio_chunk)} bytes")

asyncio.run(stream_example())

3. Streaming Incremental (Palavra por Palavra)

async def incremental_streaming():
    client = TalkLabsClient(api_key="tlk_live_xxxxx")

    # Simula digitação em tempo real
    async for audio_chunk in client.stream_redis(
        text="Olá mundo! Este texto é enviado palavra por palavra.",
        voice="yasmin_alves",
        incremental=True,  # Envia palavra por palavra
        word_delay=0.1     # 100ms entre palavras
    ):
        print(f"Audio chunk: {len(audio_chunk)} bytes")

asyncio.run(incremental_streaming())

4. Streaming HTTP (Fallback)

# Streaming tradicional via HTTP
for chunk in client.generate_stream(
    text="Streaming HTTP incremental",
    voice="yasmin_alves"
):
    # Processa chunks
    pass

API Reference

TalkLabsClient

Métodos Principais

generate(text, voice, **kwargs) → bytes

• Geração síncrona completa
• Retorna áudio WAV completo

stream_redis(text, voice, **kwargs) → AsyncIterator[bytes] ⚡ NOVO!

• Ultra-low latency streaming (~200-500ms)
• Processamento inteligente otimizado
• Retorna chunks de áudio conforme são gerados
• Parâmetros:
  • text: Texto para sintetizar
  • voice: ID da voz (ex: "yasmin_alves", "adam_rocha")
  • language: Idioma ("pt", "en", "es", etc) - padrão: "pt"
  • speed: Velocidade (0.5-2.0) - padrão: 1.0
  • voice_settings: Configurações opcionais
  • incremental: Se True, envia palavra por palavra - padrão: False
  • word_delay: Delay entre palavras no modo incremental - padrão: 0.1s

generate_stream(text, voice, **kwargs) → Iterator[bytes]

• Streaming HTTP tradicional
• Fallback para quando WebSocket não está disponível

stream_input(text_iterator, voice, **kwargs) → AsyncIterator[bytes]

• Streaming bidirecional WebSocket
• Aceita iterador assíncrono de texto

Vozes Disponíveis

# Listar todas as vozes
voices = client.get_voices()
for voice in voices:
    print(f"{voice['voice_id']}: {voice['name']}")

Vozes Populares:

• yasmin_alves - Português (BR) - Feminina
• adam_rocha - Português (BR) - Masculina
• maria_silva - Português (PT) - Feminina
• joao_santos - Português (PT) - Masculina

Arquitetura do Streaming Otimizado

Como Funciona

1. Segmentação Inteligente: Texto é dividido em sentenças naturais
2. Sistema de Filas: Chunks são processados com prioridades:
   • P1 (Alta): Primeira sentença - processada imediatamente
   • P2 (Média): Sentenças intermediárias
   • P3 (Baixa): Última sentença
3. Processamento Paralelo: TTS processa chunks simultaneamente
4. Streaming Real-time: Áudio retorna conforme é gerado

Benefícios

• ⚡ Latência 95% menor: ~200-500ms vs 5-10s
• 🎯 Primeira Palavra Rápida: Usuário ouve resposta quase instantânea
• 📊 Escalável: Suporta múltiplas sessões simultâneas
• 🧠 Inteligente: Quebras naturais de sentença garantidas

Exemplos Avançados

Salvar Chunks Progressivamente

async def save_streaming():
    client = TalkLabsClient(api_key="tlk_live_xxxxx")

    with open("output_streaming.wav", "wb") as f:
        async for chunk in client.stream_redis(
            text="Este áudio será salvo em tempo real.",
            voice="yasmin_alves"
        ):
            f.write(chunk)

    print("Áudio salvo!")

asyncio.run(save_streaming())

Reprodução em Tempo Real com pyaudio

import pyaudio
import asyncio
from talklabs import TalkLabsClient

async def play_realtime():
    client = TalkLabsClient(api_key="tlk_live_xxxxx")

    # Inicializar pyaudio
    p = pyaudio.PyAudio()
    stream = p.open(format=pyaudio.paInt16, channels=1, rate=24000, output=True)

    try:
        async for chunk in client.stream_redis(
            text="Olá! Este áudio está sendo reproduzido em tempo real.",
            voice="yasmin_alves"
        ):
            # Reproduzir imediatamente
            stream.write(chunk)
    finally:
        stream.stop_stream()
        stream.close()
        p.terminate()

asyncio.run(play_realtime())

Configurações Avançadas de Voz

from talklabs import TalkLabsClient, VoiceSettings

client = TalkLabsClient(api_key="tlk_live_xxxxx")

settings = VoiceSettings(
    stability=0.85,           # Estabilidade da voz (0-1)
    similarity_boost=0.75,    # Similaridade com voz original
    style=0.0,                # Estilo expressivo (0-1)
    use_speaker_boost=True    # Boost de clareza
)

audio = client.generate(
    text="Teste com configurações customizadas",
    voice="yasmin_alves",
    voice_settings=settings,
    speed=1.2  # 20% mais rápido
)

Compatibilidade com ElevenLabs

Este SDK é 100% compatível com o SDK da ElevenLabs. Basta trocar:

# ElevenLabs
from elevenlabs import ElevenLabs
client = ElevenLabs(api_key="...")

# TalkLabs (drop-in replacement)
from talklabs import TalkLabsClient
client = TalkLabsClient(api_key="tlk_live_...")

Configuração

Base URL

• Produção: https://api.talklabs.com.br
• Local: http://localhost:5000 (desenvolvimento)

Endpoints

• HTTP: /v1/text-to-speech/{voice_id}
• WebSocket: /v1/text-to-speech/{voice_id}/stream-redis ⚡ NOVO!

Troubleshooting

Erro: "Connection refused"

Verifique se a API está rodando:

curl https://api.talklabs.com.br/health

Latência alta no streaming

1. Use stream_redis() ao invés de generate_stream()
2. Verifique sua conexão com a API
3. Certifique-se que está usando a região mais próxima

Chunks de áudio corrompidos

• Certifique-se de salvar/reproduzir como WAV 24kHz mono
• Use io.BytesIO para buffer temporário se necessário

Licença

MIT License - veja LICENSE para detalhes.

📚 Documentação Completa

Esta é uma visão rápida. Para documentação completa, consulte:

📖 Guias Principais

• 📘 Documentação Completa - Guia definitivo com todos os detalhes
• 🚀 Guia Avançado - Arquitetura, otimização e casos avançados
• 🔄 Guia de Migração - Migração de v1.x ou ElevenLabs

🎯 Tópicos Específicos

• API Reference Completa
• Sessões Persistentes Avançadas
• Tratamento de Erros
• Concorrência e Paralelismo
• Integração com Frameworks
• Performance Tuning
• Debugging

---

Suporte

Recursos

• 📚 Documentação: docs/README.md
• 🌐 Website: https://talklabs.com.br
• 💬 Discord: https://discord.gg/talklabs
• 📧 Email: [e-mail]
• 🐛 Issues: https://github.com/talklabs/python-sdk/issues

Comunidade

• 🎓 Tutoriais: https://youtube.com/talklabs
• 📝 Blog: https://talklabs.com.br/blog
• 💡 Exemplos: https://github.com/talklabs/examples

---

📄 Licença

MIT License - veja LICENSE para detalhes.

---

Desenvolvido com ❤️ pela equipe TalkLabs