module ZXUtils::MusicBox::CommonInstrumentCommands

Turns off, if any, a chord applied to the played note at the current channel.

# File lib/zxutils/music_box/track.rb, line 255
def chord_off
        start_chord nil
end

Turns off the AY-3-891x automatic volume envelope control of the current channel.

# File lib/zxutils/music_box/track.rb, line 448
def disable_ay_volume_ctrl
        @commands << Command.new(Command::Headers::CMD_DISABLE_AY_VOLUME_CTRL)
        @commands.length
end

Enables the AY-3-891x automatic volume envelope control of the current channel.

# File lib/zxutils/music_box/track.rb, line 436
def enable_ay_volume_ctrl
        @commands << Command.new(Command::Headers::CMD_ENABLE_AY_VOLUME_CTRL)
        @commands.length
end

Sets the AY-3-891x automatic volume envelope duration: 1 to 65535.

# File lib/zxutils/music_box/track.rb, line 181
def envelope_duration(duration)
        @commands << AYEnvelopeDurationCommand.new(duration)
        @commands.length
end

Sets the shape of the AY-3-891x automatic volume envelope: 0 to 15. You may use ZXLib::AYSound::EnvelopeControl constants.

# File lib/zxutils/music_box/track.rb, line 194
def envelope_shape(shape)
        @commands << AYEnvelopeShapeCommand.new(shape)
        @commands.length
end

Loops execution from the marked point name. Repeats repeat times. If repeat is nil or missing loops forever.

See also CommonInstrumentCommands.mark and CommonInstrumentCommands.repeat.

# File lib/zxutils/music_box/track.rb, line 124
def loop_to(mark_name, repeat=nil)
        @commands << LoopCommand.new(mark_name, repeat)
        @commands.length
end

Marks a point in the track and gives it a name as a symbol or a string. You can later use CommonInstrumentCommands.loop_to with a marked point name.

# File lib/zxutils/music_box/track.rb, line 111
def mark(name)
        @commands << MarkCommand.new(name)
        @commands.length
end

Applies a mask defined by SongCommands.mask to the current channel's envelope bit controlling the AY-3-891x automatic volume envelope. When the current mask bit has value 1: turns on the envelope. When 0: turns it off.

# File lib/zxutils/music_box/track.rb, line 266
def mask_ay_volume_envelope(mask_name)
        @commands << MaskCommand.new(:volume, mask_name)
        @commands.length
end

Turns off, if any, a mask applied to the current channel's envelope bit.

# File lib/zxutils/music_box/track.rb, line 276
def mask_ay_volume_envelope_off
        mask_ay_volume_envelope nil
end

Applies a mask defined by SongCommands.mask to the current channel's mixer controlling the noise output. When the current mask bit has value 1: turns off the noise. When 0: turns it on.

# File lib/zxutils/music_box/track.rb, line 309
def mask_noise(mask_name)
        @commands << MaskCommand.new(:noise, mask_name)
        @commands.length
end

Turns off, if any, a mask applied to the current channel's mixer controlling the noise output.

# File lib/zxutils/music_box/track.rb, line 320
def mask_noise_off
        mask_noise nil
end

Applies a mask defined by SongCommands.mask to the current channel's mixer controlling the tone output. When the current mask bit has value 1: turns off the tone. When 0: turns it on.

# File lib/zxutils/music_box/track.rb, line 287
def mask_tone(mask_name)
        @commands << MaskCommand.new(:tone, mask_name)
        @commands.length
end

Turns off, if any, a mask applied to the current channel's mixer controlling the tone output.

# File lib/zxutils/music_box/track.rb, line 298
def mask_tone_off
        mask_tone nil
end

Switches to play mode 1. This is the default mode. In this mode after playing a note the instrument track, if set, starts executing from the beginning.

See also CommonInstrumentCommands.mode2 and TrackCommands.set_instrument.

# File lib/zxutils/music_box/track.rb, line 157
def mode1
        @commands << Command.new(Command::Headers::CMD_PLAY_MODE_1)
        @commands.length
