crayolon.portamod
Class PortaMod

java.lang.Object
  crayolon.portamod.PortaMod

public class PortaMod
extends java.lang.Object

PortaMod - a MOD/XM/S3M replayer library for Processing by Brendan Ratliff (aka Crayolon, aka Syphus of UpRough) Based on IBXM by Martin Cameron (© 2008) Fundamentally, PortaMod is a Processing implementation of IBXM so that the Processing community can benefit from the advantages that oldschool 'tracker' formats offer. Compared to WAV/MP3/OGG, these advantages include small file-size, the ability to synchronise visuals and other triggered events to events in the music (e.g. synching a screenflash to a particular note, at a particular time and volume) and the possibility for allowing extensive user interaction with the music itself. Compared to MIDI, tracked formats use instruments based on samples which sound the same on any replayer system, rather than being dependent on varying MIDI-synths. Though oldschool 4-channel chiptunes can be as small as 3 kilobytes, complex and high- quality music can be arranged in an XM of up to 32 channels, often matching mp3 quality but with a reduced filesize. PortaMod builds quite heavily on IBXM in the control features it offers, while retaining IBXM's efficiency and reliable handling of these formats and their idiosyncrasies. Its diverse range of methods is intended to give the Processing community a very granular relationship with tracked audio data, which can either be found amongst the gigabytes of free modules available online or created with trackers such as ProTracker (Amiga), FastTracker (MS-DOS), ScreamTracker (MS-DOS), or the modern-day and very cross-platform MilkyTracker - www.milkytracker.org Feedback always appreciated - echolevel@gmail.com Special thanks to Peter Quayle (parapete), Paul Carpenter (Vampire^TZT) and Anders Carlsson (goto80), for help and bugtesting; to Joey Scully (dataprole) and Jamie Allen for advice; to Martin Cameron (of course!) for IBXM :D

Author:

Brendan Ratliff

Field Summary

int	bpmvalue
CellContent[]	cellcontent
int[]	chantranspose
CellContent[]	content
java.util.ArrayList<CurrentPattern>[]	currentpatternrows
int	delayedchannel
java.util.ArrayList<CustomNote>	delayednotes
CustomNote[]	delaynotes
Player	delayplayerA
java.lang.String	filepath
int	globvol
java.lang.String[]	infotext
int	initialtempo
int	interpolation
int	jamcounter
int	loadSuccess
byte[]	localmod_header
NoteData	localnotes
boolean	looping
int[]	looplength
int[]	loopstart
float	maxVol
float	minVol
byte[]	mod_header
java.lang.String	modtype
boolean	muted
int	numchannels
int	numinstruments
int	numpatterns
java.util.ArrayList<Instrument>	oldsamples
int[]	origlooplength
int[]	origloopstart
boolean	paused
Player	player
boolean	playing
int[]	sampledatalength
int	sequencecounter
long	songLength
long	songPosition
long	songStart
NoteData	thisrow
int	transpose
java.lang.String	VERSION
javax.sound.sampled.FloatControl	volCtrl

Constructor Summary

PortaMod(PApplet p)
a Constructor, usually called in the setup() method in your sketch to initialize and start the library.

Method Summary

