Kamafeu Studio

Editor e sintetizador vocal para UTAU e OpenUtau, escrito em Rust.

Desenvolvimento: xiao · Direção de arte: mori-p · QA: makki (Linux), zoneryth (Windows e Linux) e xiao (macOS)

Downloads · Primeiros passos · Compilação · Reportar bug · Pedir recurso · Histórico de alterações

Versão atual: 3.0.0, codinome Calafate. A série 3.0 é a linha principal de desenvolvimento. O núcleo do editor e os formatos principais estão maduros; motores externos, bancos de voz e drivers de áudio ainda precisam ser validados na máquina do usuário.

DEV-MODE: esta pré-release é destinada aos integrantes do Studio Pomar. Ela ainda está em validação e pode apresentar instabilidades.

Linha de lançamentos, suporte e codinomes

Versão	Codinome	Lançamento	Fim de suporte	Situação
`0.1.0-alpha.1`	EX7Carbono	30/07/2026	06/09/2026	encerrada
`0.0.4-hotfix`	7CHidrogenio	06/09/2026	06/09/2026	substituída por `0.0.4-hotfix.1`
`0.0.4-hotfix.1`	Âmbar	06/09/2026	08/09/2026	substituída por `1.0.0-A`
`1.0.0-A`	Bariloche	08/09/2026	19/09/2026	substituída pela linha RC
`1.0.2-rc.1` → `rc.22`	Bariloche	19/09/2026 → 14/10/2026	15/10/2026	encerrada na transição para `3.0`
`3.0` (`3.0.0`)	Calafate	15/10/2026	em aberto	linha atual

Download

O Kamafeu Studio reúne composição, edição e síntese de canto em um só ambiente. O piano roll, as ferramentas de afinação e os ajustes fonéticos oferecem controle sobre cada etapa, desde a calibração do banco de voz (oto.ini) até a renderização. O programa combina motores nativos em Rust com executáveis externos compatíveis.

O nome Kamafeu vem do camafeu, joia esculpida em relevo. O formato nativo .aps mantém a ligação com o Projeto Saturno, antecessor do Kamafeu Studio.

Sumário

Recursos do sistema
- Piano roll e composição melódica
- Bancos de voz e suporte fonético
- Processamento e efeitos (DSP)
- Personalização e temas visuais
Arquitetura e fluxo de síntese
Formatos de arquivo suportados
Motores de áudio
- Motores de afinação (Resamplers)
- Motores de junção e emenda de fonemas (Wavtools)
Kamafeu KAMUSE
Primeiros passos
Instalação para usuários finais
Versão mobile (Android; iOS em avaliação)
Arquivos de configuração, cache e logs
Instruções de compilação
- Linux
- FreeBSD
- macOS
- Windows
Interface de linha de comando
Extensões
Contrato de extensões
Tabela de atalhos de teclado
Estrutura do código-fonte
Guia detalhado dos arquivos
Roteiro de produto
Auditoria comparativa
Star History
Licença

Recursos do sistema

Piano roll e composição melódica

Ferramentas de edição: Ponteiro de seleção e movimentação (V), lápis de desenho contínuo (N), divisão de notas (C) e borracha (E).
Desenho e modelagem de afinação: Pincel livre de pitch (P), glissando em linha reta, pincel gerador de vibrato e suavizador de curvas. Suporte completo a pontos de portamento e envelopes com curvas S, lineares e Bézier.
Suporte a escalas musicais e guia tonal: Assistente de escalas (Maior, Menor Natural, Harmônica, Melódica, Pentatônicas, Blues, Dórico e Mixolídio) com destaque visual das notas dentro do tom e marcação da tônica.
Indicação visual da tonalidade: As linhas do piano roll mudam de cor conforme a escala e a tônica escolhidas, facilitando a criação de harmonias; também é possível selecionar notas fora da escala ativa.
Expressões por nota: Painel inferior retrátil para edição de dinâmica, modulação, velocidade de consoante, sopro (breathiness), formante de gênero (gender) e envelopes UTAU de amplitude em 5 pontos.
Controles por fonema: Com um fonema selecionado, o inspetor permite direcionar alias, flags literais, timing de consoante, envelope UTAU, vibrato e portamento ao subfonema, mantendo visíveis os valores herdados da nota e os overrides persistentes.
Auditoria de render: O inspetor mostra os comandos efetivos de resampler e wavtool com flags, timing e envelope; os caminhos são placeholders e a prévia nunca executa shell.
Navegação sincronizada: Playhead compartilhada entre arranjo, RADAR e piano roll, com acompanhamento horizontal durante a reprodução e opção de acompanhamento vertical das notas.
RADAR interativo: Mini mapa com notas e janela de viewport arrastável para navegar rapidamente por projetos longos, inclusive quando o ponteiro sai dos limites do radar.
Navegação por mouse e trackpad: Scroll vertical no arranjo, Shift + scroll para deslocamento horizontal e suporte a gestos de dois eixos de trackpads.
Waveforms em camadas: Forma de onda do áudio instrumental permanece na faixa de arranjo; a forma de onda vocal processada é exibida separadamente no rodapé do piano roll, sem interferir nas notas de outras faixas.
Ferramenta de repetição de loop: Delimitação de região de repetição [A ... B] diretamente na régua com Shift + Clique / Arraste, além de controles numéricos com recomeço contínuo e sem engasgos.
Metrônomo sincronizado: Síntese de cliques no andamento do projeto com acentuação tonal no primeiro tempo de cada compasso.
Exportação rápida de seleção: Opção de menu e atalho de clique direito para exportar exclusivamente as notas selecionadas no formato [Projeto] - [Voicebank] - wip.wav.
Menu contextual de notas: Ações em lote para converter aliases japoneses VCV→CV ou CV→VCV, remover caracteres não-Hiragana, limpar parâmetros, resetar tempos de fonemas e forçar a atualização fonética, com suporte a Undo/Redo.
Área de trabalho otimizada: Painéis recolhíveis de arranjo multifaixa (Alt + A), expressões (Tab), fonemas (Alt + O), inspetor lateral (Cmd/Ctrl + B) e modo de tela cheia (F11).

Bancos de voz e suporte fonético

Compatibilidade UTAU e OpenUtau: Leitura e gravação de arquivos oto.ini em codificações UTF-8 e Shift-JIS com suporte a múltiplos tons via prefix.map.
Campos do oto.ini: Campos numéricos presentes, mas vazios, equivalem a 0, assim como 0 explícito. Alias vazio usa o nome do WAV; coluna ausente ou número malformado continua sendo erro de validação.
Fonemizadores integrados:
- Japonês: CV (Hiragana), VCV e CVVC, com conversão automática de romaji para kana.
- Português: BRAPA VCCV, CVC, CVVC e VCV, além de conversão ortográfica G2P.
- Inglês: VCCV com suporte ao inventário fonético de encontros consonantais.
- Modo manual: inserção direta de aliases e subfonemas separados por ponto ou ponto e vírgula.
Conversão de letras japonesas: limpeza de caracteres não Hiragana, normalização de Katakana e conversão contextual de aliases CV/VCV pelo menu da nota.
Régua de fonemas: Visualização gráfica dos limites de corte, preutterance, overlap e consoante fixa diretamente abaixo do piano roll.
Pacotes compactados .kfv: Formato do Kamafeu para distribuição de cantores virtuais com metadados e áudio empacotados.

Processamento e efeitos (DSP)

Rack de efeitos integrado: Equalizador paramétrico e gráfico de 31 bandas, compressor de dinâmica, chorus, delay de sincronismo e reverb estéreo aplicáveis por faixa.
Visualização de áudio otimizada: Waveforms processadas em cache, com atualização em segundo plano e invalidação por alteração, reduzindo trabalho repetido durante edição e reprodução.
Alinhamento de fase e equal-power crossfade: Junção suave entre notas adjacentes na mixagem de saída, eliminando estalos de fase e picos de distorção no somatório do buffer.
Auto-Pitch: Sistema de afinação orgânica para aplicação de portamentos de entrada, quedas de final de frase e vibratos proporcionais ao andamento musical.

Personalização e temas visuais

O Kamafeu Studio conta com um editor de temas em tempo real (Ctrl + Alt + T / Cmd + Alt + T). Ele permite editar cores da interface e do editor, criar uma biblioteca de temas, importar arquivos antigos ou versionados e exportar temas em JSON.

O tema padrão Calafate 3.0 combina grafite quente, ameixa suave, coral de goiaba e texto marfim. Os acentos são discretos, sem depender de ciano elétrico ou neon; estados de sucesso, aviso e erro mantêm cores editáveis próprias.

