Class: Musa::MusicXML::Builder::Internal::Clef Private

Inherits:
Object
  • Object
show all
Includes:
Helper::ToXML
Defined in:
lib/musa-dsl/musicxml/builder/attributes.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.

Clef specification.

Clef represents musical clefs that determine the pitch range displayed on a staff. MusicXML supports standard clefs (treble, bass, alto, tenor), percussion clefs, and tablature clefs.

For multi-staff parts (like piano), the number attribute specifies which staff the clef applies to.

Common Clefs

Standard clefs are defined by a sign and staff line number:

  • Treble (G clef): sign='G', line=2
  • Bass (F clef): sign='F', line=4
  • Alto (C clef): sign='C', line=3
  • Tenor (C clef): sign='C', line=4
  • Percussion: sign='percussion'
  • Tablature: sign='TAB'

Clef Signs

The sign parameter determines the clef type:

  • G: Treble clef family
  • F: Bass clef family
  • C: Alto/tenor clef family (movable C clef)
  • percussion: For unpitched percussion
  • TAB: For guitar/bass tablature

Staff Lines

The line parameter indicates which staff line the clef sign sits on:

  • Lines are numbered 1-5 from bottom to top
  • Treble clef (G) typically on line 2
  • Bass clef (F) typically on line 4
  • Alto clef (C) on line 3, Tenor clef (C) on line 4

Octave Transposition

The octave_change parameter transposes notation by octaves:

  • -2: 15ma basso (two octaves down)
  • -1: 8va basso (one octave down)
  • 0: No transposition (default)
  • +1: 8va alta (one octave up)
  • +2: 15ma alta (two octaves up)

Common for tenor voice (treble clef 8va basso) and piccolo (treble 8va alta).

Examples:

Treble clef

Clef.new(sign: 'G', line: 2)

Bass clef

Clef.new(sign: 'F', line: 4)

Alto clef

Clef.new(sign: 'C', line: 3)

Tenor clef

Clef.new(sign: 'C', line: 4)

Tenor voice (treble 8va basso)

Clef.new(sign: 'G', line: 2, octave_change: -1)

Piccolo (treble 8va alta)

Clef.new(sign: 'G', line: 2, octave_change: 1)

Piano - different clefs per staff

Clef.new(1, sign: 'G', line: 2)  # Treble clef (right hand)
Clef.new(2, sign: 'F', line: 4)  # Bass clef (left hand)

Percussion

Clef.new(sign: 'percussion')

Guitar tablature

Clef.new(sign: 'TAB')

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(number = nil, sign:, line:, octave_change: nil) ⇒ Clef

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 clef.

Examples:

Treble clef

Clef.new(sign: 'G', line: 2)

Bass clef

Clef.new(sign: 'F', line: 4)

Tenor voice (treble 8va basso)

Clef.new(sign: 'G', line: 2, octave_change: -1)



339
340
341
342
343
344
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 339

def initialize(number = nil, sign:, line:, octave_change: nil)
  @number = number
  @sign = sign
  @line = line
  @octave_change = octave_change
end

Instance Attribute Details

#line ⇒ Integer

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.

Staff line number (1-5).



356
357
358
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 356

def line
  @line
end

#number ⇒ Integer? (readonly)

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.

Staff number (for multi-staff instruments).



348
349
350
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 348

def number
  @number
end

#octave_change ⇒ Integer?

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.

Octave transposition (-2 to +2).



360
361
362
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 360

def octave_change
  @octave_change
end

#sign ⇒ 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.

Clef sign (G, F, C, percussion, TAB).



352
353
354
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 352

def sign
  @sign
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 clef XML element.



370
371
372
373
374
375
376
377
378
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 370

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<clef#{" number=\"#{@number.to_i}\"" if @number}>"

  io.puts "#{tabs}\t<sign>#{@sign}</sign>"
  io.puts "#{tabs}\t<line>#{@line.to_i}</line>" if @line
  io.puts "#{tabs}\t<clef-octave-change>#{@octave_change.to_i}</clef-octave-change>" if @octave_change

  io.puts "#{tabs}</clef>"
end

#to_xml(io = nil, indent: nil) ⇒ IO, StringIO Originally defined in module 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