<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
To validate or process this file as a standalone document, uncomment
this prolog. Be sure to comment it out again when you are done -->

<chapter id="arts-modules">
<title>Módulos do &arts;</title>

  <sect1 id="modules-introduction">
<title>Introdução</title>

<para>Este capítulo descreve todos os módulos normais do &arts;. Sendo uma das funcionalidades mais poderosas do &arts;, os módulos podem ser ligados em conjunto através de estruturas para implementar novas funções como efeitos e instrumentos. </para>

<para>Os módulos são divididos em duas categorias. Os módulos de síntese são usados para implementar a <quote>canalização</quote> que manipula as sequências de dados multimédia para implementar novos efeitos, instrumentos, misturadores e aplicações. Os módulos visuais permitem-lhe oferecer uma interface gráfica para o utilizador poder controlar as estruturas de som que são criadas com os módulos de síntese. </para>

</sect1>

<sect1 id="synth-modules-reference">
<title>Referência dos Módulos de Síntese</title>
 

<sect2 id="mcat-synth-arithmetic-mixing">
<title>Aritmética + Mistura</title>

 

<sect3 id="mref-synth-add-sect">
<title>Synth&lowbar;ADD</title>
<anchor id="mref-synth-add"/>

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_ADD.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;ADD</phrase></textobject>
</mediaobject>

<para>Isto adiciona dois sinais. </para>

</sect3>

<sect3 id="mref-synth-mul-sect">
<title>Synth&lowbar;MUL</title>
<anchor id="mref-synth-mul"/>

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_MUL.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;MUL</phrase></textobject>
</mediaobject>

<para>Isto multiplica um sinal por um determinado factor. Você poderá usar isto para reduzir a amplitude dos sinais (0 &lt; factor &lt; 1) ou ampliá-los (factor &gt; 1) ou ainda invertê-los (factor &lt; 0). Tenha em atenção que o factor pode ser um sinal e não tem de ser constante (&eg; um sinal de envelope ou um sinal real). </para>

</sect3>

<sect3 id="mref-synth-div-sect">
<title>Synth&lowbar;DIV</title>
<anchor id="mref-synth-div"/>

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_DIV.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;DIV</phrase></textobject>
</mediaobject>

<para>Isto divide um sinal por um dado facto. Poderá usar isto para dividir um sinal por outro. Pode definir também o valor1 como sendo 1 e irá obter o simétrico do valor2 como resultado. Tenha em atenção que o valor2 nunca deverá ser igual a 0, caso contrário irá ter problemas com divisões por zero. </para>

</sect3>

<sect3 id="mref-synth-multi-add-sect">
<title>Synth&lowbar;MULTI&lowbar;ADD</title>
<anchor id="mref-synth-multi-add"/>

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_MULTI_ADD.png"
  format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;MULTI&lowbar;ADD</phrase></textobject>
</mediaobject>

<para>Isto adiciona uma quantidade arbitrária de sinais. Se você precisar de somar todas as formas de onda produzidas por quatro osciladores, você poderá ligar todas as saídas deles a um único módulo Synth&lowbar;MULTI&lowbar;ADD. Isto é mais eficiente do que usar três módulos Synth&lowbar;ADD. </para>

</sect3>

<sect3 id="mref-synth-xfade-sect">
<title>Synth&lowbar;XFADE</title>
<anchor id="mref-synth-xfade"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_XFADE.png" format="PNG"/>
</imageobject>
<textobject><phrase>Synth&lowbar;XFADE</phrase></textobject>
</mediaobject>

<para>Isto mistura dois sinais. Se o valor da percentagem for igual a -1, só o sinal esquerdo é ouvido; se for igual a 1, só o sinal direito é ouvido. Se for 0 (zero), ambos os sinais são ouvidos com o mesmo volume. </para>

<para>Isto permite-lhe garantir que o seu sinal permanece num intervalo bem definido. Se você tiver dois sinais que estejam entre -1 e 1 antes da mistura, eles irão permanecer dentro do mesmo intervalo após a dita mistura. </para>
</sect3>

<sect3 id="mref-synth-autopanner-sect">
<title>Synth&lowbar;AUTOPANNER</title>
<anchor id="mref-synth-autopanner"/>

<para>O oposto de um 'crossfader'. Este recebe um sinal mono e divide-o num sinal estéreo: É usado para deslocar automaticamente o sinal à entrada entre a saída esquerda e a direita. Isto torna as misturas mais vivias. Uma aplicação normal seria uma guitarra ou um som principal. </para>

<para>Ligue um <acronym>LFO</acronym>, uma onda sinusoidal ou dente-de-serra por exemplo ao 'inlfo'. e seleccione uma frequência entre 0,1 e 5Hz para um efeito tradicional ou mais ainda para efeitos especiais. </para>

</sect3>

</sect2>

<sect2 id="mcat-synth-busses">
<title>Barramentos</title>