As paletas oficiais são verificadas automaticamente com a razão de contraste WCAG AA (4,5:1 para texto normal) entre o texto primário e as superfícies de canvas e painel. Temas personalizados não são sobrescritos: a mesma regra fica disponível no núcleo como contrast_ratio_rgb e meets_text_contrast, permitindo que a interface e plugins diagnostiquem combinações de baixo contraste sem alterar a escolha do usuário.

Calafate 3.0 (padrão 3.0.0)

Grafite quente, notas em ameixa e seleção coral, com curvas em lilás suave e playhead âmbar. Temas personalizados existentes são preservados na atualização.

Pomar Neon (Esmeralda)

Âmbar Clássico

Cyberpunk (Synthwave)

Nordic Slate (Clean Dark)

Horta Mikan

Arquitetura e fluxo de síntese

A arquitetura do Kamafeu Studio foi projetada de ponta a ponta em Rust para garantir baixa latência na interface do usuário, processamento DSP determinístico e síntese paralela de áudio.

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           CAMADA DE PROJETO & MODELAGEM                         │
│  Projeto (.aps, .ustx, .ust, .mid, .ufdata, .svp, .vsqx)                        │
│  ├── Faixas Vocais e Partes de Áudio (Volume, Pan, Mute, Solo)                  │
│  ├── Sequência de Notas (Posição ms, Duração ms, Notação MIDI, Sílaba / Letra)   │
│  ├── Curva Contínua de Afinação (Pontos de Portamento, Vibrato, Glissando)       │
│  └── Parâmetros de Expressão (Dinâmica, Velocity, Modulação, Sopro, Gênero)     │
└──────────────────────────────────────┬──────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                    CAMADA FONÉTICA & TEMPORIZAÇÃO (oto.ini)                     │
│  ├── Resolução de Fonemas: Motor Fonemizador (Japonês, Português BRAPA, Inglês)  │
│  ├── Mapeamento Multitom: prefix.map (Seleção automática da amostra por tom)    │
│  └── Calibragem Acústica: oto.ini                                               │
│      (Offset, Consonant Fixo, Cutoff, Preutterance de Ataque, Overlap de Fusão) │
└──────────────────────────────────────┬──────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                   PIPELINE DE RENDERIZAÇÃO & SÍNTESE DSP                        │
│  ├── Fila Concorrente (Thread Pool Rayon) & Cache de Amostras em Memória        │
│  ├── Resampler (Modulação Tonal & Estiramento Temporal):                        │
│  │   ├── Tainah: análise/ressíntese WORLD com stretch de sustentação e erro explícito │
│  │   └── straycat-rs / Motores Externos via UTAU CLI Protocol                    │
│  ├── Wavtool (Emenda, Splicing & Envelopamento):                                │
│  │   ├── Andromeda: wavtool alternativo para envelopes UTAU                      │
│  │   └── wavtool-yawu / Utilitários Externos                                    │
│  ├── Alinhamento de Fase: Redução de cancelamentos harmônicos em vogais ligadas │
│  ├── Rack de Efeitos (FX): Equalizador Gráfico 31 bandas, Compressor, Reverb     │
│  └── Barramento de Saída: Streaming progressivo (AudioPlayer) / Exportação WAV   │
└─────────────────────────────────────────────────────────────────────────────────┘

Etapas do ciclo de processamento

Estrutura de dados e eventos temporais: O projeto decompõe composições em faixas e partes independentes. As notas musicais contêm posições e durações absolutas em milissegundos calculadas em função do andamento (BPM) e da métrica de compasso.
Resolução fonética e particionamento silábico: O fonemizador converte as letras digitadas em cadeias de fonemas individuais (como ataques de início de frase, transições consoante-vogal e consoantes de término). Para cada fonema, o sistema consulta a tabela oto.ini do cantor ativo e determina a amostra WAV correspondente de acordo com o tom da nota (prefix.map).
Cálculo de temporização e sobreposição (Timing Engine): A posição acústica de cada amostra é ajustada aplicando os valores de preutterance (para antecipar consoantes antes da batida musical) e overlap (definindo a zona de fusão com a nota precedente).
Resampling e transposição tonal: O resampler selecionado processa o trecho definido por offset e cutoff. Tainah usa WORLD para ajustar altura e duração e retorna um diagnóstico quando a biblioteca não carrega ou quando análise, síntese ou cobertura falham. SOLA é um motor separado e não substitui Tainah em caso de erro.
Emenda, envelopamento e splicing (Wavtool & Mixing): O wavtool escolhido aplica o envelope e posiciona as amostras. Andromeda é uma alternativa que aplica o envelope UTAU com curva cosseno; Galapagos é o caminho nativo de alinhamento de fase. Seus papéis e critérios são distintos, e nenhum rótulo sozinho comprova qualidade acústica.
Streaming em tempo real e visualização: O renderizador despacha tarefas em paralelo por blocos temporais (progressive chunks) através de um pool de threads gerenciado pelo Rayon. À medida que os blocos ficam prontos, eles são enviados diretamente para o dispositivo de áudio através de canais sincronizados sem bloqueio da interface gráfica, gerando simultaneamente a forma de onda de alta resolução exibida no fundo do piano roll.

Por baixo dos panos

Esta seção descreve o caminho que uma nota percorre dentro do Kamafeu. A interface é apenas a camada visível: o resultado audível depende da combinação entre o modelo persistido, a resolução fonética, a geometria do oto.ini, o motor de resampling, o wavtool e o scheduler de áudio.

1. O projeto é um modelo temporal, não uma lista de eventos soltos

O editor trabalha sobre um UProject. Ele contém faixas, partes vocais, partes de áudio, marcadores, seções, andamento, métrica e estado de renderização. Uma nota (UNote) guarda pelo menos:

posição e duração em milissegundos;
chave MIDI e letra original;
alias ou cadeia de subfonemas;
pontos de portamento, pitch bend e vibrato;
velocity, dinâmica, volume, ataque, decay, gênero, sopro e modulação;
envelope UTAU e overrides de fonemas.

O tempo interno é convertido para milissegundos antes de chegar ao renderer. Isso permite que piano roll, arrangement, régua de fonemas, RADAR, loop e playhead compartilhem a mesma linha do tempo. Quando o BPM muda, o projeto ajusta as posições temporais preservando as posições musicais, em vez de simplesmente deslocar pixels na interface.

O arquivo .aps é o formato nativo porque preserva esse modelo completo. O .ufdata é mantido como formato universal de intercâmbio: exporta notas, tempo e pitch em ticks/semitons, mas não substitui o APS e informa as perdas de FX rack, áudio e metadados próprios. Formatos de intercâmbio mais antigos ou externos passam por adaptadores que registram o que foi convertido e o que não possui equivalente direto.

2. A fonemização acontece antes do áudio

Ao importar ou editar uma letra, o Kamafeu não envia texto diretamente ao resampler. O dispatcher escolhe um modo fonético entre japonês CV/VCV/CVVC, português BRAPA ou G2P, inglês VCCV, modo manual e outros disponíveis. Depois, transforma a nota em uma sequência de aliases.

O resultado é resolvido contra o voicebank ativo nesta ordem conceitual:

respeitar alias manual ou override persistido;
procurar a variante de tom indicada por prefix.map;
escolher a entrada correspondente no oto.ini correto, inclusive em subpastas;
aplicar contexto de frase, transição e variantes CV/VC/VCV;
registrar falha explícita quando um fonema necessário não existe.

O oto.ini continua sendo a autoridade acústica. Seus valores de offset, consonant, cutoff, preutterance e overlap não são substituídos por uma sugestão visual da interface. O inspector e o Copaiba expõem a geometria resolvida para revisão, mas a renderização usa a entrada efetivamente encontrada no banco.

3. O timing engine transforma aliases em segmentos acústicos

Depois da resolução fonética, o timing engine calcula a posição de cada segmento no eixo absoluto do projeto. Ele combina:

duração musical da nota;
duração de cada fonema;
preutterance e overlap do oto.ini;
consonant fixa, offset e cutoff;
overrides importados de UST/USTX;
velocity e controles de timing por fonema;
transições entre notas adjacentes e frases VCV/CVVC.

Esse estágio é importante porque o mesmo alias pode ocupar regiões diferentes da amostra dependendo do contexto. A consoante não deve ser esticada como uma vogal sustentada, e um overlap existente no oto.ini não deve receber um segundo fade arbitrário apenas porque duas notas são vizinhas.

O renderer também calcula envelopes absolutos por fonema. Assim, a transição de uma consoante para uma vogal e a transição entre duas vogais continuam complementares mesmo quando há mudanças de velocidade, notas curtas, portamento ou duração negativa de cutoff.

