VDJPedia



 

Go back to German content

VERSION 8 Syntax - http://www.virtualdj.com/wiki/ControllerDefinitionMIDIv8.html

ab Version 6.x

Controller Definition für MIDI - selbst gemacht
(Übersetzung aus dem Englischen von H. Jakovski)

Die 'Definition' Datei für einen MIDI Controller ist eine XML Datei und liegt in 'Eigene Dateien/VirtualDJ/Devices/'. Sie hat folgenden Aufbau:

Das 'root' Element der XML Datei muss <device> heissen und hat folgende Werte:
- name: Eindeutiger Name welcher den Controller Identifiziert (Wird auch im Mapper Bereich verwendet).
- author: (Optional) Name des Authoren der XML Definition Datei.
- type: Muss in diesem Fall "MIDI" sein.
- decks: Kann entweder "1" oder "2" sein, je nachdem ob der Controller nur für ein Deck oder eben für zwei Decks gleichzeitig ausgelegt ist.
- sysexid: (Optional) Antwort auf die Identitätsanfrage per Sysex. (Siehe auch "Geräte Identifizierung" weiter unten)
- drivername: (Optional) Name des Treibers
- drivernameout: (Optional) Name des Output Treibers, ist unterschiedlich
- midiin: (Optional) Nummer des Midi Input Interfaces auf diesem Computer
- midiout: (Optional) Nummer des Midi Output Interfaces auf diesem Computer
- sysexquery: (Optional) Sysex Kommandos das zur Identifizierung an das Gerät geschickt werden soll
- sysexanswer: (Optional) Sysex Antwort die vom Gerät zurück kommt
- vid und pid: Die vid und pid müssen ab Version 7.0 bei der Erstellung von Definitions mit angegeben werde. Die beiden Werte können im Moment im Gerätemanager ermittelt werden. Suchen Sie das USB Endgerät und notieren Sie die beiden Werte. In unserem Beispiel lauten die Werte: vid="0x1AA1" pid="0x0010"




Beispiel:
<?xml version="1.0" encoding="UTF-8"?>
<device name="Mein Controller" author="Ich" type="MIDI" decks="2" sysexid="F07E??06020001020304" vid="0x1AA1" pid="0x0010">
...
</device>

Beispiel für den Dateinamen einer eigene Definition Datei: 'Vestax VCI100 definition.xml'.


Geräte Identifizierung:

Um eine automatische Erkennung der Geräte in VirtualDJ zu gewährleisten muss in der Definition Datei eine Möglichkeit hinterlegt werden das Gerät und den Midi Port an dem es angeschlossen wurde zu ermitteln. Hierfür gibt es, je nach dem wie MIDI kompatibel der Controller ist, verschiedene Möglichkeiten dies zu tun.

Wenn sich der angeschlossene MIDI Controller an die Spezifikationen des MIDI Protokolls hält ist der beste Weg die sogenannte 'Geräte ID' (SysExID) im XML zu hinterlegen. Das wird erreicht in dem der Wert 'sysexid="WERT"' wie im obigen Beispiel eingetragen wird. Die SysExID (Antwort auf die Identitätsanfrage) solltemit 'F07E??0602' starten. Dann folgt eine 3-Byte Hersteller ID und zum Schluß die Produkt ID. Die beiden '??' in unserem Beispiel stehen für den verwendeten MIDI Kanal der aktuell benutzt wird. Dort stehen in der Regel 2 Zahlen, die aber für die Eintragung mit '??' ersetzt werden müssen da sonst der Controller NUR auf dem angegebenen MIDI Kanal erkannt würde. Wenn Ihr also z.B. einen zweiten, anderen, Midi Controller anschließen würdet könnte das zu einer Verschiebung im MIDI Kanal führen und das Gerät würde somit nicht mehr erkannt.

Am einfachsten ermittelt Ihr die ID und alle weiteren benötigten Daten mit folgendem Tool: http://www.virtualdj.com/download/miditrace.exe

Hier findet Ihr eine Erklärung wie das Miditrace Tool verwendet wird.

Wenn Ihr das Programm Euren Controller angeschlossen habt startet einfach das Tool klickt mit der Maus rechts in der Liste den Controller an und drückt oben auf 'Send'. Die Hexadezimalen Zahlen die bereits eingetragen sind (SysEx ID Request) werden an den Controller gesendet der hierauf in der Regel mit seiner SysExID antworten sollte. Diese einfach kopieren und den Midi Kanal wie oben beschrieben durch '??' ersetzten.