void	channelDelay(int chan, int delaytime, int delaysend) channelDelay(int, int, int) - OMG this'll be so awesome if it works.
void	customkeyDown(int note, int inst, java.lang.String vol, java.lang.String effect, java.lang.String effparam) customkeyDown(int, int, String, String, String) takes note, instrument, volume, effect and effect-parameter and uses them to override playing notes in the selected channel.
void	customkeyUp(int note, int inst) customkeyUp(int, int) takes note and instrument numbers and flips the relevant keydown switch to off.
void	delaykeyDown(int note, int inst, int vol, int effect, int effparam) delaykeyDown(int, int, int, int, int) takes note, instrument, volume, effect and effect-parameter and uses them to override playing
void	delayTap1(int channel, int volume)
void	doIt(IBXM instance, NoteData notedata) Callback from the replayer engine.
int	doModLoad(java.lang.String tune, boolean autostart, int startVol) Load the MOD/XM/S3M module by filepath string.
void	effector(int chan, java.lang.String effect, java.lang.String effparam) effector(int, String, String) - quite experimental for now.
boolean	getChanmute(int chan) getChanmute(int) returns the mute status of a channel as a boolean - true for muted, false for unmuted.
int	getChanvol(int chan) getChanvol(int) takes a channel as its argument and returns that channel's current volume as an int between 0 and 64.
int	getCurrent_row() getCurrent_row() returns the current row at the current sequence position as an int
int	getCurrent_sequence_index() getCurrent_sequence_index
int	getGlobvol() getGlobvol()
int	getNext_row() getNext_row() returns the sequence number of the next pattern due to be played
int	getNext_sequence_index() getNext_sequence_index() returns the sequence number of the next pattern due to be played
float	getPanning() getPanning() returns the current panning value for this instance as a flot of between -1.0f and 1.0f, where 0 is the centre-position.
int	getSeek() getSeek() returns the current position of the song in milliseconds as an int.
int	getTempo() getTempo() returns an int of between 32 and 255 indicating the playing module's current BPM tempo.
java.lang.String	getTitle() getTitle() returns a string containing the module's title.
float	getVol() getVol() - returns the current overall volume as a float of between -40.0f and 6.020f
boolean	headerCheck(java.lang.String tune) headerCheck(String) takes the file path of a module, returns a boolean (true if the module is a valid MOD/S3M/XM file) and updates 'modtype'.
void	loopLength(int inst, int newlooplength)
void	loopReset(int inst) loopReset(inst) takes the chosen instrument and resets the loop start/end points to the originals.
void	loopStart(int inst, int newloopstart) loopAdjust(inst, loopstart, looplength) takes an instrument number and two percentage values.
void	mute() Mute audio (playback continues)
java.lang.String	noteConvert(int noteval) Returns a formatted tracker-style representation of a given decimal note along with its octave and either an accidental or a hyphen, e.g.
void	pause() Pause playback
void	play() Start playback, or resume playback after pause
void	sampleDump()
void	sampleRestore(int idx) sampleRestore(int) takes the index of a sample you've replaced and restores the original sample.
void	sampleSwap(int idx, java.lang.String inputpath, int offset) sampleSwap(int, byte[]) takes a MOD sample number and the path to a new sample, then replaces the extant sampledata with the new.
void	setChanmute(int chan, boolean flip) setChanmute(int, boolean) takes a channel-number as an int and and a boolean to mute or unmute that channel.
void	setChanvol(int chan, int vol) setChanvol(int, int) takes the channel number and the desired channel volume - it will override the channel's mixing volume, possibly with some unexpected consequences (such as more 'clipped'-sounding volume slides), and may be overridden by some varieties of volume change command in the module's patterndata.
void	setGlobvol(int vol) setGlobvol(int)
void	setInterpolation(int interp) setInterpolation(int) sets the mixing interpolation to 'none' (0), 'linear' (1) or 'sinc' (2).
void	setNext_row(int newrow) setNext_row(int) takes the number of the desired next row in the current pattern.
void	setNext_sequence_index(int newpos, int behaviour) setNext_sequence_index(newpos, behaviour) takes the desired new sequence position and an int 0 or 1 to choose between 'continuous' pattern-skip behaviour (where the row in the new pattern follows smoothly from the row in the old pattern) and 'play from start' behaviour, where the new pattern plays from row 0.
void	setOverridetempo(boolean flip) setOverridetempo() switches tempo override on or off.
void	setPanning(float panval) setPanning(float) takes a float from -1.0f to 1.0f to pan the overall audio output across the stereo spectrum.
void	setSeek(int newpos) setSeek(int) sets the current position of the song in milliseconds, from an int parameter.
void	setSongloop(boolean flip) loopSong() switches song-looping on or off.
void	setStereosep(int percentage) setStereosep(int) takes a percentage for desired MOD stereo spread.
void	setTempo(int tempo) setTempo(int) adjusts tempo in beats-per-minute when given an int value between 32 and 255
void	setTranspose(int chan, int trans) setTranspose(int, int) shifts playback key up or down by 12 semitones, while retaining tempo.
void	setVol(float newvol) setVol(float) adjusts overall volume.
void	stop()
java.lang.String	version() return the version of the library.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