4. Drivers isolam o contrato entre Kamafeu e motores de áudio

O renderer não precisa conhecer cada detalhe de um executável externo. Ele produz uma solicitação normalizada e entrega a execução a um driver:

driver nativo: chama os módulos Rust do próprio aplicativo;
driver externo: monta a linha de comando compatível com o protocolo UTAU;
driver via Wine: converte caminhos e prepara o ambiente para executáveis Windows em macOS/Linux;
driver de wavtool: une segmentos, aplica envelope e devolve o trecho pronto para a mixagem.

Os drivers mantêm separados o nível do resampler e o nível do wavtool. O resampler altera altura e duração do material útil; o wavtool posiciona os segmentos no tempo, aplica o envelope de amplitude e realiza o crossfade. Misturar essas responsabilidades causaria duplicação de fades, perda da consoante fixa ou diferenças de duração entre o áudio e a playhead.

Falhas de processo, alias ausente, saída vazia, amostras não finitas e geometria inválida são tratados como diagnóstico. O sistema não deve transformar um erro de resampler em áudio silencioso apresentado como sucesso.

5. O renderer é paralelo, mas a timeline de áudio é ordenada

Projetos longos são divididos em janelas temporais. O pool de tarefas pode renderizar várias janelas em paralelo, porém cada chunk carrega identidade de geração, índice, início e fim absolutos, taxa de amostragem e número de canais.

O fluxo possui duas filas conceituais:

renderer worker
    ├── progresso e mensagens de diagnóstico ──> UI
    └── chunks de áudio ──> playback buffer ──> scheduler ──> dispositivo

O playback buffer rejeita chunks duplicados, antigos, fora de ordem ou com mudança inesperada de canais. O scheduler só entrega ao dispositivo uma sequência temporal contígua. Isso permite que a interface receba um chunk atrasado sem reiniciar o áudio ou mover a playhead para trás.

O áudio progressivo é diferente de um render completo bloqueante: a reprodução pode começar quando existe runway suficiente, enquanto os chunks seguintes continuam sendo produzidos. O scheduler controla o que já foi aceito pelo dispositivo; a UI usa a posição do player quando disponível e um fallback monotônico quando o backend não fornece posição direta.

6. Mixagem, fase e efeitos acontecem depois da síntese dos segmentos

Cada faixa recebe os segmentos resolvidos pelo renderer. Na mixagem, o Kamafeu:

preserva a geometria temporal calculada para cada fonema;
alinha bordas periódicas quando há informação suficiente de fase;
usa equal-power crossfade nas junções necessárias;
soma volume e pan por faixa;
processa o FX rack quando habilitado;
valida amplitude, finitude e layout de canais;
envia o buffer para playback progressivo ou exportação.

A análise de fase é uma correção de junção, não um novo motor de síntese. Ela evita cancelamento harmônico e estalos nas bordas sem alterar a afinação musical solicitada. O rack de efeitos também permanece depois da renderização das vozes, para que bypass, compressor, equalizador, chorus, delay e reverb possam ser comparados de maneira previsível.

7. A interface recebe estado; ela não executa o renderer

O KamafeuStudioApp coordena estado e eventos. A interface egui desenha piano roll, arrangement, inspector, RADAR, envelopes e notificações a partir desse estado. Workers de renderização comunicam progresso por canais; a UI coleta mensagens em cada frame e atualiza:

percentual e título do render;
status do transport;
waveform processada;
chunks aceitos ou rejeitados;
posição da playhead;
estado de erro, cancelamento ou conclusão.

O RADAR e o arrangement não mantêm relógios separados. Ambos consomem playhead_ms. O scrub altera a posição compartilhada e, quando necessário, interrompe o áudio atual antes de permitir um novo playback a partir do ponto escolhido.

Animações visuais passam pela política central de src/gui/animation.rs. Ela limita amplitude, velocidade e cadência; reduce_motion elimina movimento contínuo; frame time alto muda para qualidade reduzida; animações desativadas não mantêm repaint contínuo. Isso é deliberado: repaint da UI é um mecanismo visual e de polling, não o relógio de áudio.

8. Cache, cancelamento e proveniência evitam trabalho invisível

Solicitações de resampler podem ser reutilizadas quando a identidade dos inputs é a mesma. A chave considera conteúdo e parâmetros relevantes, e alterações no áudio de origem invalidam a análise associada. O cache reduz chamadas repetidas, mas não transforma um artefato antigo em resultado válido quando projeto, voicebank, timing ou engine mudaram.

Cada render possui um token de cancelamento. Parar a reprodução, iniciar outra geração ou fechar a tarefa marca o trabalho anterior como obsoleto; chunks antigos não devem contaminar o waveform nem o scheduler atual.

Renders e exports podem gerar proveniência em JSON ao lado do áudio. O sidecar registra hashes e decisões de timing, incluindo dados de oto.ini, overrides, extensões e diagnósticos de borda. Esses dados permitem investigar uma diferença de áudio sem depender apenas de mensagens visuais ou de memória do usuário.

9. Extensões são descobertas por manifesto e executadas com limites

O catálogo de extensões separa descoberta, consentimento e execução. Um manifesto declara tipo, versão, limitações, permissões e entrypoint. Caminhos absolutos ou que escapam da pasta da extensão são rejeitados.

Extensões WASM passam por verificação de versão da API antes da ativação. O runtime valida assinatura de exports e limites do buffer invocado; a existência de um arquivo .wasm não significa que o módulo seja um fonemizador, resampler ou efeito funcional. A execução deve possuir contrato de entrada, saída, codificação fonética, pré-processamento e decodificação documentados.

10. O que esta série garante e o que ainda depende do ambiente

Os testes automatizados cobrem modelo, formatos, fonemização, timing, drivers nativos, mixagem, cache, playback progressivo, contratos de extensão e interações importantes da UI. A release também publica artefatos por plataforma através do workflow de build.

Ainda assim, três camadas exigem validação no computador do usuário:

dispositivo de áudio, backend gráfico e permissões do sistema;
voicebank específico, codificação, aliases e qualidade do oto.ini;
executáveis externos, Wine, bibliotecas compartilhadas e comportamento do resampler escolhido.

Por isso 3.0 inaugura a série Calafate, enquanto a última milha acústica continua dependendo dos recursos instalados em cada máquina.

Formatos de arquivo suportados

O Kamafeu Studio lê e grava projetos em múltiplos formatos do ecossistema de síntese vocal:

Formato	Extensão	Importação	Exportação	Descrição técnica
Arquivo de Projeto Saturno	`.aps`	Sim	Sim	Formato nativo do Kamafeu Studio. Armazena em JSON estruturado todas as faixas vocais, partes de áudio WAV, curvas contínuas de pitch bend em alta resolução, envelopes de 5 pontos, configurações do FX Rack e metadados de projeto.
OpenUtau Project	`.ustx`	Sim	Sim	Formato moderno do OpenUtau (YAML). Preserva estrutura multifaixa, cantores atribuídos, expressões dinâmicas, curvas de afinação e parâmetros de respiração/gênero.
UTAU Sequence Text	`.ust`	Sim	Sim	Formato clássico do UTAU. Arquivo de texto estruturado por seções `[#0000]` contendo notas, letras, andamento (BPM), portamentos (`PBType`, `PBDst`) e envelopes de amplitude.
Standard MIDI File	`.mid`, `.midi`	Sim	Sim	Padrão internacional MIDI. Importa e exporta notas, tempos métricos, andamento e mensagens de pitch wheel para intercâmbio com DAWs como Reaper, FL Studio, Ableton e Logic Pro.
UtaFormatix Data	`.ufdata`	Sim	Sim	Esquema universal de intercâmbio (JSON). Exporta notas, tempo e pitch; não armazena FX rack, áudio de arranjo ou metadados específicos do Kamafeu. A exportação informa essas perdas.
Synthesizer V Project	`.svp`	Sim	Sim	Formato de projeto do Synthesizer V (Dreamtonics). Conversão direta de trilhas melódicas, notas, letras e divisões silábicas.
VOCALOID Sequence	`.vsqx`	Sim	Sim	Formato de sequência XML do VOCALOID (Yamaha). Converte dados de trilhas de canto (`vocaloidStyleTrack`), notas musicais, letras e curvas de pitch bend.
Kamafeu Voicebank	`.kfv`	Sim	Sim	Pacote de cantor do Kamafeu Studio (ZIP compactado). Agrupa gravações de áudio WAV, arquivos `oto.ini`, `character.txt`, `prefix.map` e metadados de identificação do banco de voz.

