# Chapter 15: Providing MIDI Services

Chapter 13, "Introduction to the Service Provider Interfaces," explained that the `javax.sound.sampled.spi` and`javax.sound.midi.spi` packages define abstract classes to be used by developers of sound services. By implementing a subclass of one of these abstract classes, a service provider can create a new service that extends the functionality of the runtime system. Chapter 14 covered the use of the `javax.sound.sampled.spi` package. The present chapter discusses how to use the `javax.sound.midi.spi` package to provide new services for handling MIDI devices and files.

Applications programmers who only use existing MIDI services in their programs can safely skip this chapter. For an overview of MIDI and the use of the installed MIDI services in an application program, see Part II, "MIDI," of this Programmer's Guide. This chapter assumes that the reader is familiar with the JavaTM Sound API methods that application programs invoke to access installed MIDI services.

### Introduction

There are four abstract classes in the `javax.sound.midi.spi` package, which represent four different types of services that you can provide for the MIDI system:

- `MidiFileWriter` provides MIDI file-writing services. These services make it possible for an application program to save, to a MIDI file, a MIDI `Sequence` that it has generated or processed.
- `MidiFileReader` provides file-reading services that return a MIDI `Sequence` from a MIDI file for use in an application program.
- `MidiDeviceProvider` supplies instances of one or more specific types of MIDI device, possibly including hardware devices.
- `SoundbankReader` supplies soundbank file-reading services. Concrete subclasses of `SoundbankReader` parse a given soundbank file, producing a `Soundbank` object that can be loaded into a `Synthesizer`.

An application program will not directly create an instance of a service object—whether a provider object, such as a `MidiDeviceProvider`, or an object, such as a `Synthesizer`, that is supplied by the provider object. Nor will the program directly refer to the SPI classes. Instead, the application program makes requests to the `MidiSystem` object in the`javax.sound.midi` package, and `MidiSystem` in turn uses concrete subclasses of the `javax.sound.midi.spi` classes to process these requests.

### Providing MIDI File-Writing Services

There are three standard MIDI file formats, all of which an implementation of the Java Sound API can support: Type 0, Type 1, and Type 2. These file formats differ in their internal representation of the MIDI sequence data in the file, and are appropriate for different kinds of sequences. If an implementation doesn't itself support all three types, a service provider can supply the support for the unimplemented ones. There are also variants of the standard MIDI file formats, some of them proprietary, which similarly could be supported by a third-party vendor.

The ability to write MIDI files is provided by concrete subclasses of `MidiFileWriter`. This abstract class is directly analogous to `javax.sampled.spi.AudioFileWriter`. Again, the methods are grouped into query methods for learning what types of files can be written, and methods for actually writing a file. As with `AudioFileWriter`, two of the query methods are concrete:

>     boolean isFileTypeSupported(int fileType)
>     boolean isFileTypeSupported(int fileType, Sequence sequence)

The first of these provides general information about whether the file writer can ever write the specified type of MIDI file type. The second method is more specific: it asks whether a particular Sequence can be written to the specified type of MIDI file. Generally, you don't need to override either of these two concrete methods. In the default implementation, each invokes one of two other corresponding query methods and iterates over the results returned. Being abstract, these other two query methods need to be implemented in the subclass:

>     abstract int[] getMidiFileTypes()
>     abstract int[] getMidiFileTypes(Sequence sequence)

The first of these returns an array of all the file types that are supported in general. A typical implementation might initialize the array in the file writer's constructor and return the array from this method. From that set of file types, the second method finds the subset to which the file writer can write the given Sequence. In accordance with the MIDI specification, not all types of sequences can be written to all types of MIDI files.

The `write` methods of a `MidiFileWriter` subclass perform the encoding of the data in a given `Sequence` into the correct data format for the requested type of MIDI file, writing the coded stream to either a file or an output stream:

