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')

Artificial harmonic

Harmonic.new(kind: 'artificial')

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')

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'



389
390
391
392
393
394
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 389

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:



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

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:



402
403
404
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 402

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



412
413
414
415
416
417
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 412

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

File.open('output.xml', 'w') do |f|
  element.to_xml(f)
end

Getting XML as string

xml_string = element.to_xml.string

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