Os formatos .aps, .ustx, .ust, .mid/.midi e .kfv são os formatos mais diretamente integrados ao fluxo do Kamafeu. .ufdata, .svp e .vsqx possuem conversores próprios e devem ser tratados como formatos de intercâmbio: algumas informações específicas de cada aplicativo podem não ter equivalente no modelo interno do Kamafeu e, portanto, podem não sobreviver a uma conversão de ida e volta.

Motores de áudio (Resamplers e Wavtools)

O Kamafeu Studio permite alternar entre o pipeline nativo de processamento e ferramentas clássicas de linha de comando:

Motores de afinação (Resamplers)

Tainah: Resampler WORLD integrado ao Kamafeu por uma biblioteca compartilhada sob LGPL-3.0. Estende a sustentação e preserva ataques e caudas conforme os tempos de oto.ini, com suporte às flags g, t, B e H. Erros de carregamento, análise, síntese ou cobertura são informados sem troca automática para SOLA ou redimensionamento. A biblioteca Tainah 2.1.0 já acompanha os pacotes desktop, então não é preciso instalá-la à parte para usá-la no Kamafeu. O Tainah também pode ser baixado separadamente para testar em outros sintetizadores compatíveis com o protocolo de resampler UTAU. Veja o repositório do Tainah e os downloads. Consulte o estado auditado dos motores.
SOLA (Nativo · experimental): Driver nativo independente e backend explicitamente usado pelo preview KFV 2 atual. A comparação auditiva necessária para escolher um backend de referência ainda não foi concluída.
straycat-rs (UtaUtaUtau): Motor padrão recomendado para máxima compatibilidade e clareza acústica.
Motores externos: Suporte transparente a executáveis da comunidade como Hifisampler, macres, moresampler, OpenMoresampler, world4utau, TIPS e Organum. Os artefatos de release compilam straycat-rs e Organum quando a plataforma permite; o openmoresampler.exe versionado do repositório é um artefato separado e só deve ser considerado incluído quando estiver presente no pacote baixado. No macOS e Linux, executáveis Windows dependem do Wine. Consulte os avisos de terceiros.

Motores de junção e emenda de fonemas (Wavtools)

Andromeda (wavtool alternativo): Implementação nativa que aplica o envelope UTAU por fonema com curva cosseno. A concatenação/alinhamento de fase é fornecida por outros caminhos do mixer.
wavtool-yawu / wavtool clássico: Junção e costura de fonemas via linha de comando com suporte a fluxo contínuo por frases.

Kamafeu KAMUSE

KAMUSE significa Kamafeu Autoria e Modelagem de Unidades Sonoras Editáveis. É a ferramenta guiada para criar bancos nativos cantor.toml. Ela importa gravações WAV e MP3 sem alterar os originais, permite revisar as marcações em milissegundos, organiza gravações por idioma e tom e empacota o banco em .kfv. Tainah WORLD é a engine nativa disponível; falhas são mostradas sem troca automática para SOLA. A especificação e um exemplo estão em docs/cantor-toml.md.

Bancos UTAU com oto.ini continuam disponíveis no editor principal. O KAMUSE se concentra na autoria do formato nativo.

Primeiros passos

Obtenha o executável: Baixe a versão correspondente ao seu sistema operacional na aba de Releases ou realize a compilação local.
Carregue um banco de voz: Abra a aba de cantores no painel lateral e selecione uma pasta de voicebank contendo arquivos .wav e oto.ini.
Crie ou importe sequências: Desenhe notas com o lápis (N) ou importe projetos .ustx, .ust ou .mid pelo menu Arquivo.
Configure a fonética: Selecione o fonemizador apropriado no menu Modos Vocais ou insira aliases manualmente nas notas.
Modele a afinação: Utilize a ferramenta de pitch (P) para criar curvas de transição, portamentos e vibratos.
Reproduza e exporte: Pressione Espaço para ouvir a prévia e utilize o menu Arquivo -> Exportar Áudio para gerar o arquivo final em WAV ou FLAC.

Instalação para usuários finais

Os pacotes oficiais são publicados na página de Releases. Cada pacote inclui o editor, o Kamafeu KAMUSE e os resamplers externos compilados para a plataforma correspondente.

Windows

Baixe o pacote windows-x64 ou windows-x86.
Extraia o .zip para uma pasta de sua preferência.
Execute kamafeu.exe.

O Windows x64 é a opção recomendada. O pacote não possui instalador tradicional; o programa pode ser executado diretamente da pasta extraída.

macOS

Baixe o pacote macos-arm64 para Apple Silicon ou macos-intel para Macs Intel.
Abra o .dmg e execute Kamafeu.app.
Caso o macOS exiba um aviso de segurança, autorize o aplicativo em Ajustes do Sistema -> Privacidade e Segurança.

Os artefatos podem não estar assinados ou notarizados, dependendo da release.

Linux

Baixe o pacote linux-x64.
Extraia o .tar.gz.
Execute ./kamafeu a partir da pasta extraída.

O pacote é distribuído como binário portátil, mas ainda depende das bibliotecas gráficas e de áudio indicadas na seção de compilação. Para resamplers Windows, instale o Wine antes de abrir o projeto.

Android

Baixe o APK Android ARM64 quando ele estiver anexado à release.
Autorize a instalação de aplicativos externos, se necessário.
Instale o APK e conceda acesso aos arquivos quando solicitado.

O APK é experimental. No Android, os caminhos disponíveis são os nativos WORLD e Galapagos; falhas de Tainah retornam erro sem trocar para SOLA. Resamplers externos e executáveis Windows não são suportados.

iOS

Não há pacote oficial para iOS nesta release. A seção de requisitos usa iOS 15.1 apenas como referência de compatibilidade de aplicativos modernos.

Dependências em tempo de execução

Além do executável, o uso completo pode depender de recursos do sistema:

Windows: dispositivo de áudio funcional e drivers atualizados. Resamplers .exe funcionam nativamente.
macOS: CoreAudio e permissões de áudio/arquivos do sistema. Wine é necessário para resamplers Windows.
Linux: ALSA, X11 ou Wayland e as bibliotecas gráficas da distribuição. Wine é necessário para resamplers Windows.
Android: armazenamento acessível pelo seletor de arquivos do sistema e driver gráfico compatível. O armazenamento é controlado pelo sandbox do Android.
iOS: ainda sem build oficial; não há dependências de execução definidas.

O Kamafeu não instala automaticamente voicebanks de terceiros. Os arquivos WAV, oto.ini, character.txt e, quando aplicável, prefix.map devem ser fornecidos pelo usuário.

Arquivos de configuração, cache e logs

O aplicativo armazena preferências, últimos projetos e últimos voicebanks usados em kamafeu_config.json. Nas builds nativas atuais, o caminho padrão é $HOME/.config/kamafeu/kamafeu_config.json; se a variável HOME não estiver disponível, o arquivo é criado como kamafeu_config.json no diretório atual. O caminho do cache de resamplers é $HOME/.cache/kamafeu/resampler-v<versão> no Linux/Windows e $HOME/Library/Caches/kamafeu/resampler-v<versão> no macOS, e pode ser alterado pelas preferências do aplicativo.

O cache contém dados temporários de renderização e pode ser removido para diagnóstico ou para liberar espaço. Remover o cache não apaga projetos nem voicebanks. Para investigar falhas, use a janela Console do editor e inclua o log de renderização ao abrir um issue.

Projetos recentes e voicebanks recentes são apenas referências de caminho; mover ou renomear esses arquivos pode exigir que sejam selecionados novamente no editor.

Com autosave ativado, projetos com alterações pendentes recebem cópias APS recuperáveis no intervalo configurado (30 a 600 segundos). Para um projeto salvo, elas ficam em .kamafeu_snapshots ao lado do arquivo; para um projeto ainda sem nome, ficam na pasta atual. Em Arquivo → Recuperar Snapshot..., escolha uma cópia por data e tamanho. Ela abre de forma segura como um projeto novo: use Salvar Como para preservar a recuperação sem substituir o snapshot. Esse mecanismo funciona nas versões desktop; a edição Web não grava snapshots locais.

Versão mobile (Android; iOS em avaliação)

O Kamafeu Studio conta com infraestrutura baseada em winit e egui, permitindo a compilação para Android. O suporte a iOS permanece em avaliação e não faz parte dos artefatos oficiais desta série. O ecossistema mobile impõe desafios arquiteturais e restrições técnicas significativas:

Desafios de adaptação e build

