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.

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



86
87
88
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 86

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) 


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

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



102
103
104
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 102

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

File.open('output.xml', 'w') do |f|
  element.to_xml(f)
end

Getting XML as string

xml_string = element.to_xml.string

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