MidiPlayer (SoundHelix 0.10u API)

java.lang.Object
- com.soundhelix.component.player.impl.AbstractPlayer
- - com.soundhelix.component.player.impl.MidiPlayer

All Implemented Interfaces:

Component, Player, RandomSeedable, XMLConfigurable
```
public class MidiPlayer
extends AbstractPlayer
```
Implements a MIDI player, which can distribute instrument playback to an arbitrary number of MIDI devices in parallel. Each instrument used must be mapped to a combination of MIDI device and MIDI channel. For each channel the MIDI program to use can be defined individually. If no program is specified for a channel, the program is not modified, i.e., the currently selected program is used. All specified MIDI devices are opened for playback, even if they are not used by any instrument. If clock synchronization is enabled for at least one device, the devices are synchronized to the player by sending out TIMING_CLOCK MIDI events to each synchronized device 24 times per beat. For the synchronization to work, each device will be sent a START event before playing and a STOP event after playing. MIDI synchronization works independent of the selected groove. Timing ticks are sent out using a fixed frequency according to the BPM, even though sending out note MIDI messages can vary depending on the selected groove. Clock synchronization should be used for devices using synchronized effects (for example, synchronized echo) in order to communicate the BPM speed to use. As clock synchronization requires some additional overhead, e.g., sending out MIDI messages 24 times per beat instead of the number of ticks per beat, it should only be used if really required. Timing the ticks (or clock synchronization ticks) is done by using a feedback algorithm based on Thread.sleep() calls with nanosecond resolution. As mentioned, sending out timing ticks is not groove-dependent, whereas sending out note MIDI messages is groove-dependent. This player supports LFOs, whose frequency can be based on a second, a beat, the whole song or on the activity (first activity until last activity) of an instrument. The granularity of an LFO is always a tick. With every tick, each LFO will send out a MIDI message with the new value for the target controller, but only if the LFO value is the first one sent or if it has changed since the last value sent.

Author:

Thomas Schuerger (thomas@schuerger.com)

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class MidiPlayer.DeviceChannel
Container for the combination of device, channel and preselected program.

Nested Classes
Modifier and Type	Class and Description
`static class`	`MidiPlayer.DeviceChannel` Container for the combination of device, channel and preselected program.

Field Summary

Fields
Modifier and Type Field and Description

protected Logger logger
The logger.
- Fields inherited from class com.soundhelix.component.player.impl.AbstractPlayer
  randomSeed

Fields
Modifier and Type	Field and Description
`protected Logger`	`logger` The logger.

Constructor Summary

Constructors
Constructor and Description

MidiPlayer()

Constructors
Constructor and Description
`MidiPlayer()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`abortPlay()` Aborts play().
`void`	`configure(SongContext songContext, Node node)` Configures the instance using the specified XML node.
`int`	`getCurrentTick()` Returns the current tick of the player.
`int`	`getMilliBPM()` Gets the number of beats per minute for playback.
`void`	`muteAllChannels()` Mutes all channels of all devices.
`void`	`play(SongContext songContext)` Plays the arrangement from the song context.
`void`	`setAfterPlayWaitTicks(int postWaitTicks)`
`void`	`setBeforePlayWaitTicks(int preWaitTicks)`
`void`	`setChannelMap(Map<String,MidiPlayer.DeviceChannel> channelMap)` Sets the channel map, which maps instruments to MIDI devices and channels.
`void`	`setControllerLFOs(com.soundhelix.component.player.impl.MidiPlayer.ControllerLFO[] controllerLFOs)`
`void`	`setControllerValues(com.soundhelix.component.player.impl.MidiPlayer.ControllerValue[] controllerValues)`
`void`	`setGroove(String grooveString)` Sets the groove for playback.
`void`	`setInstrumentControllerLFOs(com.soundhelix.component.player.impl.MidiPlayer.InstrumentControllerLFO[] instrumentControllerLFOs)`
`void`	`setMaxWindowSize(int maxWindowSize)`
`void`	`setMidiFilename(String midiFilename)`
`void`	`setMilliBPM(int milliBPM)` Sets the number of beats per minute for playback.
`void`	`setMinWindowSize(int minWindowSize)`
`void`	`setTransposition(int transposition)` Sets the transposition.
`void`	`setWaitForStart(boolean waitForStart)`
`boolean`	`skipToTick(int tick)` Skips to the specified tick.

Methods inherited from class com.soundhelix.component.player.impl.AbstractPlayer
getRandomSeed, setRandomSeed

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - logger
```
protected final Logger logger
```
    The logger.
- Constructor Detail
  - MidiPlayer
```
public MidiPlayer()
```
- Method Detail
  - getMilliBPM
```
public int getMilliBPM()
```
    Gets the number of beats per minute for playback.
    
    Returns:
    the number of millibeats per minute
  - setMilliBPM
```
public void setMilliBPM(int milliBPM)
```
    Sets the number of beats per minute for playback.
    
    Parameters:
    milliBPM - the number of millibeats per minute
  - setTransposition
```
public void setTransposition(int transposition)
```
    Sets the transposition.
    
    Parameters:
    transposition - the transposition pitch
  - setGroove
```
public final void setGroove(String grooveString)
```
    Sets the groove for playback. A groove is a comma-separated list of integers acting as relative weights for tick lengths. The player cycles through this list while playing and uses the list for timing ticks. For example, the string "5,3" results in a ratio of 5:3, namely 5/8 of the total tick length on every even tick and 3/8 of the tick length for every odd tick. If even and odd ticks originally had a length of 100 ms each, then they would be 125 ms and 75 ms, respectively. The default groove (i.e., no groove) is "1", resulting in equally timed ticks. Note that even though the groove is handled correctly by the player, it might not be handled as expected on the MIDI device used for playback. For example, if some time-synchronized echo is used on the MIDI device, it might sound strange if grooved input is used for a non-grooved echo.
    
    Parameters:
    grooveString - the groove string
  - setChannelMap
```
public void setChannelMap(Map<String,MidiPlayer.DeviceChannel> channelMap)
```
    Sets the channel map, which maps instruments to MIDI devices and channels. All used instruments must be mapped.
    
    Parameters:
    channelMap - the channel map
  - play
```
public void play(SongContext songContext)
```
    Description copied from interface: Player
    
    Plays the arrangement from the song context. The method will return as soon as playing has finished. This method will block until the song is finished or playback has been aborted successfully via abortPlay(). Only one thread can run play() at a time.
    
    Parameters:
    songContext - the song context
  - muteAllChannels
```
public final void muteAllChannels()
                           throws InvalidMidiDataException
