GitHub - baijum/ukulele-companion: A free, offline, ad-free Android app for learning ukulele — interactive fretboard, chord library, scales, strumming patterns, music theory, ear training, and more. Built with Kotlin and Jetpack Compose. Contributions welcome!

An offline app for learning ukulele — on Android and iOS
Chords, scales, music theory, composition tools, and more.
Built with Kotlin Multiplatform, Jetpack Compose, and SwiftUI.

🎸 Interactive Fretboard Explorer

Tap fret positions on a visual ukulele fretboard (standard GCEA tuning, frets 0–12) and the app instantly detects and displays the chord. Supports 20 chord types across triads, sevenths, suspended, and extended chords. Shows alternate notational symbols ("Also written as") so you can recognize chords written in different styles.

📚 Chord Library

Browse playable voicings for any chord. Select a root note, category (Triad, Seventh, Suspended, Extended), and chord type to see algorithmically generated voicings displayed as mini fretboard diagrams.

🔄 Transpose

Shift chords up or down by semitones with +/- buttons. Shows the capo equivalent for easy reference.

🧠 Neural-Powered Tuner

The tuner now uses a hybrid pipeline: fast YIN pitch tracking on every frame, supervised by SwiftF0 neural inference at intervals. This improves robustness against octave mistakes and unstable frames while preserving responsive needle movement.

🥁 Strumming & Fingerpicking Patterns

A reference guide with 15 strumming and 11 fingerpicking patterns — from beginner to advanced — in 4/4, 3/4, and 6/8 time. Each pattern includes visual beat/step display, notation, description, and a play button with adjustable tempo so you can hear what each pattern sounds like. Create custom patterns with adjustable beat counts (2–16) and time signatures, or duplicate any preset to make your own variations.

🎶 Chord Progressions

Common chord progressions for any key across seven modes (Major, Minor, Dorian, Phrygian, Lydian, Mixolydian, Locrian). Each chord chip shows its harmonic function (Tonic, Subdominant, Dominant) with colour coding. Includes Pop, Classic Rock, 50s, Folk, Jazz ii-V-I, Reggae, and more. Create custom progressions with diatonic chord suggestions from the selected scale, duplicate presets, copy to clipboard, and use tap tempo for practice.

🎼 Scale Overlay

Highlight notes from any of 38 scales (Major, Natural/Harmonic/Melodic Minor, Pentatonic, Blues, modes, Bebop, Diminished, and more) directly on the fretboard. Filter by fret position and see the diatonic chords for each scale.

⭐ Favorites

Long-press any voicing in the Chord Library to save it. Access your saved voicings from the dedicated Favorites tab.

📝 Song Chord Sheets

Create a personal songbook with lyrics and inline chord markers (e.g., Some[C]where over the [Em]rainbow). Search, sort, label, and batch-manage songs for easy organisation. Associate strum patterns, use quick-insert chord chips in the editor, and preview chords above lyrics in real time. Tap any chord name to see its diagram, hear it played, or jump to the library. Organise songs into setlists for gigs and practice sessions. Use Performance Mode for full-screen, hands-free viewing with adjustable auto-scroll. Jump between sections (Verse, Chorus, Bridge), adjust font size, and start the metronome at the song's BPM. Track view count and total practice time. Transpose songs with +/- controls and Save in this key to permanently rewrite chords. Share via ChordPro, plain text, PDF, or clipboard. Duplicate songs and import by pasting ChordPro text.

🎵 Metronome

A standalone practice metronome with adjustable BPM (30–300), tap tempo, time signatures (2/4 to 7/4), customizable accent patterns, and subdivisions (quarter, eighth, triplet, sixteenth). Visual beat indicators pulse in time.

🎹 Melody Notepad

Compose melodies by tapping notes, recording from your ukulele's microphone, or using the step sequencer — a grid of 8 or 16 steps for building loops and rhythmic patterns. Choose note durations, set the octave, and play back at any tempo. Save and load multiple melodies.

✍️ Songwriter Mode

