The ProTrackR2 package has defined a number of hierarchical classes to represent ProTracker modules. This vignette explains how these objects are organised, and how they can be used to work with ProTracker modules in R. We start with the diagram below, which shows an object tree. It shows how object classes are organised and related. It is similar (but not identical) to how ProTracker module files are organised. We follow the tree to explain each object by starting at its root: the ProTracker module.
pt2mod)The pt2mod class object is a memory representation of
ProTracker module files. The type of this object is
externalptr and points to the location in memory where the
data is stored for manipulation and/or play back.
An empty module can be created by calling
pt2_new_mod("song title"). It can also be initiated by
reading a module from a file like this:
library(ProTrackR2)
mod <- pt2_read_mod(system.file("mod.intro", package = "ProTrackR2"))
mod
#> pt2mod 'intro' [01:09]As you might know, external pointers cannot be accessed directly in
R. Instead you need to use the functions and methods
presented in this package to approach it. If you want a more ‘physical’
manifestation of the object, you can call as.raw() (which
returns the raw file representation of the object). Or write it to a
file using pt2_write_mod(). If you want to know what the
module sounds like you can simply play it:
pt2samplist)The sample list is a collection of distinct instruments (samples) and
is represented by the pt2samplist class. Essentially, it is
a list of samples (pt2samp class objects; see below). The
sample list of a module can be obtained using the
$-operator as shown below.
See also vignette("sel_assign") for more details about
selecting or replacing a sample list. The sample list returned here is
the complete list of samples, including empty sample slots. If you want
to count the number of non-empty samples in a module use
pt2_n_sample(mod).
pt2samp)ProTracker uses pulse-code modulation (PCM) mono audio samples with 8
bit depth. In this package it’s represented by the pt2samp
class. It can either by a list where the first element is a
pt2samplelist object and the second is an
integer index of the sample in the list. It can also be a
vector of raw values, where each value is a PCM sample. The
raw form will also hold an attribute named
"sample_info" used to interpret the sample. The attribute
"sample_info" is a named list containing the following
elements:
length: should be identical to the length of the vector
of raw values.loopStart: start position (in number of samples) of a
loop in the sample (0 when loop is off).loopLength: length (in number of samples) of a loop (2
when loop is off).fineTune: an integer value (between -8 and
7) to tweak a sample when it is out of tune.volume: volume level of the sample. An
integer value between 0 (muted) and 64 (max).text: 22 UTF-8 characters. Usually describing the
sample or the module.A sample can be initiated by reading it from an audio file using
pt2_read_sample(). It can also be selected from a sample
list as shown below.
See also vignette("sel_assign") for more details about
selecting or replacing a sample.
pt2patlist)The pattern list is a collection of distinct pattern tables and is
represented by the pt2patlist class. Essentially, it is a
list of pattern tables (pt2pat class objects; see below).
Note that this list of pattern tables is not necessarily the order in
which they are played. This is determined by the pattern sequence
(pt2_pattern_table(mod)).
The pattern list of a module can be obtained using the
$-operator as shown below.
The loaded module consists of 4 unique pattern tables. See also
vignette("sel_assign") for more details about selecting or
replacing a pattern list.
pt2pat)A pattern table defines the rhythm and melody of a ProTracker module. The columns in a pattern table represent the four audio channels (red borders in Table 1). Each row (orange borders in Table 1) is subsequently played and specifies which note (blue fields in Table 1) using a specific instrument (sample, cyan fields in Table 1) is heard. It can also specify specific effects such as tremolo, porta or vibrato (green fields in Table 1).
| Row | Channel 1 | Channel 2 | Channel 3 | Channel 4 |
|---|---|---|---|---|
| 0 | C−3 01 A08 |
C−3 02 C40 |
A#1 03 F06 |
A#2 04 000 |
| 1 | −−− 01 A08 |
C−3 02 C30 |
−−− 00 A01 |
−−− 00 A02 |
| 2 | −−− 01 A08 |
C−3 02 000 |
−−− 00 A01 |
C−3 04 000 |
| 3 | −−− 00 000 |
C−3 02 000 |
−−− 00 A02 |
−−− 00 A02 |
| ... | ... | ... | ... | ... |
| 63 | −−− 00 A08 |
C−3 04 C08 |
−−− 00 000 |
−−− 00 A02 |
A ProTracker pattern is represented by the pt2pat class.
It can be a list where the first element is its parent
module (pt2mod) and the second element is the index in the
pattern list. It can also be a vector of raw
values that either represents the file structure of a pattern or its
representation in memory used by the play back routine.
A pattern can be initiated with pt2_new_pattern(). This
produces a raw representation of a pattern. Here the
logical argument compact determines if the
notation is compact (TRUE) as is the case in a file, or not
(FALSE) as in memory. This is stored as an attribute to the
object for its correct interpretation.
It can also be selected from an existing module as shown below.
Consult vignette("sel_assign") for more information
about selecting and replacing patterns.
pt2celllist)The cell list is a collection of cells from a pattern table and is
represented by the pt2celllist class. Essentially, it is a
list of cells (pt2cell class objects; see below). The cell
list can be obtained using the [-operator from a pattern as
shown below.
Consult vignette("sel_assign") for more information
about selecting and replacing cell lists.
pt2cell)A cell is an elementary unit in a pattern table and contains
information about which note to play (blue fields in
Table 1), which instrument (sample cyan
fields in Table 1) and what kind of
effect to apply (green fields in Table
1). It is represented by the pt2cell class and can
consist of a list, where the first element is a
pt2mod object and followed by three indices i
(pattern id), j (pattern row) and k (channel
id). It can also be represented by a vector of raw values
as stored in file (compact) or in memory (not compact). A cell can be
selected from a cell list as shown below.
See vignette("sel_assign") for more information about
selecting and replacing cell values.