Impossibilidade de executar resamplers externos (Subprocessos CLI):
- Nos sistemas operacionais desktop (Windows, macOS, Linux), o Kamafeu pode invocar executáveis externos como straycat-rs.exe ou hifisampler através de processos filhos (std::process::Command) e Wine.
- No Android e iOS, o isolamento rigoroso de processos (sandbox) e as políticas de segurança das lojas proíbem a criação de processos filhos arbitrários e a execução de binários Win32/x86.
- Estado no Kamafeu: Dispositivos móveis usam resampling nativo WORLD e o caminho nativo Galapagos para mistura/alinhamento. Falhas WORLD não recorrem a SOLA; a disponibilidade do código não substitui testes de performance e áudio no aparelho.
Sistema de arquivos e permissões de armazenamento (Scoped Storage):
- No Android moderno (API 30+) e iOS, o acesso direto a caminhos tradicionais como /sdcard/ ou pastas compartilhadas é bloqueado. O carregamento de voicebanks e projetos exige integração com Storage Access Framework (SAF) ou empacotamento prévio em arquivos .kfv / .zip.
Adaptação de interface para toque (Touch & Gesture Input):
- O piano roll e a régua do UTAU foram historicamente projetados para cursor de mouse com precisão de pixel, botões secundários (clique direito) e atalhos de teclado.
- A adaptação mobile exige zonas de toque ampliadas, gestos de pinça (pinch-to-zoom) para navegação temporal e vertical, e diálogos contextuais sensíveis ao toque.
Gerenciamento de memória e limites de CPU:
- Em dispositivos móveis, a renderização multithread com Rayon precisa respeitar limites térmicos e de consumo de bateria, exigindo particionamento adaptativo de blocos de áudio e buffers menores de baixa latência (via AAudio/OpenSL ES no Android e CoreAudio no iOS).

Compilação para Android

A compilação do APK do Kamafeu utiliza a ferramenta cargo-apk e o Android NDK:

# Compilar APK em modo release para arquitetura ARM64
cargo apk build --lib --release --no-default-features --target aarch64-linux-android

Os binários Android não são publicados pelo workflow desktop; a assinatura exige um keystore configurado conforme docs/android-signing.md.

Para instruções detalhadas sobre assinatura criptográfica de APKs e variáveis de ambiente de keystore, consulte docs/android-signing.md.

Especificações técnicas

O Kamafeu Studio é um aplicativo nativo relativamente leve. Os requisitos abaixo são referências práticas para executar o editor; voicebanks grandes, muitos tracks, efeitos e renderizações simultâneas podem exigir mais recursos.

Plataforma	Requisito mínimo	Requisito recomendado
Windows	Windows 10/11, CPU dual-core, 2 GB de RAM, 500 MB livres e GPU integrada compatível com a renderização gráfica do sistema	Windows 10/11 64-bit, CPU quad-core, 8 GB de RAM, 1 GB livre e GPU integrada moderna
macOS	macOS compatível com Intel ou Apple Silicon, CPU dual-core, 2 GB de RAM e 500 MB livres	macOS atualizado, Apple Silicon ou Intel quad-core, 8 GB de RAM e 1 GB livre
Linux	Distribuição 64-bit com X11 ou Wayland, ALSA, CPU dual-core, 2 GB de RAM e 500 MB livres	Distribuição 64-bit atual, CPU quad-core, 8 GB de RAM, ALSA e 1 GB livre
Android	Android 5.0/API 21 ou superior, CPU ARM, 3 GB de RAM e 500 MB livres	Android 10/API 29 ou superior, ARM64, 4 GB ou mais de RAM e 1 GB livre
iOS	Referência: iOS 15.1 ou superior, aproximadamente 2 GB de RAM e 500 MB livres	iOS atualizado, aparelho com 4 GB ou mais de RAM e 1 GB livre

Arquiteturas e artefatos

Windows: x86_64-pc-windows-msvc (x64) e i686-pc-windows-msvc (x86).
macOS: x86_64-apple-darwin (Intel) e aarch64-apple-darwin (Apple Silicon).
Linux: x86_64-unknown-linux-gnu.
Android: aarch64-linux-android (ARM64) no APK distribuído; o pipeline também contempla ARMv7.
iOS: nenhum artefato oficial nesta release.

O suporte a iOS ainda está em avaliação e não faz parte dos artefatos oficiais desta release. A versão iOS 15.1 é usada apenas como referência de compatibilidade com aplicativos atuais, como o WhatsApp, e não significa que exista uma versão iOS publicada do Kamafeu Studio.

Os valores de memória são estimativas operacionais, pois o projeto não impõe um limite mínimo de RAM. O espaço indicado não inclui voicebanks, projetos, cache e arquivos temporários do usuário.

Instruções de compilação

Requisitos básicos: Rust 1.82 ou superior e ferramenta Cargo instalados via rustup.rs.

Linux

Instale o compilador C, o gerenciador de pacotes pkg-config, os cabeçalhos do ALSA para áudio e as bibliotecas gráficas do X11/Wayland:

Ubuntu / Debian / Linux Mint / Pop!_OS

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  pkg-config \
  libasound2-dev \
  libxcb-render0-dev \
  libxcb-shape0-dev \
  libxcb-xfixes0-dev \
  libxkbcommon-dev \
  libfontconfig1-dev

Fedora / RHEL

sudo dnf install -y \
  gcc \
  pkg-config \
  alsa-lib-devel \
  libxcb-devel \
  libxkbcommon-devel \
  fontconfig-devel

Arch Linux / Manjaro

sudo pacman -S --needed \
  base-devel \
  pkgconf \
  alsa-lib \
  libxcb \
  libxkbcommon \
  fontconfig

FreeBSD

No FreeBSD, instale o compilador LLVM/Clang, pkgconf e as bibliotecas do sistema gráfico X11 e ALSA:

sudo pkg install -y \
  rust \
  pkgconf \
  alsa-lib \
  libxcb \
  libxkbcommon \
  fontconfig

Nota: Para habilitar a saída de áudio com compatibilidade ALSA no FreeBSD, certifique-se de que o pacote alsa-plugins esteja configurado ou utilize a camada de emulação de áudio OSS/sndio suportada pelo sistema.

macOS

No macOS (Apple Silicon M1/M2/M3/M4 ou Intel x86_64), são necessárias apenas as ferramentas de linha de comando do Xcode (o backend gráfico Metal/Cocoa e o subsistema CoreAudio são nativos):

# Instalar ferramentas de compilação da Apple
xcode-select --install

Windows

No Windows 10/11, utilize a cadeia de ferramentas MSVC recomendada pelo Rust:

Baixe e instale o Visual Studio Build Tools.
No instalador, marque a carga de trabalho Desenvolvimento para Desktop com C++ (Desktop development with C++) e conclua a instalação dos componentes Windows 10/11 SDK.
Certifique-se de que o Rust esteja configurado para a toolchain MSVC:
```
rustup default stable-x86_64-pc-windows-msvc
```

Compilação dos binários

Clone o repositório e compile todos os executáveis em modo otimizado (release):

git clone https://github.com/studiopomar/kamafeu.git
cd kamafeu
cargo build --release --bins

Os executáveis gerados estarão localizados em target/release/:

kamafeu (ou kamafeu.exe no Windows): Editor principal e sintetizador multifaixa.
kamuse (ou kamuse.exe no Windows): Ferramenta de autoria de bancos nativos Kamafeu KAMUSE. O executável copaiba permanece como alias de compatibilidade.

Limitações conhecidas da RC

O aplicativo não instala automaticamente resamplers de terceiros. O pacote oficial inclui apenas os motores externos cuja compilação foi concluída no workflow; outros executáveis devem ser instalados pelo usuário.
No macOS, o artefato é um Kamafeu.app dentro do .dmg, mas assinatura e notarização dependem do processo de distribuição do mantenedor.
A qualidade final depende das gravações, marcações e cobertura fonética do banco, além do resampler/wavtool escolhido. Bancos UTAU continuam dependendo da qualidade do oto.ini.
A reprodução com motores externos no Linux/macOS pode exigir Wine e bibliotecas de áudio/gráficas do sistema.
Projetos importados de .ufdata, .svp e .vsqx podem perder recursos específicos do formato original durante a conversão.
Voicebanks muito grandes, renderização de várias faixas e uso simultâneo de efeitos podem exceder o limite prático de 2 GB de RAM.
No Android, o sandbox impede a execução de resamplers externos e o acesso direto a caminhos tradicionais como /sdcard/; use o seletor de arquivos ou pacotes .kfv/.zip.
A interface mobile ainda está em adaptação para toque; mouse, teclado físico e telas maiores oferecem a experiência mais completa.
Falhas de áudio podem depender do driver, do dispositivo selecionado, do backend do sistema ou da configuração do Wine.
FreeBSD possui instruções de compilação experimentais, mas não possui artefato oficial no workflow de releases.