end

Switches to play mode 2. In this mode after playing a note the instrument track, if set, continues executing uninterrupted.

See also CommonInstrumentCommands.mode1 and TrackCommands.set_instrument.

# File lib/zxutils/music_box/track.rb, line 170
def mode2
        @commands << Command.new(Command::Headers::CMD_PLAY_MODE_2)
        @commands.length
end

Sets noise pitch level: 0 to 31.

# File lib/zxutils/music_box/track.rb, line 90
def noise(level)
        @commands << NoisePitchCommand.new(level)
        @commands.length
end

Turns off, if any, an envelope applied to the noise pitch level.

# File lib/zxutils/music_box/track.rb, line 235
def noise_envelope_off
        start_noise_envelope nil
end

Turns off the current channel's noise output.

# File lib/zxutils/music_box/track.rb, line 479
def noise_off
        @commands << Command.new(Command::Headers::CMD_DISABLE_NOISE)
        @commands.length
end

Turns on the current channel's noise output.

# File lib/zxutils/music_box/track.rb, line 489
def noise_on
        @commands << Command.new(Command::Headers::CMD_ENABLE_NOISE)
        @commands.length
end

Enables the smooth tone frequency progression of the notes played on the current channel.

period

A number of ticks after which the tone reaches the next played note's frequency.

If the period is 0, the tracking of the frequency of the played notes is being disabled. To turn on the frequency progression first set period to 1, play at least one note and then set the desired progression period for the following notes being played.

# File lib/zxutils/music_box/track.rb, line 401
def note_progress(period)
        @commands << NoteProgressPeriodCommand.new(period)
        @commands.length
end

Pauses the current track execution for a length period. The length value should be a positive integer.

The number of ticks paused is being calculated based on the TrackConfigCommands.tempo value.

ticks = tempo / length

For the tempo unrelated pause see CommonInstrumentCommands.wait.

In the music theory the length of:

• 1 means Semibreve or Whole note.

• 2 means Minim or Half note.

• 4 means Crotchet or Quarter note.

• 8 means Quaver or Eighth note.

• 16 means Semiquaver or Sixteenth note.

• 32 means Demisemiquaver or Thirty-second note.

• 64 means Hemidemisemiquaver or Sixty-fourth note.

You may provide as many lengths as additional arguments as necessary. E.g.:

pause 1, 2, 4 # will pause for the whole and half and quarter note.

# File lib/zxutils/music_box/track.rb, line 77
def pause(length, *length_exts)
        ticks = Rational(@tempo, length)
        length_exts.each do |len_ext|
                ticks += Rational(@tempo, len_ext)
        end
        wait(ticks)
end

Repeats the execution of the commands in the given block repeat times. If repeat is nil or missing repeats forever.

See also CommonInstrumentCommands.mark and CommonInstrumentCommands.loop_to.

# File lib/zxutils/music_box/track.rb, line 137
def repeat(times=nil, mark:nil, &block)
        mark_cmd = MarkCommand.new(mark)
        @commands << mark_cmd
        if times != 0
                yield
                unless @commands.last.equal?(mark_cmd) or times == 1
                        loop_to mark_cmd.mark_name, times
                end
        end
        @commands.length
end

Applies a chord defined by SongCommands.chord to the currently played note at the current channel.

# File lib/zxutils/music_box/track.rb, line 245
def start_chord(chord_name)
        @commands << ChordCommand.new(chord_name)
        @commands.length
end

Applies an envelope defined by SongCommands.envelope to the noise pitch level.

# File lib/zxutils/music_box/track.rb, line 225
def start_noise_envelope(envelope_name)
        @commands << EnvelopeCommand.new(:noise, envelope_name)
        @commands.length
end

Applies an envelope defined by SongCommands.envelope to the volume level at the current channel.

# File lib/zxutils/music_box/track.rb, line 206
def start_volume_envelope(envelope_name)
        @commands << EnvelopeCommand.new(:volume, envelope_name)
        @commands.length
