Help for package ProTrackR2

Title:

Manipulate and Play 'ProTracker' Modules

Version:

0.0.5

Maintainer:

Pepijn de Vries <pepijn.devries@outlook.com>

Description:

'ProTracker' is a popular music tracker to sequence music on a Commodore Amiga machine. This package offers the opportunity to import, export, manipulate and play 'ProTracker' module files. Even though the file format could be considered archaic, it still remains popular to this date. This package intends to contribute to this popularity and therewith keeping the legacy of 'ProTracker' and the Commodore Amiga alive. This package is the successor of 'ProTrackR' providing better performance.

License:

GPL (≥ 3)

Encoding:

UTF-8

RoxygenNote:

7.2.3

LinkingTo:

cpp11

Collate:

'ProTrackR2-package.R' 'cell.R' 'command.R' 'cpp11.R' 'data.R' 'demo.R' 'helpers.R' 'instrument.R' 'io.R' 'mod_info.R' 'modplug.R' 'note.R' 'pattern.R' 'render.R' 's3.R' 'samples.R' 'select_ops.R' 'validate.R'

Imports:

audio

Suggests:

cli, htmltools, kableExtra, knitr, rmarkdown

VignetteBuilder:

knitr

URL:

https://pepijn-devries.github.io/ProTrackR2/, https://github.com/pepijn-devries/ProTrackR2

BugReports:

https://github.com/pepijn-devries/ProTrackR2/issues

NeedsCompilation:

yes

Packaged:

2024-11-09 11:10:58 UTC; vries171

Author:

Pepijn de Vries

[aut, cre], Olav Sørensen [aut] (Developer of the ProTracker 2.3d clone)

Depends:

R (≥ 3.5.0)

Repository:

CRAN

Date/Publication:

2024-11-09 15:00:07 UTC

ProTrackR2: Manipulate and Play 'ProTracker' Modules

Description

Author(s)

Maintainer: Pepijn de Vries pepijn.devries@outlook.com (ORCID)

Authors:

Olav Sørensen (Developer of the ProTracker 2.3d clone)

Select and assign operators for ProTrackR2 S3 class objects

Description

Functions to select and assign elements to ProTracker modules. See vignette('s3class') for an overview of ProTrackR2 S3 class objects. See vignette('sel_assign') for practical guidance on selecting and assigning elements of ProTrackR2 class objects.

Usage

## S3 method for class 'pt2mod'
x$i, ...

## S3 replacement method for class 'pt2mod'
x$i <- value

## S3 method for class 'pt2mod'
x[[i, ...]]

## S3 method for class 'pt2patlist'
x[i, ...]

## S3 method for class 'pt2patlist'
x[[i, ...]]

## S3 replacement method for class 'pt2patlist'
x[[i]] <- value

## S3 method for class 'pt2samplist'
x[i, ...]

## S3 method for class 'pt2samplist'
x[[i, ...]]

## S3 method for class 'pt2pat'
x[i, j, ...]

## S3 replacement method for class 'pt2pat'
x[i, j, ...] <- value

## S3 method for class 'pt2celllist'
x[[i, ...]]

## S3 method for class 'pt2celllist'
x[i, ...]

## S3 method for class 'pt2command'
x[[i, ...]]

## S3 method for class 'pt2command'
x[i, ...]

## S3 replacement method for class 'pt2command'
x[[i, ...]] <- value

## S3 replacement method for class 'pt2command'
x[i, ...] <- value

Arguments

x

Object to apply S3 method to. See 'usage' section for allowed object types.

i, j

Indices for extracting or replacing ProTrackR2 object elements

...

Passed on to other methods.

value

Replacement value for the selected element(s).

Value

