siteswap.js

Parse, examine and manipulate juggling patterns in JavaScript.

Supported environments: Node 6.5+, Chrome, Firefox, Edge, Safari, Opera.

Usage

Siteswap( string, notation = "compressed" )

• string - siteswap string or throws array.
• notation - notation(s) used to parse string. See supported notations.

new Siteswap("753")
new Siteswap("[43]14")
new Siteswap("(4,2x)*")
new Siteswap("7,5,3", "standard")
new Siteswap("<3p,3,3|3p,3,3>", "passing")
new Siteswap("<(4xp,4x)|(4xp,4x)>", "passing")
new Siteswap(`B3,A3,A3
              C3,B3,B3
              A3,C3,C3`, "multihand")

The following properties/functions are exposed:

.valid » boolean showing if the siteswap is valid.

.error » error message (set to invalid siteswaps).

.input » passed arguments (set to invalid siteswaps).

.notation » notation used to parse the siteswap.

.degree » number of hands used per beat.

.props » number of props the pattern requires.

.multiplex » greatest number of props released together from a single hand.

.greatestValue » greatest throw value.

.period » length of one cycle.

.fullPeriod » length of one coloured cycle (one which distinguishes props).

.groundState » boolean showing if the siteswap is ground state or excited.

.prime » boolean showing if the siteswap is prime (cannot be decomposed).

.throws » array of tosses like { from: int, to: int, value: int } three levels deep representing the throw sequence. .throws[1][0][3] is the fourth (multiplex) toss of the first hand during the second throw of the sequence.

.states » array of states representing the number of props in hands over time. .states[1][0][3] is the number of props in the first hand, four beats after the second throw is made.

.strictStates » array of states representing positions of specific props within hands over time. .states[1][0][3][2] is the id of the third ball in the first hand, four beats after the second throw is made.

.orbits » array of siteswap's orbits which are themselves Siteswaps.

.composition » array of prime Siteswaps the siteswap is consisted of.

.equals( siteswap ) » returns a boolean showing if the siteswap's .throws match those of any rotation of siteswap.

.rotate( count = 1 ) » returns a new Siteswap obtained by rotating the throw sequence by count beats to the right.

.toString( notation = this.notation ) » returns a string representing the siteswap in a given notation.

.log() » outputs all the siteswap properties in a human friendly form to console.

Invalid siteswaps only have .valid, .error, and .input properties set.

Example

const siteswap = new Siteswap("753")
siteswap.valid                      // true
siteswap.notation                   // "compressed:async"
siteswap.degree                     // 1
siteswap.props                      // 5
siteswap.multiplex                  // 1
siteswap.greatestValue              // 7
siteswap.period                     // 3
siteswap.fullPeriod                 // 12
siteswap.groundState                // true
siteswap.prime                      // true
siteswap.throws                     // [
                                    //  [[{ "value": 7, "from": 0, "to": 0 }]],
                                    //  [[{ "value": 5, "from": 0, "to": 0 }]],
                                    //  [[{ "value": 3, "from": 0, "to": 0 }]]
                                    // ]
siteswap.states                     // [
                                    //  [[1,1,1,1,1]],
                                    //  [[1,1,1,1,0,0,1]],
                                    //  [[1,1,1,0,1,1]]
                                    // ]
siteswap.strictStates               // [
                                    //  [[[1],[2],[3],[4],[5]]],
                                    //  [[[2],[3],[4],[5],[],[],[1]]],
                                    //  [[[3],[4],[5],[],[2],[1]]],
                                    //  [[[4],[5],[3],[2],[1]]],
                                    //  [[[5],[3],[2],[1],[],[],[4]]],
                                    //  [[[3],[2],[1],[],[5],[4]]],
                                    //  [[[2],[1],[3],[5],[4]]],
                                    //  [[[1],[3],[5],[4],[],[],[2]]],
                                    //  [[[3],[5],[4],[],[1],[2]]],
                                    //  [[[5],[4],[3],[1],[2]]],
                                    //  [[[4],[3],[1],[2],[],[],[5]]],
                                    //  [[[3],[1],[2],[],[4],[5]]]
                                    // ]
siteswap.composition                // [this]
siteswap.orbits                     // [new Siteswap("750"), new Siteswap("003")]
siteswap.toString()                 // "753"
siteswap.toString("standard:async") // "7,5,3"

Notations

standard

• shorthand for ["standard:async", "standard:sync"]

standard:async

• throw values > 9 are written as numbers: 11 is eleven ball cascade
• throw values are separated: 1,1 is one ball cascade

5
11,1
[4,3],1,4

standard:sync

• throw values are doubled
• throw values > 9 are written as numbers: (10x,10x) is a ten ball wimpy pattern
• throw values are separated: ([4,4],4)

(4,4)
(4,2x)(2x,4)
([2x,2x],0)*

compressed

• shorthand for ["compressed:async", "compressed:sync"]

compressed:async

• throw values > 9 are written as alphabetical letters: b is eleven ball cascade
• throw values are not separated: 11 is one ball cascade

5
b1
[43]14

compressed:sync

• throw values are doubled
• throw values > 9 are written as alphabetical letters: (ax,ax) is a ten ball wimpy pattern
• multiplex throw values are not separated: ([44],4)
• hands are optionally separated: ([44],4) ([44]4)

(44)
(4,4)
(4,2x)(2x,4)
([2x2x],0)*

passing

• shorthand for ["passing:async", "passing:sync"]

passing:async

• jugglers' actions are separated like < … | … | … > and respect the standard:async rules
• a pass is denoted with p when there are two jugglers: <3p|3p>
• a pass is denoted with pN when there are two or more jugglers: <3p2|3p3|3p1>

<3|3>
<3p|3p>
<3p2|3p1>
<3p2|3p3|3p1>
<[3,3p],3,3|3p,3,3>

passing:sync

• jugglers' actions are separated like < … | … | … > and respect the standard:sync rules
• a pass is denoted with p when there are two jugglers: <(4xp,4)|(4,4xp)>
• a pass is denoted with pN when there are two or more jugglers: <(4xp2,4)|(4,4xp1)>

<(4,2x)*|(4x,4x)>
<(4p,4)|(4p,4)>
<(4p2,4)|(4p1,4)>
<([6x,4p],4)(4,6x)|([4x,4p],6)(6,4x)>

multihand

• throws are grouped by hands in rows
• tosses are comma separated: A5,A3
• a toss is denoted with the target hand (A,B,C...) and throw value: A3, or
• a toss is denoted with the relative target hand and throw value in parentheses: (-1,3)

A6,A4

B3
C3
D3
A3

[A4,B3],A4,A1
[A3,B5],B3,B1

(0,6)(0,4)

( 1,4)( 1,2)[(0,3)( 1,3)]
(-1,1)(-1,5)[(0,3)(-1,3)]

All notations support multiplex throws using the [ ] syntax.

All choices (like comma/space as separator) must be consistently applied.

To do

• Siteswap and transition generator.
• Custom hand rhythm. Like two hands in one handed patterns.
• Combining siteswaps of different degrees.

License

MIT License