filepath

public java.lang.String filepath

sequencecounter

public int sequencecounter

interpolation

public int interpolation

globvol

public int globvol

paused

public boolean paused

loadSuccess

public int loadSuccess

mod_header

public byte[] mod_header

localmod_header

public byte[] localmod_header

delayedchannel

public int delayedchannel

looping

public boolean looping

transpose

public int transpose

minVol

public float minVol

maxVol

public float maxVol

playing

public boolean playing

muted

public boolean muted

songStart

public long songStart

songLength

public long songLength

songPosition

public long songPosition

numchannels

public int numchannels

numinstruments

public int numinstruments

bpmvalue

public int bpmvalue

initialtempo

public int initialtempo

numpatterns

public int numpatterns

infotext

public java.lang.String[] infotext

volCtrl

public javax.sound.sampled.FloatControl volCtrl

player

public Player player

delayplayerA

public Player delayplayerA

localnotes

public NoteData localnotes

thisrow

public NoteData thisrow

currentpatternrows

public java.util.ArrayList<CurrentPattern>[] currentpatternrows

oldsamples

public java.util.ArrayList<Instrument> oldsamples

delayednotes

public java.util.ArrayList<CustomNote> delayednotes

delaynotes

public CustomNote[] delaynotes

chantranspose

public int[] chantranspose

origloopstart

public int[] origloopstart

origlooplength

public int[] origlooplength

loopstart

public int[] loopstart

looplength

public int[] looplength

sampledatalength

public int[] sampledatalength

cellcontent

public CellContent[] cellcontent

content

public CellContent[] content

modtype

public java.lang.String modtype

jamcounter

public int jamcounter

VERSION

public final java.lang.String VERSION

See Also:

Constant Field Values

Constructor Detail

PortaMod

public PortaMod(PApplet p)

a Constructor, usually called in the setup() method in your sketch to initialize and start the library.

Parameters:

p -

Method Detail

version

public java.lang.String version()

return the version of the library.

Returns:

String

getTitle

public java.lang.String getTitle()

getTitle() returns a string containing the module's title.

Returns:

play

public void play()

Start playback, or resume playback after pause

pause

public void pause()

Pause playback

getVol

public float getVol()

getVol() - returns the current overall volume as a float of between -40.0f and 6.020f

setVol

public void setVol(float newvol)

setVol(float) adjusts overall volume. Checks for min/max limits to avoid crashes.

mute

public void mute()

Mute audio (playback continues)

setTranspose

public void setTranspose(int chan,
                         int trans)

setTranspose(int, int) shifts playback key up or down by 12 semitones, while retaining tempo. If chan is set to -1, all channels are transposed.

getTempo

public int getTempo()

getTempo() returns an int of between 32 and 255 indicating the playing module's current BPM tempo.

setTempo

public void setTempo(int tempo)

setTempo(int) adjusts tempo in beats-per-minute when given an int value between 32 and 255

getPanning

public float getPanning()

getPanning() returns the current panning value for this instance as a flot of between -1.0f and 1.0f, where 0 is the centre-position.

setPanning

public void setPanning(float panval)

setPanning(float) takes a float from -1.0f to 1.0f to pan the overall audio output across the stereo spectrum. The centre-point is 0.

getChanmute

public boolean getChanmute(int chan)

getChanmute(int) returns the mute status of a channel as a boolean - true for muted, false for unmuted.

setChanmute