Returns the selected object in case of a selection ([, [[, or $) operator. Returns the updated object x in case of an assignment (⁠<-⁠) operator.

Format a ProTracker pattern conform OpenMPT specs

Description

OpenMpt is a popular modern music tracker. This function allows you to format a pattern such that it can be pasted directly into OpenMPT. On Windows you can use writeClipboard() for this purpose.

Usage

as_modplug_pattern(pattern, ...)

Arguments

pattern

An object of class pt2pat to be formatted

...

Ignored

Value

Returns a character object formatted such that it can be copied into OpenMPT

Author(s)

Pepijn de Vries

Examples

mod    <- pt2_read_mod(pt2_demo())
mp_pat <- as_modplug_pattern(pt2_pattern(mod, 0L))

Effect commands (data.frame)

Description

ProTracker uses codes to achieve certain effects or jump to a specific position (see vignette("effect_commands")).

Format

effect_commands is a data.frame with three columns:

Code: a character of pseudo code used to achieve a certain effect in ProTracker
Effect: Name of the effect.
Description: Description of the effect.

It is used for documentation and reference purposes.

Examples

data("effect_commands")

Implementation of basic S3 methods

Description

Implementation of basic S3 methods, such as, format, print, as.raw and as.character ( see usage section for a complete overview). See vignette('s3class') for an overview of ProTrackR2 S3 class objects. See usage section for an overview of available methods.

Usage

## S3 method for class 'pt2mod'
format(x, ...)

## S3 method for class 'pt2mod'
print(x, ...)

## S3 method for class 'pt2pat'
format(
  x,
  padding = " ",
  empty_char = "-",
  fmt = getOption("pt2_cell_format"),
  ...
)

## S3 method for class 'pt2command'
format(x, fmt = getOption("pt2_effect_format"), ...)

## S3 method for class 'pt2command'
print(x, max.print = 10L, ...)

## S3 method for class 'pt2pat'
print(x, sep = "  ", show_header = TRUE, show_row = TRUE, ...)

## S3 method for class 'pt2pat'
as.character(x, ...)

## S3 method for class 'pt2celllist'
as.raw(x, ...)

## S3 method for class 'logical'
as.raw.pt2celllist(x, compact = TRUE, ...)

## S3 method for class 'pt2pat'
as.raw(x, ...)

## S3 method for class 'logical'
as.raw.pt2pat(x, compact = TRUE, ...)

## S3 method for class 'pt2cell'
format(
  x,
  padding = " ",
  empty_char = "-",
  fmt = getOption("pt2_cell_format"),
  ...
)

## S3 method for class 'pt2cell'
print(x, ...)

## S3 method for class 'pt2cell'
as.character(x, ...)

## S3 method for class 'pt2command'
as.raw(x, ...)

## S3 method for class 'pt2cell'
as.raw(x, ...)

## S3 method for class 'logical'
as.raw.pt2cell(x, compact = TRUE, ...)

## S3 method for class 'pt2samp'
format(x, ...)

## S3 method for class 'pt2samp'
print(x, ...)

## S3 method for class 'pt2patlist'
format(x, ...)

## S3 method for class 'pt2patlist'
print(x, ...)

## S3 method for class 'pt2celllist'
format(x, ...)

## S3 method for class 'pt2celllist'
print(x, ...)

## S3 method for class 'pt2samplist'
format(x, ...)

## S3 method for class 'pt2samplist'
print(x, ...)

## S3 method for class 'pt2mod'
as.raw(x, ...)

## S3 method for class 'pt2samp'
as.raw(x, ...)

## S3 method for class 'pt2samp'
as.integer(x, ...)

## S3 method for class 'pt2celllist'
length(x, ...)

## S3 method for class 'pt2command'
length(x, ...)

Arguments

x

Object to apply S3 method to. See 'usage' section for allowed object types.

...

Passed on to other methods.

padding

A vector of character strings used to pad between note and instrument number (element 1) and between instrument number and effect command (element 2). Values are recycled.

empty_char

A vector of single character values used to represent empty pattern elements. First element is used for notes, second for instrument number, the third for effect commands (see also vignette("effect_commands")). Values are recycled.

fmt

Experimental feature to format a pt2cell. It should be a named list containing formatting strings for elements in the cell. It should contain the elements "note", "padding", "instrument" and "effect". Its implementation may change in future releases.

max.print

Maximum number of elements to be printed.

sep

A separator character string for concatenating pattern table columns (i.e. channels).

show_header

A logical value indicating if a header should be shown for the pattern table.

show_row

A logical value indicating if the row of a pattern table should be labelled with its index.

compact

Should the pattern be formatted using a compact notation (as used for file storage), or a none-compact format as used by the player? This can be set with the compact argument.

Value

The following is returned by the different methods:

format: a formatted character representation of the object
print: same as format
as.character: same as format
as.raw: a raw representation of the object. In many cases it inherits the same class as x
as.integer: converted raw 8 bit sample data to signed pulse code modulation integer values between -128 and +127.
length returns number of elements in x

Play a ProTracker module

Description

Renders a ProTracker module as audio::audioSample() and plays it.

Usage

## S3 method for class 'pt2mod'
play(x, duration = NA, options = pt2_render_options(), position = 0L, ...)

Arguments

x

Object to be played.

duration

Duration of the rendered output in seconds. When set to NA the duration of the module is calculated and used for rendering.

options

A list of options used for rendering the audio. Use pt2_render_options() to obtain default options, or modify them.

position

Starting position in the pattern sequence table (pt2_pattern_table()). Should be a non negative value smaller than the mule length (pt2_length()).

...

Arguments passed to pt2_render().

Value

Returns an ⁠[audio::⁠$.audioInstance⁠]⁠ object which allows you to control the playback (pause, resume, rewind).

Author(s)

Pepijn de Vries

Examples

## Not run: 
mod <- pt2_read_mod(pt2_demo())

## ctrl will contain the audioInstance that will let you control the audio playback:
ctrl <- play(mod)

## End(Not run)

Select a cell from a ProTracker pattern table

Description

A cell is an element at a specific row and column (channel). It holds information aboute the note to be played, the instrument (sample) number and the effect to be applied. For mor information about cells (class pt2cell) consult vignette("s3class"). For more information about selecting elements from ProTrackR2 class objects check out vignette("select_opts").

Usage

pt2_cell(pattern, i, j, ...)

Arguments

pattern

A pt2pat class object to extract a cell (pt2cell) from.

i, j

Indices for extracting or replacing ProTrackR2 object elements. The indices starts at 0, for consistency with ProTracker!

...

Ignored

Value

Returns a cell object from the table as class pt2cell.

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())

pt2_cell(mod$patterns[[1]], 0L, 0L)

Extract effect commands from a ProTracker module

Description

As explained in vignette("s3class"), the ProTracker pattern table consists of cells, containing information about the note and instrument to be played. This function can be used to retrieve or replace the effect commands in a module.

Usage

pt2_command(x, ...)

pt2_command(x, silent = TRUE, ...) <- value

Arguments

x

An object of class pt2cell, which can be extracted from a pattern table with pt2_cell(). A cell list (class pt2celllist) is also allowed. See vignette("sel_assign") for more details about selecting cells and cell lists.

...

Ignored

silent

Don't warn about replacement values not being used or recycled.

value

A replacement value. It should be an object that can be converted into an effect command. It can be a character string as shown in the example below.

Value

Returns a pt2command object containing the raw command code. In case of the assign operator (⁠<-⁠) an update version of x is returned.

Examples

mod <- pt2_read_mod(pt2_demo())

## select a specific cell from the module
cell <- pt2_cell(mod$patterns[[1]], 0L, 0L)

## show the command used for this cell
pt2_command(cell)

## convert character strings into ProTracker commands
pt2_command(c("C30", "F06"))

## Set the command for all cells in the first pattern
## to `C20` (volume at 50%):
pt2_command(mod$patterns[[1]][]) <- "C20"

Path to demonstration ProTracker module file

Description

A path to demonstration ProTracker module file. It can be used for demonstration purposes.

Usage

pt2_demo()

Value

Returns a string with a path of a ProTracker module file

Author(s)

Pepijn de Vries

Calculate the duration of the module

Description

How long a module will play depends on several aspects such as the length of the pattern sequence table (pt2_pattern_table(), pt2_length()), the speed and tempo at which the patterns are defined, loops, pattern breaks and delay effects. The duration in seconds of the module is calculated by this function.

Usage

pt2_duration(x, options = pt2_render_options(), position = 0L, ...)

Arguments

x

Object for which to determine the duration. Should be of class pt2mod.

options

A list of options used for rendering the audio. Use pt2_render_options() to obtain default options, or modify them.

position

Starting position in the pattern sequence table (pt2_pattern_table()). Should be a non negative value smaller than the mule length (pt2_length()).

...

Ignored

Value

The duration in seconds (as a difftime class object)

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())

pt2_duration(mod)

Extract or replace a sample index from a ProTracker pattern

Description

As explained in vignette("s3class"), the ProTracker pattern table consists of cells containing information about the note and instrument to be played. This function extracts the sample index (instrument) from such a cell.

Usage

pt2_instrument(x, ...)

pt2_instrument(x, silent = TRUE, ...) <- value

Arguments

x

...

Ignored.

silent

Don't warn about replacement values not being used or recycled.

value

Replacement value for the instrument (sample id). An integer value ranging from 0 to 31.

Value

Returns the integer sample index in x. The index has a base of 1. An index of 0 means 'no sample'. In case of the assignment operator (⁠<-⁠) an updated version of x is returned

Examples

mod <- pt2_read_mod(pt2_demo())

## select a specific cell from the first pattern
cell <- pt2_cell(mod$patterns[[1]], 0L, 0L)

## get the sample number used in this cell
pt2_instrument(cell)

## Replace the instrument in all cells of
## pattern 1 with sample number 3:
pt2_instrument(mod$patterns[[1]][]) <- 3

Obtain ProTracker module information

Description

Obtain information about a protracker module or embedded samples.

Usage

pt2_length(mod, ...)

pt2_length(mod, ...) <- value

pt2_n_pattern(mod, ...)

pt2_pattern_table(mod, ...)

pt2_name(x, ...)

## S3 method for class 'pt2mod'
pt2_name(x, ...)

## S3 method for class 'pt2samp'
pt2_name(x, ...)

pt2_n_sample(mod, ...)

Arguments

...

Ignored

value

New length of a module in number of patterns in the pattern sequence table.

x, mod

A pt2mod class object for which to obtain information. For x also samples of class pt2samp are allowed as input.

Value

Returns information about the specified ProTracker module

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())

