Effect options and methods

Erik Loyer edited this page Mar 21, 2017 · 14 revisions

Stepwise effects provide more robust output handling with minimal effort. Effects bundle commonly used functionality into discrete modules, including the ability to direct output from individual characters to separate DOM elements.

Abstract effect

These base options and methods are available to all effects (though for specific effects, some may be more relevant than others).

Options

Option Description
useCharacterNames Prepends the name of the character to their steps. Useful for distinguishing individuals when the dialogue of multiple characters is directed to a single DOM element. Defaults to true.
createBreakTags Converts line breaks in step content (\r, \n, and \r\n) to <br> tags. Defaults to true.
includeTemporal Displays the temporal events setDate and setTime as visible text showing the current date or time. Defaults to true.
includeEnvironmental Displays the environmental event setTemperature as visible text showing the current temperature. Defaults to true.
includeGeographic Displays the geographic event setLocation as visible text showing the name of the current location. Defaults to true.

Methods

Method Description
addDisplayStepListener(function(step, element) {}) Adds the given function to the list of functions that will be called when the effect shows a visible step. The current step and the element where it is being displayed are passed as parameters.
bindCharacterToElement(characterId, elementSelector) Designates a DOM element where visible steps executed by the character with the given id are to be displayed.
bindToElement(element) Designates a DOM element where all visible steps from all characters will be displayed.
bindToInstance(stepwiseInstance) Sets the specific Stepwise instance to which the effect will be applied.
getVisibleCharacterCount() Returns the number of characters capable of displaying visible steps in the current script (useful for creating layouts which automatically adapt to varying numbers of characters).
removeDisplayStepListener(listener) Removes the given handler from the list of currently active functions called when the effect shows a visible step.
unbindCharacterFromElement(characterId, element) Removes the binding between the character with the given id and the specified element.
unbindFromElement(element) Removes any binding between all characters and the given element.

GibberSynth effect

The GibberSynth effect makes the Gibber.lib.js library and its synthesizers available to Stepwise. When a character whose id matches the name of a Gibber synth patch speaks a note name, that note will be played using the patch.

GibberSynth supports General MIDI patch names like baritonesax as well as General MIDI family names like chromaticpercussion which are mapped (somewhat arbitrarily) to Gibber synth presets.

To use this effect, first make sure you've made it and Gibber.lib.js available to the page:

<script type="text/javascript" src="js/libs/Gibber.lib.js"></script>
<script type="text/javascript" src="js/effects/GibberSynth.js"></script>

Here's a typical usage:

// Load a script
$("#output").stepwise({source:"myscript.xml", dataType:"xmlfile",
	handleLoad: function(instance) {
		// Initialize the effect and bind it to the instance
		var gibberSynth = new $.fn.stepwise.effects.GibberSynth(instance);
	}
});

Using the General MIDI patch or family names will make your script more compatible with future Stepwise music effects. If you must target a specific Gibber sound, however, you can use the following character ids:

Character id Gibber preset
gibberdrumkick 808 Emulator, kick
gibberdrumsnare 808 Emulator, snare
gibberdrumhat 808 Emulator, hi hat (closed)
gibberhatopen 808 Emulator, hi hat (open)
gibbercowbell 808 Emulator, cowbell
gibberclave 808 Emulator, clave
gibbertom 808 Emulator, tom
gibbersynthshort Synth, "short" preset
gibbersynthbleep Synth, "bleep" preset
gibbersynthrhodes Synth, "rhodes" preset
gibbersynthcalvin Synth, "calvin" preset
gibbermonoshort Mono, "short" preset
gibbermonobass Mono, "bass" preset
gibbermonowinsome Mono, "windome" preset
gibbermonodark Mono, "dark" preset
gibbermonodark2 Mono, "dark2" preset
gibbermonoeasy Mono, "easy" preset
gibbermonoeasyfx Mono, "easyfx" preset
gibbermononoise Mono, "noise" preset
gibbermonolead Mono, "lead" preset
gibbermonobass FM, "bass" preset
gibberfmstabs FM, "stabs" preset
gibberfmgong FM, "gong" preset
gibberfmdrum FM, "drum" preset
gibberfmdrum2 FM, "drum2" preset
gibberfmbrass FM, "brass" preset
gibberfmclarinet FM, "clarinet" preset
gibberfmglockenspiel FM, "glockenspiel" preset
gibberfmnoise FM, "noise" preset
gibberpluck Pluck

