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

Inherits:
Object
  • Object
show all
Includes:
Extension::With, 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).

Reaching it

Clefs are written through the attributes DSL. The examples below are against measure = Measure.new(1, divisions: 2).

line: is optional, as it is in MusicXML: a clef that sits on no line simply leaves it out, and no <line> element is written.

Examples:

Treble clef

measure.attributes { clef sign: 'G', line: 2 }

Bass clef

measure.attributes { clef sign: 'F', line: 4 }

Alto and tenor clefs

measure.attributes { clef sign: 'C', line: 3 }
measure.attributes { clef sign: 'C', line: 4 }

Tenor voice (treble 8va basso)

measure.attributes { clef sign: 'G', line: 2, octave_change: -1 }

Piccolo (treble 8va alta)

measure.attributes { clef sign: 'G', line: 2, octave_change: 1 }

Piano - different clefs per staff

measure.attributes do
  clef 1, sign: 'G', line: 2  # Treble clef (right hand)
  clef 2, sign: 'F', line: 4  # Bass clef (left hand)
end

Percussion

measure.attributes { clef sign: 'percussion' }

Guitar tablature

measure.attributes { clef sign: 'TAB' }

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(number = nil, sign:, line: nil, octave_change: nil, &block) ⇒ 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)

Percussion, which has no line

Musa::MusicXML::Builder::Internal::Clef.new(sign: 'percussion').line  # => nil

Parameters:

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

    staff number (for multi-staff parts)

  • sign (String) —

    clef sign: 'G', 'F', 'C', 'percussion', 'TAB'

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

    staff line number (1-5, bottom to top). Optional, as it is in MusicXML: percussion and tablature clefs sit on no line, and omitting it writes no <line> element.

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

    octave transposition (-2, -1, 0, +1, +2)



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

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

  with &block if block_given?
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).

Returns:

  • (Integer) 


407
408
409
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 407

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

Returns:

  • (Integer, nil) 


399
400
401
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 399

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

Returns:

  • (Integer, nil) 


411
412
413
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 411

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

Returns:



403
404
405
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 403

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.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



421
422
423
424
425
426
427
428
429
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 421

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

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

#with(*value_parameters, keep_block_context: nil, **key_parameters, &block) ⇒ Object Originally defined in module Extension::With

Note:

The _ parameter is special: when present, it signals "keep caller's context" and receives self (the object) as its value.

Note:

Uses SmartProcBinder internally to handle parameter matching.

Executes a block with flexible context and parameter handling.

Parameters:

  • value_parameters (Array) —

    positional parameters to pass to block.

  • keep_block_context (Boolean, nil) (defaults to: nil) —

    explicit control of context switching:

    • true: always keep caller's context
    • false: always use object's context
    • nil: auto-detect based on _ parameter
  • key_parameters (Hash) —

    keyword parameters to pass to block.

  • block (Proc) —

    block to execute.

Returns:

  • (Object) —

    result of block execution.