<sect3 id="mref-synth-bus-uplink-sect">
<title>Synth&lowbar;BUS&lowbar;UPLINK</title>
<anchor id="mref-synth-bus-uplink"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_BUS_UPLINK.png"
               format="PNG"/>
</imageobject>
<textobject><phrase>Synth&lowbar;BUS&lowbar;UPLINK</phrase></textobject>
</mediaobject>

<para>Um canal de envio para um barramento. Forneça os sinais ao 'left' (esquerdo) e ao 'right' (direito), bem como o nome do barramento onde os dados deverão ir no porto <quote>bus</quote>. O sinal combinado de todos os canais de envio ('uplinks') irão aparecer em todos os canais de recepção ('downlinks') desse <quote>barramento</quote>. </para>
</sect3>

<sect3 id="mref-synth-bus-downlink-sect">
<title>Synth&lowbar;BUS&lowbar;DOWNLINK</title>
<anchor id="mref-synth-bus-downlink"/>

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_BUS_DOWNLINK.png"
  format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;BUS&lowbar;DOWNLINK</phrase></textobject>
</mediaobject>

<para>Obtém (a soma de) todos os dados que são colocados num determinado barramento (com o nome que você indicar no porto <quote>bus</quote> (barramento)). </para>
</sect3>

</sect2>

<!-- TODO AFTER KDE2.1: move freeverb into delays, and rename category to
     Delays &amp; reverbs -->

<sect2 id="mcat-synth-delays">
<title>Atrasos</title>

 

<sect3 id="mref-synth-delay-sect">
<title>Synth&lowbar;DELAY</title>
<anchor id="mref-synth-delay"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_DELAY.png"
               format="PNG"/></imageobject></mediaobject>

<para>Isto atrasa o sinal de entrada por um período de tempo determinado. A especificação do tempo deverá ser entre 0 e 'maxdelay' (atraso máximo) para obter um atraso equivalente em segundos. </para>

<para>Este tipo de atrasos <emphasis>não pode ser usado</emphasis> nas estruturas de realimentação ('feedback'). Isto acontece por ser um atraso variável. Você poderá modificar o seu tamanho enquanto corre e até mesmo configurá-lo como sendo zero. Mas como numa estrutura de realimentação a própria saída é necessária para calcular as próximas amostras, uma atraso cujo valor possa cair para zero durante a síntese poderá conduzir a uma situação de paragem. </para>

<para>Use os CDELAYs nesse caso, e combinando talvez um atraso constante (de 0,001 segundos) com um atraso flexível. </para>

<para>Você poderá também combinar um CDELAY com um DELAY para obter um atraso de tamanho variável com um valor mínimo num ciclo de realimentação. Certifique-se apenas que tem um CDELAY. </para>

</sect3>

<sect3 id="mref-synth-cdelay-sect">
<title>Synth&lowbar;CDELAY</title>
<anchor id="mref-synth-cdelay"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_CDELAY.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;CDELAY</phrase></textobject>
</mediaobject>

<para>Isto atrasa o sinal de entrada por um período de tempo determinado. A especificação do tempo deverá ser maior que 0 para obter um atraso de 0 segundos ou mais. O atraso é constante durante o cálculo, o que significa que ele não poderá ser modificado. </para>

<para>Isto poupa no tempo de cálculo, atendendo a que não é feita nenhuma interpolação e é útil para estruturas recursivas. Veja a descrição acima (Synth&lowbar;DELAY). </para>

</sect3>

</sect2>

<sect2 id="mcat-synth-envelopes">
<title>Envelopes</title>

 

<sect3 id="mref-synth-envelope-adsr-sect">
<title>Synth&lowbar;ENVELOPE&lowbar;ADSR</title>
<anchor id="mref-synth-envelope-adsr"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_ENVELOPE_ADSR.png"
               format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;ENVELOPE&lowbar;ADSR</phrase></textobject>
</mediaobject>

<para>Este é um envelope clássico de <acronym>ADSR</acronym>, o que significa que você indica: </para>

<variablelist>
<varlistentry>
<term>active</term>
<listitem>
<para>Se a nota está a ser carregada de momento pelo utilizador. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>invalue</term>
<listitem>
<para>O sinal de entrada. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>attack</term>
<listitem>
<para>O tempo que deverá passar entre o utilizador carregar na nota e o sinal atingir a sua amplitude máxima (em segundos). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>decay</term>
<listitem>
<para>O tempo que deverá passar entre o sinal atingir a sua amplitude máxima e o sinal a voltar para um nível constante (em segundos). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>sustain</term>
<listitem>
<para>O nível constante em que o sinal é mantido até que o utilizador solte a nota. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>release</term>
<listitem>
<para>O tempo que deverá passar depois de o utilizador soltar a nota até que o sinal seja reduzido até zero (em segundos). </para>
</listitem>
</varlistentry>
</variablelist>

<para>Você irá obter o sinal redimensionado em 'outvalue' (na saída). Se o envelope do <acronym>ASDR</acronym> tiver terminado, irá colocar o 'done' (terminado) a 1. Você poderá usar isto para fornecer a saída <quote>done</quote> de um instrumento (que fará com que a estrutura do instrumento seja removida pelo encaminhador de &MIDI; logo que a fase do 'release' tenha terminado). </para>

