Creating Stepwise content in Google Sheets

Erik Loyer edited this page Apr 6, 2017 · 9 revisions

The Stepwise jQuery plugin can import specially formatted Google Sheets documents, converting them to Stepwise XML. This is currently the easiest, fastest way to do sophisticated Stepwise authoring.

The philosophy behind the formatting is that, thinking of Stepwise as a kind of multimodal, multitrack content sequencer, we treat each column of the spreadsheet like an individual "track" or content source—in Stepwise terms, a character.

Ultimately, the goal is to create a true Stepwise-based content sequencer application using this approach. If you're interested in helping with this effort, please get in touch.

Note: This page is about formatting your Google Sheets document for Stepwise. For details on loading Google Sheets documents into Stepwise, see the Loading content section.

Declaring characters

To add a character to your story, add the character's name in the top row of a column in your spreadsheet. To mute the display of the character's content, add the suffix "-hidden".

Each row of text below the header will be treated as a separate step. For example, here's how to create a character named Nathan who counts to four in successive steps:

Nathan
1
2
3
4

This will be converted into the following Stepwise XML:

<stepwise>
	<title>Sheet1</title>
	<description></description>
	<primarycredits>[your Google user name]</primarycredits>
	<secondarycredits></secondarycredits>
	<version>1</version>
	<sequence id="global" repeat="+">
		<speak character="nathan">1</speak>
		<speak character="nathan">2</speak>
		<speak character="nathan">3</speak>
		<speak character="nathan">4</speak>
	</sequence>
	<character id="nathan" firstname="nathan"></character>
</stepwise>

This example results in a hidden character named Piano who utters the first six notes of the melody from Thelonious Monk's 'Round Midnight. If the resulting script were loaded into a Stepwise client that converted the speech acts of characters named for musical instruments into actual musical sounds, each note of the melody would be played audibly on successive user inputs:

Piano-hidden
Eb2
Bb2
Eb3
F3
Bb3
Gb3

Multiple characters

To add more characters to your story, simply add more named columns. All content in the same row will be grouped for simultaneous playback. Here, we add a singer to our 'Round Midnight instrumental:

Singer Piano-hidden
It Eb2
be Bb2
gins Eb3
F3
to Bb3
tell Gb3

Resulting in the following script:

<stepwise>
	<title>Sheet1</title>
	<description></description>
	<primarycredits>[your Google user name]</primarycredits>
	<secondarycredits></secondarycredits>
	<version>1</version>
	<sequence id="global" repeat="+">
		<group>
			<speak character="singer">It</speak>
			<speak character="piano">Eb2</speak>
		</group>
		<group>
			<speak character="singer">be</speak>
			<speak character="piano">Bb2</speak>
		</group>
		<group>
			<speak character="singer">gins</speak>
			<speak character="piano">Eb3</speak>
		</group>
			<speak character="piano">F3</speak>
		<group>
			<speak character="singer">to</speak>
			<speak character="piano">Bb3</speak>
		</group>
		<group>
			<speak character="singer">tell</speak>
			<speak character="piano">Gb3</speak>
		</group>
	</sequence>
	<character id="singer" firstname="singer"></character>
	<character id="piano" firstname="piano" visible="false"></character>
</stepwise>

Creating sequences

By default, Stepwise will generate a single repeating sequence encompassing all of the characters in your spreadsheet. Sometimes, however, you want more control of how sequences are defined. This can be accomplished by putting metadata defining a sequence into a cell of a character's column using a standard format for multi-parameter commands:

$command: param1:value1, param2:value2

To create a new sequence, use the command $sequence, followed by the id parameter and the sequence's id (which much be unique), and then (optionally) any of the following parameters:

Parameter Description
grouping Defines a pattern in which steps in the sequence will be grouped, with rhythmic delays. For example, the value xxxx will assemble steps in the sequence into groups of four, with each step delayed in time by one pulse, as defined in the story's <pulse> element. You can use the & character instead of x to indicate that a step should be appended to the previous step, instead of replacing it outright.
repeat Sets the number of times the sequence will repeat, or use + to repeat indefinitely.
shuffle If true, steps in the sequence will be played in random order.

So, for example, here is how we would define a character named Shirley who utters three colors at a time:

Shirley
$sequence: id:colors, repeat:+, grouping:x&&
Red
Orange
Yellow
Green
Blue
Indigo
Violet

You can declare multiple sequences for a single character by simply adding additional $sequence commands in the character's column. Each sequence will derive its steps from the rows below its $sequence command, until all content is exhausted or another $sequence command is encountered.

Creating steps

Entering content in a spreadsheet cell will by default create a <speak> command uttered by the character declared at the header of that cell's column.

Delay, append, and tone shortcuts

A few shortcuts are available to set the delay and append properties of that command:

Shortcut Description Example
&[content] Sets the append property of the step to true. &and
[content]+[delay] Sets the delay property of the step to the specified value (decimals allowed). the+1
[content]@[tone] Sets the tone property of the step to the specified value. The @ must come after any use of the + delay shortcut. Hey!@shout

Musical dynamics are also allowed in the tone shortcut, and are mapped to the five canonical speech tones as follows:

Tone shortcut Corresponding speech tone
@pp, @ppp whisper
@p murmur
[nothing] normal
@f shout
@ff, @fff scream

Empty steps

Empty cells in a spreadsheet are not parsed. There may be cases, however, in which an author might want to include a step between two others which has no outward effect. This can be accomplished by entering a single space in a cell, which will be parsed as a <nothing> step.

Additional step types

Steps with types other than <speak>, nothing, and group must be declared explicitly, like so:

$setforecolor: #4A6491

Not all Stepwise step types are supported by the Google Sheets parser. Here are the ones that are supported:

Command Description
$reset: [sequence id] Resets the specified sequence to its initial state.
$sample: [sequence id] Samples a step from the specified sequence.
$setbackcolor: [CSS color] Sets the current background color.
$setdate: [date string] Sets the current date and time.
$setforecolor: [CSS color] Sets the current foreground color.
$setmidcolor: [CSS color] Sets the current mid color.
$setsequence: [sequence id] Makes the specified sequence the current sequence.
$settime: [time string] Sets the current date and time.
$setweather: [weather condition id] Sets the current weather conditions.
$sing: [content] Directs the character in this column to sing the specified content.

Using unsupported step types

The Google Sheets parser will pass through unsupported commands. For example, $setemotion: happy in your spreadsheet will be parsed as <setemotion>happy</setemotion> and Stepwise will dutifully create a step of that type and trigger it on user input, even though it will have no effect within Stepwise itself. Use this approach sparingly, as it makes your scripts less portable to other clients.

Specifying metadata

Metadata for a story is declared in a column with the heading of "Metadata" that contains a cell in the following format (all parameters are optional):

Metadata
title: [title], primaryCredits: [credits], secondaryCredits: [credits], description: description], version: [version], pulse: [beats per minute/pulses per beat/swing]

Parameter values can be enclosed in double straight quotes to preserve internal commas and colons.

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.