VDJPedia



 VDJScript_pt

NOTAS DE TRADUÇÃO : Uma vez que o VDJScript é baseado em língua inglesa, somente verbos em inglês irão funcionar nos comandos escritos. Porém, para que você possa fazer uma correlação com o português, no decorrer do artigo o verbo PRINCIPAL será grafado separado por aspas (") enquanto que a tradução será posta entre parênteses (). Exemplos de comandos não serão traduzidos, pois as traduções não funcionarão no programa.
Do mesmo modo, caso necessite expressar números decimais, utilize "pontos" ao invés de "vírgulas" para separar o número inteiro da primeira casa decimal. Ex.:0.001



VDJScript

Versão original



Definições de Controladores

Verbos VDJScript

Exemplos de ações VDJScript



VDJscript é a linguagem na qual são escritos todos os comandos no VirtualDJ 6 e 7.
É utilizado em skins, atalhos de teclado ou mapeamentos para controladores.

VDJScript foi projetado para ser simples e curto quando utilizado para ações simples, porém versátil o suficiente para permitir programações complexas e macros.
Em sua forma simples, você pode escrever comandos como "play", "pause", "goto_cue 1", "volume 70%", "pitch +0.5%", etc...
Ou você pode escrever macros como "play ? crossfader +12.3% & effect 'flanger' activate : deck 2 loop 4 & set $myvar 42"


Verbos

Os elementos básicos do VDJScript são os "verbos".
Você encontrará uma lista de verbos que podem ser utilizados com VirtualDJ no painel "see also" na janela CONFIG -> Mappers do programa.
Ou alternativamente, você pode abrir o arquivo English.xml localizado na pasta Documentos/VirtualDJ/Languages/ folder, e verificar todos os verbos (e sua descrição) sob o elemento <action>. A tradução para português será encontrada na mesma pasta, porém no arquivo Portuguese.xml.


Comandos

A maioria dos comandos básicos irá consistir de somente um verbo (como "play" ou "pause").

Opcionalmente, o verbo pode ser acompanhado de modificadores e parâmetros diferentes:

- deck: você pode definir em qual deck o verbo irá agir adicionando "deck xxx" em frente ao verbo. xxx pode ser substituído por "1", "2", "left" (esquerdo), "right" (direito), "default" (padrão) ou "active" (ativo). ("1"/"left" e "2"/"right" são sinônimos).

- parâmetros: o verbo pode ser seguido por um ou dois parâmetros. A função destes parâmetros dependerá do que faz o verbo. Os parâmetros podem ser strings, porcentagens, funções boolianas, tempos, valores integrais, ou valores decimais.

- efeitos: para verbos que agem em efeitos, você precisa preceder o verbo com palavra chave "effect" (efeito), seguida opcionalmente pelo nome do efeito ou pelo número do slot do efeito: "effect activate" ou "effect 'flanger' slider 1 100%".

- sampler: para verbos que agem no sampler, você precisa preceder o verbo com a palavra chave "sampler", seguida opcionalmente pelo número do slot do sampler: "sampler activate" ou "sampler 3 volume 100%".

- queries (questões): todos os verbos podem ser questionados quanto ao seu 'estado' e retornar condições boolianas ("0" falso e "1" verdadeiro). Mas algumas queries específicas que devem retornar algum texto ou número devem utilizar a palavra chave "get" (apurar) antes do verbo: "get time_ms".

- ação temporária: você pode especificar que o verbo deve agir somente enquanto o botão for mantido pressionado adicionando "while_pressed" (enquanto pressionado) ao fim do comando: "volume 100% while_pressed".

- blinks (piscar): para queries, você pode adicionar "blink" (piscar) ou "blinkfast" (piscar rápido) para que a resposta booliana alterne entre falso e verdadeiro caso a resposta original seja verdadeiro: "play blink" [Nota: a utilização do "blink" como acréscimo ao verbo foi depreciada, e o que era acréscimo virou verbo. Então, utilize o verbo "blink" ou "blinkfast" em substituição dentro de uma macro: "play ? blink : nothing"]

A sintaxe de comando completa será:

[deck [deck]] [sampler [slot] | effect [effectname/slot] | get] verb [param1] [param2] [while_pressed]


Ou em português para analogia, lembrando sempre que os comandos devem ser feitos em inglês conforme já explicado no início do texto.

[deck [nº deck]] [sampler [nº slot] | efeito [nome efeito/nº slot] | apurar] verbo [parâmetro1] [parâmetro2] [enquanto pressionado]


[...] significa : opcional
| significa : ou


Macros

Se você necessita escrever comandos ainda mais complexos – os macros – utilize o caracter operador "&" para encadear comandos, ou os caracteres operadores "?" e ":" para escrever derivações condicionais.
A sintaxe explicativa "comando1 & comando2 & comando3 " irá executar uma sequência, primeiramente executa o comando1, então executa o comando2 e então executa o comando3.
A sintaxe explicativa "comando1 ? comando2 : comando3 " é uma query e irá questionar o estado do comando1. Se o resultado for verdadeiro será executado o comando2, e se o resultado for falso será executado o comando3.

Por exemplo:
A sintaxe explicativa "ação_deck 1? comando1 : comando2 " irá executar o comando1 se o botão do controlador estiver definido para agir no deck 1 (verifique o arquivo de definições "definition.xml") ou executar o comando1 se o botão do controlador estiver definido para agir no deck 2.


Actions vs Queries (Ações x Questões)

Comandos podem ser usados tanto como ações (actions) quanto como questões (queries), dependendo do contexto.
Por exemplo, o comando "play" utilizado em um atalho de teclado será uma ação (action) e irá dar o play na música quando acionado.
O mesmo comando "play" se usado para mapear o LED de um controlador, será uma questão (query) que irá retornar verdadeiro se a música estiver tocando, ou falso se não estiver.

Alguns comandos podem retornar uma condição booliana (verdadeiro ou falso) ou um valor de texto ou numérico, dependendo dos parâmetros:
- "crossfader" irá retornar um valor (entre 0.0 and 1.0) se utilizado em uma query.
- "crossfader 42%" irá retornar verdadeiro se o crosfader estiver em 42%, e falso se o crossfader estiver em qualquer outra posição.
Comandos que utilizam a palavra chave "get" (apurar) também podem retornar um string ou um número, dependendo do verbo.


Parâmetros

VDJScript reconhece 6 tipos de parâmetros:
- texto: devem ser limitados tanto por apóstrofos (') quanto por haspas ("): "load 'myfile.mp3’" (onde 'myfile’ é o texto que descreve o caminho completo do referido arquivo, por exemplo 'C:\Users\User\Music\Maid with the Flaxen Hair.mp3’
- booliana: podem ser as palavras chaves "on" (ligado = verdadeiro), "off" (desligado = falso) ou "toggle" (alternar). Algumas vezes são equivalents aos números integrais "1", "0" e "-1" respectivamente: "smart_play off"
- tempo: é especificado pela adição da palavra chave "ms": "nudge +100ms" (ms equivale a milissegundo, milésimo de segundo, 0.001 segundo ou 1/1000 segundo)
- número inteiro: "effect select +1"
- número decimal: "crossfader 0.5"
- percentagem: "crossfader 50%"

Na maior parte dos casos, numerous decimais e percentagens são tratados como iguais (claro, após divisão da percentagem por 100).
Existem poucas exceções, como no caso do verbo "pitch", onde "pitch 100%" define o pitch na posição intermediária (no meio), enquanto que "pitch 1.0" define o pitch no máximo do deslizante.

Tenha tambérm em mente que "nudge +1" e "nudge +1.0" não é a mesma coisa. O primeiro move 1 batida, e o segundo equivale a "nudge +100%" que pulará para o fim da música. Na maior parte do tempo, utilize percentagem ao invés de números decimais, mas se você for escrever programações complexas vale a pena saber a diferença.


Parâmetros Implícitos

Quando um comando é usado para atribuir uma ação (action) para um determinado deslizante (botão giratório, jogwheel, etc.), o valor do deslizante será adicionado como parâmetro implícito.

Quando um parâmetro implícito é adicionado, o mesmo é acrescentado ao fim do comando, como um parâmetro adicional depois dos que já existem.
Então se sua função é "volume" e você a atribuiu a este deslizante que você moveu até 42%, a ação enviada será "volume 0.42".
Mas se sua função é "volume +10%", então ação enviada sera "volume +10% 0.42" (e o segundo parâmetro 0.42 será ignorado por segurança pois o verbo volume demanda somente um parâmetro).

Se você necessita modificar o parâmetro implícito, você pode usar verbos como "param_multiply" (multiplicar parâmetro), "param_add" (somar parâmetro), etc...
Então "param_multiply 0.1 & volume" irá resultar no ajuste do volume no valor 4.2%

Se você tem uma macro com diversos comandos, cada comando terá o parâmetro implícito adicionado.
Então se você escrever "crossfader & loop", atribuir a um deslizante e movê-lo até 42%, o action enviado será "crossfader 0.42 & loop 0.42".
Se você deseja prevenir que o parâmetro implícito interfira em alguns comandos, você pode usar a palavra chave "value" (valor) para especificar onde o parâmetro implícito irá interferir.
Então "crossfader value & loop" irá enviar a action "crossfader 0.42 & loop".
(caso você tenha diversas ocorrências da palavra chave "value" no seu comando macro, cada uma sera substituída pelo parâmetro implícito).

Também vale a pena saber que deslizantes irão acrescentar um parâmetro implícito decimal ("crossfader" -> "crossfader 0.42"), jogwheels irão acrescentar um parâmetro implícito decimal relativo ("crossfader" -> "crossfader +0.42", +1.0 sendo uma volta completa na roda), e endless encoders (decodificadores sem fim) irão adicionar um número inteiro relativo ("crossfader" -> "crossfader +1").
Se você utilizar um encoder para um verbo que normalmente é atribuído a um deslizante, o número inteiro sera automaticamente convertido para um número decimal. O número inteiro sera dividido por 32 (então serão necesários 32 passos do encoder para mover o deslizante de 0% até 100%). Então no exemplo anterior "crossfader +1" sera equivalente a "crossfader +0.03125". Você pode usar "param_multiply" caso necessite outra resolução (e melhorar a precisão de ajuste).


Variáveis

VDJScript pode armazenar estados ou numeros em variáveis internas.
Se o nome da variável inicia com $ (como "set $myvar"), a variável será 'global' para ambos decks.
Se o nome da variável inicia com % (como "set %myvar") ou não comoeça com nada (como "set 'myvar'"), a variável sera 'local’ para este deck (e pode ter um valor diferente se atribuída a outro deck).
Variáveis estão presentes durante todo o tempo em que VirtualDJ está rodando (elas não são destinadas para uma skin ou controlador específicos).

Para definir uma variável, você pode usar verbos como "set" (definir), "toggle" (alternar), "cycle" (ciclar).
Para ler uma variável, você pode usar verbos como "var" (variável), "var_equal" (variável igual), "var_smaller" (variável menor), etc...
Um exemplo típico da utilização de variáveis é atribuir "set $myshift while_pressed" para um botão SHIFT, e "var $myshift ? comando1 : comando2" para outro botão.




VOLTAR ao Indice

VOLTAR para Perguntas Frequentes (F.A.Q.)...