Module: Vissen::Input::Message

Included in:
Base, Unknown
Defined in:
lib/vissen/input/message.rb,
lib/vissen/input/message/base.rb,
lib/vissen/input/message/note.rb,
lib/vissen/input/message/unknown.rb,
lib/vissen/input/message/aftertouch.rb,
lib/vissen/input/message/channel_mode.rb,
lib/vissen/input/message/control_change.rb,
lib/vissen/input/message/program_change.rb,
lib/vissen/input/message/channel_pressure.rb,
lib/vissen/input/message/pitch_bend_change.rb

Overview

This module implements the minimal interface for an input message. All message classes must include this module to be compatible with the input matching engine.

All Vissen Input Messages must be representable by one to three bytes. This stems from the tight connection with the MIDI protocol. Each message must also store a timestamp from when the input arrived to the system.

The individual message implementations are based off the information given on the midi association website.

Terminology

The first (and mandatory) byte of the data byte array is referred to as the message status. Since this byte also include channel information the term status is, howerver, sometimes also used to name only the upper nibble of the status field.

Defined Under Namespace

Classes: Aftertouch, Base, ChannelMode, ChannelPressure, ControlChange, Note, PitchBendChange, ProgramChange, Unknown

Constant Summary collapse

STATUS_MASK =

The status mask determines which bits of the first byte belong to the status code.

0xF0
CHANNEL_MASK =

The channel mask determines which bits of the first byte belong to the channel value.

0x0F
DATA_LENGTH =

Data length specifies what number of bytes must be present in the raw message for it to be valid.

1

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#data ⇒ Array<Integer> (readonly) Also known as: to_a

Returns the raw message data.

Returns:

  • (Array<Integer>) —

    the raw message data.



38
39
40
 
# File 'lib/vissen/input/message.rb', line 38

def data
  @data
end

#timestamp ⇒ Float (readonly)

Returns the time of arrival for the message.

Returns:

  • (Float) —

    the time of arrival for the message.



41
42
43
 
# File 'lib/vissen/input/message.rb', line 41

def timestamp
  @timestamp
end

Instance Method Details

#channel ⇒ Integer

Returns the message channel.

Returns:

  • (Integer) —

    the message channel.



95
96
97
 
# File 'lib/vissen/input/message.rb', line 95

def channel
  @data[0] & self.class::CHANNEL_MASK
end

#fetch(key) ⇒ Array<Integer>, Float

Allows every message instance to pass for a Hash object on the same form returned by #to_h.

Parameters:

  • key (Symbol) —

    the field to fetch (either :data or :timestamp).

Returns:

  • (Array<Integer>) —

    when key is :data.

  • (Float) —

    when key is :timestamp.

Raises:

  • (KeyError) —

    unless the given key is :data or :timestamp.



81
82
83
84
85
86
87
 
# File 'lib/vissen/input/message.rb', line 81

def fetch(key)
  case key
  when :data then @data
  when :timestamp then @timestamp
  else raise KeyError
  end
end

#initialize(data, timestamp) ⇒ Object

Parameters:

  • data (Array<Integer>) —

    the raw message data.

  • timestamp (Float) —

    the time that the message was received.

Raises:

  • (TypeError) 


48
49
50
51
52
53
 
# File 'lib/vissen/input/message.rb', line 48

def initialize(data, timestamp)
  raise TypeError unless data.length >= self.class::DATA_LENGTH

  @data      = data.freeze
  @timestamp = timestamp.freeze
end

#status ⇒ Integer

Returns the message status.

Returns:

  • (Integer) —

    the message status.



90
91
92
 
# File 'lib/vissen/input/message.rb', line 90

def status
  @data[0] & self.class::STATUS_MASK
end

#to_h ⇒ Hash

Converts the message back into a raw hash representation. The format is intentionally similar to the output of the Unimidi gem.

Returns:

  • (Hash) —

    a hash containing both the message data and the timestamp marking when it arrived.



68
69
70
 
# File 'lib/vissen/input/message.rb', line 68

def to_h
  { data: @data, timestamp: @timestamp }.freeze
end

#valid? ⇒ true

The default for messages is to always be valid. Message implementations can override this behaviour.

Returns:

  • (true) 


59
60
61
 
# File 'lib/vissen/input/message.rb', line 59

def valid?
  true
end