Tai Chi Practice & Timer

An offline-first, private Android app for timing routines, scheduling practice, practice logging, and lightweight lineage/posture reference. Built with Jetpack Compose, Material 3, and a dark charcoal, jade, and warm gold aesthetic.

• Completely offline — no internet permission, no account, no ads, no tracking. Everything stays on your device.

• Structured Practice Timers — circular timer supporting Master Huang Sheng-shyan's Opening/Closing, Five Loosening Exercises, Cheng Man-Ching's Yang Style Short Form, Section-specific routines, and customizable Yang Style Posture Drills.

• Sound Feedback — clear chime audio notifications on timer state transitions and completion powered by SoundPool.

• Practice Stats & Streaks — calculates current/longest streaks, weekly practice minutes, and provides a timezone-aware weekly heatmap.

• Practice Log & Notes — view historical sessions, append custom notes to practices, delete log entries, and export logs to CSV.

• Reminders & Alerts — schedule inexact daily/weekly reminders via WorkManager, or opt-in to advanced exact alarms via AlarmManager.

• Reference Library — browse the complete Short Form posture sequence with preferred names/aliases and read concise core principle cards (Yi, Chi, Li, etc.).

---

Screenshots

1. Practice Screen	2. Start Timer	3. Routine Selection	4. Practice Logs
5. Stats & Heatmap	6. Postures Library	7. Custom Notifications	8. Settings

---

Requirements

• An Android phone running Android 8.0 (Oreo) or newer (API level 26+).
• ~30 MB of free storage.

This app is developed for personal use and is built from source.

---

Installing on your Android phone

To compile and install the app, you need Android Studio (or the Android SDK command-line tools) and JDK 17.

Note

Ensure the ANDROID_HOME environment variable is configured, or open the project in Android Studio once first to automatically generate the local.properties file.

1. Clone the repository and navigate to the project root directory.
2. Build the debug APK:

   ./gradlew assembleDebug        # macOS/Linux
   .\gradlew.bat assembleDebug    # Windows

   The APK will be generated at app/build/outputs/apk/debug/app-debug.apk.
3. Install to a connected phone (with USB debugging enabled):
   • Via Android Studio: Press Run ▶ with your device selected.
   • Via command line:

     adb install -r app/build/outputs/apk/debug/app-debug.apk

     (If using the workspace-local SDK tools, run: & ".android-sdk\platform-tools\adb.exe" install -r "app\build\outputs\apk\debug\app-debug.apk")

---

How to use the app

The app navigation consists of three main bottom tabs: Practice, Schedule, and Library. A settings gear icon is accessible in the top-right app bar of the Practice tab.

1. Practice Tab

1. Select your target Routine from the horizontal list at the top. Available routines include:
   • Opening/Closing
   • Five Loosening Exercises
   • Full Form (Short Form sequence)
   • Form Section 1 / Form Section 2
   • Posture Drill (allows picking a specific form movement like Snake Creeps Down or Single Whip).
2. Adjust the practice duration using the quick-select buttons (e.g., 5 min, 10 min, 20 min) or fine-tune using stepper controls.
3. Tap Start. The circular timer sequences through the routine steps, playing a chime at each step transition.
4. If you practiced without the timer, tap Log Practice Manually at the bottom of the screen to add a session.

2. Schedule Tab

• Streak Stats: Check your current practice streak, longest streak, weekly minutes, and last practiced date.
• Heatmap: A seven-day heatmap displays your daily practice habits in jade and gold.
• Practice Log: View previous practice entries in reverse-chronological order.
  • Tap the edit icon to append or modify a private practice note.
  • Tap the delete icon to remove the log entry (with confirmation).

3. Library Tab

• Short Form Postures: View the full sequence of postures with preferred names, phonetic Chinese characters, and posture descriptions.
• Core Principles: Browse cards explaining foundational Tai Chi concepts like Yi (Intention), Chi (Energy), Li (Force), Opening & Closing, and the Five Loosening Exercises.

4. Settings Screen

• Reminders: Configure daily or weekly practice reminders.
  • Standard reminders use WorkManager for battery-friendly, inexact scheduling.
  • Exact reminders use AlarmManager for precise timing (requires opting into the Android exact alarms permission).
• Export Practice Log: Generates a CSV file containing your practice history and triggers the system share sheet for local backup or sharing.

---

Privacy

• No Internet Permission: The app does not declare the android.permission.INTERNET permission. No data can leave your device.
• Local Storage: All practice logs, routines, and settings are stored locally on the device using a Room SQL database.
• No Cloud Backup: The database is excluded from Android's automatic cloud backups via custom data_extraction_rules.xml.

---

For developers

Tech Stack

• UI / Presentation: Jetpack Compose, Material 3, Navigation Compose
• Dependency Injection: Dagger Hilt
• Local Database: Room Database
• Background Tasks: WorkManager (for reminders)
• Audio Feedback: SoundPool
• Key Versions: Kotlin 2.3.21, AGP 9.2.1, Room 2.8.4, compileSdk/targetSdk 36, minSdk 26

Build & Test Commands

.\gradlew.bat assembleDebug              # Build the debug APK
.\gradlew.bat testDebugUnitTest          # JVM unit tests
.\gradlew.bat connectedDebugAndroidTest  # Instrumented UI tests (device/emulator required)

Learning Resources (Tai Chi Philosophy and Books)

• Yi Chi Li Theory of Tai Chi by Glenn Blythe
• Yi Chi Li of Opening & Closing and the Five Loosening Exercises of Tai Chi by Glenn Blythe
• A Single Step by Wee Kee Jinn
• Taijiquan Wuwei - a Natural Process by Wee Kee Jinn
• Taijiquan - True to the Art by Wee Kee Jinn
• Brennan Translation
• Tai Chi School Yi Chi Li

Seeding Data

The application database is seeded on first launch from app/src/main/assets/seed_data.json containing the posture lists, routines, and principle cards. The seeder parses this JSON file and writes the content to Room tables. If you modify seed data in development, you can clear app data or increment DATABASE_VERSION to trigger re-seeding.

---

License

This project is licensed under the MIT License - see below for details.

MIT License

Copyright (c) 2026 Tai Chi Practice & Timer Authors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.