</sect3>

<sect3 id="mref-synth-pscale-sect">
<title>Synth&lowbar;PSCALE</title>
<anchor id="mref-synth-pscale"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_PSCALE.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PSCALE</phrase></textobject>
</mediaobject>

<para>O módulo Synth&lowbar;PSCALE irá aplicar um factor de escala ao canal de áudio que passa por ele, desde um volume 0 (silêncio) até o 1 (volume original), e de volta a 0 (silêncio). De acordo com a posição (pode obter a posição a partir de Synth&lowbar;SEQUENCE). A altura em que o pico deverá ocorrer poder ser indicada em 'pos'. </para>

<para>Exemplo: Se definir o 'top' igual a 0,1 significa que, ao fim de 10&percnt; da nota ter sido tocada, o volume atingiu o seu máximo e começa a decair a partir daí. </para>
</sect3>

</sect2>

<sect2 id="mcat-synth-effects">
<title>Efeitos</title>

<sect3 id="mref-synth-freeverb-sect">
<title>Synth&lowbar;FREEVERB</title>
<anchor id="mref-synth-freeverb"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_FREEVERB.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;FREEVERB</phrase></textobject>
</mediaobject>

<para>Este é um efeito de reverberação. Na implementação actual, passa um sinal estéreo através do efeito, adicionando a tal reverberação ao mesmo sinal. </para>

<note>
<para>Isto significa que ele também poderá ser usado numa StereoEffectStack. </para>
</note>

<para>O sinal de entrada deverá ser ligado a (inleft, inright) e o de saída a (outleft, outright). </para>

<para>Os parâmetros que você poderá configurar são: </para>

<variablelist>
<varlistentry>
<term>roomsize</term>
<listitem>
<para>O tamanho da sala que a reverberação irá simular (intervalo: 0..1, em que o 1 é a maior sala possível). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>damp</term>
<listitem>
<para>Isto indica um filtro que fará com que a sala simulada absorva as altas frequências (intervalo de 0..1, em que o 1 significa que as altas frequências são absorvidas de forma agressiva). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>wet</term>
<listitem>
<para>A quantidade de sinal reverberado (isto é, a quantidade de sinal que deverá ser modificado pelos filtros, resultando num som <quote>molhado</quote>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>dry</term>
<listitem>
<para>A quantidade de sinal puro que é passado, resultando num eco (ou atraso combinado), em vez de ser afectado por reverberação (intervalo: 0..1). </para>
<!-- TODO: do some measurements to show that this documentation -is- correct,
I am not sure if it is echo, or really pure (non-delayed), or multiple delay
or whatever -->
</listitem>
</varlistentry>

<varlistentry>
<term>largura</term>
<listitem>
<para>A quantidade de efeito de estéreo que o algoritmo de reverberação adiciona ao efeito, tornando o som reverberado mais amplo no panorama estéreo (intervalo: 0..1). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>modo</term>
<listitem>
<para>[ TODO: Pensa-se que, se o 'mode' for igual a 1, a reverberação mantém a imagem actual do som, e onde o 0 é a operação normal ] </para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="mref-synth-tremolo-sect">
<title>Synth&lowbar;TREMOLO</title>
<anchor id="mref-synth-tremolo"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_TREMOLO.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;TREMOLO</phrase></textobject>
</mediaobject>

<para>O módulo 'tremolo' modula a amplitude com base numa onda <acronym>LFO</acronym>. Tradicionalmente você iria usar uma onda sinusoidal, mas porquê limitar-se? O que irá obter é um efeito muito intenso que corta a maioria dos arranjos devido ao seu efeito altamente dinâmico. O efeito de 'tremolo' é ainda um dos efeitos favoritos dos guitarristas, ainda que não seja tão popular como era nos anos 60. </para>

<para>[ TODO: de momento, isto está implementado como 'invalue + abs(inlfo)' - provavelmente faria mais sentido se fosse implementado como 'invalue * (1+inlfo*depth)', onde o 'depth' (profundidade) seria um parâmetro entre 0..1 - isto poderá ter sido decidido após o &kde;2.1 ; se tiver um comentário, envie uma mensagem para a lista do &arts; ;). ] </para>

</sect3>
<sect3 id="mref-synth-fx-cflanger-sect">
<title>Synth&lowbar;FX&lowbar;CFLANGER</title>
<anchor id="mref-synth-fx-cflanger"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_FX_CFLANGER.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;FX&lowbar;CFLANGER</phrase></textobject>
</mediaobject>

<para>Um 'flanger' é um efeito de atraso variável no tempo. Para tornar o desenvolvimento de efeitos complexos de 'flanger' mais simples, é fornecido este módulo que contém a base de um 'flanger' de um canal. </para>

<para>Ele contém os seguintes portos:</para>

