Class: MIDICommunicationsWindows::Output

Inherits:
Object
  • Object
show all
Extended by:
Device::ClassMethods
Includes:
Device::InstanceMethods
Defined in:
lib/midi-communications-windows/output.rb

Overview

A MIDI output port: somewhere to send messages.

Examples:

Send a note through the first output

output = MIDICommunicationsWindows::Output.first
output.open
output.puts(0x90, 60, 100)   # Note On, middle C
sleep 0.5
output.puts(0x80, 60, 0)     # Note Off

Send the same thing as a hex string

output.puts_s('903C64')

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#enabled ⇒ Object (readonly) Also known as: enabled? Originally defined in module Device::InstanceMethods

#id ⇒ Integer (readonly) Originally defined in module Device::InstanceMethods

Returns the port's WinMM index within its direction; see the note on identity in MIDICommunicationsWindows::Device.

Returns:

#name ⇒ String (readonly) Originally defined in module Device::InstanceMethods

Returns the port's name, as WinMM reports it, truncated to 31 characters. Not unique: see the note on names in MIDICommunicationsWindows::Device.

Returns:

Class Method Details

.all ⇒ Array<Input>, Array<Output> Originally defined in module Device::ClassMethods

Every port of this direction.

WinMM is asked afresh on every call, so a port that appeared or went away since the last one is reflected. A port that is still there comes back as the same object as before; see MIDICommunicationsWindows::Device.enumerate.

Returns:

.direction ⇒ Symbol

Returns :output.

Returns:

  • (Symbol) —

    :output



22
23
24
 
# File 'lib/midi-communications-windows/output.rb', line 22

def self.direction
  :output
end

.first ⇒ Input, ... Originally defined in module Device::ClassMethods

The first port of this direction, or nil if there are none.

Returns:

.last ⇒ Input, ... Originally defined in module Device::ClassMethods

The last port of this direction, or nil if there are none.

Returns:

Instance Method Details

#close ⇒ Boolean Originally defined in module Device::InstanceMethods

Closes the port.

Returns:

  • (Boolean) —

    true if it was open, false if it already was not

#display_name ⇒ String Originally defined in module Device::InstanceMethods

The name to show a person choosing a port.

This is the port name unchanged. On macOS the display name is built as "manufacturer model (name)", which here would render as a name wrapped in the punctuation of two absent fields.

Returns:

  • (String)

#initialize(id, name) ⇒ Object Originally defined in module Device::InstanceMethods

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

  • id (Integer) —

    the port's WinMM index within its direction

  • name (String) —

    the port's name as reported by WinMM

#manufacturer ⇒ nil Originally defined in module Device::InstanceMethods

Who made the device.

Always nil on Windows. See the note in MIDICommunicationsWindows::Device for why this is not derived from wMid.

Returns:

  • (nil)

#model ⇒ nil Originally defined in module Device::InstanceMethods

The device model.

Always nil on Windows, for the same reason as #manufacturer.

Returns:

  • (nil)

#open {|self| ... } ⇒ self Also known as: enable, start Originally defined in module Device::InstanceMethods

Opens the port.

Opening twice is not an error and does nothing the second time, which is what midi-communications relies on when it opens a port a caller may already hold.

Yields:

  • (self) —

    if a block is given, the port is closed when it returns

Returns:

  • (self)

Raises:

  • (Error) —

    if WinMM refuses to open the port

#puts(*args) ⇒ Boolean Also known as: write

Sends a MIDI message, in whichever form it is given.

Examples:

Every one of these sends the same Note On

output.puts(0x90, 60, 100)
output.puts([0x90, 60, 100])
output.puts('903C64')

Parameters:

  • args (Array<Integer>, Array<String>, Integer, String) —

    one message, as loose bytes, an array of bytes, or a hex string

Returns:

  • (Boolean) —

    true

Raises:

  • (Error) —

    if WinMM refuses the message



37
38
39
40
41
42
43
44
45
 
# File 'lib/midi-communications-windows/output.rb', line 37

def puts(*args)
  case args.first
  when Array then args.each { |argument| puts(*argument) }
  when Integer then puts_bytes(*args)
  when String then puts_s(*args)
  end

  true
end

#puts_bytes(*data) ⇒ Boolean

Sends a MIDI message given as numeric bytes.

System Exclusive takes a different route through WinMM than everything else, and this is where the two part company.

Parameters:

  • data (Array<Integer>) —

    the message, status byte first

Returns:

  • (Boolean) —

    true

Raises:

  • (Error) —

    if WinMM refuses the message



67
68
69
70
71
 
# File 'lib/midi-communications-windows/output.rb', line 67

def puts_bytes(*data)
  Message.sysex?(data) ? send_sysex(data) : send_short(data)

  true
end

#puts_s(data) ⇒ Boolean Also known as: puts_bytestr, puts_hex

Sends a MIDI message given as a hex string.

Parameters:

  • data (String) —

    hex, two characters per byte, e.g. '903C64'

Returns:

  • (Boolean) —

    true

Raises:

  • (Error) —

    if WinMM refuses the message



53
54
55
 
# File 'lib/midi-communications-windows/output.rb', line 53

def puts_s(data)
  puts_bytes(*data.scan(/../).map(&:hex))
end

#to_s ⇒ String Originally defined in module Device::InstanceMethods

Returns:

  • (String)

#type ⇒ Symbol Originally defined in module Device::InstanceMethods

The port's direction.

Returns:

  • (Symbol) —

    :input or :output