>     abstract int write(Sequence in, int fileType,
>                        java.io.File out)
>     abstract int write(Sequence in, int fileType,
>                        java.io.OutputStream out)

To do this, the `write` method must parse the `Sequence` by iterating over its tracks, construct an appropriate file header, and write the header and tracks to the output. The MIDI file's header format is, of course, defined by the MIDI specification. It includes such information as a "magic number" identifying this as a MIDI file, the header's length, the number of tracks, and the sequence's timing information (division type and resolution). The rest of the MIDI file consists of the track data, in the format defined by the MIDI specification.

Let's briefly look at how the application program, MIDI system, and service provider cooperate in writing a MIDI file. In a typical situation, an application program has a particular MIDI `Sequence` to save to a file. The program queries the `MidiSystem` object to see what MIDI file formats, if any, are supported for the particular `Sequence` at hand, before attempting to write the file. The `MidiSystem.getMidiFileTypes(Sequence)` method returns an array of all the MIDI file types to which the system can write a particular sequence. It does this by invoking the corresponding `getMidiFileTypes` method for each of the installed `MidiFileWriter` services, and collecting and returning the results in an array of integers that can be thought of as a master list of all file types compatible with the given `Sequence`. When it comes to writing the `Sequence` to a file, the call to `MidiSystem.write` is passed an integer representing a file type, along with the `Sequence` to be written and the output file; `MidiSystem` uses the supplied type to decide which installed `MidiFileWriter` should handle the write request, and dispatches a corresponding `write` to the appropriate `MidiFileWriter`.

### Providing MIDI File-Reading Services

The `MidiFileReader` abstract class is directly analogous to `javax.sampled.spi.AudioFileReader` class. Both consist of two overloaded methods, each of which can take a `File`, `URL`, or `InputStream` argument. The first of the overloaded methods returns the file format of a specified file. In the case of `MidiFileReader`, the API is:

>     abstract MidiFileFormat getMidiFileFormat(java.io.File file)
>     abstract MidiFileFormat getMidiFileFormat(
>         java.io.InputStream stream)
>     abstract MidiFileFormat getMidiFileFormat(java.net.URL url)

Concrete subclasses must implement these methods to return a filled-out `MidiFileFormat` object describing the format of the specified MIDI file (or stream or URL), assuming that the file is of a type supported by the file reader and that it contains valid header information. Otherwise, an `InvalidMidiDataException` should be thrown.

The other overloaded method returns a MIDI `Sequence` from a given file, stream, or URL :

>     abstract Sequence getSequence(java.io.File file)
>     abstract Sequence getSequence(java.io.InputStream stream)
>     abstract Sequence getSequence(java.net.URL url)

The `getSequence` method performs the actual work of parsing the bytes in the MIDI input file and constructing a corresponding `Sequence` object. This is essentially the inverse of the process used by `MidiFileWriter.write`. Because there is a one-to-one correspondence between the contents of a MIDI file as defined by the MIDI specification and a `Sequence` object as defined by the Java Sound API, the details of the parsing are straightforward. If the file passed to `getSequence` contains data that the file reader can't parse (for example, because the file has been corrupted or doesn't conform to the MIDI specification), an `InvalidMidiDataException` should be thrown.

### Providing Particular MIDI Devices

A `MidiDeviceProvider` can be considered a factory that supplies one or more particular types of MIDI device. The class consists of a method that returns an instance of a MIDI device, as well as query methods to learn what kinds of devices this provider can supply.

As with the other `javax.sound.midi.spi` services, application developers get indirect access to a `MidiDeviceProvider` service through a call to `MidiSystem` methods, in this case `MidiSystem.getMidiDevice` and `MidiSystem.getMidiDeviceInfo`. The purpose of subclassing `MidiDeviceProvider` is to supply a new kind of device, so the service developer must also create an accompanying class for the device being returned—just as we saw with `MixerProvider` in the `javax.sound.sampled.spi` package. There, the returned device's class implemented the `javax.sound.sampled.Mixer` interface; here it implements the `javax.sound.midi.MidiDevice` interface. It might also implement a subinterface of `MidiDevice`, such as `Synthesizer` or `Sequencer`.