<variablelist>
<varlistentry>
<term>invalue</term>
<listitem>
<para>O sinal que você deseja processar. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>lfo</term>
<listitem>
<para>De preferência, uma onda sinusoidal que modula o tempo de atraso no 'flanger' (-1 .. 1). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>mintime</term>
<listitem>
<para>O valor mínimo para o atraso no 'flanger' em milisegundos. Valores sugeridos: tente algo do género 1 ms. Por favor use valores &lt; 1000 ms. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>maxtime</term>
<listitem>
<para>O valor máximo para o atraso no 'flanger' em milisegundos. Valores sugeridos: tente algo do género 5 ms. Por favor use valores &lt; 1000 ms. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>outvalue</term>
<listitem>
<para>O sinal de saída. É importante que você misture isso com o sinal original para obter o efeito desejado. </para>
</listitem>
</varlistentry>
</variablelist>

<tip>
<para>Você poderá usar isto com base para um efeito de coro. </para>
</tip>

</sect3>

</sect2>

<sect2 id="mcat-synth-filters">
<title>Filtros</title>

<sect3 id="mref-synth-pitch-shift-sect">
<title>Synth&lowbar;PITCH&lowbar;SHIFT</title>
<anchor id="mref-synth-pitch-shift"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_PITCH_SHIFT.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PITCH&lowbar;SHIFT</phrase></textobject>
</mediaobject>

<para>Este efeito de mudança de frequência altera a frequência do sinal da entrada sem afectar a velocidade. Uma aplicação para isto é por exemplo a alteração do toma da sua voz enquanto você a grava (e reproduz) em tempo-real. </para>

<para>O parâmetro <emphasis>speed</emphasis> (velocidade) é a velocidade relativa com que o sinal será reproduzido. Deste modo, uma velocidade igual a dois fará com que o som fique duas vezes mas alto (&ie; uma frequência de entrada de 440 Hz iria resultar numa frequência de saída de 880 Hz). </para>

<para>O parâmetro <emphasis>frequency</emphasis> (frequência) é usado internamente para mudar entre as várias diferenças do sinal. É ajustável e, dependendo da sua escolha, o desvio de frequência parecerá mais ou menos realístico para o seu caso de uso. Um bom valor para começar será algo do tipo 5 ou 10. </para>

</sect3>

<sect3 id="mref-synth-shelve-cutoff-sect">
<title>Synth&lowbar;SHELVE&lowbar;CUTOFF</title>
<anchor id="mref-synth-shelve-cutoff"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_SHELVE_CUTOFF.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;SHELVE&lowbar;CUTOFF</phrase></textobject>
</mediaobject>

<para>Filtra todas as frequências superiores à frequência de corte. </para>

</sect3>

<sect3 id="mref-synth-brickwall-limiter-sect">
<title>Synth&lowbar;BRICKWALL&lowbar;LIMITER</title>
<anchor id="mref-synth-brickwall-limiter"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_BRICKWALL_LIMITER.png"
                            format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;BRICKWALL&lowbar;LIMITER</phrase></textobject>
</mediaobject>

<para>Este módulo corta um sinal, de modo a fazer com que ele caiba no intervalo [-1;1]. Ele não faz nada para evitar a distorção que acontece ao cortar os sinais altos. Você poderá usar isto como um efeito (por exemplo, para criar uma onda sinusoidal ligeiramente cortada). Contudo, é provavelmente uma boa ideia passar o sinal através de um filtro passa-baixo depois disso, para tornar o som menos agressivo. </para>
</sect3>

<sect3 id="mref-synth-std-equalizer-sect">
<title>Synth&lowbar;STD&lowbar;EQUALIZER</title>
<anchor id="mref-synth-std-equalizer"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_STD_EQUALIZER.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;STD&lowbar;EQUALIZER</phrase></textobject>
</mediaobject>

<para>Este é um bloco de equalização parametrizado engraçado. Os seus parâmetros são: </para>

<variablelist>
<varlistentry>
<term>invalue, outvalue</term>
<listitem>
<para>O sinal que é filtrado pelo equalizador. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>low</term>
<listitem>
<para>Como é que as frequências baixas deverão ser alteradas. O valor está em dB, e onde 0 significa que as baixas frequências não são alteradas, o -6 significa que as reduzirá em 6dB, e o +6 significa que as aumenta em 6dB. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>mid</term>
<listitem>
<para>Como é que as frequências intermédias deverão ser alteradas pelo equalizador (ver em 'low'). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>high</term>
<listitem>
<para>Como é que as altas frequências deverão ser alteradas pelo equalizador (ver em 'low'). </para>
</listitem>
</varlistentry>

<varlistentry>
<term>frequency</term>
<listitem>
<para>Esta é a frequência central do equalizador em Hz, onde as frequências intermédias se situam à volta desse espectro, tendo as baixas frequências à sua esquerda e as altas à direita. Tenha em atenção que a frequência não poderá ser mais elevada que metade da taxa de amostragem; normalmente esta é igual a 22 050 Hz e não poderá ser menor que 1 Hz. </para>
</listitem>
</varlistentry>