pt2_length(mod)
pt2_n_pattern(mod)
pt2_n_sample(mod)
pt2_pattern_table(mod)
pt2_name(mod)

Create a new (empty) ProTracker module

Description

Creates an empty ProTracker module, it is returned as a pt2mod class object.

Usage

pt2_new_mod(name, ...)

Arguments

name

Name for the new module. It will be truncated if longer than 20 characters.

...

Ignored

Value

A pt2mod class module, with no samples and one empty pattern.

Author(s)

Pepijn de Vries

Examples

mod <- pt2_new_mod("my_song")

Create a new ProTracker pattern

Description

Creates a new ProTracker pattern, consisting of four channels and 64 rows.

Usage

pt2_new_pattern(..., compact = TRUE)

Arguments

...

Currently ignored

compact

Should the pattern be formatted using a compact notation (as used for file storage), or a none-compact format as used by the player? This can be set with the compact argument.

Value

Returns a new clean pt2pat object.

Author(s)

Pepijn de Vries

Examples

pt2_new_pattern()

Extract a note from a ProTracker module

Description

Gets note information from a cell in a pattern table in a ProTracker Module.

Usage

pt2_note(x, ...)

pt2_note(x, silent = TRUE, ...) <- value

Arguments

x

...

Ignored

silent

Don't warn about replacement values not being used or recycled.

