Revision 2007-09-10 15:06

This document describes the interfaces that can be used by JACK MIDI clients to talk to each other over D-Bus. Basically, it can be used by sequencers to find out about the available MIDI programs and MIDI controllers that are valid for a certain JACK MIDI input port, as well as some other metadata.

These interfaces are only meant to provide very basic information - since D-Bus objects can implement any number of interfaces, additional interfaces that allow querying more advanced information can be defined later.

Interfaces
foo.org.jackaudio.MidiInputListener
Methods: HereIAm,
Signals: WhereAreYou,
foo.org.jackaudio.MidiInput
Methods: GetPrograms, GetCurrentProgram, GetControllers, GetNamedKeys, GetActiveChannels,
Signals: CurrentProgramChanged, ProgramAdded, ProgramRemoved, ProgramChanged, ControllerAdded, ControllerRemoved, ControllerChanged, NamedKeyAdded, NamedKeyRemoved, NamedKeyChanged, ChannelActivated, ChannelDeactivated, ChannelMoved, PortAdded, PortRemoved, PortNameChanged,

interface foo.org.jackaudio.MidiInputListener

This interface should be implemented by any object that is interested in querying the D-Bus bus for existing objects that implement the foo.org.jackaudio.MidiInput interface. It is not mandatory - the same information could be accessed by browsing every object of every D-Bus connection and check if they implement it - but using the signal defined in this interface is much more efficient.

Methods

