VDJscript_FR
VDJscript
(traduit de la version originale en anglais par JeremK)
Les commandes de VirtualDJ 6 sont écrites en langage VDJscript.
Ce langage est utilisé dans les Skins, les Raccourcis clavier, les mappeurs des contrôleurs et les nouveaux plugins 6.x.
Il a été conçu pour être simple et court lorsqu'il est utilisé pour des actions simples, mais suffisamment souple pour permettre des scripts et des macros complexes.
Dans sa forme la plus simple, vous pouvez écrire des commandes comme "play", "pause", "goto_cue 1", "volume 70%", "pitch +0,5%", etc ..
Ou vous pouvez écrire des macros plus complexes comme "play ? crossfader +12.3% & effect 'flanger' activate : deck 2 loop 4 & set $myvar 42"
Verbes
Les éléments de base du VDJscript sont les "verbes".
Vous trouverez la liste des verbes utilisés par VirtualDJ au niveau de la liste "see also" dans la fenêtre Paramètres/Mappeur de VirtualDJ.
Aussi, vous pouvez ouvrir le fichier English.xml (également dans French.xml) du dossier Documents/VirtualDJ/Languages/, et voir la liste des verbes et leur description respective en dessous de l'élément <action>.
Commandes
La commande la plus basique ne contient qu'un verbe (comme "play" ou "pause").
De manière facultative, un verbe peut être accompagné de modificateurs et paramètres:
- deck: vous pouvez spécifier sur quelle platine agit le verbe, en ajoutant "deck xxx" devant le verbe. xxx peut prendre les valeures "1", "2", "left", "right", "default" ou "active". ("1" et "left" ou "2" et "right" sont synonymes).
- paramètres: le verbe peut être suivi d'un ou deux paramètres. La fonction de ces paramètres dépend du verbe. Les paramètres peuvent être des chaînes de caractères (string: " "), pourcentages (%), booléens (true,false), temps (ms), valeurs entières ou valeurs décimales (xx.xx).
- effets: pour les verbes agissant sur les effets, vous devez précéder le verbe du mot clé "effect", suivi optionnellement du nom de l'effet ou du numéro de l'emplacement de l'effet: "effect activate" ou "effect 'flanger' slider 1 100%".
- sampler: comme pour les effets, vous devez précéder le verbe du mot clé "sampler", suivi optionnellement du numéro de l'emplacement du sample: "sampler activate" ou "sampler 3 volume 100%".
- requêtes: certaines requêtes spécifiques nécessitent le mot clé "get" avant le verbe: "get time_ms".
- action temporaire: vous pouvez spécifier que le verbe doit agir uniquement pendant que le bouton (contrôleur, souris, ...) est enfoncé en ajoutant "while_pressed" à la fin de la commande: "volume 100% while_pressed".
- clignotements: pour certaines requêtes ou actions, vous pouvez ajouter "blink" ou "blinkfast" pour que la réponse booléenne oscille entre vrai et faux si la réponse d'origine est vrai: "play blink"
La syntaxe complète de commande est:
[deck [deck]] [sampler [slot] | effect [effectname/slot] | get] verbe [paramètre1] [paramètre2] [blink | blinkfast] [while_pressed]
( [...] signifie : optionnel)
( | signifie : ou )
(Remarque: ne pas ajouter les symboles "[" , "]" et "|" lorsque vous écrivez votre commande. Ils sont juste là pour des raisons explicatives !!!)
Macros
Si vous avez besoin d'écrire des commandes plus complexes, vous pouvez utiliser l'opérateur "&" pour enchaîner les commandes, ou les opérateurs "?" et ":" pour écrire des conditions (tests).
L'utilisation de "commande1 & commande2 & commande3" exécutera successivement la commande1, la commande2 et enfin la commande3.
L'utilisation de "commande1 ? commande2 : commande3" évaluera la commande1 (test), si le résultat est vrai, commande2 sera exécutée, sinon commande3 sera exécuté.
Par exemple:
L'utilisation de "action_deck 1 ? commande1 : commande2" exécutera commande1 si le bouton utilisé est sur le contrôleur de la platine 1 (deck=1) [voir fichier xml "definition"] ou exécutera commande2 si le bouton est sur le contrôleur de la platine 2 (deck=2).
Actions vs. requêtes
Les commandes peuvent être utilisées soit comme une action soit comme une requête, selon le contexte.
Par exemple, la commande "play" utilisée dans un raccourci clavier, sera une action, et lancera la musique.
La même commande "play" utilisée dans le mapping d'une LED d'un contrôleur (ou d'un bouton sur une skin), sera une requête, et retournera true (vrai) si la musique joue, ou false (faux) sinon.
Certaines commandes peuvent retourner une valeur booléenne (vrai ou faux) ou une valeur, selon les paramètres:
- "crossfader" retournera la valeur (entre 0.0 et 1.0) si utilisé dans une requête.
- "crossfader 42%" retournera "true" si le crossfader est à 42%, et "false" sinon.
Les commandes utilisant le mot clé "get" peuvent aussi retourner une chaîne de caractères ou un nombre, en fonction du verbe.
Paramètres
VDJscript connait 6 types de paramètres:
- texte: doit être mis entre simple quotes (') ou double quotes ("): "load 'myfile.mp3'"
- booléen: peut être les mots clés "on", "off" ou "toggle". (ils sont souvent respectivement équivalent aux entiers 1, 0 et -1): "smart_play off"
- temps/durée: sont spécifiés en ajoutant le mot clé "ms": "nudge +100ms"
- valeur entière: "effect select +1"
- valeur décimale: "crossfader 0.5"
- pourcentage: "crossfader 50%"
La plupart du temps, les valeurs décimales et les pourcentages sont traités de la même manière (après division du % par 100).
Il y a tout de même quelques exceptions, comme le verbe "pitch" où "pitch 100%" place le pitch au milieu, alors que "pitch 1.0" place le pitch au maximum du slider.
Gardez en tête que "nudge +1" et "nudge +1.0" ne sont pas les mêmes. Le premier bougera de 1 beat, alors que le deuxième est équivalent à "nudge +100%" ce qui sautera à la fin du morceau. Vous devriez utiliser des pourcentages à la place des valeurs décimales, mais si vous écrivez des scripts complexes, il est utile de le savoir.
Paramètres implicites
Lorsqu'une commande est utilisée en tant qu'action pour un slider (ou potard, jog, etc), la valeur du slider sera ajoutée en tant que paramètre implicite.
Lorsqu'un paramètre implicite est ajouté, il est ajouté à la fin de la commande, en tant que paramètre additionel placé après les paramètres existants.
Donc si votre action est "volume" et que vous mappez ceci sur un slider, que vous bougez le slider à 42%, l'action envoyée sera "volume 0.42"
Mais si votre action est "volume +10%", l'action envoyée sera "volume +10% 0.42" (et le second paramètre 0.42 sera ignoré car le verbe volume n'utilise qu'un seul paramètre).
Si vous souhaitez modifiez le paramètre implicite, vous pouvez utiliser certains verbes comme "param_multiply", "param_add", ...
Donc "param_multiply 0.1 & volume" mettra le volume à 42%.
Si vous avez une macro avec plusieurs commandes, le paramètre implicite de chaque commande sera ajouté.
Donc si vous écrivez "crossfader & loop" et vous le mappez sur un slider que vous bougez de 42%, l'action envoyée sera "crossfader 0.42 & loop 0.42".
Si vous souhaitez empêcher le paramètre implicite d'agir sur certaine commande, vous pouvez utiliser le mot clé "value" pour spécifier où le paramètre implicite devra être placé.
Donc "crossfader value & loop" enverra la commande "crossfader 0.42 & loop".
(Vous pouvez écrire plusieurs occurences de "value" dans votre macro, chaque occurence sera remplacée par le paramètre implicite).
De plus, il est important de savoir que les sliders ajouteront en paramètre un nombre décimal ("crossfader" -> "crossfader 0.42"), le jogwheel ajoutera un nombre décimal relatif ("crossfader" -> "crossfader +0.42", +1.0 étant un tour complet de la roue), et les encodeurs ajouteront un entier relatif ("crossfader" -> "crossfader +1").
Si vous utilisez un encodeur pour un verbe qui attend un slider, l'entier va être automatiquement converti en nombre décimal en le divisant par 32 (donc celui-ci aura besoin de 32 déplacements de l'encodeur pour bouger le slider de 0% à 100%). Ainsi dans l'example précédent "crossfader +1" est équivalent à "crossfader +0.03125". Vous pouve utiliser "param_multiply" si vous avez besoin d'une autre résolution.
Variables
VDJscript peut stocker des états ou des nombres dans des variables internes.
Si le nom de la variable commence par un $ (comme "set $myvar"), la variable sera 'globale', c'est-à-dire applicable aux deux platines.
Si le nom de la variable commence par un % (comme "set %myvar") ou sans rien (comme "set 'myvar'"), la variable sera 'locale' c'est-à-dire applicable uniquement à la platine définie (et peut avoir une valeur différente lorsqu'utilisé sur l'autre platine).
Les variables existent tant que VirtualDJ est en activité (elles ne sont pas locales et spécifiques à un contrôleur ou une skin).
Pour définir une variable, vous pouvez utiliser un verbe comme "set", "toggle", "cycle".
Pour lire une variable, vous pouvez utiliser un verbe comme "var", "var_equal", "var_smaller", etc...
Un example typique d'utilisation de variables est d'avoir "set $myshift while_pressed" sur un bouton shift, et "var $myshift ? command1 : command2" sur un autre bouton.
Exemples
Wiki Français
Wiki HOME
(traduit de la version originale en anglais par JeremK)
Les commandes de VirtualDJ 6 sont écrites en langage VDJscript.
Ce langage est utilisé dans les Skins, les Raccourcis clavier, les mappeurs des contrôleurs et les nouveaux plugins 6.x.
Il a été conçu pour être simple et court lorsqu'il est utilisé pour des actions simples, mais suffisamment souple pour permettre des scripts et des macros complexes.
Dans sa forme la plus simple, vous pouvez écrire des commandes comme "play", "pause", "goto_cue 1", "volume 70%", "pitch +0,5%", etc ..
Ou vous pouvez écrire des macros plus complexes comme "play ? crossfader +12.3% & effect 'flanger' activate : deck 2 loop 4 & set $myvar 42"
Verbes
Les éléments de base du VDJscript sont les "verbes".
Vous trouverez la liste des verbes utilisés par VirtualDJ au niveau de la liste "see also" dans la fenêtre Paramètres/Mappeur de VirtualDJ.
Aussi, vous pouvez ouvrir le fichier English.xml (également dans French.xml) du dossier Documents/VirtualDJ/Languages/, et voir la liste des verbes et leur description respective en dessous de l'élément <action>.
Commandes
La commande la plus basique ne contient qu'un verbe (comme "play" ou "pause").
De manière facultative, un verbe peut être accompagné de modificateurs et paramètres:
- deck: vous pouvez spécifier sur quelle platine agit le verbe, en ajoutant "deck xxx" devant le verbe. xxx peut prendre les valeures "1", "2", "left", "right", "default" ou "active". ("1" et "left" ou "2" et "right" sont synonymes).
- paramètres: le verbe peut être suivi d'un ou deux paramètres. La fonction de ces paramètres dépend du verbe. Les paramètres peuvent être des chaînes de caractères (string: " "), pourcentages (%), booléens (true,false), temps (ms), valeurs entières ou valeurs décimales (xx.xx).
- effets: pour les verbes agissant sur les effets, vous devez précéder le verbe du mot clé "effect", suivi optionnellement du nom de l'effet ou du numéro de l'emplacement de l'effet: "effect activate" ou "effect 'flanger' slider 1 100%".
- sampler: comme pour les effets, vous devez précéder le verbe du mot clé "sampler", suivi optionnellement du numéro de l'emplacement du sample: "sampler activate" ou "sampler 3 volume 100%".
- requêtes: certaines requêtes spécifiques nécessitent le mot clé "get" avant le verbe: "get time_ms".
- action temporaire: vous pouvez spécifier que le verbe doit agir uniquement pendant que le bouton (contrôleur, souris, ...) est enfoncé en ajoutant "while_pressed" à la fin de la commande: "volume 100% while_pressed".
- clignotements: pour certaines requêtes ou actions, vous pouvez ajouter "blink" ou "blinkfast" pour que la réponse booléenne oscille entre vrai et faux si la réponse d'origine est vrai: "play blink"
La syntaxe complète de commande est:
( [...] signifie : optionnel)
( | signifie : ou )
(Remarque: ne pas ajouter les symboles "[" , "]" et "|" lorsque vous écrivez votre commande. Ils sont juste là pour des raisons explicatives !!!)
Macros
Si vous avez besoin d'écrire des commandes plus complexes, vous pouvez utiliser l'opérateur "&" pour enchaîner les commandes, ou les opérateurs "?" et ":" pour écrire des conditions (tests).
L'utilisation de "commande1 & commande2 & commande3" exécutera successivement la commande1, la commande2 et enfin la commande3.
L'utilisation de "commande1 ? commande2 : commande3" évaluera la commande1 (test), si le résultat est vrai, commande2 sera exécutée, sinon commande3 sera exécuté.
Par exemple:
L'utilisation de "action_deck 1 ? commande1 : commande2" exécutera commande1 si le bouton utilisé est sur le contrôleur de la platine 1 (deck=1) [voir fichier xml "definition"] ou exécutera commande2 si le bouton est sur le contrôleur de la platine 2 (deck=2).
Actions vs. requêtes
Les commandes peuvent être utilisées soit comme une action soit comme une requête, selon le contexte.
Par exemple, la commande "play" utilisée dans un raccourci clavier, sera une action, et lancera la musique.
La même commande "play" utilisée dans le mapping d'une LED d'un contrôleur (ou d'un bouton sur une skin), sera une requête, et retournera true (vrai) si la musique joue, ou false (faux) sinon.
Certaines commandes peuvent retourner une valeur booléenne (vrai ou faux) ou une valeur, selon les paramètres:
- "crossfader" retournera la valeur (entre 0.0 et 1.0) si utilisé dans une requête.
- "crossfader 42%" retournera "true" si le crossfader est à 42%, et "false" sinon.
Les commandes utilisant le mot clé "get" peuvent aussi retourner une chaîne de caractères ou un nombre, en fonction du verbe.
Paramètres
VDJscript connait 6 types de paramètres:
- texte: doit être mis entre simple quotes (') ou double quotes ("): "load 'myfile.mp3'"
- booléen: peut être les mots clés "on", "off" ou "toggle". (ils sont souvent respectivement équivalent aux entiers 1, 0 et -1): "smart_play off"
- temps/durée: sont spécifiés en ajoutant le mot clé "ms": "nudge +100ms"
- valeur entière: "effect select +1"
- valeur décimale: "crossfader 0.5"
- pourcentage: "crossfader 50%"
La plupart du temps, les valeurs décimales et les pourcentages sont traités de la même manière (après division du % par 100).
Il y a tout de même quelques exceptions, comme le verbe "pitch" où "pitch 100%" place le pitch au milieu, alors que "pitch 1.0" place le pitch au maximum du slider.
Gardez en tête que "nudge +1" et "nudge +1.0" ne sont pas les mêmes. Le premier bougera de 1 beat, alors que le deuxième est équivalent à "nudge +100%" ce qui sautera à la fin du morceau. Vous devriez utiliser des pourcentages à la place des valeurs décimales, mais si vous écrivez des scripts complexes, il est utile de le savoir.
Paramètres implicites
Lorsqu'une commande est utilisée en tant qu'action pour un slider (ou potard, jog, etc), la valeur du slider sera ajoutée en tant que paramètre implicite.
Lorsqu'un paramètre implicite est ajouté, il est ajouté à la fin de la commande, en tant que paramètre additionel placé après les paramètres existants.
Donc si votre action est "volume" et que vous mappez ceci sur un slider, que vous bougez le slider à 42%, l'action envoyée sera "volume 0.42"
Mais si votre action est "volume +10%", l'action envoyée sera "volume +10% 0.42" (et le second paramètre 0.42 sera ignoré car le verbe volume n'utilise qu'un seul paramètre).
Si vous souhaitez modifiez le paramètre implicite, vous pouvez utiliser certains verbes comme "param_multiply", "param_add", ...
Donc "param_multiply 0.1 & volume" mettra le volume à 42%.
Si vous avez une macro avec plusieurs commandes, le paramètre implicite de chaque commande sera ajouté.
Donc si vous écrivez "crossfader & loop" et vous le mappez sur un slider que vous bougez de 42%, l'action envoyée sera "crossfader 0.42 & loop 0.42".
Si vous souhaitez empêcher le paramètre implicite d'agir sur certaine commande, vous pouvez utiliser le mot clé "value" pour spécifier où le paramètre implicite devra être placé.
Donc "crossfader value & loop" enverra la commande "crossfader 0.42 & loop".
(Vous pouvez écrire plusieurs occurences de "value" dans votre macro, chaque occurence sera remplacée par le paramètre implicite).
De plus, il est important de savoir que les sliders ajouteront en paramètre un nombre décimal ("crossfader" -> "crossfader 0.42"), le jogwheel ajoutera un nombre décimal relatif ("crossfader" -> "crossfader +0.42", +1.0 étant un tour complet de la roue), et les encodeurs ajouteront un entier relatif ("crossfader" -> "crossfader +1").
Si vous utilisez un encodeur pour un verbe qui attend un slider, l'entier va être automatiquement converti en nombre décimal en le divisant par 32 (donc celui-ci aura besoin de 32 déplacements de l'encodeur pour bouger le slider de 0% à 100%). Ainsi dans l'example précédent "crossfader +1" est équivalent à "crossfader +0.03125". Vous pouve utiliser "param_multiply" si vous avez besoin d'une autre résolution.
Variables
VDJscript peut stocker des états ou des nombres dans des variables internes.
Si le nom de la variable commence par un $ (comme "set $myvar"), la variable sera 'globale', c'est-à-dire applicable aux deux platines.
Si le nom de la variable commence par un % (comme "set %myvar") ou sans rien (comme "set 'myvar'"), la variable sera 'locale' c'est-à-dire applicable uniquement à la platine définie (et peut avoir une valeur différente lorsqu'utilisé sur l'autre platine).
Les variables existent tant que VirtualDJ est en activité (elles ne sont pas locales et spécifiques à un contrôleur ou une skin).
Pour définir une variable, vous pouvez utiliser un verbe comme "set", "toggle", "cycle".
Pour lire une variable, vous pouvez utiliser un verbe comme "var", "var_equal", "var_smaller", etc...
Un example typique d'utilisation de variables est d'avoir "set $myshift while_pressed" sur un bouton shift, et "var $myshift ? command1 : command2" sur un autre bouton.
Exemples
- settings
Ouvre la fenêtre de configuration de VirtualDJ - sampler play_stop
Play/stop du sample sélectionné - sampler 1 play while_pressed
Jouer le sample 1 tant que la touche est enfoncée - effect slider 2
(à utiliser sur un slider ou bouton rotatif) modifie la valeur du slider 2 pour l'effet sélectionné. - crossfader 0%
Place le crossfader en position 0% (tout à gauche) - crossfader -10%
Déplace le crossfader de 10% de sa course totale vers la gauche - pitch '12,16,25' +1
Modifie l'étendue du pitch en passant de 12% à 16% à 25% à chaque pression sur le bouton. - deck 1 play ? crossfader 100% & deck 2 play & deck 1 stop : crossfader 0% & deck 1 play & deck 2 stop
Si la platine 1 est en marche, le crossfader se met tout à droite, la platine 2 est lancée et la platine 1 arrêtée.
Si la platine 1 n'est pas en marche, le crossfader se met tout à gauche, la platine 1 est lancée et la platine 2 arrêtée.
Cette macro permet de réaliser facilement une transition "Cut"
Wiki Français
Wiki HOME