value

A character string to replace the selected notes from x.

Details

A string representing the note's key is returned by the function. The first letter indicates the position of the note in the diatonic scale. The second character indicates if it is a sharp key (with a hash symbol, and a dash if it is not). The third character indicates the octave of the note. In ProTracker allowed notes range from "C-1" to "B-3".

Value

Returns a string representing the note's key.

Examples

mod <- pt2_read_mod(pt2_demo())

## select a specific cell from the first pattern
cell <- pt2_cell(mod$patterns[[1]], 0L, 0L)

## get the note played by this particular cell
pt2_note(cell)

## Replace the notes in the first pattern
## with those of the first bar of
## 'Frère Jacques'
pt2_note(mod$patterns[[1]][]) <-
  c("C-2", "---", "---", "---",
    "D-2", "---", "---", "---",
    "E-2", "---", "---", "---",
    "C-2", "---", "---", "---")

Get a corresponding period value from a note string

Description

Back in the days, ProTracker was hardware driven on a Commodore Amiga. It made advantage of a custom chipset where each chip had specific tasks. One of the chips (named Paula) could play 8 bit audio samples stored in memory directly to one of the four audio channels. On that chip you could set the integer 'period' value which is inversely related to the sample rate at which the sample is played. Hence, it defines the pitch of the sample. ProTracker used the period value to play different notes. With this function you can convert a character string representing a note to its corresponding period value used by Paula.

