The distraction-free way to find, read, and play guitar chords, right in your browser.
Chordium is designed with simplicity in mind, helping new guitar players and casual enthusiasts learn songs without visual clutter:
- Install-less App (PWA) - Works offline and installs like a native app
- Clean Interface - Distraction-free chord viewing experience
- Smart Search - Search by artist, song title, or lyrics. Voice-enabled for hands-free searching
- Transpose & Capo - Shift chords to any key or capo position on the fly
- Auto-scrolling - Practice at your own pace with speed controls
- Dark Mode - Light, dark, and system theme options
- Mobile-friendly - Learn on-the-go with responsive design
- File Upload - Import your own chord sheets with metadata extraction
- Works Offline - Install as a native app, fully functional without internet
- Transpose & Capo - Shift chords to any key or capo position on the fly
- Fullscreen Mode - Distraction-free fullscreen reading with translated lyrics side-by-side
- Auto-scrolling - Practice at your own pace with speed controls
Scan a QR code or tap a link to instantly share the exact chord sheet you're viewing — no account, no server round-trip, ready to play the moment it opens.
- React + TypeScript - Modern UI with type safety
- Vite - Fast build tool and development server
- Tailwind CSS + shadcn/ui - Beautiful, accessible components
- React Router - Client-side navigation
- @tanstack/react-query - Data fetching and state management
- Vercel Serverless Functions - API endpoints in
frontend/api/ - Neon - PostgreSQL database (via Vercel Postgres)
- @sparticuz/chromium + Puppeteer - Headless scraping for chord sheets
- Turborepo - High-performance build system for monorepos
- npm Workspaces - Monorepo dependency management
- @chordium/types - Shared TypeScript types published to npm
- Vitest + Jest + Cypress - Comprehensive testing
- OpenAI Whisper - On-device voice search (original, ONNX model)
| Topic | Description |
|---|---|
| Getting Started | Installation, setup, and development commands |
| Testing | Testing frameworks, running tests, and guidelines |
| Error Handling | Error recovery and user-friendly error messages |
| Project Structure | Codebase organization and architecture |
| Deployment | Frontend and backend deployment guides |
| Contributing | How to contribute to the project |
| Backend API | Backend documentation and API reference |
| Search Guide | Smart search functionality details |
| Monorepo | Monorepo architecture and workspace management |
| Cache Architecture | Frontend caching system design and implementation |
| Build Optimizations | Performance optimizations and bundle configuration |
| PWA Development | PWA setup, development workflow, and features |
| Technical Decisions | Key architectural decisions and rationale |
| Offline Translation | Translation without internet connection |
git clone https://github.com/arthurboss/chordium.git
cd chordium
npm install
npm run devSee Getting Started for full setup and commands.
This project follows semantic versioning (semver):
- MAJOR - Breaking changes
- MINOR - New features (backwards compatible)
- PATCH - Bug fixes (backwards compatible)
Each version bump is tagged in git as v<major>.<minor>.<patch> (e.g., v0.5.0) and published as a GitHub Release. See Releases for the full changelog.
For developers: When you merge a version bump PR, create a corresponding git tag:
git tag v<major>.<minor>.<patch> <commit-hash>
git push origin v<major>.<minor>.<patch>Then add release notes on GitHub describing what changed in that version.
This project is licensed under the MIT License - see the LICENSE file for details.