Wim Hof Breathing Trainer

Atmospheric desktop breathing trainer inspired by the Wim Hof breathing method and other structured breathing techniques.

Built with Python, PySide6, and YAML-driven session configuration.

The application focuses on smooth pacing, minimal UI distractions, and configurable breathing protocols.

Features

• Fullscreen breathing trainer
• Smooth breathing ring animation
• YAML-configurable breathing protocols
• Multiple breathing techniques support
• Timeline visualization
• Countdown and cycle-based displays
• Ambient background image and music
• Pause / resume support
• Fade-out completion sequence
• Config inheritance system
• Protocol presets support

Supported Breathing Styles

The application is protocol-driven and can describe different breathing techniques entirely through YAML configuration.

Current examples include:

• Wim Hof style breathing
• 4-7-8 breathing
• Box breathing

Design Goals

This project intentionally avoids:

• excessive UI complexity
• account systems
• online services
• unnecessary gamification

The focus is:

• calm pacing
• smooth visual transitions
• readable structure
• extensible protocol configuration

Demo

Big picture: demo/demo.jpg

Video preview:

demo/demo.webm ~ 3.4 Mb

Installation

• For a quick local run:

git clone --depth 1 git@github.com:dmi3s/wimhof.git
cd wimhof
uv sync

• For development with full dependency groups (including dev extras):

git clone git@github.com:dmi3s/wimhof.git
cd wimhof
uv sync --all-groups

Run the application:

uv run wimhof

Using Custom Presets

Run with a custom configuration file:

uv run wimhof --breathing presets/4-7-8.yaml

Short form:

uv run wimhof -b presets/box_breathing.yaml

Configuration System

Breathing protocols are described using YAML timelines. The breathing engine is intentionally data-driven. Protocols are described as timelines rather than hardcoded logic.

Each section may contain:

• repeated sequences
• arbitrary phase ordering
• different display modes
• animation behaviors
• inherited configuration

Example:

rounds:
  # ==========================================================
  # PREPARATION
  # ==========================================================

  - section: Preparation
    repeat: 1

    sequence:
      - type: prepare
        behavior: prepare
        duration: 3
        label: "PREPARE"

The configuration system supports partial overrides of inherited sequences:

• sequence inheritance
• partial sequence overrides

Example Protocol

Example 4-7-8 breathing sequence:

- section: breathing
  repeat: 8

  sequence:
    - type: inhale
      behavior: expand
      duration: 4
      label: "INHALE"

    - type: hold
      behavior: pulse_small
      duration: 7
      label: "HOLD"

    - type: exhale
      behavior: shrink
      duration: 8
      label: "EXHALE"

- section: breathing
  repeat: 6
  inherit: true

  sequence:
    - type: inhale
      display: "cycles"

    - type: hold
      display: "cycles"

    - type: exhale
      display: "cycles"

Controls

Key	Action
M	Mute / Unmute
Space	Pause / Resume / Restart
ESC	Quit application

Project Structure

wimhof/
├──.github/
│   └── workflows/
│       └── ci.yml                  -- GitHub CI workflow
├──.zed/
│   └── tasks.json                  -- Zed tasks (Run, Ruff, Mypy, Audit, Build)
├── demo/
│   ├── demo.thumbnail.jpg
│   ├── demo.jpg
│   └── demo.webm
├── src/
│   └── wimhof/
│       ├── assets/
│       │   ├── app_icon.png
│       │   ├── background.jpg
│       │   ├── music.mp3
│       │   └── sources.md          -- Sources for music, background, icon
│       └── presets/
│           ├── 4-7-8.yaml          -- Preset for 4-7-8 breathing sequence
│           ├── box_breathing.yaml  -- Preset for box breathing sequence
│           └── wimhof.yaml        -- Preset for Wim Hof breathing sequence
│       └── themes/
│           └── default.yaml        -- Default theme. Just one for now.
│       ├── __init__.py             -- Package marker (empty)
│       ├── __main__.py             -- Entry point. Runs the application.
│       ├── config.yaml             -- Wim Hof breathing configuration
│       └── main.py                 -- Application code. Sorry about the long file,
│                                   --     the main reason - easenest way of communication
│                                   --     with different LLM's.
├── LICENSE
├── pyproject.toml
├── README.md
├── config.yaml                     -- Configuration file for the default
│                                   --   Wim Hof breathing application
└── uv.lock

Dependencies

Main dependencies:

requires-python = ">=3.12"
dependencies = [
  "pyside6>=6.11.1",
  "pyyaml>=6.0.3",
]

Future Ideas

Possible future additions:

• logging
• Sessions statistics

Icebox:

• Local analytics database
• Audio guidance
• Breathing protocol sharing
• Mobile version
• Wearable integration

Safety Notice

This application is intended for relaxation and controlled breathing exercises.

Do not use while:

• driving
• swimming
• operating machinery
• performing activities requiring full attention

Media Sources

Background image and music are used under free licenses.

Full attribution information is available in src/wimhof/assets/sources.md.

License

MIT License.

© 2026 dmi3s

---

Developed using Python and PySide6 (Qt) with assistance from ChatGPT and DeepSeek.