Usage

pt2_note_to_period(note, empty_char = "-", finetune = 0, ...)

Arguments

note

A character string representing notes (see also pt2_note()).

empty_char

A character that is used to represent empty values.

finetune

ProTracker used integer finetune values to tweak the playback rate. it should be in the range of -8, up to +7.

...

Ignored.

Value

Returns a vector of integer period values.

Examples

pt2_note_to_period(c("A#2", "C-1"))

Retrieve a pattern from a ProTracker module

Description

Get a pattern table (sequence of notes and effects on each of the 4 channels) at a specific index from a ProTracker module.

Usage

pt2_pattern(mod, i, ...)

Arguments

mod

A pt2mod class objects from which to retrieve a pattern table

i

The index (integer) of the pattern. Note that the index starts at 0.

...

Ignored

Value

A pt2pat object representing the pattern.

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())

pt2_pattern(mod, 0L)

Read and write ProTracker modules

Description

Functions to read and write ProTracker module. The read function will read a number of mod files that are compatible with ProTracker, this includes files compressed with PowerPacker (PP). The write function will only write modules conform ProTracker specifications.

Usage

pt2_read_mod(file, ...)

pt2_write_mod(mod, file, ...)

Arguments

file

Filename of the file to read from or write to.

...

Ignored

mod

An object of class pt2mod.

Value

pt2_read_mod() returns a pt2mod class object when successful. pt_write_mod() returns NULL invisibly.

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())

Read and write ProTracker audio samples

Description

Functions to read and write ProTracker audio samples. Reading is supported for common types of WAV, IFF and AIFF files. Writing is supported for WAV and IFF files.

Usage

pt2_read_sample(file, ...)

pt2_write_sample(sample, file, ...)

Arguments

file

Filename of the file to read from or write to. For pt2_write_sample() the file extension will be used to determine which file format to write.

...

Ignored

sample

An object of class pt2samp.

Value

pt2_read_sample() returns a pt2samp class object when successful. pt_write_sample() returns NULL invisibly.

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())
my_sample <- pt2_sample(mod, 1L)
my_sample_file <- tempfile(fileext = ".iff")
pt2_write_sample(my_sample, my_sample_file)

Render ProTracker modules to a playable format

Description

Renders a 16bit pulse-code modulation waveform from a ProTracker module. The rendered format can be played on a modern machine.

Usage

pt2_render(x, duration = NA, options = pt2_render_options(), ...)