Wenn Euer Controller sich nicht so ganz an die Spezifikation des MIDI Standards hält wird es deutlich schwieriger. (An dieser Stelle Empfehle ich Anfängern auszusteigen und im Forum um Hilfe zu bitten.) Ihr benötigt vom Hersteller des Controller die Information ob es eine 'SysEx' Anfrage gibt die eine Eindeutige Identifizierung des Gerätes ermöglicht und wie diese Antwort aussieht. Da SysEx dem Hersteller die Möglichkeit gibt eigene Kommandos für seine Geräte zu implementieren kommt Ihr hier ohne die Info's des Herstellers nicht weiter.

!!! ACHTUNG !!! Schickt auf keinen Fall sinnlose, zufällige oder nicht 100% Verstandene SysEx Befehle an Euren Controller. Unter Umständen wird sonst etwas an der Hardware beschädigt.Zum Beispiel wenn Ihr den 'Hersteller SysEx' für den Befehl - 'Lösche die bestehende Firmware' an den Controller schickt. KEINE GUTE IDEE ;-)

Alternativ habt Ihr auch die Möglichkeit, sofern der Controller keine SysExID implementiert hat, das Gerät durch den Namen des verwendeten Treibers zu identifizieren.

Beachtet aber bitte hierbei das der Name des Treibers unter Windows Vista und Mac OSX durch den User geändert werden kann, bzw. wenn Ihr eine z.B. Englische Windows Version verwendetder Namen auf Grund der anderen Sprache variieren kann. Diese Methode ist also nicht 100%ig !!!
Wenn das Output Interface z.B. einen anderen Treiber Namen verwendet kann dieser mit 'drivernameout=WERT' ebenfalls eingetragen werden um eine bessere Trefferquote zu erreichen.


Sollte der Treiber KEINEN eindeutigen Namen haben und Ihr auch keine SysExID verwenden könnt habt Ihr als letzte Möglichkeit noch die Eintragung des verwendeten Midiports.
Diese Nummer ändert sich allerdings wenn Ihr weitere/andere MIDI Geräte in Betrieb nehmt, bzw. ist auf anderen Computern auf jeden Fall falsch.
Diese Art der Identifikation soll vor allem dazu dienen Entwicklern, während der Testphase, einen schnellen und einfachen Zugriff zu ermöglichen. Die beiden Werte 'midiin=WERT' und 'midiout=WERT' wurden hierzu implementiert. Die Dauerhafte Identifizierung eines Gerätes sollte auf einem der oben beschriebenen Wegen realisiert werden !!!


Für den Fall das alle der hier aufgezeigten Wege NICHT funktionieren kann auf einen Identifizierungsstring auf verzichtet werden. Dann wird das Mapping auf alle Profile die NICHT durch ein anderes, mit Identifizierung, angelegtes Profil abgedeckt werden angewendet. D.h. wenn Ihr die Definition Datei NUR FÜR EUCH SELBST schreibt könnt Ihr auf eine Identifizierung Notfalls auch verzichten. (Anm. d. Übersetzers: Besser ist immer eine Identifizierung da so die Definition Datei auch von anderen Usern genutzt werden kann.)



Weil immer wieder unbrauchbare Definitions generiert werden hier nochmal ein ganz wichtiger Punkt.
Wenn ein Controller 2 Decks verarbeiten kann, d.h. auf dem Controller z.B. 2 Jogwheels oder 2 Play Tasten vorhanden sind (1x Deck A und einmal Deck B) erhalten die gleichen Elemente im Definition IMMER den selben Namen. Also z.B. JOGWHEEL. Bitte KEINE Nummern oder Zahlen an die Elementnamen anhängen. (JOGWHEEL_1 oder JOGWHEEL_A ist falsch !)

Das Getrennte Ansteuern in VDJ ist mit der Scriptsprache trotzdem möglich. Die Unterscheidung zwischen Jog 1 und 2 erfolgt durch das Anhängen von deck="1" oder deck="2"



MIDI Elemente:

Jeder Taster, Fader, Drehregler, LED, LCD, etc. wird durch ein sogenanntes 'child' Element innerhalb des <device> Elements definiert.
Alle dieser 'child' Elemente (mit Ausnahme von 'init' und 'exit') können die folgenden Parameter beinhalten:
- name: Der Name des Elements - dieser wird später im Mapper angezeigt
- deck: (Optional) Das Deck (1/2) für welches dieses Element verwendet wird (sofern der Controller zwei Decks unterstützt) - z.B. für die 'PLAY' Taste. Für gleiche Elemente auf den
beiden Decks sollten IMMER die selben Namen verwendet werden, also z.B. für den Play Button 'PLAY' - die Unterscheidung ob linkes oder rechtes Deck erfolgt durch den
'deck' Parameter.
- channel: (Optional) Der Midi Kanal auf dem gesendet wird (Sofern zwischen verschiedenen Kanälen unterschieden werden muß)


Taster:

Ein Taster wird durch das '<button>' Element mit den folgenden möglichen Parametern definiert:
- note: Die Midi Note
- inverted: (Optional) Hier könnt Ihr 'true' eintragen wenn Euer Controller ein 'note-off' beim drücken und ein 'note-on' beim loslassen sendet (Also genau anders herum als normal)

Beispiel:
<button note="0x1F" name="PLAY" deck="1" />


Die Namen sollten IMMER als Großbuchstaben gewählt werden und bei gleicher Funktion auf dem Controller für 2 Decks mit dem Parameter 'deck' unterschieden werden.

Beispiel:
<button note="0x1F" name="PLAY" deck="1" /> - für den linken Play Button und
<button note="0x3D" name="PLAY" deck="2" /> - für den rechten Play Button.


Sollte der Taster 'CC' - sogenannte 'Control changes' senden statt 'note-on' und 'note-off' müsst Ihr stattdessen die folgenden Parameter verwenden:
- cc: Der MIDI cc
- value: Der Wert des MIDI cc


Als letzte Möglichkeit gibt es noch Taster die während des drückens kein Signal ausgeben sondern erst nach dem Loslassen der Taste eine Zustandsinformation senden, also in der Art 'ich bin jetzt eingeschaltet', bzw. 'jetzt bin ich aus'. In diesem Fall verwendet bitte das '<toggle>' Element mit den folgenden Parametern:

- note: Die MIDI Note
- inverted: (Optional) Hier könnt Ihr 'true' eintragen wenn Euer Controller ein 'note-off' sendet wenn er aktiviert ist und ein 'note-on' wenn er nicht aktiviert ist.


Fader:

Fader werden durch das '<slider>' element mit den folgenden Parametern definiert:
- cc: Der MIDI cc
- ccmsb: (Optional) the MIDI cc of the MSB (Für 14-bit MIDI)
- min: (Optional) Der Wert der 0% repräsentiert (Standard 0)
- max: (Optional) Der Wert der 100% repräsentiert (Standard 0x7F)
- zero: (Optional) Der Wert der 50% des Sliders repräsentiert (z.B. beim Pitchregler)
- inverted: (Optional) Auf 'true' setzen wenn der Slider auf dem Kopf steht / Seitenverkehrt eingebaut ist.

Beispiel:
<slider cc="0x42" name="VOLUME" /> (denkt bitte daran das '<deck>' Element zu verwenden wenn es zwei Volume Regler (linker und rechter Player) auf dem Controller gibt.)

Wenn der Fader 'MIDI PITCH' Nachrichten (Ex YY YY) schickt benutzt bitte das '<slider>' Element mit folgenden Parametern:
- pitch: Auf "true" setzen
- inverted: (Optional) Wenn der Fader auf dem Kopf steht, bzw. Seitenverkehrt eingebaut ist hier einfach 'true' eintragen.

Beispiel:
<slider pitch="true" channel="1" name="PITCH" deck="1" />

(MSB, und LSB - siehe auch: http://de.wikipedia.org/wiki/Bitwertigkeit)


Jog Wheels:

Jogwheels werden durch das '<jog>' Element mit folgenden Parametern definiert:
- cc: Der MIDI cc
- inverted: (Optional) Auf 'true' setzen wenn das Jog genau falsch herum funktioniert wie es soll
- zero: Setzt den Wert der Null repräsentiert.
Für ein Jog das '0x01' für vorwärts und '0x7F' für rückwärts sendet tragt hier '0' ein (Standard).
Sollte Euer Jog jedoch '0x41' für vorwärts und '0x3F' für rückwärts senden tragt hier bitte '0x40' ein.
- full: Die Anzahl der Schritte für eine volle Umdrehung des Jogs rein (Standard ist hier '128')

Beispiel:
<jog cc="0x24" name="JOGWHEEL" deck="1" full="512" />


Sollte Euer Jogwheel Nachrichten mit Abolutwerten senden könnt Ihr dies mit dem '<fulljog>' Element definieren. Hier werden folgende Parameter genutzt:
- cc: Der MIDI cc
- inverted: (Optional) 'true' eintragen wenn das Jog genau falsch herum funktioniert wie es sollte
- full: Die Anzahl der Schritte für eine volle Umdrehung des Jogs rein (Standard ist hier '128')
- max: (Optional) Der maximale Wert der gesendet wird bevor das Jogwheel wieder mit dem kleinsten Wert anfängt (Umbruchpunkt)
- mask: (Optional) set a bitmask to apply to the cc value (Da fällt mir leider im Moment die passende Übersetzung nicht ein ;-))


