module Vissen::Input::Message

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](www.midi.org/specifications/item/table-1-summary-of-midi-message).

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.

Constants

CHANNEL_MASK

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

DATA_LENGTH

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

STATUS_MASK

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

Attributes

data[R]

@return [Array<Integer>] the raw message data.

timestamp[R]

@return [Float] the time of arrival for the message.

to_a[R]

@return [Array<Integer>] the raw message data.

Public Class Methods

new(data, timestamp) click to toggle source

@param data [Array<Integer>] the raw message data. @param timestamp [Float] the time that the message was received.

# 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

Public Instance Methods

channel() click to toggle source

@return [Integer] the message channel.

# File lib/vissen/input/message.rb, line 95
def channel
  @data[0] & self.class::CHANNEL_MASK
end
fetch(key) click to toggle source

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

@raise [KeyError] unless the given key is `:data` or `:timestamp`.

@param key [Symbol] the field to fetch (either `:data` or

`:timestamp`).

@return [Array<Integer>] when key is `:data`. @return [Float] when key is `:timestamp`.

# 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
status() click to toggle source

@return [Integer] the message status.

# File lib/vissen/input/message.rb, line 90
def status
  @data[0] & self.class::STATUS_MASK
end
to_h() click to toggle source

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

@return [Hash] a hash containing both the message data and the timestamp

marking when it arrived.
# File lib/vissen/input/message.rb, line 68
def to_h
  { data: @data, timestamp: @timestamp }.freeze
end
valid?() click to toggle source

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

@return [true]

# File lib/vissen/input/message.rb, line 59
def valid?
  true
end