libspech

Visão Geral

libspech fornece:

• Recursos de user-agent SIP: registro, configuração/desmontagem de chamadas (INVITE/200/ACK/BYE), autenticação digest
• Canais de mídia RTP/RTCP: receber e enviar quadros de áudio
• API orientada a eventos com callbacks para toque, resposta, desligamento e áudio recebido
• Envio de DTMF (RFC 2833)
• Auxiliares de gravação WAV para PCM capturado
• I/O assíncrono de alto desempenho via Swoole

📘 Nova Documentação: Veja SIGNALING_ARRAYS.md para entender em profundidade como os arrays de sinalização SIP são construídos e processados.

Stack

• Linguagem: PHP (sem Composer neste repositório)
• Framework/runtime: Corrotinas Swoole (incluído nas releases pcg729)
• Protocolos: SIP, RTP/RTCP, SDP, DTMF (RFC 2833)
• Extensões nativas: bcg729, opus, psampler (incluídas nas releases pcg729)

Requisitos

• Linux/macOS recomendado
• Releases do berzersks/pcg729 que incluem PHP 8.4+ com Swoole, bcg729 (baseado no Belladone BCG729), Opus e psampler pré-compilados

Instalação

Baixe a última release do berzersks/pcg729. Esta release inclui todas as extensões necessárias (Swoole, bcg729 baseado no Belladone BCG729, Opus, psampler) pré-compiladas e prontas para uso.

Siga as instruções de instalação fornecidas na release para configurar o ambiente.

Começando

O repositório inclui um exemplo executável em example.php.

Configuração Inicial

1. Configure suas credenciais SIP no arquivo .env:

   cp .env.example .env
   # Edite .env com suas credenciais

2. Execute o exemplo:

   php example.php

Exemplo Mínimo

<?php
use libspech\Sip\trunkController;

include 'plugins/autoloader.php';

\Swoole\Coroutine\run(function () {
    $username = getenv('SIP_USERNAME');
    $password = getenv('SIP_PASSWORD');
    $domain   = getenv('SIP_DOMAIN');
    $host     = gethostbyname($domain);

    $phone = new trunkController($username, $password, $host, 5060);

    if (!$phone->register(2)) {
        throw new \Exception('Falha no registro');
    }

    // Oferecer codec Opus em SDP
    $phone->mountLineCodecSDP('opus/48000/2');

    $phone->onRinging(function ($phone) {
        echo "Tocando...\n";
    });

    $phone->onAnswer(function (trunkController $phone) {
        echo "Atendido. Recebendo mídia...\n";
        $phone->receiveMedia();
        \Swoole\Coroutine::sleep(10);
    });

    $phone->onReceiveAudio(function ($pcmData, $peer, trunkController $phone) {
        echo "Recebido: " . strlen($pcmData) . " bytes\n";
    });

    $phone->onHangup(function (trunkController $phone) {
        echo "Chamada finalizada\n";
        $phone->close();
    });

    $phone->call('5511999999999');
});

Exemplo Completo (Production-Ready)

Veja o arquivo example.php para um exemplo completo. Recursos principais demonstrados:

• ✅ Carregar credenciais de variáveis de ambiente (.env)
• ✅ Registrar no servidor SIP
• ✅ Configurar codec Opus
• ✅ Gerenciar callbacks de estado (ringing, answer, hangup)
• ✅ Receber e processar áudio PCM
• ✅ Enviar DTMF (RFC 2833)
• ✅ Salvar áudio em arquivo WAV
• ✅ Usar CLI helper para logging colorido
• ✅ Fazer chamadas de saída

Variáveis de Ambiente

A biblioteca utiliza variáveis de ambiente para gerenciar credenciais SIP de forma segura:

SIP_USERNAME=seu_username
SIP_PASSWORD=sua_password
SIP_DOMAIN=sip.example.com
SIP_PORT=5060
SIP_TIMEOUT=120

API de Callbacks

A classe trunkController oferece os seguintes callbacks para gerenciar eventos de chamada:

Eventos de Chamada

// Chamada recebida (ringing)
$phone->onRinging(function ($phone) {
    echo "Tocando...\n";
});