Checklist rápido para reportar problemas

Inclua sempre a versão exibida na janela, sistema operacional, resampler, wavtool, voicebank, alias problemático e um projeto mínimo que reproduza o defeito. Para problemas de transição, envie também o WAV renderizado e informe se o cache foi limpo.

Para executar diretamente:

# Executar o editor Kamafeu
cargo run --release --bin kamafeu

# Executar a ferramenta Kamafeu KAMUSE
cargo run --release --bin kamuse

Interface de linha de comando

O Kamafeu Studio disponibiliza comandos via terminal para tarefas em lote e checagem de arquivos:

# Exibir lista completa de comandos
cargo run --release --bin kamafeu -- --help

# Inspecionar dados e integridade de um banco de voz
cargo run --release --bin kamafeu -- voicebank-info "/caminho/do/voicebank"

# Inspecionar diretamente um alias composto e seus tempos do oto.ini
cargo run --release --bin kamafeu -- voicebank-info "/caminho/do/voicebank" \
  --alias "k a" --pitch C4 --json

# Listar bancos UTAU e OpenUTAU nas pastas padrão do sistema
cargo run --release --bin kamafeu -- voicebanks

# Ou apontar uma ou mais bibliotecas de cantores explicitamente
cargo run --release --bin kamafeu -- voicebanks --path "/musica/Cantores" --path "/outros/Cantores"

# Validar WAVs e tempos do oto.ini; retorna erro se houver problemas
cargo run --release --bin kamafeu -- validate-voicebank "/caminho/do/voicebank"

# Medir render frio e aquecido, verificando identidade do PCM entre iterações
cargo run --release --bin render-benchmark -- projeto.aps "/caminho/do/voicebank" 9

# Medir explicitamente o resampler WORLD/Tainah
cargo run --release --bin render-benchmark -- projeto.aps "/caminho/do/voicebank" 9 --world

# Usar projeto e voicebank sintéticos reproduzíveis para uma referência local
cargo run --release --bin render-benchmark -- --synthetic 9

# Medir WORLD/Tainah sem acertos de cache usando os fixtures sintéticos
cargo run --release --bin render-benchmark -- --synthetic 9 --world --uncached

# Comparar custo end-to-end sem acertos de cache entre iterações
cargo run --release --bin render-benchmark -- --synthetic 9 --uncached

# Comparar com executáveis UTAU externos instalados localmente
cargo run --release --bin render-benchmark -- projeto.aps "/caminho/do/voicebank" 9 \
  --resampler "/caminho/resampler" --wavtool "/caminho/wavtool"

# Conferir as faixas, notas e duração de qualquer projeto suportado
cargo run --release --bin kamafeu -- project-info "musica.svp"

# Comparar duas revisões sem modificar nenhum dos arquivos
cargo run --release --bin kamafeu -- diff "musica.aps" "musica-revisada.aps"
cargo run --release --bin kamafeu -- --json diff "musica.aps" "musica-revisada.aps"

# Encontrar problemas estruturais antes de renderizar ou enviar um projeto
cargo run --release --bin kamafeu -- validate-project "musica.ustx"

# Também verificar extensões persistidas no APS contra um catálogo local
cargo run --release --bin kamafeu -- validate-project "musica.aps" \
  --extensions-path "extensions"

# Em CI, também reprovar avisos vocais, como sobreposições e offsets extremos
cargo run --release --bin kamafeu -- validate-project --fail-on-warning "musica.ustx"

# Converter um projeto sem abrir a interface; o resultado informa recursos que possam ter sido reduzidos
cargo run --release --bin kamafeu -- convert "musica.ustx" "musica.ufdata"

# Em CI, falhar quando a auditoria detectar alteração musical
cargo run --release --bin kamafeu -- convert --fail-on-loss "musica.ustx" "musica.ufdata"

# Verificar manifestos de extensões sem executar código de terceiros
cargo run --release --bin kamafeu -- extensions "extensions"

# Verificar módulos WASM declarados em sandbox, sem imports do sistema
cargo run --release --bin kamafeu -- extensions --verify-wasm "extensions"

# Conceder uma permissão somente para esta verificação, após consentimento
cargo run --release --bin kamafeu -- extensions --verify-wasm \
  --grant-permission read_voicebank "extensions"

O manifesto e o exemplo mínimo de plugin estão em
[`docs/plugin-sdk.md`](docs/plugin-sdk.md) e
[`examples/extensions/minimal`](examples/extensions/minimal).

# Usar saída estruturada em scripts, CI ou outra ferramenta
cargo run --release --bin kamafeu -- --json validate-voicebank "/caminho/do/voicebank"

# Ver tamanho, localização e eficiência do cache de renderização
cargo run --release --bin kamafeu -- cache-info

# Remover somente entradas de cache sem uso há mais de 30 dias
cargo run --release --bin kamafeu -- cache-prune --days 30

# Renderizar um projeto diretamente para áudio WAV
cargo run --release --bin kamafeu -- render \
  --voicebank "/caminho/do/voicebank" \
  --input "projeto.aps" \
  --output "saida.flac" \
  --sample-rate 44100 \
  --dither

render e project-info aceitam .aps, .ust, .ustx, .mid, .midi, .vsqx, .svp, .ufdata e JSON do Kamafeu. Os três últimos são formatos de intercâmbio. Após converter, o Kamafeu reabre o destino e compara tempo, faixas, partes, notas, áudio, pitch bend, curvas de dinâmica e expressões. Também compara uma assinatura de letra, altura e tempo de cada nota, para detectar alterações mesmo quando a contagem não muda. Em scripts, convert --json retorna o relatório completo. Use convert --fail-on-loss em CI quando o destino não puder ser aceito com nenhuma alteração detectada; o arquivo ainda é criado para inspeção, mas o comando retorna status diferente de zero.

O renderizador de terminal escolhe WAV 16-bit, FLAC 16-bit ou PCM RAW pela extensão de saída. Para controle explícito, use --format wav24, --format wav32-float, --format flac24 ou --format raw-f32; nesses casos a extensão precisa corresponder ao formato. --dither aplica TPDF determinístico somente a exportações PCM inteiras.

Ao finalizar, render --json e a operação render da automação retornam duração, pico, RMS, clipping, valores não finitos, maior salto entre amostras e detecção de silêncio. Isso permite que um pipeline interrompa exportações inseguras ou vazias sem precisar analisar o arquivo manualmente.

Os comandos de inspeção (voicebank-info, voicebanks, validate-voicebank, project-info, diff, platform-info e extensions) aceitam --json. Nesse modo, o terminal recebe exclusivamente um documento JSON e validate-voicebank continua retornando status diferente de zero quando encontrar problemas, o que o torna adequado para CI.

Modelos neurais

A integração de modelos neurais acústicos e vocoders em Rust ainda é experimental e tecnicamente desafiadora. Esse caminho não faz parte do suporte estável desta release, não é recomendado para produção e pode apresentar limitações de carregamento, compatibilidade de modelos e renderização. O foco atual do Kamafeu permanece no pipeline clássico UTAU/OpenUtau, com oto.ini, resampler e wavtool.

Para integrações persistentes, kamafeu automation executa um protocolo local JSON Lines pelo stdin/stdout: uma requisição JSON por linha gera exatamente uma resposta JSON por linha. As operações disponíveis são project_info, validate_project, diff, list_voicebanks, create_project, add_note, set_tempo, convert, set_note, remove_note, apply_lyrics, set_pitch_bend, render, validate_voicebank, extensions, set_expression, add_audio_part, add_marker, remove_marker, cache_info e cache_prune.

diff recebe before e after, retorna os mesmos dados semânticos da CLI e não modifica nenhum dos projetos. O servidor MCP oferece a mesma operação por meio da ferramenta kamafeu_diff.

