Package uk.co.xfactorylibrarians.coremidi4j

Class CoreMidiDeviceProvider

    • Constructor Detail

      • CoreMidiDeviceProvider

        public CoreMidiDeviceProvider()
                       throws CoreMidiException
        Class constructor
        Throws:
        CoreMidiException - if there is a problem initializing the provider

    • Method Detail

      • setScanInterval

        public static void setScanInterval​(int interval)
        Controls how often, in milliseconds, the MIDI environment should be examined for changes to report. This will have no effect on macOS, because changes are delivered by CoreMIDI as soon as they occur. It will also have no effect if there are currently no listeners registered via addNotificationListener(CoreMidiNotification). The default interval is 500, or half a second.
        Parameters:
        interval - how often to check the MIDI environment for changes in the list of available devices, in ms
        Throws:
        IllegalArgumentException - if interval is less than 10 or more than 60000 (one minute).

      • getScanInterval

        public static int getScanInterval()
        Check how often, in milliseconds, the MIDI environment should be examined for changes to report. This value is meaningless on macOS, because changes are delivered by CoreMIDI as soon as they occur. It is also irrelevant if there are currently no listeners registered via addNotificationListener(CoreMidiNotification). The default interval is 500, or half a second.
        Returns:
        how often the MIDI environment will be checked for changes on non-macOS systems, in ms

      • addNotificationListener

        public static void addNotificationListener​(CoreMidiNotification listener)
                                    throws CoreMidiException

        Adds a listener to be notified when the MIDI environment changes. If the current system is not running macOS, then ensure that our watcher daemon thread is running in order to be able to deliver these notifications, since we don't have CoreMIDI to initiate them.

        If you are using this capability on a non-macOS system, you must be sure to only call getMidiDeviceInfo() on this class, and never call MidiSystem.getMidiDeviceInfo() directly, because the latter is not thread-safe, and you can run into exceptions trying to get information about MIDI devices if your call happens to occur at the same time that our watcher daemon thread is gathering information. The version provided by this class uses synchronization to avoid such conflicts.

        Instances of CoreMidiDeviceProvider register themselves when they are constructed, so they can keep their lists of working CoreMIDI-backed devices up to date. We only keep the most recent one, since the Java MIDI subsystem will create many, and we only want to update the device map once when the MIDI environment changes. This self-registration will also not cause the daemon thread to be started because such updates are only needed on macOS.

        Parameters:
        listener - The CoreMidiNotification listener to add
        Throws:
        CoreMidiException - if there is a problem loading the shared library

      • removeNotificationListener

        public static void removeNotificationListener​(CoreMidiNotification listener)
                                       throws CoreMidiException
        Removes a listener that had been receiving notifications of MIDI environment changes. If there are none remaining (other than CoreMidiDeviceProvider itself) after this operation, arranges for the non-macOS daemon thread to stop running.
        Parameters:
        listener - The CoreMidiNotification listener to remove
        Throws:
        CoreMidiException - when there is a problem interacting with the native library

      • isLibraryLoaded

        public static boolean isLibraryLoaded()
                               throws CoreMidiException
        Check whether we have been able to load the native library.
        Returns:
        true if the library was loaded successfully, and we are operational, and false if the library was not available, so we are idle and not going to return any devices or post any notifications.
        Throws:
        CoreMidiException - if something unexpected happens trying to load the native library on a Mac OS X system.

      • getLibraryVersion

        public static String getLibraryVersion()
        Determine the version of the library which is being used.
        Returns:
        the implementation version of the library, as compiled into the JAR manifest.
        Since:
        0.9

      • getMidiDeviceInfo

        public static MidiDevice.Info[] getMidiDeviceInfo()

        Obtains an array of information objects representing the set of all working MIDI devices available on the system. This is a replacement for MidiSystem.getMidiDeviceInfo(), and only returns fully-functional MIDI devices. If you call it on a non-Mac system, it simply delegates to the javax.sound.midi implementation. On a Mac, it calls that function, but filters out the broken devices, returning only the replacement versions that CoreMidi4J provides. So by using this method rather than the standard one, you can give your users a menu of MIDI devices which are guaranteed to properly support MIDI System Exclusive messages.

        A returned information object can then be used to obtain the corresponding device object, by invoking MidiSystem.getMidiDevice(MidiDevice.Info).

        As mentioned in addNotificationListener(CoreMidiNotification), if you use that method, you must only ever call this version of getMidiDeviceInfo(), never MidiSystem.getMidiDeviceInfo(), due to thread-safety issues in the latter.

        Returns:
        an array of MidiDevice.Info objects, one for each installed and fully-functional MIDI device. If no such devices are installed, an array of length 0 is returned.