<varlistentry>
<term>q</term>
<listitem>
<para>Isto influencia quão estreito é o espectro central. Deverá ser um número positivo &gt; 0. Um valor igual a um é razoável, os valores mais elevados correspondem a um espectro mais estreito de frequências intermédios e os menores que um correspondem a um espectro largo. </para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="mref-synth-rc-sect">
<title>Synth&lowbar;RC</title>
<anchor id="mref-synth-rc"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_RC.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;RC</phrase></textobject>
</mediaobject>

<para>Um filtro por ressonância filtra todas as frequências à volta de um determinado valor de pico. Não existe nenhuma forma útil de indicar a frequência intermédia (a que não será cortada), dado que as entradas são duas constantes estranhas 'f' e 'b'. O código é muito antigo, desde os primeiros dias do sintetizador, e provavelmente será substituído por um filtro novo que terá um frequência e um valor de ressonância como parâmetros). </para>

<para>Tente algo do género b=5, f=5 ou b=10, f=10 ou b=15, f=15, todavia. </para>

</sect3>

<sect3 id="mref-synth-moog-vcf-sect">
<title>Synth&lowbar;MOOG&lowbar;VCF</title>
<anchor id="mref-synth-moog-vcf"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_MOOG_VCF.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;MOOG&lowbar;VCF</phrase></textobject>
</mediaobject>

<para>Filtra todas as frequências acima da frequência de corte (é um filtro de 24dB com 4 pólos, o qual filtra -24db por oitava acima da frequência de corte), mas oferece um parâmetro adicional para ajustar a ressonância do filtro, em que o 0 significa ausência de ressonância e o 4 significa auto-oscilação. </para>

</sect3>

</sect2>

<sect2 id="mcat-synth-midi-sequencing">
<title>MIDI + Sequenciação</title>

<sect3 id="mref-synth-midi-test-sect">
<title>Synth&lowbar;MIDI&lowbar;TEST</title>
<anchor id="mref-synth-midi-test"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_TEST.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;MIDI&lowbar;TEST</phrase></textobject>
</mediaobject>

<para>Este módulo carrega uma estrutura de um instrumento a partir de um ficheiro e regista-se como uma saída de MIDI com o gestor de &MIDI; do &arts;. As notas que são enviadas para esta saída irão resultar na criação de vozes dos instrumentos. </para>

<note>
<para>Você poderá configurar algo mais conveniente no &artscontrol; do que fazê-lo manualmente no &arts-builder;. </para>
</note>

</sect3>

<sect3 id="mref-synth-sequence-sect">
<title>Synth&lowbar;SEQUENCE</title>
<anchor id="mref-synth-sequence"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_SEQUENCE.png"
format="PNG"/></imageobject></mediaobject>

<para>Irá tocar uma sequência de notas outra e outra vez. As notas são dadas na notação de teclado e são separadas por ponto-e-vírgula. Um exemplo será <literal>A-3;C-4;E-4;C-4;</literal>. A velocidade é dada em segundos por nota, por isso, se você quiser 120 batidas por minuto, você deverá indicar provavelmente 0,5 segundos por nota, dado que 60 segundos/0,5 segundos por nota=120 bpm. </para>

<para>Você poderá indicar em cada nota um tamanho relativo à velocidade adicionado dois pontos (:) a seguir à nota, seguido do tamanho. O <literal>A-3:2;C-4:0.5;D-4:0.5;E-4;</literal> demonstra isto. Como pode ver, os programas de composição de &MIDI; tendem a oferecer mais conforto ;) </para>

<para>O Synth&lowbar;SEQUENCE dá-lhe informações adicionais sobre a posição da nota que está a tocar de momento, onde o 0 indica que iniciou agora e o 1 que terminou. Esta informação poderá ser usada no Synth&lowbar;PSCALE (veja em baixo). </para>
</sect3>

<sect3 id="mref-synth-sequence-freq-sect">
<title>Synth&lowbar;SEQUENCE&lowbar;FREQ</title>
<anchor id="mref-synth-sequence-freq"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_SEQUENCE_FREQ.png"
format="PNG"/></imageobject></mediaobject>

<para>Este módulo funciona tal-e-qual o Synth&lowbar;SEQUENCE com a única diferença que você não indica nomes de notas mas sim frequências. </para>

</sect3>

</sect2>

<sect2 id="mcat-synth-samples">
<title>Amostras</title>

<sect3 id="mref-synth-play-wav-sect">
<title>Synth&lowbar;PLAY&lowbar;WAV</title>
<anchor id="mref-synth-play-wav"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_PLAY_WAV.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PLAY&lowbar;WAV</phrase></textobject>
</mediaobject>

<para>Isto irá tocar um ficheiro <literal role="extension">wav</literal>. Isto só estará presente se você tiver a 'libaudiofile' instalada no seu computador. O ficheiro WAVE iniciar-se-á logo que o módulo for criado. </para>