Endlos Drehregler:

Wenn der Regler Nachrichten mit Inkrementellen Werten seiner aktuellen Position sendet, also z.B. '+1' oder '-4', wird das '<encoder>' Element mit folgenden Parametern genutzt:
- cc: Der MIDI cc
- inverted: (Optional) Auf 'true' setzen wenn der Regler genau falsch herum funktioniert wie er soll
- zero: Setzt den Wert der Null repräsentiert.
Für ein Jog das '0x01' für vorwärts und '0x7F' für rückwärts sendet tragt hier '0' ein (Standard).
Sollte Euer Jog jedoch '0x41' für vorwärts und '0x3F' für rückwärts senden tragt hier bitte '0x40' ein.
- max: (Optional) Der maximale Wert der gesendet wird bevor der Encoder wieder mit dem kleinsten Wert anfängt (Umbruchpunkt)


Sollte Euer Drehregler Nachrichten mit Abolutwerten senden könnt Ihr dies mit dem '<fullencoder>' Element definieren. Hier werden folgende Parameter genutzt:
- cc: Der MIDI cc
- inverted: (Optional) 'true' eintragen wenn der Regler genau falsch herum funktioniert wie er sollte
- full: Die Anzahl der Schritte für eine volle Umdrehung des Jogs rein (Standard ist hier '128')
- mask: (optional) set a bitmask to apply to the cc value (Da fällt mir leider im Moment die passende Übersetzung nicht ein ;-))


LEDs:

Eine LED wird mit dem '<led>' Element definiert. Hierbei werden folgende Parameter genutzt:
- note: Die MIDI Note
- default: (Optional) Der Name des korespondierenden Taster Elements. Sollte im Mapper KEINE Aktion für die LED definiert werden, wird hier automatisch der Status des Tasters mithilfe der LED angezeigt.

Beispiel:
<led note="0x42" name="LED_PLAY" default="PLAY" />

Achtung: LEDs sollten immer mit der Zeichenfolge 'LED_' im Namen beginnen. Dies erleichtert später das Zuordnen im Mapper.

Sollte die LED einen MIDI cc Befehl erwarten kann dieser im '<led>' Element mit den folgenden Parametern definiert werden:
- cc: Der MIDI cc
- value: Der CC Wert
- ccoff: (Optional) Ein zusätzlicher MIDI cc an den der 'value' ebenfalls gesendet wird um die LED abzuschalten.

Wenn eine LED nur mithilfe von SysEx Befehlen gesteuert werden kann (Hersteller abhängig) schaut bitte weiter unter im Bereich 'Senden von SysEx Befehlen' nach.


Zahlen (auf einem LCD d. Controllers):

Zahlen auf einer LCD Anzeige werden durch das '<digit>' Element mit folgenden Parametern definiert:
- cc: Der MIDI cc
- blank: (Optional) Der Wert der gesendet werden soll um das Display zu löschen.
- ccmsb: (Optional) Der MIDI cc an welchen das MSB gesendet werden soll.
- ccmsb2: (Optional) Der MIDI cc an welchen das MMSB (Wert/(Basis*Basis)) gesendet werden soll.
- base: (Optional) Die Basis mit welcher errechnet wird was das LSB und was das MSB ist (Standard ist hier 100)
- multiply: (Optional) Wenn eine Dezimalzahl gesendet werden soll bitte hier '10' eintragen.
- max: (Optional) Der maximale Wert der gesendet werden kann (Nach der Multiplikation mit dem Parameter 'multiply')
- ccsign: (Optional) Der MIDI cc der das '+' und '-' Zeichen kontrolliert.
- signplus: (Optional) Der Wert der an den 'ccsign' Parameter übergeben werden soll um das '+' Zeichen anzuzeigen,
- signminus: (Optional) der Wert um das '-' Zeichen anzuzeigen.

