Class: Musa::MusicXML::Builder::Internal::Time 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.

Time signature specification.

Time represents time signatures in MusicXML. It supports simple meters (4/4, 3/4), compound meters (6/8), complex meters (5/4), and compound time signatures with multiple beat groups. Also supports unmeasured time (senza misura) for cadenzas and free-form sections.

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

Simple Time Signatures

Most common meters use a single beats/beat_type pair:

  • 4/4 (common time): beats=4, beat_type=4
  • 3/4 (waltz): beats=3, beat_type=4
  • 6/8 (compound): beats=6, beat_type=8
  • 2/2 (cut time): beats=2, beat_type=2

Compound Time Signatures

Some meters combine multiple beat groups (e.g., 3+2+3/8):

Time.new do |t|
  t.add_beats beats: 3, beat_type: 8
  t.add_beats beats: 2, beat_type: 8
  t.add_beats beats: 3, beat_type: 8
end

Senza Misura (Unmeasured Time)

For cadenzas and free-form sections without strict meter:

Time.new(senza_misura: '')

Examples:

Common time (4/4)

Time.new(beats: 4, beat_type: 4)

Waltz (3/4)

Time.new(beats: 3, beat_type: 4)

Compound meter (6/8)

Time.new(beats: 6, beat_type: 8)

Complex meter (5/4)

Time.new(beats: 5, beat_type: 4)

Compound signature (3+2+3/8)

time = Time.new
time.add_beats(beats: 3, beat_type: 8)
time.add_beats(beats: 2, beat_type: 8)
time.add_beats(beats: 3, beat_type: 8)

Piano - different time per staff

Time.new(1, beats: 4, beat_type: 4)  # Treble: 4/4
Time.new(2, beats: 3, beat_type: 4)  # Bass: 3/4

Cadenza (unmeasured)

Time.new(senza_misura: '')

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(number = nil, senza_misura: nil, beats: nil, beat_type: nil) ⇒ Time

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 time signature.

Examples:

4/4 time

Time.new(beats: 4, beat_type: 4)

6/8 time

Time.new(beats: 6, beat_type: 8)

Unmeasured time

Time.new(senza_misura: '')



183
184
185
186
187
188
189
190
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 183

def initialize(number = nil, senza_misura: nil, beats: nil, beat_type: nil)
  @number = number

  @senza_misura = senza_misura unless beats && beat_type
  @beats = []

  add_beats beats: beats, beat_type: beat_type if beats && beat_type
end

Instance Attribute Details

#beats ⇒ Array<Hash> (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.

Array of beat groups for compound time signatures.



202
203
204
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 202

def beats
  @beats
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).



194
195
196
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 194

def number
  @number
end

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

Senza misura indicator for unmeasured time.



198
199
200
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 198

def senza_misura
  @senza_misura
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 time signature XML element.



230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 230

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

  io.puts "#{tabs}\t<senza-misura>#{@senza_misura}</senza-misura>" if @senza_misura
  @beats.each do |beats|
    io.puts "#{tabs}\t<beats>#{beats[:beats].to_i}</beats>"
    io.puts "#{tabs}\t<beat-type>#{beats[:beat_type].to_i}</beat-type>"
  end

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

#add_beats(beats:, beat_type:) ⇒ 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.

Adds a beat group to the time signature.

Used for compound time signatures that combine multiple beat groups (e.g., 3+2+3/8 or 2+2+3/4).

Examples:

Complex meter (3+2+3/8)

time = Time.new
time.add_beats(beats: 3, beat_type: 8)
time.add_beats(beats: 2, beat_type: 8)
time.add_beats(beats: 3, beat_type: 8)



218
219
220
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 218

def add_beats(beats:, beat_type:)
  @beats << { beats: beats, beat_type: beat_type }
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