<para>Irá parar logo que tenha terminado, situação em que o 'finished' (terminado) será posto a 1. O parâmetro 'speed' (velocidade) pode ser usado para reproduzir o ficheiro mais depressa ou mais devagar, e onde o 1,0 é a velocidade normal (com que foi gravado). </para>
<!-- TODO: KDE2.2: check that this really works together in instruments with
the done parameter things ;) -->
</sect3>

</sect2>

<sect2 id="mcat-synth-soundio">
<title>E/S de Som</title>

<sect3 id="mref-synth-play-sect">
<title>Synth&lowbar;PLAY</title>
<anchor id="mref-synth-play"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_PLAY.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PLAY</phrase></textobject>
</mediaobject>

<important>
<para>Você normalmente não irá necessitar deste módulo, a menos que esteja a criar aplicações autónomas. Dentro do &artsd;, existe já um módulo Synth&lowbar;PLAY e, se criar outro, este não irá funcionar. </para>
</important>

<para>O módulo Synth&lowbar;PLAY irá enviar o seu sinal de áudio para a placa de som. Os canais 'left' (esquerdo) e 'right' (direito) deverão conter a entrada <emphasis>normalizada</emphasis> dos canais. Se a sua entrada não estiver entre -1 e 1, será cortado o sinal. </para>

<para>Como já foi referido, só pode existir um módulo Synth&lowbar;PLAY em uso, dado que este acede directamente à sua placa de som. Utilize os barramentos se você quiser misturar mais do que um canal de áudio em conjunto antes de o reproduzir. Use o módulo Synth&lowbar;AMAN&lowbar;PLAY para obter algo semelhante a uma saída no &artsd;. </para>

<para>Tenha em atenção que o Synth&lowbar;PLAY também faz a temporização da estrutura completa. Isto significa: sem Synth&lowbar;PLAY = sem fonte de temporização = sem som. Por isso, você irá necessitar (exactamente) de um objecto Synth&lowbar;PLAY. </para>

</sect3>

<sect3 id="mref-synth-record-sect">
<title>Synth&lowbar;RECORD</title>
<anchor id="mref-synth-record"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_RECORD.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;RECORD</phrase></textobject>
</mediaobject>

<important>
<para>Você normalmente não irá necessitar deste módulo, a menos que esteja a criar aplicações autónomas. Dentro do &artsd;, existe já um módulo Synth&lowbar;RECORD e, se criar outro, este não irá funcionar. </para>
</important>

<para>O módulo Synth&lowbar;RECORD irá gravar um sinal proveniente da placa de som. Os canais 'left' (esquerdo) e 'right' (direito) irão conter a entrada dos canais (entre -1 e 1). </para>

<para>Como já foi referido, só pode existir um módulo Synth&lowbar;RECORD em uso, dado que este acede directamente à sua placa de som. Utilize os barramentos se você quiser usar os canais de áudio gravados em mais do que um sítio. Use o módulo Synth&lowbar;AMAN&lowbar;RECORD para obter algo semelhante a uma entrada no &artsd;. Para isto funcionar, o &artsd; terá de estar a correr <emphasis>com o 'full duplex' activo</emphasis>. </para>
</sect3>

<sect3 id="mref-synth-aman-play-sect">
<title>Synth&lowbar;AMAN&lowbar;PLAY</title>
<anchor id="mref-synth-aman-play"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_AMAN_PLAY.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;AMAN&lowbar;PLAY</phrase></textobject>
</mediaobject>

<para>O módulo Synth&lowbar;AMAN&lowbar;PLAY irá enviar para a saída o seu sinal de áudio. É bom (mas não necessário) se você enviar para fora um sinal normalizado (entre -1 e 1). </para>

<para>Este módulo irá usar o gestor de áudio para atribuir onde o sinal será tocado. O gestor de áudio poderá ser controlado através do &artscontrol;. Para o tornar mais intuitivo no seu uso, é bom dar ao sinal que tocar um nome. Isto poderá ser obtido através da opção <emphasis>title</emphasis> (título). Outra funcionalidade do gestor de áudio é ser capaz de se recordar onde tocou um dado sinal da última vez. Para o fazer, ele precisa de ser capaz de distinguir os sinais. É por isso que você deverá atribuir algo único ao <emphasis>autoRestoreID</emphasis>, também. </para>
</sect3>

<sect3 id="mref-synth-aman-record-sect">
<title>Synth&lowbar;AMAN&lowbar;RECORD</title>
<anchor id="mref-synth-aman-record"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_AMAN_RECORD.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;AMAN&lowbar;RECORD</phrase></textobject>
</mediaobject>

<para>O módulo Synth&lowbar;AMAN&lowbar;RECORD irá gravar um sinal de áudio de uma fonte externa (&ie;. 'line in'/'microfone') para dentro do &artsd;. O resultado será um sinal normalizado (entre -1 e 1). </para>