(MSB, und LSB - siehe auch: http://de.wikipedia.org/wiki/Bitwertigkeit)


Progress bars und VUE Meter:

---------------------------
Progress bars werden durch das '<bar>' Element, mit folgenden Parametern definiert:
- cc: Der MIDI cc
- min: (Optional) Der Wert der 0% repräsentiert (Standard 0)
- max: (Optional) Der Wert der 100% repräsentiert (Standard 0x7F)
- inverted: (Optional) Dreht die Richtung der Anzeige um
- mask: (Optional) mask to apply to the value to send (Da fällt mir leider im Moment die passende Übersetzung nicht ein ;-))
- ccoff: (Optional) MIDI cc an den der Wert gesendet wird bevor er sich ändert.

Alternativ kann ein Progress bar der aus mehreren einzelnen LEDs besteht die alle durch individuelle MIDI Noten angesprochen werden das '<bar>' Element
mit den folgenden Parametern definiert werden:
- note: Die MIDI Note der ersten LED
- nb: Die Anzahl der LEDs (Die Midi Note der letzten LED entspricht dabei dann note+nb-1)
- inverted: (optional) Wenn Ihr hier 'true' eintragt wird der Bar von rechts nach links angezeigt.


Text Displays:

Text Displays können mittels des '<text>' Elements und den folgenden Parametern definiert werden:
- cc: Die MIDI cc für das erste Zeichen auf dem Display
- size: Die Anzahl der möglichen Zeichen
- encoding: (Optional) Die Zeichenkodierung die verwendet werden soll ('urf8', 'iso-8859-1', 'ascii', etc.)
- scroll: Auf 'false' setzen um das Display vor dem Scrollen zu langer Texte zu schützen. (Standard ist 'true')

Sollten die MIDI cc's nicht direkt hintereinander liegen, sondern verschiedene Werte haben kann anstatt des 'cc=' Parameters der folgende genutzt werden:
- ccs: Liste aller MIDI cc's, zum Beispiel 'ccs="010A12"' bedeutet 'CC 0x01' für das erste Zeichen, 'CC 0x0A' für das zweite, und so weiter.

Wenn die Zeichen mittels 14-bit MIDI übermittelt werden kann folgender Parameter anstelle von 'cc=' genutzt werden:
- ccs: Liste aller MIDI cc für das MSB
- ccs_lsb: Liste aller MIDI cc für den LSB Wert

(MSB, und LSB - siehe auch: http://de.wikipedia.org/wiki/Bitwertigkeit)


Senden von SysEx Befehlen

Sollte ein Gerät vor der Verwendung eine entsprechende Initialisierung mittels SysEx Befehlen erwarten (Hersteller abhängig) so kann dies mittels des
'<init>' Elements definiert werden. Es werden folgende Parameter genutzt:
- sendsysex: Die Liste Hexadezimaler Werte die an das Gerät gesendet werden sollen.

Beispiel:
<init sendsysex="F00001020304057F" />

Die <init> Elemente werden in der Reihenfolge in der sie in der XML Datei stehen gesendet.

Wenn das Gerät spezielle SysEx Kommandos beim beenden benötigt, so können diese mittels des '<exit>' Elements mit folgenden Parametern definiert werden:
- sendsysex: Die Liste Hexadezimaler Werte die an das Gerät gesendet werden sollen.

Sollte das Gerät zum ansteuern von LEDs einen SysEx Befehl benötigen kann dies mit dem '<ledsysex>' Element mit folgenden Parametern definiert werden:
- value: Die Liste Hexadezimaler Werte die an das Gerät gesendet werden sollen.

Das '<ledsysex>' Element kann jetzt weitere 'child' Elemente vom Typ '<led>' haben. Hierbei werden folgende Parameter genutzt:
- bit: Die Position des Bit innerhalb des SysEx Befehles welches auf '1' oder '0' gesetzt werden muss um die LED an, bzw. aus zu schalten.
- name, default, deck: Diese Elemente können wie beim normalen '<led>' Element (siehe oben) verwendet werden.


Hier noch eine recht gute Dokumentation verschiedener MIDI Befehle (ext. Link).

(Übersetzung aus dem Englischen von H. Jakovski)


Go back to German content