Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Creating Stepwise content in Google Sheets
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.
- Example of a simple Google Sheets document for Stepwise
- Example of a sophisticated Google Sheets document for Stepwise
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.
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:
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:
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:
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>
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:
|grouping||Defines a pattern in which steps in the sequence will be grouped, with rhythmic delays. For example, the value
|repeat||Sets the number of times the sequence will repeat, or use
So, for example, here is how we would define a character named Shirley who utters three colors at a time:
|$sequence: id:colors, repeat:+, grouping:x&&|
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.
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
append properties of that command:
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|
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
Additional step types
Steps with types other than
group must be declared explicitly, like so:
Not all Stepwise step types are supported by the Google Sheets parser. Here are the ones that are supported:
|$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.
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):
|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.