root/ABeatDetector/README_ABT.txt

Inicialize o ABT em 2 passos:

1) Inicie o ChucK em loop no diretorio do ABT:
# chuck --loop

2) Em outro terminal, inicie o ABeatTracker:

# python abt.py

ou, preferencialmente, utilize o ipython para que tenhamos facilidades como recorrer a comandos anteriores:

# ipython abt.py


O ABT deve estar pronto para disparar as macros.
Basta apertar <enter> para que o ABT inicie o playback de alguma macro padrao.

------------------------------------------------------------------------
Especificacao:

O ABT eh um aplicativo dedicado `a execussao ritmica de samples.

Conceitualmente, o ABT executa linhas ritmicas definidas atraves de macros.
Estas macros sao escolhidas em tempo real atraves de um interpretador interativo Python que
recodifica estas escolhas para execussao atraves de scripts ChucK, uma linguagem dedicada a execussao
de audio em tempo real.

Cada linha ritmica eh definida por uma sequencia de caracteres que especificam seus atributos.
Estes nao precisam ser especificados individualmente, sendo utilizada a opcao padrao para
cada atributo nao especificado.

Para mais informacoes, veja os dicionarios de comandos a seguir e as notas de funcionamento abaixo.

------------------------------------------------------------------------
Dicionario de comandos primarios:

1) Sair do ABT:
q -> sai do ABT

2) Ajuda:
h -> printa o menu de comandos

3) Sincronizacao:
s -> sincroniza o ABT com alguma pulsacao especifica.

4) Remover todas as linhas ritmicas:
r -> remove todas as linhas ritmicas.

5) Consulta das linhas em execussao:
l -> printa as linhas em execussao e seus atributos.

6) Consulta estado da execussao:
e -> printa a duracao de cada tempo e o numero de BPM.
o ganho RMS utilizado.
a variacao do ganho RMS.
a variacao da velocidade de playback.
o numero de linhas.
o tempo decorrido de execussao.

7) Consulta contagem de shreds:
p -> printa a contagem de shreds. isso eh especifico da linguagem ChucK e a principio nao precisa ser entendido ou 
utilizado. Este recurso cabe aqui mais como um recurso para debug e acompanhamento do funcionamento.
------------------------------------------------------------------------
Dicionario de atributos globais da execussao:

1) Pulsacao, pulso ou duracao de cada tempo:
T200 -> cada tempo tera a duracao em milisegundos que segue a letra T (no caso 200 milisegundos)
B70 -> 70 BPM.

2) Ambito de variacao randomica de ganho:
VG0.2 -> variacao randomica uniforme no intervalo de [-0.2,0.2] para o ganho.

3) Ambito de variacao randomica de velocidade de playback dos samples:
VR0.2 -> variacao randomica uniforme no intervalo de [-0.2,0.2] para a velocidade de playback dos samples.

4) Ganho:
G0.8 -> volume de 0.8 peak.

5) Velocidade de playback:
R1.3 -> velocidade de playback de 1.3

6) Remocao seletiva de linhas ritmicas:
-P -> remove a linha cujo identificador eh "R". Multiplas linhas podem ser removidas em um so comando assim:
-P O U A d -> remove as linhas cujos identificadores sao "P", "O", "U", "A" e "d".

7) listagem dos samples prontos para serem carregados:
s -> lista os samples
 
------------------------------------------------------------------------
Dicionario de atributos basicos definidos ou planejados para linhas ritmicas:

0) Identificacao da linha:
a..z, A..Z -> qualquer caracter ascii pode ser utilizado como identificador da linha.
Caso a linha ja tenha sido definida anteriormente, so serao alterados os atributos especificados.
PADRAO: Z
obs: este eh o unico atributo que requer entrada ordenada. Ele deve encabecar um comando que se remete a uma linha ritmica.
Os outros atributos podem vir em quaisquer ordem.

1) Padrao Ritmico:
aapa ap a a -> "a" para ataque, "p" para pausa, " " separa os tempos.
adicao posterior de "-" para continuar a nota sem que ocorra um novo ataque.
PADRAO: a

2) Numero de execussoes da celula:
1...100 -> quantas vezes a celula deve ser executada.
loop, l -> loop infinito.
PADRAO: loop

3) Escolha do sample:
arquivo.wav -> arquivo WAV PCM 16bits, 44100kHz para execussao da linha definida
PADRAO: Agostinho-cell.wav

4) Modo de leitura do sample:
walk-sample, ws -> sample eh lido inteiramente e em loop.
walk-pattern, wp -> sample eh lido continuamente para o padrao, depois volta e se repete.
sonoridade igual para cada repeticao da celula.
always-rewind, ar -> leitura da amostra eh reiniciada a cada ataque.
PADRAO: walk-sample

4b) Modo de leitura do sample, tratamento dos silencios:
silence-rest, si -> nos silencios, a leitura da amostra continua (porem em com volume zero).
stop-rest, st -> nos silencios a leitura do sample para.
PADRAO: silence-rest

5) Ganho da linha:
g0.4 -> ganho de 0.4

6) Variacao de ganho da linha:
vg.3 -> variacao de ganho da linha.

7) Velocidade de playback
r1 -> velocidade normal de playback do sample

8) Variacao da velocidade de playback do sample
vr0.2 -> [-0.2,+0.2] de velocidade de playback da amostra

9) Encaixe da amostra em número específico de tempos:
P4 -> a amostra será tocada como um todo em 4 tempos.
---------------------------------------------------------------
Dicionario de atributos complementares definidos ou planejados para linhas ritmicas:
1) Linha melodica:
7 0 1 0 7 6 -> Definida atraves de uma relacao de semitons que implica em relacoes na velocidade de playback da amostra.
Cada nota especificada eh relacionada a um ataque do padrao ritmico.

2) Permutacao: (5)
perm ritmica (q opera sobre as celulas ou os tempos ritmicos). -> ainda nao implementado.

---------------------------------------------------------------
Notas de funcionamento:

* Quando uma linha ritmica for diparada sem nenhuma especificacao (apenas acionando <enter>),
o ABT utilizara' a lista de auto identificadores. Esta se encontra na classe C do arquivo abt_data.py.
Note que se mais de 4 linhas ritmicas forem adicionadas desta forma, o ABT levantara' erro.
Para adicionar uma linha padrao, o melhor eh escrever o identificador seguido de um espaco " ".

* o ABT distigue 3 tipos de comandos:
1) Comandos primarios: de uma sso letra. estes sao os comandos primarios e devem ser chamados com uma unica letra, sem espaco, e <enter>
2) Mudanca de variavel global: Comando unico. Comecam com uma ou duas letras a as quais se seguem um novo valor da variavel. 
3) Linha ritmica: Linha de comandos. Comecam com uma letra (identificador) seguida de espaco e das especificacoes da linha.

Excessao: Remocao de linhas ritmicas. Sinal de menos "-" seguido de um ou mais caracteres identificadores de linha ritmica separados por espaco.

Nota: Caso seja requisitado o comando nulo (simplesmente <enter>), o ABT dispara uma linha ritmica com todos os atributos padroes.

* Multiplos comandos podem ser executados de uma so vez se separados pelo caracter "|".

---------------------------------------------------------------
Recentes:
02/02/2010

adicionado comando PX (P2, P4) q faz a amostra inteira tocar, na duração exata de X pulsos. útil para encaixar amostras que já possuem um ritmo próprio e, além disso, possibilitando poliritmias diversas.

adicionado recurso para escrever, carregar e disparar presets. arquivo de texto com os presets: presets.txt. formatação é auto-explicativa. qqr coisa me escreva.

20/02/2010
o comando "s" agora lista os arquivos de áudio que podem ser carregados (presentes no diretório samples/)

24/04/2010
Empreitada para usar somente OSC, sem recorrer mais ao bash.

1) Fazendo a comunicação via OSC e implementando o arquivo ABT.ck que possui todas as funcionalidades dos outros arquivos .ck, dispensando todo aquele monte de arquivos.

2) Alterando abt.py e abt_funcs.py


---------------------------------------------------------------
ToDo:

* Mecanismo de sincronizacao

* Alteracao das linhas ritmicas. inclusive mutar, etc.

* variável global índice de incidência. (individual tamb)

* fazer um sampler para a função PX, pois se houver algum VR, o PX vai sair do sync.
---------------------------------------------------------------
Notas Técnicas (20/02/2010):

O ABT é constituído por poucos arquivos, a saber:
(obs: terminação ".py" arquivo python,terminação ".ck" arquivo ChucK, terminação ".txt" arquivo de texto)
1) abt.py: inicializa o ABT e inicia o loop principal, que consiste em esperar comandos e acionar as funções do ABT de acordo com os comandos recebidos, encaminha o resultado para processamento no ChucK
2) abt_funcs.py: possui todas as funções de execussão do ABT. Isso inclui o sistematizador das características de cada linha e as funções específicas para reconhecer e codificar cada linha.
3) abt_data.py: declara a classe C que possui as variáveis do ABT utilizadas por diversas rotinas. Também carrega os presets.

4) scentral.ck: declara a classe pública SCentral que possui as variáveis utilizadas pelo arquivo sampler.ck e alteráveis via outros scripts.
5) sampler.ck: é o tocador de arquivos de áudio utilizado pelo ABT. É capaz de desempacotar e interpretar as informações enviadas pelo abt.py e aplicá-las à linha rítmica.
6) rec-auto.ck: grava automaticamente a execussão gerando um arquivo de áudio com a seguinte formatação: "chuck-session(Thu Feb  4 10h42m24 2010).wav"
7) setG.ck, setR.ck, setT.ck, setVG.ck, setVR.ck, são utilizados para modificar o valor do ganho, da velocidade de playback, da duração do tempo, da variação do ganho, da variação da velocidade de playback respectivamente.

8) presets.txt: contém os presets já criados
9) sessoes-memoraveis.txt: contém o registro escrito de algumas boas sessões.

10) samples/*: arquivos de áudio para serem utilizados nas execussões. (pode adicionar os arquivos que quiser)
11) ABD/*: arquivos ligados à detecção de células rítmicas e pulsações.