// Chamada atendida
$phone->onAnswer(function (trunkController $phone) {
    $phone->receiveMedia();
    // ... processar áudio ...
});

// Chamada finalizada (hangup)
$phone->onHangup(function (trunkController $phone) {
    $phone->close();
});

// Pressionamento de tecla (DTMF)
$phone->onKeyPress(function ($event, $peer) {
    echo "Dígito recebido: " . $event . "\n";
});

Callbacks de Mídia

// Receber áudio PCM
$phone->onReceivePcm(function ($pcmData, $peer, trunkController $phone) {
    // $pcmData: dados de áudio em formato PCM
    // $peer: endereço IP e porta do servidor RTP remoto
    // $phone: instância do controlador
});

Métodos Principais

// Registro no servidor SIP
$phone->register($retries);

// Fazer chamada de saída
$phone->call($number);

// Configurar codec SDP
$phone->mountLineCodecSDP('opus/48000/2');  // Opus, 48kHz, estéreo
$phone->mountLineCodecSDP('L16/8000');      // Linear PCM, 8kHz

// Gerenciamento de áudio
$phone->receiveMedia();                      // Iniciar recepção
$phone->defineAudioFile('file.wav');         // Definir arquivo para envio
$phone->saveBufferToWavFile('out.wav', $data);

// Enviar DTMF (RFC 2833)
$phone->send2833($number, $duration);       // $duration em ms

// Configuração
$phone->defineTimeout($seconds);             // Timeout em segundos
$phone->close();                             // Finalizar conexão

Estrutura do Projeto

Codecs

Payloads suportados/disponíveis no codebase:

Codec	Tipo de Payload	Taxa de Amostragem	Status	Notas/Extensão
PCMU (G.711 µ-law)	0	8 kHz	Integrado	Nenhuma extensão extra necessária
PCMA (G.711 A-law)	8	8 kHz	Integrado	Nenhuma extensão extra necessária
G.729	18	8 kHz	Integrado	Incluído na release pcg729 (baseado no Belladone BCG729)
Opus	111	48 kHz	Integrado	Incluído na release pcg729
L16 (Linear PCM)	96	8 kHz	Integrado	psampler incluído para reamostragem
telephone-event (DTMF)	101	8 kHz	Integrado	RFC 2833 para sinalização DTMF

Arquitetura e Fluxo de Dados

Fluxo de Uma Chamada Outbound (Enviada)

Integração com Swoole Coroutines

Toda a I/O é não-bloqueante usando corrotinas Swoole:

\Swoole\Coroutine\run(function () {
    \Swoole\Coroutine::create(function () {
        // Cada coroutine = contexto de chamada isolado

        // I/O não-bloqueante
        $phone->register(2);        // Yield até resposta
        $phone->call($number);      // Yield até resposta
        $phone->receiveMedia();     // Yield em loop RTP

        // Nenhum thread, nenhum callback hell - código sequencial
    });
});

Benefícios:

• ✅ Milhares de chamadas simultâneas em um thread
• ✅ Zero overhead de sincronização
• ✅ Código linear e fácil de entender
• ✅ Integração nativa com extensões Swoole (timers, queues, etc.)

Exemplos Avançados

Gravando Áudio de Múltiplas Chamadas

<?php
use libspech\Sip\trunkController;

\Swoole\Coroutine\run(function () {
    $calls = [
        '5511999999999',
        '5511888888888',
    ];

    foreach ($calls as $number) {
        \Swoole\Coroutine::create(function () use ($number) {
            $phone = new trunkController($username, $password, $host, 5060);
            $phone->register(2);

            $audioBuffer = '';

            $phone->onReceivePcm(function ($pcmData, $peer, $p) use (&$audioBuffer) {
                $audioBuffer .= $pcmData;
            });

            $phone->onHangup(function ($p) use (&$audioBuffer, $number) {
                $filename = "call_{$number}_" . date('YmdHis') . ".wav";
                $p->saveBufferToWavFile($filename, $audioBuffer);
                echo "Gravado: $filename\n";
            });

            $phone->call($number);
        });
    }
});

Detecção de DTMF e Menu IVR