<para>Este módulo irá usar o gestor de áudio para atribuir onde o sinal será tocado. O gestor de áudio poderá ser controlado através do &artscontrol;. Para o tornar mais intuitivo no seu uso, é bom dar ao sinal que gravar um nome. Isto poderá ser obtido através da opção <emphasis>title</emphasis> (título). Outra funcionalidade do gestor de áudio é ser capaz de se recordar onde gravou um dado sinal da última vez. Para o fazer, ele precisa de ser capaz de distinguir os sinais. É por isso que você deverá atribuir algo único ao <emphasis>autoRestoreID</emphasis>, também. </para>
</sect3>

<sect3 id="mref-synth-capture-sect">
<title>Synth&lowbar;CAPTURE</title>
<anchor id="mref-synth-capture"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_CAPTURE.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;CAPTURE</phrase></textobject>
</mediaobject>

<para>O módulo Synth&lowbar;CAPTURE irá gravar um sinal de áudio num ficheiro WAVE no seu disco rígido. O ficheiro será sempre chamado de <filename>/tmp/mcop-<replaceable>utilizador</replaceable>/capture.wav</filename> </para>
</sect3>

</sect2>

<sect2 id="mcat-synth-tests">
<title>Testes</title>

<sect3 id="mref-synth-nil-sect">
<title>Synth&lowbar;NIL</title>
<anchor id="mref-synth-nil"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_NIL.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;NIL</phrase></textobject>
</mediaobject>

<para>Isto simplesmente não faz nada. Só é útil para situações de teste. </para>

</sect3>

<sect3 id="mref-synth-debug-sect">
<title>Synth&lowbar;DEBUG</title>
<anchor id="mref-synth-debug"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_DEBUG.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;DEBUG</phrase></textobject>
</mediaobject>

<para>Você poderá usar isto para depuração. Ele irá imprimir o valor do sinal em 'invalue' em intervalos regulares (p.ex. a cada 1 segundo), combinado com o comentário que você indicou. Desta forma, você poderá descobrir se alguns dos sinais estão dentro de determinados intervalos ou se estão lá mesmo de todo. </para>
</sect3>

<sect3 id="mref-synth-midi-debug-sect">
<title>Synth&lowbar;MIDI&lowbar;DEBUG</title>
<anchor id="mref-synth-midi-debug"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_DEBUG.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;MIDI&lowbar;DEBUG</phrase></textobject>
</mediaobject>

<para>Você poderá usar isto para depurar como é que os seus eventos &MIDI; estão a chegar ao &arts;. </para>

<para>Quando um MIDI&lowbar;DEBUG estiver a correr, o &artsserver; irá imprimir linhas do tipo: </para>

<screen><computeroutput>201 100753.837585 on 0 42 127</computeroutput></screen>

<screen><computeroutput>202 101323.128355 off 0 42</computeroutput></screen>

<para>Enquanto que a primeira linha lhe diz que 100753ms (isto é, 100 segundos) depois de o MIDI&lowbar;DEBUG começar, chegou um evento 'on' de &MIDI; no canal 0. Este evento tinha a velocidade (volume) de 127, a mais elevada possível. A linha a seguir mostra o evento de libertação do MIDI. [ TODO: isto não funciona de momento, quando funcionar, deverá ser feito através do gestor de &MIDI; ]. </para>
</sect3>

<sect3 id="mref-synth-data-sect">
<title>Synth&lowbar;DATA</title>
<anchor id="mref-synth-data"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_DATA.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;DATA</phrase></textobject>
</mediaobject>

<para>Isto cria um sinal com um número constante. </para>
<!-- TODO: this doesn't really belong in test, does it? -->
</sect3>
</sect2>

<sect2 id="mcat-synth-osc-mod">
<title>Oscilação &amp; Modulação</title>

<sect3 id="mref-synth-frequency-sect">
<title>Synth&lowbar;FREQUENCY</title>
<anchor id="mref-synth-frequency"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_FREQUENCY.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;FREQUENCY</phrase></textobject>
</mediaobject>

<para>Todos os osciladores no &arts; não precisam de uma frequência à entrada, mas si de uma posição na onda. A posição deverá ser entre 0 e 1, o que se mapeia num objecto normal do Synth&lowbar;WAVE&lowbar;SIN no intervalo 0..2*pi. Para gerar os valores oscilantes para uma frequência, é usado um módulo Synth&lowbar;FREQUENCY. </para>
</sect3>

<sect3 id="mref-synth-fm-source-sect">
<title>Synth&lowbar;FM&lowbar;SOURCE</title>
<anchor id="mref-synth-fm-source"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_FM_SOURCE.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;FM&lowbar;SOURCE</phrase></textobject>
</mediaobject>

<para>Isto é usado na modulação de frequência. Coloque a sua frequência na entrada 'frequency' (frequência) e coloque outro sinal na entrada 'modulator'. Depois disso, defina o 'modlevel' (nível de modulação) para algo do género 0,3. A frequência será então modulada com o 'modulator'. Pode experimentar. Funciona bem mesmo quando você coloca uma realimentação nele, o que significa ter uma combinação do sinal de saída atrasado com o Synth&lowbar;FM&lowbar;SOURCE (você terá de o pôr com algum oscilador, dado que só tem o papel do Synth&lowbar;FREQUENCY) e algum outro sinal para obter bons resultados. </para>