## S3 method for class 'pt2mod'
pt2_render(
  x,
  duration = NA,
  options = pt2_render_options(),
  position = 0L,
  ...
)

Arguments

x

The object to be rendered

duration

Duration of the rendered output in seconds. When set to NA the duration of the module is calculated and used for rendering.

options

A list of options used for rendering the audio. Use pt2_render_options() to obtain default options, or modify them.

...

Ignored

position

Starting position in the pattern sequence table (pt2_pattern_table()). Should be a non negative value smaller than the mule length (pt2_length()).

Value

Rendered audio inheriting the audio::audioSample() class.

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())
aud <- pt2_render(mod)

Retrieve options for rendering

Description

Retrieve options for rendering ProTracker modules. See also pt2_render().

Usage

pt2_render_options(...)

Arguments

...

Specify custom options.

Value

Returns a named list of options that can be used for rendering ProTracker modules (see pt2_render() and play()). It contains the following elements:

sample_rate: an integer value specifying the sample rate of the output in Hz.
stereo_separation: an integer percentage determining how much the tracker channels will be separated to the left and right stereo output channels.
amiga_filter: a character string specifying the hardware filter to be emulated. Can be "A500" for emulating Amiga 500 hardware filters, or "A1200" for emulating Amiga 1200 hardware filters.
speed: An integer value specifying the initial speed of the module measured in 'ticks' per row. Should be in range of 1 and 31.
tempo: An integer value specifying the initial tempo of the module. When speed is set to 6, it measures the tempo as beats per minute. Should be in the range of 32 and 255
led_filter: A logical value specifying the state of the hardware LED filter to be emultated.

Author(s)

Pepijn de Vries

Examples

pt2_render_options(stereo_separation = 100)

Obtain sample data and info from a ProTracker module

Description

Obtain sample data and info from a ProTracker module at a specific index. ProTracker modules can hold up to 31 samples. The index should range from 0 to 30.

Usage

pt2_sample(mod, i, ...)

Arguments

mod

An object of class pt2mod from which to obtain sample data and information

i

The index of the requested sample (between 0 and 30).

...

Ignored.

Value

Returns a sample object of class pt2samp.

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())

smp <- pt2_sample(mod, 0L)

Validate ProTrackR2 S3 class objects

Description

Check aspects of S3 class objects for validity. For samples for instance it is checked if all parameters (volume, finetune, etc.) are within ProTracker specifications.

Usage

pt2_validate(x, ...)

## S3 method for class 'pt2samp'
pt2_validate(x, ...)

Arguments

x

object to be validated

...

Ignored

Value

A logical value indicating whether the object is valid or not

Author(s)

Pepijn de Vries

Examples

mod <- pt2_read_mod(pt2_demo())

pt2_validate(mod$samples[[1]])

ProTrackR2: Manipulate and Play 'ProTracker' Modules

Description

Author(s)

See Also

Select and assign operators for ProTrackR2 S3 class objects

Description

Usage

Arguments

Value

Format a ProTracker pattern conform OpenMPT specs

Description

Usage

Arguments

Value

Author(s)

Examples

Effect commands (data.frame)

Description

Format

Examples

Implementation of basic S3 methods

Description

Usage

Arguments

Value

Play a ProTracker module

Description

Usage

Arguments

Value

Author(s)

Examples

Select a cell from a ProTracker pattern table

Description

Usage

Arguments

Value

Author(s)

Examples

Extract effect commands from a ProTracker module

Description

Usage

Arguments

Value

Examples

Path to demonstration ProTracker module file

Description

Usage

Value

Author(s)

Calculate the duration of the module

Description

Usage

Arguments

Value

Author(s)

Examples

Extract or replace a sample index from a ProTracker pattern

Description

Usage

Arguments

Value

Examples

Obtain ProTracker module information

Description

Usage

Arguments

Value

Author(s)

Examples

Create a new (empty) ProTracker module

Description

Usage

Arguments

Value

Author(s)

Examples

Create a new ProTracker pattern

Description

Usage