end

Turns off the current channel's tone output.

# File lib/zxutils/music_box/track.rb, line 459
def tone_off
        @commands << Command.new(Command::Headers::CMD_DISABLE_TONE)
        @commands.length
end

Turns on the current channel's tone output.

# File lib/zxutils/music_box/track.rb, line 469
def tone_on
        @commands << Command.new(Command::Headers::CMD_ENABLE_TONE)
        @commands.length
end

Enables and controls the tone frequency progression of the current channel's tone.

delta

A floating point value representing a number of half-tones to go up or down the frequency scale.

counter

An positive integer number indicating how many ticks it takes to reach the desired delta interval.

To set the starting frequency first set note_progress 1, play at least one note and then set the desired delta and counter with the tone_progress command.

NOTE

This command is an alternative to CommonInstrumentCommands.note_progress and as such can't be used with it at the same time on the same channel: tone_progress sets the note_progress 0 under the hood. Any notes being played while this command is in effect will not be heard for the counter ticks. After that the tone frequency will change to the last played note's.

# File lib/zxutils/music_box/track.rb, line 425
def tone_progress(delta, counter)
        @commands << ToneProgressCommand.new(delta, counter)
        @commands.length
end

Enables the current channel's tone vibrato and sets the distortion amplitude.

amplitude

A positive floating point value of a tone distortion amplitude. Currently the valid values are in the range from 0 to 1, where 1 corresponds to the single half-tone frequency interval.

The distortion level of the tone is calculated from:

amplitude * sinus(PI * angle / 128.0)

See also: CommonInstrumentCommands.vibrato_step and CommonInstrumentCommands.vibrato_angle.

# File lib/zxutils/music_box/track.rb, line 375
def vibrato_amplitude(amplitude=1.0)
        @commands << VibratoAmplitudeCommand.new(amplitude)
        @commands.length
end

Enables the current channel's tone vibrato and sets the current phase angle.

angle

A positive floating point value of a tone distortion angle. The value of 256.0 corresponds to the full phase of the distortion.

The distortion level of the tone is calculated from:

amplitude * sinus(PI * angle / 128.0)

See also: CommonInstrumentCommands.vibrato_step and CommonInstrumentCommands.vibrato_amplitude.

# File lib/zxutils/music_box/track.rb, line 356
def vibrato_angle(angle=0.0)
        @commands << VibratoAngleCommand.new(angle)
        @commands.length
end

Turns off, if any, the current channel's tone vibrato distortion.

# File lib/zxutils/music_box/track.rb, line 385
def vibrato_off
        @commands << Command.new(Command::Headers::CMD_VIBRATO_OFF)
        @commands.length
end

Enables the current channel's tone vibrato and sets the distortion angle progression step.

step

A floating point value of a tone distortion angle progression during a single tick. The value of 256.0 corresponds to the full phase of the distortion. The higher the absolute value of the step, the faster vibrato progresses.

Assuming the starting angle is 0, if the value of the step is positive the tone frequency ascends first then descends. If it's negative the tone first descends before ascending.

See also: CommonInstrumentCommands.vibrato_angle.

# File lib/zxutils/music_box/track.rb, line 338
def vibrato_step(step=1.0)
        @commands << VibratoStepCommand.new(step)
        @commands.length
end

Sets volume level for the current channel: 0 to 15.

# File lib/zxutils/music_box/track.rb, line 100
def volume(level)
        @commands << VolumeLevelCommand.new(level)
        @commands.length
end

Turns off, if any, an envelope applied to the volume level at the current channel.

# File lib/zxutils/music_box/track.rb, line 216
def volume_envelope_off
        start_volume_envelope nil
end

Pauses the current track execution for ticks number of ticks. The ticks value should be a positive integer as an Integer or a Rational.

For the TrackConfigCommands.tempo related pause see CommonInstrumentCommands.pause.

# File lib/zxutils/music_box/track.rb, line 48
def wait(ticks)
        @commands << PauseCommand.new(ticks)
        @commands.length
end