| SysEx Librarian Documentation |
Basics SysEx Librarian is a utility for Mac OS X which lets you communicate with MIDI devices using System Exclusive messages, also known as SysEx. The most common use is to backup patch data from synthesizers, although there are others (such as sending firmware updates). SysEx Librarian makes it easy to keep a library of the SysEx files you use most often, and to record new SysEx files. SysEx Librarian is free to download and use. The source code is available as Open Source (under the BSD license). The SysEx Librarian web page can be found at this URL: http://www.snoize.com/SysExLibrarian/ Please check there for news and updates. Quick Start To save data from your MIDI device: Run SysEx Librarian Press the "Record Many..." button Tell your device to send sysex, by pressing buttons on it. (Every MIDI device is different; check the manual!) When the transmission is done, press the "Done" button in SysEx Librarian. To send data to your MIDI device: Press the "Add..." button in the lower-left corner of the window, and choose the .syx file you want to transfer. This will add it to the list of files that SysEx Librarian knows about. You can also drag the file directly into the list from the Finder. In SysEx Librarian's toolbar, there's a pop-up menu named "Destination". Click it and choose the MIDI port that you want to send to. (It's probably named something like "Port 1" or "Port A"—it depends on your MIDI interface. "Act as a source for other programs" is NOT what you want.) Click the file in the list to select it Press the "Play" button In More Detail SysEx Librarian is based around the idea of a library of files. Each file contains one or more SysEx messages. If you are familiar with iTunes, you will find that SysEx Librarian works much the same way. The main part of the window contains the list of files in the library. The columns are as follows: SysEx File: The name of the file Manufacturer: The manufacturer of the device that this SysEx data is for. # Msgs: The number of individual SysEx messages in the file. Size: The size of all of the SysEx data in the file. To add files to the library, use the Add... button to open the standard Mac open dialog. You may also drag files or folders from the Finder into the list of files, or onto the SysEx Librarian icon in the dock. SysEx Librarian understands raw SysEx files (which often have the .syx extension) and can also read SysEx messages from standard MIDI files (which usually have the extension .mid). You can change a file's name by double-clicking its name, or by selecting it and choosing "Change Name" from the menu. Use the Delete button or the Delete key on your keyboard to delete a file from the library. To see the actual file on your disk, choose it and press the Show File button (or use the Show SysEx File menu command); the Finder will select the file and show it to you. To send SysEx to a device, select a file by clicking on it. (Shift-click or command-click to select more than one file.) Then press the Play button, and the SysEx messages in the selected files will be sent to the selected destination. A progress indicator will show the number of messages and amount of data sent. (If you choose the destination named "Act as a source for other programs", other MIDI programs running on the computer will see an input source named "SysEx Librarian". You can then play SysEx messages to those programs. Sending will happen instantaneously, so no progress indicator will be shown.) To record a new file, press the Record One or Record Many button. Record One records just one SysEx message, and then automatically stops recording. Record Many will keep recording messages until you tell it to stop. SysEx Librarian listens to all input ports on all MIDI interfaces connected to your computer, so you don't need to select any one in particular. Recorded files are stored in your SysEx folder. By default, this is a folder named "SysEx Librarian", in the Documents folder in your home folder. However, you may change this location in the preferences. Note that you may also move files around on your disk; SysEx Librarian will try to find them even if they have moved. If a file can't be found, SysEx Librarian will ask you to locate it. SysEx File Contents To see the contents of a SysEx file, select it and press the Contents button, or use the Show Contents menu command. This will open a new window showing a list of messages in the file. Click on a message to see its data in hexadecimal and ASCII formats. Preferences The preferences window lets you change the way that SysEx Librarian works. Changes in this window take effect immediately, and are automatically saved. SysEx Folder Location: The location where newly recorded SysEx files are stored, by default. To change this, press the Change button and choose a different folder. Show file size as Abbreviated / Full: Switches the file size shown in the main window between an abbreviated format (like "1.2 KB") and the full number of bytes (like "1234"). Pause between played messages: The amount of time that SysEx Librarian pauses between each SysEx message that it plays. Some devices need some time to process a message before they can accept another one. The default (150 milliseconds) should be enough for most devices. Many devices don't need any delay at all; try turning the pause down to 0 to make playback as quick as possible. SysEx receive timeout: If a SysEx message does not end normally, SysEx Librarian will wait this amount of time before deciding that the message is finished. The default (1 second) should be fine for just about everyone. Transmit Speed: Most MIDI devices can handle sysex messages sent at full speed, but a few older ones have problems keeping up. If your device doesn't work, try turning down the transmit speed a little bit. Note that you can change the speed on an individual device, if you've set it up in Audio MIDI Setup. This is the recommended way to do it (instead of setting the speed on the whole output port), because SysEx Librarian will use the appropriate speed even if you change which port the device is hooked up to. Troubleshooting Please note two things: SysEx Librarian is absolutely dependent on the MIDI interface's driver MIDI drivers can and do have bugs, especially when dealing with SysEx messages If you're having problems, your first step should be to get the latest version of the driver for your MIDI interface. Almost all manufacturers have web sites where the drivers can be downloaded -- please check with the manufacturer of your particular device. You must have a Mac OS X driver for your MIDI interface; Mac OS 9 drivers will not work. Because MIDI is a very old and primitive communications protocol, it doesn't have the kind of error checking that we take for granted in more modern systems. When SysEx Librarian records a message coming from your device, it has almost no way of checking that it received the message correctly. The message could have been corrupted while in transit -- either by the MIDI hardware or by the software in the driver -- but SysEx Librarian cannot tell the difference between a correct message and a bogus one. Similarly, when SysEx Librarian sends a message to a MIDI device, it cannot tell whether the message was successfully received. As a result, many apparent "bugs" in SysEx Librarian really turn out to be bugs in the MIDI driver. I can send SysEx to my device, but it doesn't recognize the message. Why? In order to trace this problem, we need to know a few things: Is a full-speed sysex transmission too fast for your device? Some devices, especially older ones (1980s and early 1990s), cannot deal with sysex that is transmitted at full speed. Unfortunately there's no real way to find out if this is the case, other than experimenting. You can use the Transmit Speed controls in the Preferences to turn down the speed. Is the SysEx message correct? (not corrupted somehow -- e.g. missing bytes, containing extra bytes, etc.) Where did your SysEx file originally come from? If you downloaded it from the Internet, chances are that it is good (although that's not a certainty). If you recorded it using SysEx Librarian, it may have been corrupted on the way in. If you can, try to find a file that you know is correct. Is your MIDI interface is correctly sending the data that SysEx Librarian tells it to? Here's a way to see if SysEx Librarian is sending the right data, and to see if the MIDI interface is sending what SysEx Librarian tells it to send. Run my program MIDI Monitor. Make sure it's listening to MIDI input. Press a button or turn a knob on your MIDI device--anything that would send a MIDI message. The message should appear in MIDI Monitor. Hook up a MIDI cable from the output of your MIDI interface, directly back to an input on the same MIDI interface. In the MIDI Monitor window, in the Sources section, open the "Spy on output to destinations" section and check the box for your MIDI interface. Run SysEx Librarian, and have it send to your MIDI interface. You should see two sysex messages in the MIDI Monitor window, one labeled "To your MIDI interface" and one labeled "From your MIDI interface". They should have the same length and the same contents, and they should be the same as the message that appears in SysEx Librarian. If the "To your MIDI interface" message is different from the one in SysEx Librarian, then SysEx Librarian is doing the wrong thing. I don't think this will happen, but if it does, please let me know. If the "From your MIDI interface" message is different from the "To your MIDI interface" message, then the driver either didn't send the same thing that SysEx Librarian told it to, or it couldn't receive the same message back again without corrupting it. Either way, it's a bug in the driver. Having other problems? Please let me know and I'll try to help find a solution. Contact Please send questions or comments to: SysExLibrarian@snoize.com If you find this program useful, I'd love to hear about it! And if you encounter bugs or have suggestions for improvement, please let me know. Acknowledgements SysExLibrarian is copyright © 2002-2012 by Kurt Revis. All rights reserved. It is released under the BSD license (details). The source code is available at https://github.com/krevis/MIDIApps. SysEx Librarian uses: BDAlias, from bDistributed.com, Inc. (copyright and license) CocoaCrypoHashing, from Denis Defreyne (copyright and license) Also: Thanks to the folks on the CoreAudio-API mailing list for all the help they have provided, and to everyone who has sent in bug reports and feature requests. Also thanks to Steve Grace for his original SysEx utility for the Classic Mac OS.