<?php
$phone->onKeyPress(function ($digit, $peer) use ($phone) {
    switch ($digit) {
        case '1':
            echo "Opção 1 pressionada\n";
            $phone->defineAudioFile('menu_option1.wav');
            break;
        case '2':
            echo "Opção 2 pressionada\n";
            $phone->defineAudioFile('menu_option2.wav');
            break;
        case '*':
            echo "Retornar ao menu\n";
            $phone->defineAudioFile('main_menu.wav');
            break;
        case '#':
            echo "Finalizar chamada\n";
            $phone->close();
            break;
    }
});

Documentação da API

WebSocket API

O SpechPhone utiliza WebSocket para comunicação em tempo real entre o navegador e o servidor. Todas as mensagens seguem o formato JSON.

Estrutura de Mensagens

{
  "action": "nome_da_acao",
  "data": {
    "parametro1": "valor1",
    "parametro2": "valor2"
  }
}

Ações Disponíveis (Cliente → Servidor)

1. Iniciar Chamada

{
  "action": "call",
  "data": {
    "number": "551140040104",
    "codec": "opus"
  }
}

2. Desligar Chamada

{
  "action": "hangup",
  "data": {}
}

3. Enviar DTMF

{
  "action": "dtmf",
  "data": {
    "digit": "1"
  }
}

4. Controle de Áudio

{
  "action": "audio_control",
  "data": {
    "mute": true,
    "volume": 0.8
  }
}

5. Enviar Áudio PCM

{
  "action": "send_audio",
  "data": {
    "pcm": "base64_encoded_audio_data",
    "sampleRate": 48000
  }
}

Eventos (Servidor → Cliente)

1. Status da Chamada

{
  "event": "call_status",
  "data": {
    "status": "ringing|answered|hangup",
    "callId": "unique_call_id"
  }
}

2. Áudio Recebido

{
  "event": "audio_data",
  "data": {
    "pcm": "base64_encoded_audio",
    "sampleRate": 48000,
    "channels": 1
  }
}

3. DTMF Recebido

{
  "event": "dtmf_received",
  "data": {
    "digit": "5"
  }
}

4. Erro

{
  "event": "error",
  "data": {
    "code": "ERROR_CODE",
    "message": "Descrição do erro"
  }
}

Troubleshooting

Problemas Comuns e Soluções

1. Erro: "Cannot bind to port 443"

Causa: A porta 443 requer privilégios de root.

Solução:

# Opção 1: Execute com sudo
sudo php middleware.php

# Opção 2: Use uma porta alternativa (edite configInterface.json)
{
  "port": 8443
}

# Opção 3: Use setcap para permitir bind em portas baixas
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/php

2. Erro: "SSL certificate not found"

Causa: Certificados SSL não foram gerados.

Solução:

# O sistema gera automaticamente, mas você pode forçar:
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

3. Áudio Cortado ou Com Delay

Causas possíveis:

• Jitter de rede alto
• Buffer adaptativo desabilitado
• CPU sobrecarregada

Soluções:

// Ajuste o buffer adaptativo na libspech
$phone->enableAdaptiveBuffer(true);
$phone->setBufferSize(200); // ms

// Aumente o número de workers Swoole
"serverSettings": {
  "worker_num": 4,
  "task_worker_num": 2
}

4. Erro: "Registration failed"

Causa: Credenciais SIP inválidas ou servidor inacessível.

Solução:

# Verifique conectividade
ping sip.example.com

# Teste porta SIP
nc -vz sip.example.com 5060

# Verifique logs
tail -f /var/log/spechphone.log

5. Microfone Não Funciona no Navegador

Causa: HTTPS/WSS não está configurado ou navegador não tem permissão.

Solução:

• Certifique-se que está usando HTTPS
• Verifique permissões no navegador (ícone de cadeado)
• Teste em navegador compatível (Chrome, Firefox, Edge)

6. Codec Não Suportado

Causa: Codec não está disponível no runtime pcg729.

Solução:

# Verifique codecs disponíveis
php -m | grep -E "bcg729|opus|psampler"

# Se ausentes, baixe o runtime correto
curl -L https://github.com/spechshop/pcg729/releases/download/current/php -o php
chmod +x php
sudo cp php /usr/local/bin/php

7. Alta Utilização de CPU

Causas possíveis:

• Muitas chamadas simultâneas
• Codec complexo (Opus) sem otimização
• Workers insuficientes