public void setChanmute(int chan,
                        boolean flip)

setChanmute(int, boolean) takes a channel-number as an int and and a boolean to mute or unmute that channel. Check the mute status of the channel first with getChanmute(channel).

setSongloop

public void setSongloop(boolean flip)

loopSong() switches song-looping on or off. mymod.looping shows the current status.

getChanvol

public int getChanvol(int chan)

getChanvol(int) takes a channel as its argument and returns that channel's current volume as an int between 0 and 64. This is the final volume given to the mixer engine after volume command/tremolo/envelope/global levels have been calculated.

Parameters:

chan -

Returns:

int

setChanvol

public void setChanvol(int chan,
                       int vol)

setChanvol(int, int) takes the channel number and the desired channel volume - it will override the channel's mixing volume, possibly with some unexpected consequences (such as more 'clipped'-sounding volume slides), and may be overridden by some varieties of volume change command in the module's patterndata.

setGlobvol

public void setGlobvol(int vol)

setGlobvol(int)

getGlobvol

public int getGlobvol()

getGlobvol()

setStereosep

public void setStereosep(int percentage)

setStereosep(int) takes a percentage for desired MOD stereo spread. 100 gives full Amiga hard-panning while 0 centres all channels. This only works on 4 or 8 channel files that are verified as being MODs. Panning arrangement is 1:L 2:R 3:R 4:L(5:L 6:R 7:R 8:L). Just to be clear, this has no effect on XM or S3M files!

setInterpolation

public void setInterpolation(int interp)

setInterpolation(int) sets the mixing interpolation to 'none' (0), 'linear' (1) or 'sinc' (2). Default is 0.

Parameters:

interp -

getSeek

public int getSeek()

getSeek() returns the current position of the song in milliseconds as an int.

Returns:

songSeek

setSeek

public void setSeek(int newpos)

setSeek(int) sets the current position of the song in milliseconds, from an int parameter.

setOverridetempo

public void setOverridetempo(boolean flip)

setOverridetempo() switches tempo override on or off. Many modules have tempo commands scattered throughout which can reset the BPM - sometimes it's desirable to avoid this when trying to run an entire module at a custom BPM. Use this in conjunction with bpm()

sampleSwap

public void sampleSwap(int idx,
                       java.lang.String inputpath,
                       int offset)

sampleSwap(int, byte[]) takes a MOD sample number and the path to a new sample, then replaces the extant sampledata with the new. Expect this to be highly buggy and prone to exceptions - seems safe with samples below 25kb, as long as they're RAW or IFF and 8bit/mono/22050

Parameters:

idx -

data_input -

sampleRestore

public void sampleRestore(int idx)

sampleRestore(int) takes the index of a sample you've replaced and restores the original sample.

Parameters:

idx -

doModLoad

public int doModLoad(java.lang.String tune,
                     boolean autostart,
                     int startVol)

Load the MOD/XM/S3M module by filepath string. If the second parameter is false, the module will not automatically start to play. The third parameter is the starting volume as a float value between -40.0f and 6.020f. Start at the bottom if you want to fade a module in.

Returns:

int

delayTap1

public void delayTap1(int channel,
                      int volume)

doIt

public void doIt(IBXM instance,
                 NoteData notedata)

Callback from the replayer engine. This fires an event notifier so that the contents of the current NoteData object at any given time can be accessed from a sketch. One suggested use is to set a boolean switch when some notedata fulfills a condition so that, for instance, a visual effect in the sketch can be triggered in sync.

noteConvert

public java.lang.String noteConvert(int noteval)

Returns a formatted tracker-style representation of a given decimal note along with its octave and either an accidental or a hyphen, e.g. D#3 or C-2

Returns:

String

headerCheck

public boolean headerCheck(java.lang.String tune)

headerCheck(String) takes the file path of a module, returns a boolean (true if the module is a valid MOD/S3M/XM file) and updates 'modtype'.

Returns:

boolean

customkeyDown

