ZWO

Python toolkit for the ZWO minilang.

Installation

Install from PyPi with your favorite pip invocation:

$ pip install zwolang

The ZWO File Specification

The primary purpose of this package is to provide a simple, human-readable format for constructing Zwift workouts that can be used to generate the actual workout XML.

ZWO files are parsed using a Parsimonious grammar, as specified below:

workout   = (block elws*)+ emptyline*
block     = tag ws "{" (((message / value) ","?) / elws)+ "}"
value     = tag ws (string / range / rangeval)

message   = "@" ws duration ws string
range     = rangeval ws "->" ws rangeval
rangeval  = (duration / numeric)

duration  = number ":" number
percent   = number "%"
numeric   = (percent / number)
elws      = (ws / emptyline)

tag       = ~"[A-Z]+"
string    = ~'"[^\"]+"'
number    = ~"\d+"
ws        = ~"\s*"
emptyline = ws+

Syntax & Keywords

Like Zwift's built-in workout builder, the ZWO minilang is a block-based system. Blocks are specified using a <tag> {<block contents>} format supporting arbitrary whitespace.

Each ZWO file must begin with a META block containing comma-separated parameters:

1. If specified, the rider's FTP is not used by Zwift directly. It is instead used to optionally normalize the workout's target power percentages to watts

Following the META block are your workout blocks:

1. I believe Zwift considers these the same as Ramp intervals, so the ZWO package does the same

Workout blocks can contain the following comma-separated parameters:

1. For Interval & Ramp segments, the range syntax can be used to set values for the work/rest segments (e.g. 65% -> 120%)
2. Power is optional for Free segments
3. Message timestamps are relative to their containing block

Sample Workout

META {
    NAME "My Workout",
    AUTHOR "Some Author",
    DESCRIPTION "Here's a description!",
    TAGS "super, sweet, workout",
    FTP 270,
}
FREE {DURATION 10:00}
INTERVALS {
    COUNT 3,
    DURATION 1:00 -> 0:30,
    POWER 55% -> 78%,
    CADENCE 85 -> 110,
}
SEGMENT {DURATION 2:00, POWER 65%}
RAMP {
    DURATION 2:00,
    POWER 120% -> 140%,
    @ 0:00 "Here goes the ramp!",
    @ 1:50 "10 seconds left!",
}
FREE {DURATION 10:00}