{"command":"project_info","path":"musica.ustx"}
{"command":"validate_project","path":"musica.ustx"}
{"command":"list_voicebanks","paths":["/musica/Cantores"]}
{"command":"create_project","output":"rascunho.aps","name":"Ideia","bpm":120}
{"command":"add_note","input":"rascunho.aps","output":"rascunho-01.aps","lyric":"la","pitch":"C4","position_ms":0,"duration_ms":500}
{"command":"set_tempo","input":"rascunho-01.aps","output":"rascunho-02.aps","bpm":140}
{"command":"set_note","input":"rascunho-02.aps","output":"rascunho-03.aps","part_index":0,"note_index":0,"lyric":"li","pitch":"D4"}
{"command":"remove_note","input":"rascunho-03.aps","output":"rascunho-sem-nota.aps","part_index":0,"note_index":0}
{"command":"apply_lyrics","input":"rascunho-03.aps","output":"rascunho-com-letra.aps","part_index":0,"text":"ka-ma-feu es-tu-di-o","mode":"hyphens_and_spaces"}
{"command":"add_marker","input":"rascunho-com-letra.aps","output":"com-refrão.aps","name":"Refrão","position_ms":32000,"color":"#00ffaa"}
{"command":"set_pitch_bend","input":"rascunho-03.aps","output":"rascunho-04.aps","part_index":0,"note_index":0,"points":[{"time_offset_ms":0,"pitch_offset_cents":-30,"shape":"s"},{"time_offset_ms":200,"pitch_offset_cents":0,"shape":"s"}]}
{"command":"set_expression","input":"rascunho-04.aps","output":"rascunho-05.aps","part_index":0,"note_index":0,"dynamics":25,"breathiness":20,"gender":-10,"volume":110}
{"command":"add_audio_part","input":"rascunho-05.aps","output":"arranjo.aps","file_path":"instrumental.wav","position_ms":0,"track_index":1,"volume_db":-3}
{"command":"convert","input":"musica.ustx","output":"musica.ufdata"}
{"command":"render","voicebank":"cantor","input":"musica.ustx","output":"mix.flac","dither":true}
{"command":"cache_info"}
{"command":"extensions","path":"extensions","verify_wasm":true}

Ele não abre porta de rede nem executa extensões. Um adaptador MCP ou outra integração pode iniciar esse processo e falar pelo fluxo padrão, mantendo as permissões de arquivos sob controle de quem o invoca.

Para clientes que já falam Model Context Protocol, use kamafeu mcp. O servidor MCP local anuncia ferramentas para criar e editar projetos, renderizar, validar cantores, gerir cache e verificar extensões. Ele usa o mesmo stdin/stdout e não abre portas de rede.

Extensões

O Kamafeu expõe um registro de extensões para motores de síntese, formatos de projeto, fonemizadores, efeitos e instrumentos. Manifestos são descobertos sem executar código. Quando solicitado com extensions --verify-wasm, o módulo é iniciado em sandbox: não recebe imports do host, acesso a arquivos, rede ou processos, e tem orçamento limitado de execução.

Cada extensão ocupa uma pasta e declara kamafeu-extension.json:

{
  "id": "org.exemplo.meu-motor",
  "name": "Meu motor",
  "version": "0.1.0",
  "api_version": 1,
  "kind": "synthesis_engine",
  "limitations": ["requer um modelo compatível instalado"],
  "entrypoint": "engine.wasm"
}

Os tipos atuais incluem synthesis_engine, project_format, phonemizer, effect, instrument, analysis, transform, preset e editor_panel. O entrypoint deve ser um caminho relativo à pasta da extensão; caminhos absolutos ou que escapem da pasta são rejeitados. limitations é informativo: fica visível no catálogo e no consentimento, mas não concede permissões nem altera o sandbox.

Para passar pela verificação inicial, um entrypoint .wasm deve exportar kamafeu_extension_api_version() -> i32 e retornar 1. A ABI de execução de formatos, fonemizadores e efeitos será acrescentada sobre essa base sem dar ao módulo permissões implícitas do sistema.

Os formatos incluídos no aplicativo já usam o mesmo registro de adaptadores de project_format que será oferecido às extensões. Assim, um novo formato não precisa alterar o CLI: ele se registra com suas extensões de arquivo e fornece as operações de leitura e gravação para o modelo UProject.

Diagnóstico de playback progressivo

O playback progressivo possui scheduler independente da interface. Para reproduzir atrasos controlados durante uma investigação, inicie o Kamafeu com as variáveis abaixo:

KAMAFEU_DEBUG_RENDER_CHUNK_DELAY_MS=1500 \
KAMAFEU_DEBUG_UI_CHUNK_DELAY_MS=1000 \
cargo run

KAMAFEU_DEBUG_RENDER_CHUNK_DELAY_MS atrasa a produção de cada chunk e KAMAFEU_DEBUG_UI_CHUNK_DELAY_MS atrasa o processamento visual recebido pela UI. Os eventos [AudioScheduler] registram geração, estado, tempo reproduzido, tempo enfileirado e runway. Essas variáveis não têm efeito quando não estão definidas.

Tabela de atalhos de teclado

No macOS, utilize a tecla Cmd no lugar de Ctrl.

Ferramentas de edição

Tecla / Atalho	Ferramenta / Ação
`V` ou `1`	Ferramenta Ponteiro (seleção, movimentação e redimensionamento)
`N` ou `2`	Ferramenta Lápis (inserção e desenho contínuo de notas)
`P` ou `3`	Ferramenta Pitch (desenho livre, reta, vibrato e suavizador)
`Shift + P`	Alternar submodo de desenho de pitch (Livre, Reta, Vibrato, Suave)
`C` ou `4`	Ferramenta de corte e divisão de notas
`E` ou `5`	Ferramenta Borracha (exclusão de notas)
`Duplo-clique` / `Shift + Clique` na curva	Adicionar novo ponto de ancoragem no pitch
`Alt + Clique` / `Clique Direito` na âncora	Deletar ponto de ancoragem específico da curva

Transporte e navegação

Atalho	Ação
`Espaço`	Iniciar ou pausar reprodução
`Esc`	Parar reprodução e retornar o cursor ao início (0 ms)
`Shift + Clique / Arraste na régua`	Definir região de repetição contínua [A ... B]
`M`	Alternar silenciamento (Mute) na faixa ativa
`Ctrl + =` / `Cmd + =`	Aumentar zoom horizontal da timeline
`Ctrl + -` / `Cmd + -`	Diminuir zoom horizontal da timeline
`Ctrl + 0` / `Cmd + 0`	Redefinir zoom padrão da timeline
`Shift + Scroll`	Deslocar horizontalmente a timeline/arranjo
`Scroll vertical`	Navegar verticalmente pelas faixas do arranjo
`Trackpad de dois eixos`	Navegar horizontal e verticalmente conforme o eixo do gesto
`Arrastar a janela do RADAR`	Navegar diretamente para outra região do piano roll

Edição de notas e manipulação

Atalho	Ação
`Ctrl + Z` / `Cmd + Z`	Desfazer última alteração
`Ctrl + Y` / `Ctrl + Shift + Z` / `Cmd + Shift + Z`	Refazer alteração desfeita
`Ctrl + X` / `Cmd + X`	Recortar notas selecionadas
`Ctrl + C` / `Cmd + C`	Copiar notas selecionadas
`Ctrl + V` / `Cmd + V`	Colar notas na posição do cursor de reprodução
`Ctrl + D` / `Cmd + D`	Duplicar notas selecionadas
`Ctrl + A` / `Cmd + A`	Selecionar todas as notas da faixa
`Ctrl + Shift + A` / `Cmd + Shift + A`	Desmarcar seleção de notas
`Delete` / `Backspace`	Excluir notas selecionadas
`↑` / `↓`	Transpor notas em semitons (+1 / -1 semitom)
`Shift + ↑` / `Shift + ↓`	Transpor notas em oitavas (+12 / -12 semitons)
`←` / `→`	Deslocar posição das notas no tempo (-50 ms / +50 ms)
`Shift + ←` / `Shift + →`	Alterar duração das notas (-50 ms / +50 ms)
`Botão direito em notas selecionadas`	Abrir conversões VCV/CV e limpeza de caracteres não-Hiragana em lote

Snap e subdivisões

Além das divisões binárias e ternárias, o editor oferece subdivisões quíntuplas (1/5, 1/10, 1/20, 1/40 e 1/80) no controle de grade da barra de ferramentas, úteis para fraseados e ritmos não binários.

Arquivo, janelas e painéis

