Class: Musa::MusicXML::Builder::Internal::TimeModification Private

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

Tuplet time modification (ratio).

TimeModification defines the rhythmic ratio for tuplets, indicating how many notes of one type fit in the time normally occupied by notes of another type. This modifies the playback duration without changing the visual note type.

Tuplet Ratios

Tuplets are expressed as actual_notes : normal_notes:

Common Tuplets

  • Triplet (3:2): 3 notes in the time of 2

    • Quarter note triplet: 3 quarters in time of 2 quarters (half note)
    • Eighth note triplet: 3 eighths in time of 2 eighths (quarter note)

  • Quintuplet (5:4): 5 notes in the time of 4

  • Sextuplet (6:4): 6 notes in the time of 4

  • Septuplet (7:4 or 7:8): 7 notes in time of 4 or 8

  • Duplet (2:3): 2 notes in the time of 3 (in compound meter)

Components

  • actual_notes: Number of notes actually played
  • normal_notes: Number of notes normally played in that duration
  • normal_type: Note type for normal notes (optional)
  • normal_dots: Augmentation dots on normal notes (optional)

Relationship with Tuplet

TimeModification affects playback timing, while Tuplet controls visual display (bracket, number). Both are typically used together.

Examples:

Triplet (3:2)

TimeModification.new(actual_notes: 3, normal_notes: 2)

Quintuplet (5:4)

TimeModification.new(actual_notes: 5, normal_notes: 4)

Triplet with explicit normal type

TimeModification.new(actual_notes: 3, normal_notes: 2,
                     normal_type: 'eighth')

Duplet in compound meter (2:3)

TimeModification.new(actual_notes: 2, normal_notes: 3)

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(actual_notes:, normal_notes:, normal_type: nil, normal_dots: nil) ⇒ TimeModification

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

Examples:

Quarter note triplet (3 in time of 2)

TimeModification.new(actual_notes: 3, normal_notes: 2)

Quintuplet with explicit normal type

TimeModification.new(actual_notes: 5, normal_notes: 4,
                     normal_type: 'quarter')

Parameters:

  • actual_notes (Integer) —

    number of notes in the tuplet group

  • normal_notes (Integer) —

    number of normal notes in same duration

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

    note type of normal notes ('quarter', 'eighth', etc.)

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

    augmentation dots on normal notes



75
76
77
78
79
80
81
82
83
84
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 75

def initialize(actual_notes:, # number
               normal_notes:, # number
               normal_type: nil, # quarter / ...
               normal_dots: nil) # number

  @actual_notes = actual_notes
  @normal_notes = normal_notes
  @normal_type = normal_type
  @normal_dots = normal_dots
end

Instance Attribute Details

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

Number of actual notes in the tuplet.

Returns:

  • (Integer) 


88
89
90
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 88

def actual_notes
  @actual_notes
end

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

Augmentation dots on normal notes.

Returns:

  • (Integer, nil) 


100
101
102
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 100

def normal_dots
  @normal_dots
end

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

Number of normal notes in the same duration.

Returns:

  • (Integer) 


92
93
94
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 92

def normal_notes
  @normal_notes
end

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

Note type of normal notes.

Returns:



96
97
98
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 96

def normal_type
  @normal_type
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-modification XML element.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 110

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<time-modification>"

  io.puts "#{tabs}\t<actual-notes>#{@actual_notes.to_i}</actual-notes>"
  io.puts "#{tabs}\t<normal-notes>#{@normal_notes.to_i}</normal-notes>"
  io.puts "#{tabs}\t<normal-type>#{@normal_type}</normal-type>" if @normal_type
  @normal_dots&.times do
    io.puts "#{tabs}\t<normal-dot />"
  end

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