Extract or replace a PTSample waveform

Extract or replace the waveform of a PTSample object. The waveform is represented by a vector of numeric values ranging from 0 up to 255.

Usage

# S4 method for PTSample
waveform(sample, start.pos = 1, stop.pos = sampleLength(sample), loop = TRUE)

# S4 method for PTSample
waveform(sample) <- value

Arguments

sample

A PTSample object from which the waveform needs to be extracted or replaced.

start.pos

A numeric starting index, giving the starting position for the waveform to be returned. Default value is 1. This index should be greater than zero.

stop.pos

A numeric stopping index, giving the stopping position for the waveform to be returned. Default value is sampleLength(sample) This index should be greater than start.pos.

loop

A logical value indicating whether the waveform should be modulated between the specified loop positions (see loopStart and loopLength), or the waveform should stop at the end of the sample (padded with NA values beyond the sample length). Will do the first when set to TRUE and the latter when set to FALSE.

value

A vector of numeric values ranging from 0 up to 255, representing the waveform that should be used to replace that of object sample. The length should be even and not exceed 2*0xffff = 131070. loopStart and loopLength will be adjusted automatically when they are out of range for the new waveform.

Use NA to generate an empty/blank PTSample object.

Value

For waveform, the waveform of sample is returned as a vector of numeric values ranging from 0 up to 255. If loop is set to FALSE

and the starting position is beyond the sample length, NA values are returned. If loop is set to TRUE and the starting position is beyond the sample loop (if present, see loopState), the waveform is modulated between the loop positions.

For waveform<-, a copy of object sample is returned in which the waveform has been replaced with value.

Details

Sample waveforms are stored as 8 bit signed short integer values ranging from -128 up to +127 in original ProTracker files. However, as the PTSample class extends the tuneR::Wave class, the waveforms are represented by integer values ranging from 0 up to 255 in the ProTrackR package. As per ProTracker specifications, samples are of 8 bit mono quality and can only have an even length with a maximum of 2*0xffff = 131070. This method can be used to extract a waveform or replace it.

See also

Other integer.operations: nybbleToSignedInt(), nybble(), rawToSignedInt(), rawToUnsignedInt(), signedIntToNybble(), signedIntToRaw(), unsignedIntToRaw()

Other sample.operations: PTSample-class, PTSample-method, fineTune(), loopLength(), loopSample(), loopStart(), loopState(), name, playSample(), read.sample(), sampleLength(), volume(), write.sample()

Author

Pepijn de Vries

Examples

data("mod.intro")

## Loop sample #1 of mod.intro beyond it's
## length of 1040 samples:
wav1 <- waveform(PTSample(mod.intro, 1),
                 1, 5000)

## get the waveform from sample #2
## of mod.intro:
wav2 <- waveform(PTSample(mod.intro, 2))

## create an echo effect using
## the extracted waveform:
wav2 <- c(wav2, rep(128, 1000)) +
        c(rep(128, 1000), wav2)*0.25 - 25

## assign this echoed sample to
## sample #2 in mod.intro:
waveform(PTSample(mod.intro, 2)) <- wav2

## Blank out sample #1 in mod.intro:
waveform(PTSample(mod.intro, 1)) <- NA
#> Warning: Sample loop start is outside the new range. It is set to 0.
#> Warning: Sample loop end is outside the new range. It's set to its maximum.