Class: Musa::MusicXML::Builder::Internal::Backup Private

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

Timeline rewind for polyphonic music.

Backup moves the musical timeline backwards by a specified duration, allowing overlapping musical content to be written sequentially. This is essential for polyphonic music where multiple voices or staves play simultaneously.

Use Cases

Multiple Voices: Write voice 1, backup, then write voice 2 starting at the same timepoint.

Multi-Staff Instruments: Write treble staff notes, backup, then write bass staff notes for the same measure.

Polyphonic Textures: Layer independent melodic lines that share temporal alignment.

Duration Units

Duration is specified in the measure's division units (not note values). If divisions=4, then duration=8 means 8 divisions = 2 quarter notes = 1 half note.

Common pattern: backup by the full measure duration to restart from the beginning of the measure.

The measure these examples are written against

measure = Measure.new(1, divisions: 2)

Two divisions to the quarter, so a full 4/4 measure is 8 divisions -- which is the number every backup 8 below is rewinding.

Workflow Example

  1. Write notes for voice 1
  2. Backup to measure start
  3. Write notes for voice 2 (with voice: 2 parameter)
  4. Optionally backup again for additional voices

Examples:

Piano with simultaneous treble and bass

measure.pitch 'D', octave: 4, duration: 4, type: 'half'
measure.pitch 'E', octave: 4, duration: 4, type: 'half'

measure.backup 8  # Rewind full measure (8 divisions)

measure.pitch 'C', octave: 3, duration: 8, type: 'whole', staff: 2

Two voices on the same staff

measure.pitch 'C', octave: 5, duration: 2, type: 'quarter', voice: 1
measure.pitch 'D', octave: 5, duration: 2, type: 'quarter', voice: 1
measure.pitch 'E', octave: 5, duration: 2, type: 'quarter', voice: 1
measure.pitch 'F', octave: 5, duration: 2, type: 'quarter', voice: 1

measure.backup 8  # Back to measure start

measure.pitch 'E', octave: 4, duration: 4, type: 'half', voice: 2
measure.pitch 'F', octave: 4, duration: 4, type: 'half', voice: 2

Three-voice polyphony

# Voice 1
measure.pitch 'G', octave: 5, duration: 8, type: 'whole', voice: 1

measure.backup 8

# Voice 2
measure.pitch 'C', octave: 5, duration: 8, type: 'whole', voice: 2

measure.backup 8

# Voice 3
measure.pitch 'E', octave: 4, duration: 8, type: 'whole', voice: 3

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(duration) ⇒ Backup

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 backup (timeline rewind).

Examples:

Rewind full measure (divisions=4, 4/4 time)

Backup.new(8)  # 8 divisions = 2 quarter notes

Rewind half measure

Backup.new(4)  # 4 divisions = 1 quarter note

Parameters:

  • duration (Integer) —

    rewind amount in division units



93
94
95
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 93

def initialize(duration)
  @duration = duration
end

Instance Attribute Details

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

Duration to rewind in division units.

Returns:

  • (Integer) 


99
100
101
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 99

def duration
  @duration
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 backup XML element.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



109
110
111
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 109

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<backup><duration>#{@duration.to_i}</duration></backup>"
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