public void customkeyDown(int note,
                          int inst,
                          java.lang.String vol,
                          java.lang.String effect,
                          java.lang.String effparam)

customkeyDown(int, int, String, String, String) takes note, instrument, volume, effect and effect-parameter and uses them to override playing notes in the selected channel. inst, effect and effparam should be set to '0' if unused, while volume must always be set (between 0 and 40), as must channel.

delaykeyDown

public void delaykeyDown(int note,
                         int inst,
                         int vol,
                         int effect,
                         int effparam)

delaykeyDown(int, int, int, int, int) takes note, instrument, volume, effect and effect-parameter and uses them to override playing

channelDelay

public void channelDelay(int chan,
                         int delaytime,
                         int delaysend)

channelDelay(int, int, int) - OMG this'll be so awesome if it works. The idea is to use one or more jam channels to do a classic tracker multipattern delay on the notes in the specified channel. This could be fucking dubtastic. If this shit works for 1x feedback, I want to do it for more... Takes the target channel, the time in rows by which the delayed notes should be delayed and the desired mix volume of the delayed notes. Hmm. Every row...I'll need to read the current target note and store it in an array. I'll also play current-n note in a jamchannel at half volume. If the array is empty, do nothing. Should delay status be checked for on every row, during all playback? I could just check backwards by and play what's there. If it's at the start of the song, there won't be anything to play. Call the function every time a row callback comes in IF delay is enabled. Cos this arraylist stuff is clearly bullshit...

Parameters:

chan -

rowlength -

effector

public void effector(int chan,
                     java.lang.String effect,
                     java.lang.String effparam)

effector(int, String, String) - quite experimental for now. Supports E9X retrigger, AXX volume slide, 0XX arpeggio, 2XX porta down and 1XX porta up, with extremely varying degrees of success. Other effect commands simply are simply ignored for the time being. Some effects will be impossible/impractical to support, while many would be pointless in this context.

customkeyUp

public void customkeyUp(int note,
                        int inst)

customkeyUp(int, int) takes note and instrument numbers and flips the relevant keydown switch to off. Use -1 as the parameter to disable keydowns for all channels.

loopStart

public void loopStart(int inst,
                      int newloopstart)

loopAdjust(inst, loopstart, looplength) takes an instrument number and two percentage values. loopstart sets the looping start-point to the desired percentage offset of the sample, while looplength sets the end-point to a percentage of the remaining sampleduration (from loopstart to the end of the sample). If looplength is -1, it's taken to be the full length of the sample. Warning: this is FLAKY. I might disable loopstart altogether, since it's causing real problems...more logic needed.

loopLength

public void loopLength(int inst,
                       int newlooplength)

loopReset

public void loopReset(int inst)

loopReset(inst) takes the chosen instrument and resets the loop start/end points to the originals.

Parameters:

inst -

sampleDump

public void sampleDump()

getCurrent_sequence_index

public int getCurrent_sequence_index()

getCurrent_sequence_index

getCurrent_row

public int getCurrent_row()

getCurrent_row() returns the current row at the current sequence position as an int

getNext_sequence_index

public int getNext_sequence_index()

getNext_sequence_index() returns the sequence number of the next pattern due to be played

Returns:

getNext_row

public int getNext_row()

getNext_row() returns the sequence number of the next pattern due to be played

Returns:

setNext_sequence_index

public void setNext_sequence_index(int newpos,
                                   int behaviour)

setNext_sequence_index(newpos, behaviour) takes the desired new sequence position and an int 0 or 1 to choose between 'continuous' pattern-skip behaviour (where the row in the new pattern follows smoothly from the row in the old pattern) and 'play from start' behaviour, where the new pattern plays from row 0. Do the logic in your sketch using, for instance, getCurrent_sequence_index, to determine how to skip back or forward in your chosen increments.

setNext_row

public void setNext_row(int newrow)

setNext_row(int) takes the number of the desired next row in the current pattern.

stop

public void stop()