Class: Musa::MusicXML::Builder::Internal::Harmonic Private

Inherits:
Object
  • Object
show all
Includes:
Musa::MusicXML::Builder::Internal::Helper::ToXML
Defined in:
lib/musa-dsl/musicxml/builder/note-complexities.rb

Overview

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

String harmonic technique.

Harmonic represents natural and artificial harmonics for string instruments (violin, cello, guitar, etc.). Harmonics produce ethereal, whistle-like tones by lightly touching the string at specific node points.

Harmonic Types

Natural Harmonics

Produced by lightly touching the string at natural node points (1/2, 1/3, 1/4, etc.):

  • kind: 'natural'
  • Common on open strings
  • Easier to execute

Artificial Harmonics

Produced by stopping the string at one point and lightly touching at another:

  • kind: 'artificial'
  • Requires two fingers
  • More versatile for chromaticism

Pitch Specification

Harmonics notation can indicate different pitches:

  • base-pitch: The stopped pitch (where finger presses firmly)
  • touching-pitch: Where finger lightly touches
  • sounding-pitch: The actual pitch that sounds (octave or more higher)

Different notation conventions exist; MusicXML allows specifying which pitch the written note represents.

Examples:

Natural harmonic

Harmonic.new(kind: 'natural').to_xml.string
# => "<harmonic>\n\t<natural />\n</harmonic>\n"

Artificial harmonic

Harmonic.new(kind: 'artificial').to_xml.string
# => "<harmonic>\n\t<artificial />\n</harmonic>\n"

Harmonic with sounding pitch notation

Harmonic.new(kind: 'natural', pitch: 'sounding-pitch')

Harmonic with touching pitch notation

Harmonic.new(kind: 'artificial', pitch: 'touching-pitch')

See Also:

  • Note class with harmonic support

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(kind: nil, pitch: nil) ⇒ Harmonic

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.

Creates a harmonic.

Examples:

Natural harmonic

Harmonic.new(kind: 'natural').to_xml.string
# => "<harmonic>\n\t<natural />\n</harmonic>\n"

Artificial harmonic with sounding pitch

Harmonic.new(kind: 'artificial', pitch: 'sounding-pitch')

Parameters:

  • kind (String, nil) (defaults to: nil) —

    'natural' or 'artificial'

  • pitch (String, nil) (defaults to: nil) —

    which pitch the note represents: 'base-pitch', 'sounding-pitch', or 'touching-pitch'



396
397
398
399
400
401
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 396

def initialize(kind: nil, # natural / artificial
               pitch: nil) # base-pitch / sounding-pitch / touching-pitch

  @kind = kind
  @pitch = pitch
end

Instance Attribute Details

#kind ⇒ String?

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.

Harmonic type ('natural' or 'artificial').

Returns:



405
406
407
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 405

def kind
  @kind
end

#pitch ⇒ String?

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.

Which pitch the written note represents.

Returns:



409
410
411
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 409

def pitch
  @pitch
end

Instance Method Details

#_to_xml(io, indent:, tabs:) ⇒ void

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.

This method returns an undefined value.

Generates the harmonic XML element.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



419
420
421
422
423
424
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 419

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<harmonic>"
  io.puts "#{tabs}\t<#{@kind} />" if @kind
  io.puts "#{tabs}\t<#{@pitch} />" if @pitch
  io.puts "#{tabs}</harmonic>"
end

#to_xml(io = nil, indent: nil) ⇒ IO, StringIO Originally defined in module Musa::MusicXML::Builder::Internal::Helper::ToXML

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.

Converts the object to MusicXML format.

This method sets up the IO stream and indentation, then delegates to the private _to_xml method for actual XML generation.

Examples:

Writing to file

element = Measure.new(1, divisions: 2)
File.open('output.xml', 'w') do |f|
  element.to_xml(f)
end

Getting XML as string

xml_string = element.to_xml.string
xml_string.start_with?('<measure')  # => true

Parameters:

  • io (IO, StringIO, nil) (defaults to: nil) —

    output stream (creates StringIO if nil)

  • indent (Integer, nil) (defaults to: nil) —

    indentation level (default: 0)

Returns:

  • (IO, StringIO) —

    the io parameter, containing the XML output