Metadata-Version: 2.5
Name: soundbridge-tx
Version: 1.1.0
Summary: Transmisor de audio para detecção de microfone. Auxiliar para comunicação para PCD
Project-URL: Homepage, https://github.com/Cafecanudo/soundbridge_tx
Project-URL: Repository, https://github.com/Cafecanudo/soundbridge_tx
Author: Makoto, Studio
License: MIT
Keywords: audio,file-transfer,fsk,modem,ofdm,qam
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: live
Requires-Dist: sounddevice>=0.4; extra == 'live'
Description-Content-Type: text/markdown

# 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

```bash
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`):

```bash
pip install soundbridge-tx[live]
```

---

## Uso rápido

### Como biblioteca

```python
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:

```python
from soundbridge_tx import generate_wav

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

Enviar um texto direto:

```python
from soundbridge_tx import send_text

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

Listar os dispositivos de saída:

```python
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:

```bash
# 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

```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.
