-
Notifications
You must be signed in to change notification settings - Fork 1
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:
| 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 |
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>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.
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.
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 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.
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. |
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.
If no metadata is specified, the name of the sheet will be used as the title of the work, and the creator of the document will be assigned the primary credit.
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.
The left-most sheet is the only one that will be parsed, so it is possible to compose multiple scripts on different sheets and then quickly try them out by dragging the desired sheet into the left-most position and then reloading.
Columns titled "instructions" or "comments" will be ignored by the parser, so they are good places to leave notes or comments to yourself or others.