<para>Funciona optimamente em conjunto com os osciladores Synth&lowbar;WAVE&lowbar;SIN. </para>
</sect3>

</sect2>

<sect2 id="mcat-synth-waveforms">
<title>Formas de Onda</title>

<sect3 id="mref-synth-wave-sin-sect">
<title>Synth&lowbar;WAVE&lowbar;SIN</title>
<anchor id="mref-synth-wave-sin"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_SIN.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;SIN</phrase></textobject>
</mediaobject>

<para>Oscilador sinusoidal. Coloque um sinal 'pos' de um Synth&lowbar;FREQUENCY ou de um Synth&lowbar;FM&lowbar;SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. </para>

</sect3>

<sect3 id="mref-synth-wave-tri-sect">
<title>Synth&lowbar;WAVE&lowbar;TRI</title>
<anchor id="mref-synth-wave-tri"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_TRI.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;TRI</phrase></textobject>
</mediaobject>

<para>Oscilador de ondas triangulares. Coloque um sinal 'pos' de um Synth&lowbar;FREQUENCY ou de um Synth&lowbar;FM&lowbar;SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis>tem</emphasis> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para>
</sect3>

<sect3 id="mref-synth-noise-sect">
<title>Synth&lowbar;NOISE</title>
<anchor id="mref-synth-noise"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_NOISE.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;NOISE</phrase></textobject>
</mediaobject>

<para>Um gerador de ruído. Isto gera um sinal aleatório entre -1 e 1. </para>

</sect3>

<sect3 id="mref-synth-wave-square-sect">
<title>Synth&lowbar;WAVE&lowbar;SQUARE</title>
<anchor id="mref-synth-wave-square"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_WAVE_SQUARE.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;SQUARE</phrase></textobject>
</mediaobject>

<para>Oscilador de ondas quadradas. Coloque um sinal 'pos' de um Synth&lowbar;FREQUENCY ou de um Synth&lowbar;FM&lowbar;SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis>tem</emphasis> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para>
</sect3>

<sect3 id="mref-synth-wave-softsaw-sect">
<title>Synth&lowbar;WAVE&lowbar;SOFTSAW</title>
<anchor id="mref-synth-wave-softsaw"/>

<mediaobject><imageobject><imagedata
fileref="images/Synth_WAVE_SOFTSAW.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;SOFTSAW</phrase></textobject>
</mediaobject>

<para>Oscilador de ondas dente-de-serra. Coloque um sinal 'pos' de um Synth&lowbar;FREQUENCY ou de um Synth&lowbar;FM&lowbar;SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis>tem</emphasis> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para>
</sect3>

<sect3 id="mref-synth-wave-pulse-sect">
<title>Synth&lowbar;WAVE&lowbar;PULSE</title>
<anchor id="mref-synth-wave-pulse"/>

<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_PULSE.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;PULSE</phrase></textobject>
</mediaobject>

<para>Oscilador de impulsos - este módulo é semelhante na ideia ao oscilador de ondas quadradas (Synth_WAVE_RECT), mas oferece uma relação configurável de nível alto/baixo, através do parâmetro <emphasis>dutycycle</emphasis>. Coloque um sinal 'pos' de um Synth&lowbar;FREQUENCY ou de um Synth&lowbar;FM&lowbar;SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis>tem</emphasis> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para>
</sect3>
</sect2>
<sect2 id="mcat-synth-misc">
<title>Diversos</title>

<sect3 id="mref-synth-compressor-sect">
<title>Synth&lowbar;COMPRESSOR</title>
<anchor id="mref-synth-compressor"/>

<mediaobject>
<imageobject><imagedata fileref="images/Synth_COMPRESSOR.png"
               format="PNG"/></imageobject></mediaobject>

<para>Este módulo reduz o intervalo dinâmico do sinal. Por exemplo, os compressores são úteis na compensação das variações amplas de volume se alguém estiver a falar para um microfone. </para>

<para>Assim que o nível de entrada exceder um dado nível (o patamar), o sinal é comprimido. Ele simplesmente multiplica tudo o que estiver acima do limite pelo valor de proporção, o qual é um número entre 0 e 1. Finalmente, o sinal completo é multiplicado pelo factor de saída. </para>

<para>Os argumentos 'attack' e 'release' atrasam o início e o fim da compressão. Use isto se você, por exemplo, quiser à mesma ouvir o início forte de uma batida de bateria. O argumento está em milisegundos e um valor igual a 0ms é possível, se bem que poderá resultar apenas num ligeiro ruído. </para>

</sect3>
</sect2>
</sect1>

<sect1 id="visual-modules-reference">
<title>Referência dos Módulos Visuais</title>

<para>TODO quando os módulos visuais estiverem mais "completos". </para>
</sect1>

</chapter>