soundbridge-tx

Transmisor de audio para detecção de microfone. Auxiliar para comunicação para PCD

Este pacote é o transmissor (TX) em Python. O receptor (RX) é um aplicativo C++/Qt separado, mas o pacote também inclui um oráculo em Python (soundbridge_tx.oracle) capaz de decodificar, útil para testes e validação.

---

Instalação

pip install soundbridge-tx

Para transmitir ao vivo na placa de som (não apenas gerar arquivos WAV), instale com o extra live (traz o sounddevice):

pip install soundbridge-tx[live]

---

Uso rápido

Como biblioteca

from soundbridge_tx import send_file

# escolhe modulação e FEC automaticamente pelo tamanho do arquivo
send_file("meu_arquivo.zip", device=14, auto=True)

Gerar um WAV (sem tocar), para reproduzir depois:

from soundbridge_tx import generate_wav

generate_wav("meu_arquivo.zip", "saida.wav", auto=True)

Enviar um texto direto:

from soundbridge_tx import send_text

send_text("chave: abc123", device=14, copy_to_clipboard=True)

Listar os dispositivos de saída:

from soundbridge_tx import list_devices

for dev in list_devices():
    print(dev)

Pela linha de comando

Após instalar, o comando soundbridge-tx fica disponível:

# transmitir ao vivo, escolhendo tudo automaticamente
soundbridge-tx --in meu_arquivo.zip --auto --stereo --band-high 22000 --play --device 14

# gerar um WAV
soundbridge-tx --in meu_arquivo.zip --auto --stereo --band-high 22000 --out saida.wav

# listar os dispositivos de saída
soundbridge-tx --list-devices

Não sabe o índice do --device? Use --play sem o --device. O programa lista os dispositivos e pergunta qual usar antes de enviar.

---

Parâmetros da linha de comando

Entrada e saída

Parâmetro	Descrição
--in ARQUIVO	arquivo a transmitir. Também aceita uma pasta (envia todos os arquivos dela, um a um)
--text "..."	envia um texto direto, em vez de um arquivo
--out ARQUIVO.wav	gera um arquivo WAV em vez de tocar ao vivo
--play	toca ao vivo na placa de som (requer o extra live)
--device N	índice do dispositivo de saída (com --play)
--list-devices	lista os dispositivos de saída disponíveis e encerra
--size N	tamanho de um arquivo de teste gerado internamente (quando não há --in nem --text)

Modulação e correção de erro

Parâmetro	Descrição
--auto	escolhe a modulação e o FEC automaticamente pelo tamanho do arquivo (recomendado)
--qam16	16-QAM (4 bits por subportadora)
--qam64	64-QAM (6 bits — o teto robusto, recomendado para arquivos grandes)
--qam256	256-QAM (8 bits — experimental, ideal para arquivos pequenos-médios)
--qam1024	1024-QAM (10 bits — experimental, para arquivos muito pequenos)
(nenhum)	QPSK (2 bits — o padrão, mais robusto)
--fec MODO	correção de erro: r12 (padrão, robusto), r23/r34 (mais leves/rápidos, para arquivos pequenos-médios) ou none (sem proteção)
--resync MODO	re-sincronização contra drift de clock: off, 10 (padrão), 25 ou 5 blocos
--parity MODO	blocos de paridade para recuperar perdas: off, 8, 16 (padrão) ou 32 grupos

Canal e banda

Parâmetro	Descrição
--stereo	usa os dois canais do cabo (2× mais rápido; recomendado)
--band-high N	frequência máxima da banda OFDM em Hz (padrão 14000; recomendado 22000)
--peak V	pico de amplitude do sinal (0–1; reduza se a entrada estiver saturando)
--guard S	silêncio de guarda em segundos no início/fim do sinal

Metadados (o receptor usa ao salvar)

Parâmetro	Descrição
--name "NOME"	nome do arquivo salvo no receptor (aceita subpasta: docs/a.txt)
--profile NOME	perfil de recepção (o receptor resolve a pasta de destino)
--copymemory	o receptor copia o conteúdo para a área de transferência
--zip	comprime os dados antes de enviar (o receptor descomprime). Grande ganho para texto/dados compressíveis

Múltiplos arquivos (com --in PASTA)

Parâmetro	Descrição
--gap S	intervalo em segundos entre arquivos (padrão 5)

Diagnóstico

Parâmetro	Descrição
--verbose	mostra detalhes de cada etapa (padrão: só a barra de progresso e o CRC)

---

O modo automático (--auto)

Com --auto, o transmissor escolhe a modulação e o FEC pelo tamanho do arquivo, com base no que foi validado no cabo:

Tamanho	Escolha	Motivo
até ~12 KB	1024-QAM + r12	o mais rápido; a janela curta protege a modulação densa
até ~100 KB	256-QAM + r34	denso e com FEC leve — rápido e confiável nesse tamanho
acima disso	64-QAM + r12	o teto robusto, seguro para arquivos grandes

As faixas são conservadoras (com margem sobre o medido), priorizando a entrega confiável. Para arquivos grandes, o 64-QAM r12 é sempre a escolha robusta.

Se combinado com --zip, a escolha considera o tamanho comprimido.

---

Velocidade

Depende da modulação (mais densa = mais rápida, menos robusta):

Modulação	Velocidade	Observação
QPSK	~4 KB/s	mais robusta
16-QAM	~8 KB/s	equilíbrio
64-QAM	~12 KB/s	recomendada (teto robusto)
256/1024-QAM	~16–20 KB/s	experimentais (arquivos pequenos-médios)
--zip	até 100×+	quando os dados comprimem bem

---

Preparar o PC transmissor (Windows)

Para o áudio chegar íntegro ao cabo, desative qualquer processamento de som na saída usada: efeitos do driver (equalizador, "surround", "bass boost"), o som espacial do Windows, e painéis de áudio de fabricante. Confirme que o dispositivo opera a 48000 Hz. Na prática o sistema decodifica mesmo com alguns efeitos ligados (o FEC corrige), mas desativá-los dá a melhor margem.

---

API Python

from soundbridge_tx import send_file, send_text, generate_wav, list_devices

send_file(path, device=None, auto=False, modulation="qpsk", fec="r12", stereo=True, band_high=22000, zip=False, name=None, profile=None, copy_to_clipboard=False) Transmite um arquivo ao vivo. modulation: "qpsk", "16qam", "64qam", "256qam", "1024qam". fec: "none", "r12", "r23", "r34".

generate_wav(path, out_wav, **opts) Gera um WAV em vez de tocar (mesmas opções, sem device).

send_text(text, device=None, **opts) Envia um texto direto.

list_devices() Retorna os dispositivos de saída disponíveis.

---

Como funciona (resumo)

O sinal é OFDM a 48 kHz: um símbolo de sincronização, um de estimativa de canal, um cabeçalho protegido por CRC-24, e os símbolos de dados. Os dados passam por correção de erro (código convolucional + interleaver + paridade) e são organizados em blocos com CRC próprio. No estéreo, os blocos são divididos entre os dois canais (dobrando a velocidade). O receptor remonta os blocos, recupera perdas pela paridade quando possível, e valida o CRC32 final antes de salvar.

---

Licença

MIT.