Soluções:

// Ajuste configInterface.json
{
  "serverSettings": {
    "worker_num": 8,
    "max_coroutine": 3000,
    "enable_coroutine": true
  }
}

8. WebSocket Desconecta Constantemente

Causa: Timeout ou proxy/load balancer intermediário.

Solução:

// Ajuste keepalive em configInterface.json
{
  "serverSettings": {
    "heartbeat_check_interval": 30,
    "heartbeat_idle_time": 60
  }
}

Debug e Logs

Habilitar Logs Detalhados

# Defina nível de log
export SPECH_LOG_LEVEL=debug

# Execute com output verbose
php middleware.php 2>&1 | tee server.log

Analisar Tráfego RTP

# Capture pacotes RTP
sudo tcpdump -i any -n 'udp port 10000-62000' -w rtp.pcap

# Analise com Wireshark
wireshark rtp.pcap

Monitorar Corrotinas Swoole

// Adicione ao seu código
\Swoole\Coroutine::stats(); // Retorna estatísticas de corrotinas

Deploy em Produção

Requisitos de Produção

• ✅ Certificado SSL válido (Let's Encrypt recomendado)
• ✅ Firewall configurado (portas 443, 5060, 10000-62000)
• ✅ Reverse proxy opcional (Nginx/Caddy)
• ✅ Monitoramento (Prometheus, Grafana)
• ✅ Backup de configurações

Configuração com Nginx (Reverse Proxy)

upstream spechphone {
    server 127.0.0.1:8443;
}

server {
    listen 443 ssl http2;
    server_name phone.example.com;

    ssl_certificate /etc/letsencrypt/live/phone.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/phone.example.com/privkey.pem;

    location / {
        proxy_pass https://spechphone;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 86400;
    }
}

Systemd Service

Crie /etc/systemd/system/spechphone-middleware.service:

[Unit]
Description=SpechPhone Middleware Server
After=network.target

[Service]
Type=simple
User=spechphone
WorkingDirectory=/opt/spechphone
ExecStart=/usr/local/bin/php middleware.php
Restart=always
RestartSec=5
Environment="SPECH_VAULT_KEY_HEX=your_key_here"

[Install]
WantedBy=multi-user.target

Crie /etc/systemd/system/spechphone-audio.service:

[Unit]
Description=SpechPhone Audio Server
After=network.target

[Service]
Type=simple
User=spechphone
WorkingDirectory=/opt/spechphone
ExecStart=/usr/local/bin/php audio.php
Restart=always
RestartSec=5
Environment="SPECH_VAULT_KEY_HEX=your_key_here"

[Install]
WantedBy=multi-user.target

Ative os serviços:

sudo systemctl daemon-reload
sudo systemctl enable spechphone-middleware spechphone-audio
sudo systemctl start spechphone-middleware spechphone-audio
sudo systemctl status spechphone-middleware spechphone-audio

Firewall (UFW)

# Permitir HTTPS
sudo ufw allow 443/tcp

# Permitir SIP
sudo ufw allow 5060/udp

# Permitir RTP (ajuste conforme necessário)
sudo ufw allow 10000:62000/udp

# Ative o firewall
sudo ufw enable

Docker Deployment

Crie Dockerfile:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    openssl \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY . .

RUN curl -L https://github.com/spechshop/pcg729/releases/download/current/php -o /usr/local/bin/php \
    && chmod +x /usr/local/bin/php

EXPOSE 443 5060/udp 10000-62000/udp

CMD ["php", "middleware.php"]

Crie docker-compose.yml:

version: '3.8'

services:
  middleware:
    build: .
    ports:
      - "443:443"
      - "5060:5060/udp"
      - "10000-62000:10000-62000/udp"
    environment:
      - SPECH_VAULT_KEY_HEX=${SPECH_VAULT_KEY_HEX}
    volumes:
      - ./plugins:/app/plugins
      - ./libspech:/app/libspech
    restart: unless-stopped

  audio:
    build: .
    command: php audio.php
    environment:
      - SPECH_VAULT_KEY_HEX=${SPECH_VAULT_KEY_HEX}
    volumes:
      - ./plugins:/app/plugins
      - ./libspech:/app/libspech
    restart: unless-stopped

Execute:

docker-compose up -d

Monitoramento com Prometheus

Adicione endpoint de métricas no seu código:

// plugins/Request/metrics.php
$server->on('request', function ($request, $response) {
    if ($request->server['request_uri'] === '/metrics') {
        $metrics = [
            'active_calls' => getActiveCalls(),
            'total_calls' => getTotalCalls(),
            'cpu_usage' => sys_getloadavg()[0],
            'memory_usage' => memory_get_usage(true),
        ];

        $output = '';
        foreach ($metrics as $key => $value) {
            $output .= "spechphone_{$key} {$value}\n";
        }

        $response->header('Content-Type', 'text/plain');
        $response->end($output);
    }
});

Backup Automatizado

#!/bin/bash
# backup.sh

BACKUP_DIR="/backup/spechphone"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup de configurações
tar -czf $BACKUP_DIR/config_$DATE.tar.gz plugins/configInterface.json .env

# Backup de logs
tar -czf $BACKUP_DIR/logs_$DATE.tar.gz /var/log/spechphone.log

# Manter apenas últimos 7 dias
find $BACKUP_DIR -mtime +7 -delete

Adicione ao crontab:

0 2 * * * /opt/spechphone/backup.sh

FAQ (Perguntas Frequentes)

Geral

Q: O SpechPhone é gratuito?
A: Sim, é open source sob licença Apache 2.0.

Q: Posso usar em produção?
A: O projeto está em beta. Use com cautela em produção e teste extensivamente.

Q: Suporta recebimento de chamadas?
A: Ainda não. Esta funcionalidade está em desenvolvimento.

Q: Funciona no Windows?
A: Recomendamos Linux/macOS. Windows pode funcionar com WSL2.

Técnico

Q: Qual a latência média?
A: Entre 50-150ms dependendo da rede e codec utilizado.

Q: Quantas chamadas simultâneas suporta?
A: Centenas, dependendo dos recursos do servidor (CPU, RAM, rede).

Q: Posso usar com Asterisk/FreeSWITCH?
A: Sim, o SpechPhone é compatível com qualquer servidor SIP padrão.

Q: Suporta IPv6?
A: Sim, desde que o runtime e rede estejam configurados.

Q: Preciso de WebRTC?
A: Não. O SpechPhone usa WebSocket + PCM direto, sem WebRTC.

Codecs

Q: Qual codec oferece melhor qualidade?
A: Opus (48kHz) oferece a melhor qualidade. G.729 oferece melhor compressão.

Q: Posso adicionar outros codecs?
A: Sim, através da extensão do runtime pcg729 ou via FFI.

Q: Qual codec usar para economizar banda?
A: G.729 (8kbps) ou PCMU/PCMA (64kbps).

Segurança

Q: É seguro usar em produção?
A: Use HTTPS/WSS, firewall adequado e atualizações regulares.

Q: Suporta SRTP?
A: Não. O RTP é transportado cru (UDP) no backend.

Q: Como proteger credenciais SIP?
A: Use SPECH_VAULT_KEY_HEX para criptografar configurações sensíveis.

Q: Preciso de VPN?
A: Não é obrigatório, mas recomendado para segurança adicional.

Performance e Otimização

Benchmarks

Ambiente de teste:

• CPU: Intel Core i7-9700K (8 cores)
• RAM: 32GB DDR4
• Rede: 1Gbps
• OS: Ubuntu 22.04 LTS

Métrica	Valor
Chamadas simultâneas	500+
Latência média (Opus)	80ms
Latência média (G.729)	65ms
Uso de CPU (100 chamadas)	45%
Uso de RAM (100 chamadas)	2.8GB
Throughput RTP	150 Mbps

Otimizações Recomendadas

1. Ajuste de Kernel Linux

# Aumente limites de arquivos abertos
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# Otimize rede
sysctl -w net.core.rmem_max=16777216
sysctl -w net.core.wmem_max=16777216
sysctl -w net.ipv4.udp_mem="8192 16384 32768"

2. Configuração Swoole Otimizada

{
  "serverSettings": {
    "worker_num": 8,
    "task_worker_num": 4,
    "max_coroutine": 5000,
    "socket_buffer_size": 2097152,
    "buffer_output_size": 2097152,
    "enable_coroutine": true,
    "max_connection": 10000
  }
}

3. Escolha de Codec

• Baixa latência: PCMU/PCMA (sem processamento)
• Qualidade: Opus 48kHz
• Banda limitada: G.729

4. Profile de CPU

# Use Xdebug para profiling
php -d xdebug.mode=profile middleware.php

# Ou valgrind
valgrind --tool=callgrind php middleware.php

Roadmap

Versão 1.0 (Q2 2025)

• ✅ Chamadas outbound
• ✅ Suporte a múltiplos codecs
• ✅ Interface web responsiva
• ⏳ Recebimento de chamadas (inbound)
• ⏳ Transferência de chamadas
• ⏳ Conferência (3+ participantes)

Versão 1.1 (Q3 2025)

• 📋 Gravação de chamadas
• 📋 IVR (Interactive Voice Response)
• 📋 Call queues (filas de espera)
• 📋 Integração com CRM

Versão 2.0 (Q4 2025)

• 📋 Video calling
• 📋 Screen sharing
• 📋 Chat integrado
• 📋 API REST completa

Futuro

• 📋 Suporte a SIP over TLS
• 📋 SRTP (RTP criptografado)
• 📋 Integração com IA (transcrição, análise)
• 📋 Mobile apps (iOS/Android)

Legenda:

• ✅ Implementado
• ⏳ Em desenvolvimento
• 📋 Planejado

Spechshop - Visão Geral Unificada

Spechshop é uma stack VoIP em PHP + Swoole focada em sinalização SIP-like via UDP, coordenação de workers RTP por CPU e gerenciamento via WebSocket/HTTP(S). Todo o estado é mantido em Swoole\Table, com snapshots JSON e SQLite para dados administrativos.

Stack Detectada

• Runtime: PHP 8.x (CLI) com Swoole (corrotinas; UDP/TCP/HTTP/WebSocket)
• Armazenamento: SQLite3 (gerenciamento), snapshots JSON, Swoole.Table em memória
• Mídia: RTP sobre UDP; RPC UDP entre dispatcher e workers RTP; codecs G.729/Opus/µ-law; gravações PCM opcionais
• Concorrência: workers por CPU fixados com taskset; I/O assíncrono por corrotinas
• Pacote: sem Composer/npm; scripts PHP puros e stubs

Entrypoints e Portas

• server.php — servidor UDP de sinalização (porta 5060)
• mediaServer.php — despachante de mídia; inicializa rtpServer.php (RPC UDP 9503) e um rtpw3.php por core (RTP worker; reports 9505)
• rtpServer.php — coordenação RPC UDP (0.0.0.0:9503) e snapshots rtpc_snapshot.json
• manage/middleware.php — servidor de gerenciamento WebSocket/HTTP(S); TLS conforme manage/plugins/configInterface.json; inicia audio.php
• runnerServer.php / runner.php / runner-worker.php — pipeline auxiliar TCP 9504

Requisitos (Spechshop)

• OS: Linux x86_64 recomendado (usa taskset, screen, sockets UDP)
• PHP 8.1+ CLI com extensões: swoole (5.x recomendado), sqlite3, json, mbstring, pcntl, posix
• Extensões de áudio (produção): bcg729 (G.729), opus, resampler (ex: libsamplerate)
• Pacotes de sistema: build-essential/gcc, make, php-dev, libopus-dev, libsamplerate-dev, taskset, screen
• Rede: UDP 5060/9503/9505, TCP 443 (ou 8080), TCP 4043, TCP 9504
• TLS: arquivos fullchain.pem e privkey.pem na raiz ou configurar em manage/plugins/configInterface.json

Instalação (Spechshop)

1. Clonar o repositório:

   git clone <url_do_repositorio> spechshop
   cd spechshop

2. Instalar PHP e extensões principais:

   pecl install swoole
   apt install php-sqlite3 php-mbstring
   # TODO: compilar/instalar bcg729, opus e Resampler

3. Certificados HTTPS (gerenciamento): colocar fullchain.pem e privkey.pem na raiz ou ajustar o JSON de config.
4. Revisar configurações: plugins/configInterface.json (principal) e manage/plugins/configInterface.json (gerenciamento).
5. Garantir permissões de escrita em logs/, recordings/ e arquivos JSON de snapshot.

Execução & Ferramentas CLI

O script backup controla serviços, backups e diagnósticos:

# list / save / restore backups
./backup list
./backup save my_2025_11_16
./backup restore my_2025_11_16

# delete a version
./backup delete my_2025_11_16

# status e configuração
./backup status
./backup config

# diagnósticos
./backup services
./backup diagnose
./backup diagnose server
./backup killport 9503

# controlar serviços
./backup start server
./backup stop server
./backup restart server
./backup start-all
./backup stop-all

Serviços gerenciados (nomes podem variar): server (UDP 5060), manage (WebSocket/HTTP(S)), media (mediaServer + workers). Há também cron-manager.php para instalar/gerenciar jobs cron.

Configuração

• Sinalização principal: plugins/configInterface.json — porta 5060, worker_num, enable_coroutine, listas de autoload/hot-reload.
• Gerenciamento: manage/plugins/configInterface.json — host, port, ssl, certificados, serverSettings, MIME whitelist.
• Variáveis de ambiente: não há detectadas; configuração é baseada em arquivos.

Painel de Gerenciamento (Spechshop)

O painel é servido por manage/middleware.php com rotas HTTP/WS. Ele expõe dashboards de chamadas, configuração de troncos, estatísticas de workers RTP e controle de serviços. A UI usa os assets em manage/css, manage/js e baseia-se em templates de manage/plugins/Request. A partir dele derivaram-se os projetos open-source atuais (libspech, spechphone) que compartilham a base de sinalização/mídia.

Estrutura do Projeto (alto nível)

• server.php — servidor UDP de sinalização (5060)
• mediaServer.php, rtpServer.php, rtpw3.php — dispatcher de mídia, RPC UDP, workers por core
• manage/middleware.php — gestão WebSocket/HTTP(S); inicia audio.php
• runner.php, runnerServer.php, runner-worker.php — pipeline runner TCP 9504
• plugins/ — módulos core (Utils, Packet, Request, Start, Extension, Message)
• manage/ — UI/API, assets e SQLite; autoload/config próprios
• logs/, recordings/ — logs e gravações opcionais
• Arquivos JSON na raiz: database.json, calls.json, trunks.json, rtpc_snapshot.json, etc.

Tests & Roadmap de Qualidade

Não há testes automatizados no repositório no momento. Recomenda-se adicionar smoke tests (subir plano de mídia e enviar pacotes UDP), unit tests para parsers e utilitários e fluxos ponta-a-ponta.

SpechPhone (README.pt-br completo)

⚠️ IMPORTANTE: Projeto em fase beta e em desenvolvimento. O recebimento de chamadas ainda será implementado.

Arquitetura e Funcionamento

Processamento de áudio e corrotinas: cada trunkController roda em uma corrotina via Swoole, permitindo centenas de chamadas simultâneas. A libspech identifica codecs (G.729, Opus, PCMA/U, L16) e decodifica em tempo real via funções nativas C do runtime pcg729. O áudio decodificado é entregue ao controlador WebSocket em chunks PCM para o navegador consumir diretamente com webkitAudioContext, evitando a complexidade do WebRTC.

Segurança e SSL

• Geração automática de certificados autoassinados (OpenSSL) se não existirem.
• HTTPS e WSS habilitados por padrão para permitir microfone no browser.
• Modelo: sem WebRTC (sem SRTP/ICE/DTLS); áudio em RTP cru (UDP) no backend; cliente fino via WebSocket.
• Requisitos de produção: HTTPS/WSS obrigatórios; proteger portas RTP com firewall.

Requisitos (SpechPhone)

• Runtime PHP otimizado (pcg729) com G.729, Opus, L16 e DSP em C.
• OpenSSL para TLS/SSL.
• Linux/macOS recomendados.
• Nenhuma ferramenta externa de mídia é necessária; codecs e DSP são internos.

Instalação e execução

# dependências de sistema
sudo apt update && sudo apt install -y openssl

# clone repositório principal e biblioteca de codecs
git clone https://github.com/spechshop/spechphone && cd spechphone
git clone https://github.com/spechshop/libspech

# runtime pcg729 (PHP otimizado para áudio)
curl -L https://github.com/spechshop/pcg729/releases/download/current/php -o php
# ou: wget https://github.com/spechshop/pcg729/releases/download/current/php
chmod +x ./php
sudo cp php /usr/local/bin/php

# iniciar serviços (terminais separados recomendados)
php middleware.php
php audio.php

Após subir, abra o link gerado no navegador.

O que é o SpechPhone?

Softphone SIP/VoIP moderno em PHP + Swoole. Permite chamadas de voz em tempo real, controla codecs e integra com backends sem dependências externas de mídia. Código totalmente em PHP com I/O assíncrono por corrotinas.

Características

• Autossuficiente — sem FFmpeg/SoX; processamento interno.
• Codecs integrados — PCMA, PCMU, G.729, Opus, L16 via libspech.
• Processamento embutido — reamostragem, mix, noise suppression, echo cancelation, AGC.
• I/O assíncrono — centenas de sessões por processo.
• Stack completa em PHP — SIP, RTP e controle de mídia no código.
• Integração fácil com front-ends — interface HTML/JS responsiva via WebSocket.

O que posso construir?

• Softphone empresarial com discador, hotkeys e integrações.
• Proxy/SBC cliente via UDP.
• Transmissão de áudio via WebSocket ou RTP para dashboards.
• Monitoramento e gravação usando utilitários nativos.

Funcionalidades

Chamadas e mídia

• Discador com teclado/volume.
• Negociação de codecs PCMA/PCMU/G.729/Opus/L16.
• Controles de mudo, espera, viva-voz e mixagem de múltiplos canais.
• DSP embutido (ruído, eco, ganho).

Rede e SIP

• SIP via UDP.
• Streaming RTP cru por UDP e entrega de áudio via WebSocket.
• HTTPS e WSS com OpenSSL.
• STUN opcional; TURN não utilizado.

Interface

• UI responsiva com modo claro/escuro.
• Páginas modulares: Chamadas, Áudio, Configurações.
• Suporte a atalhos de teclado.

Capturas de tela

Configuração

plugins/configInterface.json define portas, SSL, workers Swoole e parâmetros do servidor. Exemplo de campos: port (HTTP/WS), ssl (bool), serverSettings (workers, certificados).

Variáveis de ambiente: sem credenciais hardcoded. Use SPECH_VAULT_KEY_HEX para chave de criptografia de configurações sensíveis.

Estrutura de diretórios (SpechPhone)

Recursos adicionais

• Lógica SIP/RTP: ver libspech para controladores de chamadas, buffers adaptativos, DTMF.
• Exemplos e ferramentas: libspech/extra com scripts auxiliares para validar ambiente e codecs.
• CLI interativo: plugins/Start/console/cli.php para menus de gerenciamento e status.

Contribuição

• Mantenha cabeçalhos de copyright e licenças.
• Descreva claramente as mudanças e testes realizados.
• Abra issues para dúvidas ou discussões.

Licença (SpechPhone)

Distribuído sob Apache 2.0. Copyright © 2025 Lotus / berzersks.

Licença

This project is licensed under the Apache License 2.0.

Copyright © 2025 Lotus / berzersks
Website: https://spechshop.com
Official Repository: https://github.com/spechshop/libspech

Important Notice to the Community

This is open source software. You are free to use, modify, and distribute it under the Apache 2.0 license. However, we kindly ask that you:

• ✅ Respect the creator: Maintain attribution to Lotus (berzersks) in all derivative works
• ✅ Keep copyright notices: Do not remove or alter copyright notices and attributions
• ✅ Unite the community: Consider contributing improvements to the official repository rather than creating fragmented forks
• ✅ Submit pull requests: Help make this project better for everyone by contributing at github.com/spechshop/libspech
• ✅ Reference the creator: Credit the original author when discussing or referencing this software

A unified community is stronger and advances faster together. Thank you for helping build a respectful and collaborative open source project!

Third-Party Dependencies

Third-party components are under their respective licenses:

• Swoole: Apache License 2.0
• bcg729: GNU GPL v3.0
• Opus: BSD License
• psampler: See repository for details

Review their license files before use in production.