TempoWeave WIF & TWA File Format Specification
TempoWeave WIF & TWA File Format Specification
Version: 2.3 Effective: 2026-03-12 Author: LoftyFiber LLC (TempoWeave Studio)
This document describes the WIF (Weaving Information File) and TWA (TempoWeave Archive) file formats as produced and consumed by TempoWeave Studio and TempoWeave Mobile. It is intended as an integration reference for partners implementing read/write support for these files.
The base WIF format follows the WIF 1.1 specification (an INI-style weaving interchange standard maintained by the weaving community since 1997). TempoWeave Studio is fully WIF-1.1 compliant and adds a set of optional [TW *]-prefixed sections that carry application-specific metadata. These extensions are namespaced so any compliant WIF reader will ignore them safely.
The TWA format is a ZIP-archive container that holds a primary WIF plus optional companion files (section assemblies, writeup HTML, attachments, snapshots). Readers that don't understand TWA can simply extract twamain.waf from the archive and treat it as a normal WIF.
1. WIF File (.wif)
.wif)A WIF is a UTF-8 plain-text file in classic Windows INI format — case-insensitive section headers in square brackets, key=value pairs, semicolon comments. TempoWeave reads and writes WIF 1.1.
1.1 Header sections
[WIF]
Identifies the file format and producer.
Version
string
Always 1.1.
Date
string
Long-form local date when the file was written.
Developers
string
Always LoftyFiber for TempoWeave-produced files.
Source Program
string
Always TempoWeave Studio.
Source Version
string
Producing version, e.g. 26.520.1.
[CONTENTS]
Manifest listing which optional sections are present. Each key is the name of a section, value is true. Standard sections always listed by TempoWeave: WEAVING, WARP, WEFT, COLOR PALETTE, COLOR TABLE, WARP COLORS, WEFT COLORS, WARP SPACING, WEFT SPACING, THREADING, and either (TIEUP + TREADLING) or LIFTPLAN.
[WEAVING]
Loom geometry.
Shafts
integer
Number of shafts shown in the draft.
Treadles
integer
Number of treadles shown. Always present even for liftplan WIFs.
Rising Shed
bool
TempoWeave always writes true. Readers should accept false for sinking-shed looms.
[TEXT]
Title
string
Pattern title, free-form.
Author
string
Designer name, free-form.
[NOTES]
Up to 5 lines of free-form notes. Keys are 1 through 5, values are the line text. Empty lines are written as empty values, not omitted.
[WARP], [WEFT]
Per-axis defaults. TempoWeave writes the following keys:
Units
string
Always centimeters in TempoWeave-produced files.
Color
integer
Index into [COLOR TABLE] for the default warp/weft color.
Threads
integer
Total warp ends (for [WARP]) or total weft picks (for [WEFT]).
Spacing
decimal
Default thread spacing in Units.
Thickness
decimal
Default thread thickness in Units.
1.2 Color sections
[COLOR PALETTE]
Range
string
Always 0,255 (8-bit per channel).
Entries
integer
Total number of entries in [COLOR TABLE].
[COLOR TABLE]
Numbered palette entries (1-based). TempoWeave compacts the saved palette so keys are always sequential 1..N with no gaps. Each value is R,G,B (three decimal integers 0-255).
[WARP COLORS], [WEFT COLORS]
Per-thread color index. Keys are 1-based thread positions; values are 1-based indices into [COLOR TABLE].
[WARP SPACING], [WEFT SPACING]
Per-thread spacing override in Units from [WARP] / [WEFT]. Allows variable-thickness yarns within a single warp or weft. Values are decimal, formatted with three decimal places (e.g. 0.212).
1.3 Structure sections
[THREADING]
Maps each warp end (1-based) to a shaft number (1-based).
[TIEUP] (when IsLiftplan = false)
Maps each treadle (1-based) to a comma-separated list of shafts it raises (1-based).
[TREADLING] (when IsLiftplan = false)
Maps each pick (1-based) to a treadle (single-treadle) or comma-separated list of treadles (multi-treadle pickup).
[LIFTPLAN] (when IsLiftplan = true)
Replaces [TIEUP] + [TREADLING] with a direct per-pick list of raised shafts. Common for table looms and computer dobby looms. Keys are 1-based pick numbers, values are comma-separated 1-based shafts.
A WIF will contain either [TIEUP]+[TREADLING] or [LIFTPLAN], never both. Readers should inspect [CONTENTS] to determine which.
2. TempoWeave-specific WIF extensions
All TempoWeave-added sections are prefixed with TW (or, historically, TEMPOWEAVE). Standards-conformant WIF readers should ignore unknown sections; these are safe to skip.
2.1 [TW COLOR NAMES]
[TW COLOR NAMES]Optional palette metadata. Present when at least one color has a name, yarn line, or sett record. Keys mirror [COLOR TABLE] entries (1-based). Values are CSV: colorName,yarnLine,yarnThickness[,settWide,settMedium,settClose].
colorName
string
Free-form display name.
yarnLine
string
Yarn line key (e.g. UKI 8/2 Cotton). Maps to the catalog.
yarnThickness
integer
Thickness code (1=hairline ... 7=very thick).
settWide
decimal
Optional. Wide-sett EPI/PPI.
settMedium
decimal
Optional. Medium-sett EPI/PPI.
settClose
decimal
Optional. Close-sett EPI/PPI.
The optional sett triplet appears only when the user has filled it in; absent values may be parsed as zero.
2.2 [TW VARIEGATION]
[TW VARIEGATION]Optional. Encodes a variegation profile for a palette entry — a color-stop list that interpolates across positions, creating space-dyed yarn effects. Keys mirror [COLOR TABLE] entries. Values are a serialized profile (opaque format — see VariegationProfile.Serialize() in source).
This section is only present when the user has explicitly defined variegation; standard WIF readers can safely ignore it.
2.3 [TW PROJECT]
[TW PROJECT]Project-level planning metadata. Always present in TempoWeave-produced files. Fields control the Project Info / Cloth Construction tools and do not affect the underlying draft structure.
Units
string
inches, centimeters, etc. Display unit for project metrics.
Sett
decimal
Target EPI (or per-Units equivalent).
Beat
decimal
Target PPI (or per-Units equivalent).
DefaultYarnThickness
integer
Default thickness for new yarns (1-7).
ReedUnits
string
Unit for reed dent measurements.
ReedDents
integer
Reed dents per ReedUnits (e.g. dents per inch).
ReedSleyPattern
string
Sley pattern, e.g. 1,1,1,2 (free-form CSV).
RaddleUnits
string
Unit for raddle dent measurements.
RaddleDents
integer
Raddle dents per RaddleUnits.
RaddleSleyPattern
string
Raddle sley pattern (free-form CSV).
OverrideWidthInReed
decimal
Manual override (in Units). 0 = auto.
PlannedWarpLength
decimal
Planned warp length in Units.
OverrideWovenLength
decimal
Manual override. 0 = auto.
FinishLength
decimal
Planned finished length in Units.
TotalFringe
decimal
Fringe allowance per piece in Units.
Sampling
decimal
Sampling allowance in Units.
FinishedWidth
decimal
Target finished width in Units.
WovenPieces
integer
Number of pieces planned from this warp.
LoomWaste
decimal
Loom waste per warp in Units.
WeftTakeup
decimal
Weft take-up percentage (e.g. 5.0 = 5%).
WarpTakeup
decimal
Warp take-up percentage.
DrawIn
decimal
Width draw-in percentage.
LengthShrinkage
decimal
Length shrinkage percentage.
WidthShrinkage
decimal
Width shrinkage percentage.
Tags
string
Optional CSV of free-form pattern tags. Omitted if empty.
FloatingSelvedgeRight
bool
Optional. Only written when true.
FloatingSelvedgeLeft
bool
Optional. Only written when true.
FloatingSelvedgeDouble
bool
Optional. Only written when true.
Decimals use InvariantCulture formatting (period as decimal separator).
2.4 [TEMPOWEAVE]
[TEMPOWEAVE]Grid overlay display preferences. Per-document UI state; safe to ignore for purely structural integrations.
GridOverlayDrawdown
bool
Show grid lines on the drawdown. Lowercase true/false.
GridOverlayWarp
bool
Show grid on the warp/threading area.
GridOverlayTieup
bool
Show grid on the tieup.
GridOverlayWeft
bool
Show grid on the weft/treadling area.
GridOverlayShaft
integer
Major-grid stride for shafts (e.g. every 4th shaft).
GridOverlayThread
integer
Major-grid stride for warp ends.
GridOverlayColor
string
RGB hex without leading #, e.g. 505050.
2.5 [TW WARP SECTIONMARKERS], [TW WEFT SECTIONMARKERS]
[TW WARP SECTIONMARKERS], [TW WEFT SECTIONMARKERS]Optional. Named segments along the warp or weft axis, used for the Sections tool (visual labels marking pattern repeats, hems, etc.). Keys are 1-based section indices. Values are CSV: startEnd,name[,localEpi].
startEnd
integer
1-based thread (warp) or pick (weft) where the section begins.
name
string
Section label, may be empty.
localEpi (or localPpi)
decimal
Optional. Local sett override for this section, formatted with one decimal place.
Each section runs from its startEnd until the start of the next section (or end of axis).
2.6 [TW CLOTH CONSTRUCTION]
[TW CLOTH CONSTRUCTION]Optional. Cloth-structure metadata for layered fabrics (double cloth, beiderwand, etc.). Present only when the user has set non-default cloth construction parameters.
ClothFace
string
Face-side selector (encoded as a numeric code).
ClothConstruction
string
Construction type identifier.
ClothFold
string
Fold style (for Folded Cloth).
ClothTopLayerShafts
string
CSV of shaft numbers in the top layer.
ClothCustomPattern
string
Free-form custom double-cloth pattern definition.
2.7 [TW LOCK]
[TW LOCK]Optional. Present only when the draft is marked read-only by the author.
DraftLocked
string
1 = locked. Section is omitted entirely when unlocked.
A locked draft asks any TempoWeave reader to prompt before allowing edits. The lock is advisory — it has no cryptographic enforcement.
2.8 [TW DOBBY]
[TW DOBBY]Optional. Current pick position for the Weave Assistant. Lets a draft resume at the same row after close/reopen.
CurrentPick
integer
1-based current pick. Omitted when at pick 1.
2.9 [TW THREAD ASSISTANT]
[TW THREAD ASSISTANT]Optional. State of the Thread Assistant feature (tracks which warp ends the weaver has already threaded). Present only when the weaver has actively used Thread Assistant.
ThreadedEnds
string
Run-length-encoded threaded-ends list, e.g. 1-8,17-24,41. Empty if nothing threaded yet.
GroupSize
integer
Number of ends per visual group in the threading display. Default 4.
Direction
string
RightToLeft (default) or LeftToRight.
StartingEnd
integer
1-based starting end. Default 1.
The ThreadedEnds RLE format uses comma-separated ranges and singles: 1-8 = ends 1 through 8 inclusive, 41 = single end 41.
2.10 [TW VIEW]
[TW VIEW]Optional. View / rendering preferences. Per-document UI state. Safe to ignore for structural integrations.
BackView
string
1/0. Show fabric back-side.
TieupStyle
string
Tieup visual style identifier.
GrayscaleDrawdown
string
1/0. Render drawdown in grayscale.
ShowThickness
string
1/0. Render variable thread thickness.
ShowVariegated
string
1/0. Render variegation profiles.
ShowInterlacement
string
1/0. Apply interlacement shading.
GrayscalePalette
string
1/0. Render palette swatches in grayscale.
YarnBloom
integer
Bloom intensity (0 = off).
WarpStyle
string
Warp render style identifier.
WarpVisible
string
1/0.
WeftStyle
string
Weft render style identifier.
3. TWA File (.twa)
.twa)A TWA is a standard ZIP archive with a .twa extension. It bundles the primary WIF with optional companion files. Standard ZIP tools can inspect and extract a TWA; the file is not encrypted or proprietary.
3.1 Required entry
twamain.waf
WIF text
The primary WIF (as specified in §1–§2). The only mandatory entry; readers that don't understand TWA can extract this and treat as a plain WIF.
3.2 Section Assembly entries (optional)
Section Assembly trees are TempoWeave's hierarchical pattern composition tool (warp/weft built up from named building blocks, color blocks, etc.). These entries store the tree structure as XML. The format is opaque to non-TempoWeave readers — DevExpress TreeList serialization — and need not be preserved if you don't render this view.
twa1.waf
Warp Section Assembly tree (XML).
twa1c.waf
Warp Color Assembly tree (XML).
twa2.waf
Weft Section Assembly tree (XML).
twa2c.waf
Weft Color Assembly tree (XML).
When the underlying draft is regenerated from the assembly tree, the results are persisted to [THREADING], [TREADLING]/[LIFTPLAN], [WARP COLORS], [WEFT COLORS], etc. So the WIF is always self-consistent even if the assembly XML is dropped.
3.3 Writeup entries (optional)
The Weaver's Writeup is a rich-text per-pattern note (cover image, "materials", "warping", "weaving" sections, etc.) used for project documentation and PDF export.
writeup.html
HTML
Free-form HTML body. TempoWeave parses a subset (headings, paragraphs, lists, images).
attachments.json
JSON
Array of attachment records {fileName, displayName, kind}.
attachments/<filename>
binary
Image/file attachments referenced from writeup.html by name.
3.4 Snapshot entries (optional)
Snapshots capture named versions of the draft inside the TWA file (teaching workflow). Each snapshot is a full WIF and a thumbnail.
snapshots.json
JSON
Array {id, name, createdAt, ...}. id is a GUID-like identifier.
snapshots/<id>.wif
WIF text
Full draft state at the moment of snapshot.
snapshots/<id>.png
PNG
Thumbnail (typically ~300×300).
A .twa consumer that doesn't render snapshots should leave these entries intact through any read/modify/write cycle — TempoWeave's mobile writer preserves unknown entries by default.
3.5 Metadata entry (optional)
twa-meta.json
JSON
TWA-level metadata: format version, app version, last modified. Not strictly required.
3.6 Round-trip preservation rule
Producers that don't understand a particular entry should preserve it verbatim through any save cycle. This is how TempoWeave Mobile is able to edit drafts originally authored on desktop (with section assemblies, writeup HTML, etc.) without losing those features: the mobile WIF write rebuilds twamain.waf but copies all other entries through unchanged.
4. Integration notes
4.1 WIF compliance
A WIF reader that only implements the standard sections (§1) will work correctly with TempoWeave-produced files. All [TW *] and [TEMPOWEAVE] sections are additive and ignorable.
4.2 Multi-treadle treadling
TempoWeave supports multi-treadle pickup (multiple treadles pressed for a single pick). When [TREADLING] values contain commas (e.g. 5=1,3), the WIF requires multi-treadle support. Readers that expect a single treadle per pick should reject or warn on such files. This is signaled by the presence of comma-separated values; there is no explicit flag in [CONTENTS].
4.3 Liftplan vs. tieup
Standard WIF allows either a [TIEUP]+[TREADLING] pair OR a [LIFTPLAN] section. TempoWeave writes exactly one of these. Determine which by checking [CONTENTS]:
LIFTPLAN=true→ use[LIFTPLAN]TIEUP=trueandTREADLING=true→ use the pair
4.4 Color palette compaction
When TempoWeave writes a WIF, it renumbers the palette so entries are sequential 1..N with no gaps, regardless of how the palette was indexed in memory. Per-thread [WARP COLORS] / [WEFT COLORS] references are remapped to the new indices. Readers should treat the in-file indices as canonical and not assume preservation of original slot numbers.
4.5 Spacing and thickness
Per-thread [WARP SPACING] / [WEFT SPACING] values are decimal distances in the units declared in [WARP] / [WEFT]. They override the section-level Spacing default. The thickness shown to the user is derived from the spacing relative to a baseline (SpacingUnit constant in TempoWeave = 0.0212 cm).
4.6 Character encoding
WIF files are UTF-8 text. Section headers and keys are ASCII. Values may contain non-ASCII (titles, author names, color names, etc.). Avoid the BOM at file start — TempoWeave does not write one.
4.7 Line endings
TempoWeave writes platform-native line endings on save (CR/LF on Windows, LF on macOS/Linux). Readers should be tolerant of either.
4.8 Identifying TempoWeave-produced files
Check [WIF].Source Program = TempoWeave Studio. The Source Version key gives the producing version (YY.MMDD.Rev format). Files with this identifier are guaranteed to follow the conventions described above. Files from other producers may follow standard WIF 1.1 but omit the [TW *] extensions.
5. Reference
WIF 1.1 specification: https://www.mhsoft.com/wif/wif1-1.txt
TempoWeave Studio product site: https://tempoweave.com
TempoWeave docs: https://docs.tempoweave.com
Contact for integration support: [email protected]
Appendix A: Minimal example WIF
The smallest valid TempoWeave-produced WIF for a 4-shaft tabby on a 4-treadle floor loom with 4 warp ends and 4 weft picks:
Last updated
Was this helpful?