Because a single subclass of `MidiDeviceProvider` can provide more than one type of `MidiDevice`, the `getDeviceInfo` method of the class returns an array of `MidiDevice.Info` objects enumerating the different `MidiDevices` available:

>     abstract MidiDevice.Info[] getDeviceInfo()

The returned array can contain a single element, of course. A typical implementation of the provider might initialize an array in its constructor and return it here. This allows `MidiSystem` to iterate over all installed `MidiDeviceProviders` to construct a list of all installed devices. `MidiSystem` can then return this list (`MidiDevice.Info[]` array) to an application program.

`MidiDeviceProvider` also includes a concrete query method:

>     boolean isDeviceSupported(MidiDevice.Info info)

This method permits the system to query the provider about a specific kind of device. Generally, you don't need to override this convenience method. The default implementation iterates over the array returned by getDeviceInfo and compares the argument to each element.

The third and final `MidiDeviceProvider` method returns the requested device:

>     abstract MidiDevice getDevice(MidiDevice.Info info)

This method should first test the argument to make sure it describes a device that this provider can supply. If it doesn't, it should throw an `IllegalArgumentException`. Otherwise, it returns the device.

### Providing Soundbank File-Reading Services

A `SoundBank` is a set of `Instruments` that can be loaded into a `Synthesizer`. An `Instrument` is an implementation of a sound-synthesis algorithm that produces a particular sort of sound, and includes accompanying name and information strings. A `SoundBank` roughly corresponds to a bank in the MIDI specification, but it's a more extensive and addressable collection; it can perhaps better be thought of as a collection of MIDI banks. (For more background information on `SoundBanks` and `Synthesizers`, see Chapter 12, "Synthesizing Sound.")

`SoundbankReader` consists of a single overloaded method, which the system invokes to read a `Soundbank` object from a soundbank file:

>     abstract Soundbank getSoundbank(java.io.File file)
>     abstract Soundbank getSoundbank(java.io.InputStream stream)
>     abstract Soundbank getSoundbank(java.net.URL url)

Concrete subclasses of `SoundbankReader` will work in tandem with particular provider-defined implementations of `SoundBank`, `Instrument`, and `Synthesizer` to allow the system to load a `SoundBank` from a file into an instance of a particular `Synthesizer` class. Synthesis techniques may differ wildly from one `Synthesizer` to another, and, as a consequence, the data stored in an `Instrument` or `SoundBank` providing control or specification data for the synthesis process of a `Synthesizer` can take a variety of forms. One synthesis technique may require only a few bytes of parameter data; another may be based on extensive sound samples. The resources present in a `SoundBank` will depend upon the nature of the `Synthesizer` into which they get loaded, and therefore the implementation of the `getSoundbank` method of a `SoundbankReader` subclass has access to knowledge of a particular kind of `SoundBank`. In addition, a particular subclass of `SoundbankReader` understands a particular file format for storing the `SoundBank` data. That file format may be vendor-specific and proprietary.

`SoundBank` is just an interface, with only weak constraints on the contents of a `SoundBank` object. The methods an object must support to implement this interface (`getResources`, `getInstruments`, `getVendor`, `getName`, etc.) impose loose requirements on the data that the object contains. For example, `getResources` and `getInstruments` can return empty arrays. The actual contents of a subclassed `SoundBank` object, in particular its instruments and its non-instrument resources, are defined by the service provider. Thus, the mechanism of parsing a soundbank file depends entirely on the specification of that particular kind of soundbank file.

Soundbank files are created outside the Java Sound API, typically by the vendor of the synthesizer that can load that kind of soundbank. Some vendors might supply end-user tools for creating such files.