Name In Out
method HereIAm
  • string  portname
  • objectpath  path
    This method is called by a D-Bus connection that has an object implementing the foo.org.jackaudio.MidiInput interface in response to a WhereAreYou signal emission. The portname argument is the name of the JACK MIDI port that the object represents, and the path argument is the path to the object that implements foo.org.jackaudio.MidiInput.

    Signals

    Name Out
    signal WhereAreYou
    • string  portname
    This signal should be emitted when the object wants to find out which objects on the bus implement the foo.org.jackaudio.MidiInput interface. All objects implementing foo.org.jackaudio.MidiInput are required to respond to this signal by calling HereIAm in the emitting object with their own path as argument if the argument portname is either equal to their portname or the empty string - thus the emitter can use WhereAreYou("") to receive information about all available objects that implement foo.org.jackaudio.MidiInput, or WhereAreYou("synth:input") to receive information about the object that represents the JACK MIDI port with the name "synth:input".

    interface foo.org.jackaudio.MidiInput

    This interface should be implemented by any object that represents a JACK MIDI input port. It provides methods for querying some properties of the MIDI device behind the port, and signals that are emitted when something changes in this device. An object that implements this interface may only represent one single JACK MIDI port - if the client provides multiple ports each will need their own D-Bus object. An object implementing this interface is required to listen for the signal WhereAreYou from the interface foo.org.jackaudio.MidiInputListener, and respond by calling HereIAm in the object emitting the signal if the signal argument portname matches the object's portname, or is the empty string.

    Methods

    Name In Out
    method GetPrograms
      • array of struct ( byte int16 byte string )  programs
      Returns an array of all available MIDI programs. Each array element is a struct with members for channel, bank number, program number and program name, in that order. The channel member should be set to the channel that the program is available on, or 16 if it is available on all channels.
      method GetCurrentProgram
      • byte  channel
      • int16  bank
      • byte  program
      Returns the current program for the given MIDI channel. If the channel does not have a program set, bank will be set to -1 and the caller should not care about the value of program. Otherwise, the valid range for bank is 0-16383 and for program 0-127.
      method GetControllers
        • array of struct ( byte byte int16 string )  controllers
        Returns an array of all available controllers. Each array element is a struct with members for channel, type (0 for CC, 1 for RPN, 2 for NRPN), number and name, in that order. The channel may be set to 16 if the controller is available on all active channels.
        method GetNamedKeys
          • array of struct ( byte byte string )  namedKeys
          Returns an array of all named keys. A named key is a string label for a MIDI key on a given channel (or on all channels). It could be used by a drum machine or a similar device. Each array element is a struct with members for channel, key and name (in that order). The channel may be set to 16 if the named key is available on all channels. There may only be one name for each key on each channel.
          method GetActiveChannels
            • uint32  channels
            Returns a 32 bit unsigned integer which should be seen as 32 separate bit flags. If bit 0 (the least significant) is set it means that MIDI channel 0 is active, if bit 1 is set channel 1 is active and so on up to bit 15. If the MIDI device is in omni mode, it should pick a fixed channel and return that as the only active channel (for example channel 0), and also set bit 16 to indicate that it is in omni mode. This way only sequencers that care about omni need to look at bit 16, and to all others it looks like there is only one channel that accepts MIDI input. The omni state may never change during the lifetime of this D-Bus object.

            Signals

            Name Out
            signal CurrentProgramChanged
            • byte  channel
            • int16  bank
            • byte  program
            • string  name
            This is emitted when the current program on a channel has changed.
            signal ProgramAdded
            • byte  channel
            • int16  bank
            • byte  program
            • string  name
            This is emitted when a new MIDI program has been made available. The channel parameter may be set to 16 if the program is available on all channels. If this signal is emitted with a channel/bank/program combination that already had a program associated with it, the receiver should assume that the old program has been removed.
            signal ProgramRemoved
            • byte  channel
            • int16  bank
            • byte  program
            This is emitted when a MIDI program has been removed. The channel argument must be the same as when it was added, it is not allowed to add a program with channel 16 (available on all channels) and then just remove it on one channel.
            signal ProgramChanged
            • byte  channel
            • int16  oldBank
            • byte  oldProgram
            • int16  newBank
            • byte  newProgram
            • string  newName
            This is emitted when a MIDI program has been renamed or remapped to a new bank and program number. The channel/oldBank/oldProgram combination must be the same as for an existing program.
            signal ControllerAdded
            • byte  channel
            • byte  type
            • int16  number
            • string  name
            This is emitted when a new controller has been added. The channel may be set to 16 if the controller is available on all active channels, and the type argument has the same values as in GetControllers. If this signal is emitted with a channel/type/number combination that already had a controller associated with it, the receiver should assume that the old controller has been removed.
            signal ControllerRemoved
            • byte  channel
            • byte  type
            • int16  number
            This is emitted when a controller is removed. The channel must be the same as it was in ControllerAdded and GetControllers, i.e. if it was presented as a global controller earlier (with channel 16) it must be removed with channel 16 - it is not allowed to only remove it for one channel.
            signal ControllerChanged
            • byte  channel
            • byte  oldType
            • int16  oldNumber
            • byte  newType
            • int16  newNumber
            • string  newName
            This is emitted when a controller has been renamed or remapped to a new type (0=CC, 1=RPN, 2=NRPN) and number. The channel/oldType/oldNumber combination must be the same as for an existing controller.
            signal NamedKeyAdded
            • byte  channel
            • byte  key
            • string  name
            This is emitted when a new named key has been added. The channel may be set to 16 if the named key is available on all active channels. If this signal is emitted with a channel/key combination that already had a name associated with it, the receiver should assume that the old name has been removed.
            signal NamedKeyRemoved
            • byte  channel
            • byte  key
            This is emitted when a named key is removed. The channel must be the same as it was in NamedKeyAdded and GetNamedKeys, i.e. if it was presented as a global named key earlier (with channel 16) it must be removed with channel 16 - it is not allowed to only remove it for one channel.
            signal NamedKeyChanged
            • byte  channel
            • byte  oldKey
            • byte  newKey
            • string  newName
            This is emitted when a named key has been renamed, or remapped to another key. The channel/oldKey combination must be the same as for an existing named key.
            signal ChannelActivated
            • byte  channel
            This is emitted when a channel has been activated, i.e. when it starts accepting MIDI events.
            signal ChannelDeactivated
            • byte  channel
            This is emitted when a channel has been deactivated, i.e. when it stops accepting MIDI events.
            signal ChannelMoved
            • byte  oldChannel
            • byte  newChannel
            This is emitted when the instrument responding to events on oldChannel has been changed to respond to events on newChannel instead. All existing programs, controllers and named keys available on oldChannel are assumed to move over to newChannel, and if there were any programs, controllers or named keys available on newChannel they are assumed to have been removed.
            signal PortAdded
            • string  portname
            An object implementing this interface is required to emit this signal when it has been created, to tell any other object on the bus that might be interested that there is a new port available. The portname argument is the name of the JACK MIDI port that this object represents.
            signal PortRemoved
              An object implementing this interface is required to emit this signal when it is about to be removed, to tell any other object on the bus that might be interested that the object is no longer available. As an exception, if the removal of the object happens at the same time as the D-Bus client that provides the object disconnects from the bus, this signal does not have to be emitted - any listening objects should infer that the object is removed when its connection is gone.
              signal PortNameChanged
              • string  newPortname
              This signal should be emitted when the JACK MIDI port changes name.