A guided "Start a Song" flow that walks you through picking a key and scale, building a chord progression from diatonic suggestions, writing lyrics with inline chords, transposing, and saving to your songbook — all in one place.

🔊 Sound Playback

Hear chords played back using sampled ukulele audio. Notes are strummed with a configurable delay between strings.

🎓 Music Theory & Learning

Theory lessons, ear training, interval trainer, circle of fifths, glossary, scale practice, achievements, and more.

Ukulele Companion is designed to be usable by everyone, including blind and visually impaired musicians:

ukulele-companion/
├── shared/                          # Kotlin Multiplatform shared module
│   └── src/
│       ├── commonMain/              # 55 Kotlin files — domain + data logic
│       │   ├── domain/              # ChordDetector, PitchDetector, Transpose, etc.
│       │   └── data/                # Notes, Scales, ChordFormulas, Progressions, etc.
│       ├── androidMain/             # Android platform actuals (UUID, Calendar)
│       └── iosMain/                 # iOS platform actuals (NSUUID, NSDate)
│
├── app/                             # Android app module
│   └── src/main/java/com/baijum/ukufretboard/
│       ├── audio/                   # SoundPool, metronome, audio capture
│       ├── data/                    # Repositories (SharedPreferences), backup/restore
│       ├── domain/                  # NeuralPitchSupervisor, AchievementChecker
│       ├── ui/                      # 55 Compose screens and components
│       └── viewmodel/               # 13 ViewModels (StateFlow)
│
├── iosApp/                          # iOS app (SwiftUI)
│   └── UkuleleCompanion/
│       ├── Views/                   # 48 SwiftUI views
│       ├── ViewModels/              # 15 ObservableObject ViewModels
│       ├── Audio/                   # AudioCaptureEngine, TonePlayer, NeuralPitchSupervisor
│       ├── Helpers/                 # Accessibility helpers, backup/restore manager
│       └── Resources/               # WAV samples, ONNX model

git clone https://github.com/baijum/ukulele-companion.git
cd ukulele-companion

# Android
./gradlew assembleDebug

# iOS (requires macOS)
cd iosApp && ./setup_onnxruntime.sh && cd ..
xcodebuild -project iosApp/UkuleleCompanion.xcodeproj \
  -scheme UkuleleCompanion \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  build

The Android debug APK will be at app/build/outputs/apk/debug/app-debug.apk.

# Unit tests (including property-based fuzz tests)
./gradlew testDebugUnitTest

# Instrumented tests (requires emulator or device)
./gradlew connectedAndroidTest

# UI stress test with Android Monkey (requires emulator or device)
./scripts/monkey_test.sh            # 10,000 random events
./scripts/monkey_test.sh 42         # reproducible with seed
./scripts/monkey_test.sh 42 50000   # 50,000 events with seed

The project includes property-based tests using Kotest that generate thousands of random inputs to verify invariants in the domain logic (chord detection, transposition, FFT, pitch detection, and more). These run automatically as part of testDebugUnitTest and in CI on every push and PR.

The AAB will be at app/build/outputs/bundle/release/app-release.aab.

Contributions are welcome! Whether you're fixing a bug, adding a feature, improving documentation, or refactoring code — we'd love your help.

Please read the Contributing Guide for detailed instructions on development setup, code guidelines, and the PR process. All participants are expected to follow our Code of Conduct.

We actively encourage contributors to use AI coding tools to accelerate their work on this project. The codebase is well-structured and AI-friendly:

Detailed feature documentation and a user manual are available in the docs/ directory:

The Complete Ukulele Learning Book is a free PDF guide covering foundations, developing skills, mastery, and a songbook -- from first strums to jazz voicings and fingerstyle. Designed to pair with Ukulele Companion as a structured learning path.

Audio samples are from the "Ukelele single notes, close-mic" pack by stomachache on Freesound.org, licensed under CC BY 3.0. See ATTRIBUTION.md for full details.

Built with ❤️ for ukulele players everywhere
_{Star the repo if you find it useful — it helps others discover the project!}