Slabtext Effect

The Slabtext effect uses the jQuery port of the Slabtype algorithm to display text which is automatically sized to fill the screen.

To use this effect, first make sure you've made it and the Slabtext plugin available to the page:

<script type="text/javascript" src="js/libs/jquery.slabtext.min.js"></script>
<script type="text/javascript" src="js/effects/Slabtext.js"></script>

Slabtext also requires that the following CSS be in effect:

.slabtexted .slabtext {
    display: -moz-inline-box;
    display: inline-block;
    white-space: nowrap;
}
.slabtextinactive .slabtext {
    display: inline;
    white-space: normal;
    font-size: 1em !important;
    letter-spacing: inherit !important;
    word-spacing: inherit !important;
    *letter-spacing: normal !important;
    *word-spacing: normal !important;
}
.slabtextdone .slabtext {
    display: block;
}

Here's a typical usage:

// Load a script
$("#output").stepwise({source:"myscript.xml", dataType:"xmlfile",
	handleLoad: function(instance) {
		// Initialize the effect and bind it to the instance
		var slabtext = new $.fn.stepwise.effects.Slabtext(instance);
	}
});

Options

These are in addition to the base effect options.

Option Description
clearHeight A floating point value indicating how tall the element containing the text is allowed to get before it is cleared. A value of -1 means the element will never be cleared. Defaults to -1.
fontRatio A floating point value that is used when calculating the ideal number of “characters per line” (see the plugin documentation for more about how this is used). Defaults to 0.78.
maxFontSize An integer value that indicates the maximum pixel font-size that the script can set. Defaults to 999.
minCharsPerLine An integer value that indicates the minimum number of characters to set per line. Headlines that have a character count smaller than this value are not given the slabText treatment. Defaults to 5.
viewportBreakpoint An integer value that indicates the minimum pixel width the viewport may have before the slabtext treatment is removed. Defaults to 600.

Stepfade effect

The Stepfade effect displays the content of each step with a jQuery fade in applied to a <span> element wrapping the step's content.

To use this effect, first make sure you've made it available to the page:

<script type="text/javascript" src="js/effects/Stepfade.js"></script>

Here's a typical usage:

// Load a script
$("#output").stepwise({source:"myscript.xml", dataType:"xmlfile",
	handleLoad: function(instance) {
		// Initialize the effect and bind it to the instance
		var stepfade = new $.fn.stepwise.effects.Stepfade(instance);
		// Bind output from specific characters to different DOM elements
		stepfade.bindCharacterToElement("amiri", "#left-column");
		stepfade.bindCharacterToElement("maya", "#right-column");
	}
});

Options

These are in addition to the base effect options.

Option Description
appendOnly If true, then all steps will be treated as if their append property was set to true; new content will be added to old, instead of replacing it.
fadeDuration The length of the fade in milliseconds. Defaults to 250.

TonePiano effect

The TonePiano effect uses the Tone.js framework to make a sampled piano instrument available to Stepwise. When a character named "Piano" speaks a note name, that note will be played using the instrument. The piano samples were recorded by the University of Iowa Electronic Music Studios.

To use this effect, first make sure you've made it and Tone.js available to the page:

<script type="text/javascript" src="js/libs/Tone.min.js"></script>
<script type="text/javascript" src="js/effects/TonePiano.js"></script>

Here's a typical usage:

// Load a script
$("#output").stepwise({source:"myscript.xml", dataType:"xmlfile",
	handleLoad: function(instance) {
		// Initialize the effect and bind it to the instance
		var tonePiano = new $.fn.stepwise.effects.TonePiano(
			instance, 
			{pathToSamples: 'stepwise/src/js/effects/samples/UIowaPiano/'}
		);
	}
});

Options

These are in addition to the base effect options.

Option Description
supportsGeneralMIDI If true, then all General MIDI instrument names will be mapped to the piano sound.
sampleCount The number of pitch classes to use in interpolating between samples. Minimum 1, maximum 4. Larger numbers require more RAM.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.