```
    Mutes all channels of all devices. This is done by sending an ALL SOUND OFF message to all channels. In addition to that (because this does not include sending NOTE OFF) a NOTE_OFF is sent for each of the 128 possible pitches to each channel.
    
    Throws:
    
    InvalidMidiDataException - in case of invalid MIDI data
  - setControllerLFOs
```
public final void setControllerLFOs(com.soundhelix.component.player.impl.MidiPlayer.ControllerLFO[] controllerLFOs)
```
  - setInstrumentControllerLFOs
```
public final void setInstrumentControllerLFOs(com.soundhelix.component.player.impl.MidiPlayer.InstrumentControllerLFO[] instrumentControllerLFOs)
```
  - configure
```
public final void configure(SongContext songContext,
             Node node)
                     throws XPathException
```
    Description copied from interface: XMLConfigurable
    
    Configures the instance using the specified XML node. The method should read all supported configuration tags and should call the corresponding setter methods of the class. All settings of the class that are settable using XML should also be settable by using public methods (for example, if the beats per minute are settable using an XML tag, then the class should also provide a public method setBPM(), which does the same). XML configuration can also be a recursive process, if XML settings contain nodes that require XML configuration themselves, but this is up to the implementation of this method. The method should (but need not) use XPath to access the node's tags. Only the node and its descendant nodes may be used for configuration.
    
    Parameters:
    songContext - the song context
    node - the parent XML node of the configuration tags
    
    Throws:
    
    XPathException - in case of an XPath problem
  - skipToTick
```
public boolean skipToTick(int tick)
```
    Skips to the specified tick. This is done by muting all channels, resetting the player state and then silently fast-forwarding to the specified tick.
    
    Parameters:
    tick - the tick
    
    Returns:
    true if skipping was successful, false otherwise
  - abortPlay
```
public void abortPlay()
```
    Description copied from interface: Player
    
    Aborts play(). When this message returns, the playback should already have stopped and all resources should have been released. If the player isn't playing, nothing is done.
  - setBeforePlayWaitTicks
```
public void setBeforePlayWaitTicks(int preWaitTicks)
```
  - setAfterPlayWaitTicks
```
public void setAfterPlayWaitTicks(int postWaitTicks)
```
  - getCurrentTick
```
public int getCurrentTick()
```
    Description copied from interface: Player
    
    Returns the current tick of the player. If the player is not yet playing, if it is in the warm-up phase or in the cool-down phase or playing has finished, -1 will be returned.
    
    Returns:
    the current tick (or -1)
  - setMidiFilename
```
public void setMidiFilename(String midiFilename)
```
  - setControllerValues
```
public final void setControllerValues(com.soundhelix.component.player.impl.MidiPlayer.ControllerValue[] controllerValues)
```
  - setMinWindowSize
```
public void setMinWindowSize(int minWindowSize)
```
  - setMaxWindowSize
```
public void setMaxWindowSize(int maxWindowSize)
```
  - setWaitForStart
```
public void setWaitForStart(boolean waitForStart)
```

Class MidiPlayer

Nested Class Summary

Field Summary

Fields inherited from class com.soundhelix.component.player.impl.AbstractPlayer

Constructor Summary

Method Summary

Methods inherited from class com.soundhelix.component.player.impl.AbstractPlayer

Methods inherited from class java.lang.Object

Field Detail

logger

Constructor Detail

MidiPlayer

Method Detail

getMilliBPM

setMilliBPM

setTransposition

setGroove

setChannelMap

play

muteAllChannels

setControllerLFOs

setInstrumentControllerLFOs

configure

skipToTick

abortPlay

setBeforePlayWaitTicks

setAfterPlayWaitTicks

getCurrentTick

setMidiFilename

setControllerValues

setMinWindowSize

setMaxWindowSize

setWaitForStart