Atalho	Ação
`Ctrl + N` / `Cmd + N`	Criar novo projeto vazio
`Ctrl + O` / `Cmd + O`	Abrir projeto (`.aps`, `.ustx`, `.ust`, `.mid`)
`Ctrl + S` / `Cmd + S`	Salvar projeto ativo (`.aps`)
`Ctrl + Shift + S` / `Cmd + Shift + S`	Salvar projeto como novo arquivo
`Ctrl + E` / `Cmd + E`	Abrir diálogo de exportação de áudio (WAV / FLAC)
`Ctrl + K` / `Cmd + K`	Abrir a paleta de comandos com busca por ações do Studio
`Ctrl + ,` / `Cmd + ,`	Abrir diálogo de preferências e configurações
`Ctrl + Alt + P` / `Cmd + Alt + P`	Abrir janela do Pre-tunning (Afinador Orgânico / Auto-Pitch)
`Ctrl + Alt + T` / `Cmd + Alt + T`	Personalizar tema visual, cores de destaque e cantos da interface
`Ctrl + L` / `Cmd + L`	Exibir ou ocultar janela de log em tempo real do motor de áudio
`Tab`	Exibir ou ocultar gaveta inferior de parâmetros e expressões
`Alt + A`	Exibir ou ocultar painel de arranjo multifaixa
`Alt + O`	Exibir ou ocultar régua de fonemas e limites do oto.ini
`Ctrl + B` / `Cmd + B`	Exibir ou ocultar inspetor lateral direito
`F1` / `Cmd + ?`	Abrir guia interativo de teclas de atalho
`F11`	Alternar modo de tela cheia

Auditoria de renders

Exportações headless geram um sidecar JSON ao lado do áudio (*.kamafeu.json). Além dos hashes de projeto, voicebank e artefatos, o campo timing_diagnostics registra por fonema os valores de oto.ini, overrides, preutterance, overlap e tail_intrude. Durante a execução, os mesmos registros aparecem como linhas [Timing] no fluxo de progresso; ferramentas podem filtrá-las sem interpretar mensagens humanas. O render também emite uma linha boundary-rms por fonema, com RMS de janelas de 10 ms no início e no fim do áudio já processado pelo wavtool. Esses valores são diagnósticos: não alteram ganho, envelope ou o resultado exportado. O contrato completo está em docs/render-provenance.md.

Estrutura do código-fonte

kamafeu/
├── assets/             # Ícones, fontes (Outfit), imagens e identidade visual
├── docs/               # Documentação técnica e guias de build/assinatura
├── resamplers/         # Binários de resamplers externos e scripts de integração
├── wavtools/           # Utilitários externos de junção e emenda de fatias (Wavtool)
├── tests/              # Suíte de testes unitários e de integração
└── src/
    ├── main.rs         # Ponto de entrada CLI, despachante de comandos e inicialização gráfica
    ├── lib.rs          # Exportação pública da biblioteca e módulos centrais
    ├── config.rs       # Preferências do usuário, caminhos de motores e persistência JSON
    ├── discord_rpc.rs  # Integração com Discord Rich Presence para status de edição
    ├── copaiba_bridge.rs # Ponte de integração entre o editor Kamafeu e o toolkit Copaiba
    ├── dialogs.rs      # Gerenciador unificado de caixas de diálogo e mensagens modais
    │
    ├── audio/          # Motor de áudio (Rodio/CoreAudio/ALSA), metrônomo e rack FX (EQ, Reverb, Comp)
    ├── bin/            # Ferramentas autônomas (Copaiba e utilitários de áudio)
    ├── copaiba/        # Calibrador interativo de oto.ini, visualizador de onda e empacotador de voicebanks
    ├── drivers/        # Drivers de resamplers (WORLD, SOLA, externos/Wine) e wavtools
    ├── dsp/            # Processamento digital: WORLD, SOLA, análise, pitch e envelopes UTAU
    ├── formats/        # Parsers e conversores universais (.aps, .ustx, .ust, .mid, .ufdata, .svp, .vsqx, .kfv)
    ├── gui/            # Interface egui: piano roll, RADAR, arranjo multifaixa, inspetor e diálogos
    ├── oto/            # Leitura/escrita de oto.ini (UTF-8/Shift-JIS), prefix.map e scanner de cantores
    ├── phonemizer/     # Motores fonéticos (Japonês CV/VCV/CVVC, Português BRAPA VCCV/G2P, Inglês VCCV)
    ├── project/        # Modelagem de dados: faixas, notas, curvas de pitch, envelopes e histórico (Undo/Redo)
    └── renderer/       # Pipeline multithread (Rayon), síntese paralela, alinhamento de fase e mixagem de faixas

Para a descrição dos arquivos centrais, do fluxo entre camadas e dos novos utilitários VENUS, consulte o Guia do código-fonte.

Star History

Licença

O código original é distribuído sob os termos da Licença MIT. Executáveis, modelos, dados linguísticos, voicebanks, assets e ferramentas externas mantêm suas próprias licenças. Consulte o inventário de avisos, referências e créditos de terceiros, os avisos dos resamplers e os arquivos de licença distribuídos nas pastas correspondentes.

Referências e créditos

OpenUtau, referência para o fluxo UTAU/OpenUtau e parte dos dados de phonemizer.
UtaFormatix Data, referência do formato .ufdata.
OpenVPI Community Vocoder, referência e origem dos avisos dos modelos Catalina/NSF HiFi-GAN.
Studio Pomar, identidade e direção do projeto Kamafeu.
Os créditos individuais de programação, arte, QA e portabilidade permanecem registrados no cabeçalho deste README; contribuições de terceiros estão detalhadas em NOTICE.md.

Desenvolvido pelo Studio Pomar.

Compatibilidade com CPUs x86_64 antigas

Os binários x86_64 oficiais são compilados com o alvo x86-64 genérico e não dependem de AVX ou AVX2. Isso inclui compatibilidade com o AMD FX-6300. Não compile releases usando RUSTFLAGS="-C target-cpu=native", pois isso pode gerar instruções que não existem nessa CPU.

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github		.github
assets		assets
benches		benches
cantores		cantores
docs		docs
examples/extensions		examples/extensions
native		native
packaging		packaging
res		res
resamplers		resamplers
scripts		scripts
site		site
src		src
tests		tests
vendor/block		vendor/block
wavtools		wavtools
.gitignore		.gitignore
.mailmap		.mailmap
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Cross.toml		Cross.toml
KFV2_CONTRACT.md		KFV2_CONTRACT.md
LICENSE		LICENSE
NOTICE.md		NOTICE.md
README.md		README.md
Trunk.toml		Trunk.toml
build.rs		build.rs
index.html		index.html
input.venus		input.venus
mapa_de_arquivos_do_projeto.md		mapa_de_arquivos_do_projeto.md

Latest commit

History

Folders and files

Repository files navigation

Kamafeu Studio

Download

Sumário

Recursos do sistema

Piano roll e composição melódica

Bancos de voz e suporte fonético

Processamento e efeitos (DSP)

Personalização e temas visuais

Calafate 3.0 (padrão 3.0.0)

Pomar Neon (Esmeralda)

Âmbar Clássico

Cyberpunk (Synthwave)

Nordic Slate (Clean Dark)

Horta Mikan

Arquitetura e fluxo de síntese

Etapas do ciclo de processamento

Por baixo dos panos

1. O projeto é um modelo temporal, não uma lista de eventos soltos

2. A fonemização acontece antes do áudio

3. O timing engine transforma aliases em segmentos acústicos

4. Drivers isolam o contrato entre Kamafeu e motores de áudio

5. O renderer é paralelo, mas a timeline de áudio é ordenada

6. Mixagem, fase e efeitos acontecem depois da síntese dos segmentos

7. A interface recebe estado; ela não executa o renderer

8. Cache, cancelamento e proveniência evitam trabalho invisível

9. Extensões são descobertas por manifesto e executadas com limites

10. O que esta série garante e o que ainda depende do ambiente

Formatos de arquivo suportados

Motores de áudio (Resamplers e Wavtools)

Motores de afinação (Resamplers)

Motores de junção e emenda de fonemas (Wavtools)

Kamafeu KAMUSE

Primeiros passos

Instalação para usuários finais

Windows

macOS

Linux

Android

iOS

Dependências em tempo de execução

Arquivos de configuração, cache e logs

Versão mobile (Android; iOS em avaliação)

Desafios de adaptação e build

Compilação para Android

Especificações técnicas

Arquiteturas e artefatos

Instruções de compilação

Linux

Ubuntu / Debian / Linux Mint / Pop!_OS

Fedora / RHEL

Arch Linux / Manjaro

FreeBSD

macOS

Windows

Compilação dos binários

Limitações conhecidas da RC

Checklist rápido para reportar problemas

Interface de linha de comando

Modelos neurais

Extensões

Diagnóstico de playback progressivo

Tabela de atalhos de teclado

Ferramentas de edição

Transporte e navegação

Edição de notas e manipulação

Snap e subdivisões

Arquivo, janelas e painéis

Auditoria de renders

Estrutura do código-fonte

Star History

Licença

Referências e créditos

Compatibilidade com CPUs x86_64 antigas

About

Topics

Resources