🎵🧠 Toque música. Grave sinal fisiológico. Confie no tempo.
ComPasso é uma plataforma de pesquisa em psicofisiologia que sincroniza a reprodução de músicas com a aquisição contínua do sinal do BITalino (via OpenSignals + Lab Streaming Layer). Áudio, marcadores de evento e amostras do sinal compartilham um único relógio, então o que aparece no gráfico e o que fica gravado no CSV correspondem exatamente ao que o participante ouviu, no mesmo instante.
- ✨ Principais funcionalidades
- 📋 Requisitos
- 📦 Instalação
- 🔌 Antes de abrir o programa
- 🧪 Como funciona uma sessão
- 💾 Onde os dados ficam
- 📚 Documentação completa
- 🔧 Algo deu errado?
- 🎧 Sessão sincronizada por um único relógio — áudio, marcadores (início/fim de faixa, beep,
interrupção) e amostras do sinal usam o mesmo relógio (
pylsl.local_clock()), sem deriva cumulativa ao longo da sessão. - 📈 Gráfico do sinal em tempo real, com zoom ao vivo do eixo Y (funciona durante a própria gravação) e leitura do valor atual na unidade do sensor conectado.
- 🔬 Seis tipos de sensor (EDA, ECG, EMG, EOG, EEG, EGG) — cada um com sua própria unidade e escala padrão de exibição.
- 🗂️ Configurações de experimento reutilizáveis (
.config), com carga automática da última usada e planilha de condições com colunas de nome livre. - 🔊 Calibração de volume opcional, para achar o nível confortável de cada participante antes de começar.
- 🎨 Seis temas (3 escuros, 3 claros), trocados ao vivo, a qualquer momento — mesmo com o BITalino conectado ou uma sessão em andamento.
- 🧪 BITalino simulado — dá para testar a interface inteira (conexão, gráfico, gravação) sem hardware nenhum. Detalhes em docs/bitalino-simulado.md.
- ⚙️ Preferências do app configuráveis (arranque, aparência, arquivos, conexão, diagnóstico),
separadas do protocolo do experimento e registradas por sessão em
ambiente.json. Detalhes em docs/app-settings.md.
- Windows 10/11 ou macOS (Linux funciona como melhor esforço).
- OpenSignals (r)evolution, com o Lab Streaming Layer (LSL) ativado.
- BITalino emparelhado e transmitindo pelo OpenSignals — ou use o BITalino simulado para só testar a interface.
A forma mais simples é baixar o executável pronto — não precisa instalar Python nem nenhuma dependência:
- Acesse a página de Releases e baixe o build
mais recente para o seu sistema (
.exepara Windows,.apppara macOS). - Extraia a pasta em qualquer lugar — é um app "portátil" (onedir), sem instalador.
- Rode
ComPasso.exe(Windows) ou abraComPasso.app(macOS).
Prefere rodar a partir do código-fonte, ou compilar você mesmo? Veja
docs/getting-started.md (fluxo com uv)
e BUILD.md. O executável pode ser gerado com PyInstaller (padrão) ou, para um
binário bem menor (~71 MB), com Nuitka (scripts/build_nuitka.py) — detalhes no BUILD.md.
A conexão com o BITalino só funciona com o Lab Streaming Layer ativo no OpenSignals:
- Abra o OpenSignals (r)evolution.
- Em Settings → Integration, ative Lab Streaming Layer (LSL).
- Coloque o dispositivo para transmitir (botão de play).
Passo a passo completo, incluindo o que fazer se a conexão falhar, em docs/bitalino-connection.md.
- Conecte o BITalino, salve as informações do participante e carregue a pasta de músicas + a
planilha de condições (ou abra um
.configjá pronto). - Clique em Começar — a ordem das faixas é embaralhada, sem repetição.
- Cada faixa passa por uma contagem regressiva, toca até o fim e é gravada em um par de arquivos CSV + XLSX, com o gráfico do sinal acompanhando ao vivo.
- Entre uma faixa e outra, você decide quando avançar — o tempo dessa pausa também fica registrado.
Passo a passo completo, com todas as regras de validação e o fluxo do gráfico do sinal, em docs/running-an-experiment.md.
| O quê | Local |
|---|---|
| Dados do experimento | Documentos/ComPasso/Dados/ (ou a pasta escolhida na sessão) |
Configurações (.config) |
Documentos/ComPasso/Configurações do Experimento/ |
| Logs e erros | pasta de dados do app (Windows: %LOCALAPPDATA%\ComPasso; macOS: ~/Library/Application Support/ComPasso) |
Formato exato dos arquivos e das colunas em docs/output-data.md.
Este README cobre o essencial para começar. Para o detalhe de cada tela, cada validação e cada
arquivo gerado, veja o índice da documentação em /docs — inclui conexão com o
BITalino, menus, arquivo .config, arquivos de entrada, execução de um experimento (com
calibração de volume), dados de saída e solução de problemas.
Os erros mais comuns (conexão, planilha de condições, áudio, tema) e como resolvê-los estão em
docs/troubleshooting.md. O primeiro lugar para olhar quando algo falha
é o arquivo central de erros (errors.log), acessível pelo menu Ajuda → Abrir pasta de logs.
Versionamento em tags vAAAA.M.P — changelog completo em CHANGELOG.md.