WorkOutDoors WKT Parser

An unofficial parser for the .wkt files created by WorkOutDoors App.

About

This library parses binary workout files from the WorkOutDoors app and provides structured access to workout data including GPS tracks, heart rate, cadence, laps, and more. It supports JSON export for further analysis or integration with other tools.

Note: This is an unofficial, reverse-engineered parser. The .wkt format is undocumented and may change without notice in future app releases.

Features

• Parse Run, Walk, and Weightlifting workouts
• GPS track extraction with coordinate conversion
• Heart rate data including zones and samples
• Cadence data with samples
• Lap-by-lap analysis for multi-lap workouts
• App and device version information
• JSON export (to_dict(), to_json(), save_json())
• Comprehensive error handling

Installation

pip install -e .

Usage

Basic Parsing

from pathlib import Path
from wkt_parser import WKTParser

parser = WKTParser()
workout = parser.parse(Path("path/to/workout.wkt"))

print(f"Type: {workout.workout_type_code}")
print(f"Distance: {workout.distance}m")
print(f"Duration: {workout.duration}s")
print(f"GPS points: {len(workout.gps_track)}")

JSON Export

# Export to JSON string
json_str = workout.to_json()

# Save to file
workout.save_json("workout.json")

# Get as dictionary
data = workout.to_dict()

Batch Export

See examples/export_to_json.py for a complete example of batch processing multiple workout files.

python examples/export_to_json.py ~/workouts/Workouts ~/workouts/json

Development

Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install dependencies
pip install -e .

Testing

# Run tests
just test

# Or directly with pytest
pytest tests/

Linting

just check  # Run all checks (ruff, mypy)
just lint   # Ruff linting only

File Format

WorkOutDoors stores workout data in binary .wkt files with the following filename format:

YYMMDDHHMMSS_TYPE_DIST_DUR_F5_F6_STEPS_F8[_TITLE].wkt

Where:

• YYMMDDHHMMSS - End timestamp
• TYPE - Workout type code (37=Run, 52=Walk, 50=Weightlifting)
• DIST - Distance in meters
• DUR - Duration in seconds
• STEPS - Step count
• TITLE - Optional custom title

Contributing

This is primarily a personal project, but contributions are welcome. The .wkt format is undocumented and largely reverse-engineered, so discoveries about the binary structure are particularly valuable.

License

AGPL 3.0 - See LICENSE file for details