Jota

A beautiful, minimalist music player with built-in guitar tuner and chord library. Built with Tauri for desktop and deployable to web via Vercel.

Features

🎵 Music Player

• Play audio files (MP3, WAV, OGG, FLAC, M4A)
• Responsive layout:
  • Mobile: Sliding playlist drawer from bottom (60px collapsed, 80% expanded)
  • Desktop: Two-column layout (400px controls + playlist)
• Playback modes: Repeat One, Repeat All, Shuffle (PlaylistController class)
• Playlist management:
  • Multi-select with checkboxes for bulk removal
  • Automatic deduplication (uses file path as ID)
  • Context menu for track operations (reorder, remove)
  • Save and load playlists (.jpl format)
• Playback controls: Previous, Play/Pause, Next with SVG icons
• Seek slider with current/total time displays
• Volume control with mute toggle and dynamic SVG icon
• Animated gradient background during playback (purple/blue tones)
• Automatic track duration detection
• Strip file extensions from track names for cleaner display

🎸 Guitar Tuner

• Real-time pitch detection from microphone
• 6 guitar tuning presets (button grid selector)
• Large, centered tuner display
• Visual cents indicator (±50 cents range)
• Active listening indicator (fading green dot)
• String reference display with active highlighting
• Dimmed display when inactive (opacity-based feedback)

🎼 Chord Library (Dedicated Tab)

• Standardized chords across all tunings
• Root notes: C, D, E, F, G, A, B (button grid)
• Chord variants: Major, Minor, 7, m7, Maj7 (button grid)
• No inversions (all root position for simplicity)
• Button-based selectors throughout (no dropdowns)
• Reusable TuningSelector component (shared with Tuner tab)
• Interactive fretboard visualization
• Vertical orientation (traditional chord shape display)
• Flip button to reverse string order
• Chord selection persists across tuning changes

🎨 Design

• Clean, minimalist black theme (#000 background)
• Styled-components for all UI (CSS-in-JS)
• Responsive: Mobile-first with tablet/desktop enhancements
• Mobile: Sliding playlist drawer from bottom (60px collapsed, 80% expanded)
• Desktop: Two-column layout (400px player controls + playlist)
• Tab-level scrolling configuration
• Feature-based architecture for maintainability

🌐 Cross-Platform

• Desktop: Native Tauri app (macOS, Windows, Linux)
• Web: Deployable to Vercel via Vite build
• Platform-agnostic services (FileService, StorageService)
• Environment detection (EnvironmentService)
• Dynamic imports for Tauri APIs (web build compatibility)

⌨️ Keyboard Shortcuts

• Space: Play/pause current track
• Arrow Right (→): Skip forward 5 seconds
• Arrow Left (←): Skip backward 5 seconds
• Cmd/Ctrl + 1: Switch to Player tab
• Cmd/Ctrl + 2: Switch to Tuner tab
• Cmd/Ctrl + 3: Switch to Chords tab

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher)
• Rust (for Tauri)
• npm or yarn

Installation

1. Clone the repository:

git clone <your-repo-url>
cd jota

2. Install dependencies:

npm install

Development

Desktop Development

Run the Tauri desktop app:

npm run tauri dev

This will start the Vite dev server and launch the Tauri app.

Web Development

Run the web version:

npm run dev

The app will be available at http://localhost:5173

Building

Desktop Build

Build the desktop app for your platform:

npm run tauri build

The built application will be available in src-tauri/target/release.

Web Build & Deployment

Build for web deployment:

npm run build

Deploy to Vercel:

vercel --prod

See DEPLOY.md for detailed deployment instructions.

Icon Generation

If you modify the icon SVG, regenerate all formats:

./scripts/icon.sh

Requires ImageMagick to be installed:

brew install imagemagick

Project Structure

jota/
├── src/                         # React source files
│   ├── App.tsx                  # Main app entry (12 lines)
│   ├── App.styles.ts            # App-level styled components
│   ├── main.tsx                 # React entry point
│   ├── styles.css               # Global CSS reset
│   ├── features/                # Feature-based modules
│   │   ├── navigation/          # Tab management (3 tabs: Player, Tuner, Chords)
│   │   │   ├── Navigation.tsx   # Main navigation component
│   │   │   └── Navigation.styles.ts # Tab bar and content styles
│   │   ├── player/              # Music player
│   │   │   ├── PlayerTab.tsx    # Main player container with state
│   │   │   ├── Playlist.tsx     # Playlist UI with multi-select
│   │   │   ├── PlaylistController.ts # Playback logic (repeat, shuffle, history)
│   │   │   └── *.styles.ts      # Responsive styled components
│   │   └── tuner/               # Guitar tuner & chords
│   │       ├── Tuner.tsx        # Pitch detection tuner
│   │       ├── ChordsTab.tsx    # Chord library viewer (separate tab)
│   │       ├── TuningSelector.tsx # Reusable button grid tuning selector
│   │       ├── Fretboard.tsx    # Chord visualization (vertical/flipped)
│   │       ├── chords.ts        # Chord database (6 tunings)
│   │       ├── usePitchDetection.ts # Pitch detection hook
│   │       └── *.styles.ts      # Styled components
│   └── shared/                  # Shared utilities
│       ├── components/          # Reusable UI components
│       │   ├── Button.tsx       # Button variants (primary, ghost, danger, text)
│       │   ├── Icons.tsx        # SVG icons (playback, volume, chevron)
│       │   ├── ContextMenu.tsx  # Right-click menus
│       │   ├── Select.tsx       # Dropdown select
│       │   └── Modal.tsx        # Modal dialogs
│       ├── types/               # Track interface (with displayName)
│       ├── FileService.ts       # Platform-agnostic file handling
│       ├── FileService.tauri.ts # Desktop file operations
│       ├── FileService.web.ts   # Web file operations
│       ├── StorageService.ts    # Platform-agnostic storage
│       ├── StorageService.tauri.ts # Desktop storage
│       ├── StorageService.web.ts   # Web storage (localStorage)
│       └── EnvironmentService.ts   # Platform detection
├── src-tauri/                   # Tauri backend
│   ├── src/
│   │   └── main.rs              # Rust main file
│   ├── icons/                   # App icons
│   │   ├── icon.svg             # Source SVG icon
│   │   └── *.png, *.icns, *.ico # Generated icons
│   ├── Cargo.toml               # Rust dependencies
│   ├── tauri.conf.json          # Tauri configuration
│   └── entitlements.plist       # macOS microphone permissions
├── scripts/
│   └── icon.sh                  # Icon generation script (ImageMagick)
├── index.html                   # HTML entry point
├── vite.config.ts               # Vite configuration
├── vercel.json                  # Vercel deployment config
├── package.json                 # Node dependencies
├── README.md                    # This file
├── DEPLOY.md                    # Deployment guide
├── ARCHITECTURE.md              # Architecture documentation
└── PROJECT_SUMMARY.md           # Comprehensive project summary

Usage

Navigation

• Top Bar: Switch between Player, Tuner, and Chords tabs
• Mobile: Tabs span full width
• Desktop: Side-by-side layout with responsive controls

Player Tab

Desktop Layout:

• Left column (400px): Album cover (200×200), track title, seek slider, playback controls (prev/play/next), repeat/shuffle buttons, volume control
• Right column: Full playlist with checkboxes and controls

Mobile Layout:

• Main area: Vertically centered album cover (150×150), track title, seek slider, playback controls, repeat/shuffle, volume
• Bottom drawer: Sliding playlist (collapsed = 60px, expanded = 80% of screen)
  • Header always shows: "Playlist (X)", chevron toggle, "+ Add", "⋯" menu
  • Tap chevron to expand/collapse

Features:

1. Add tracks: Click "+ Add" to select audio files (auto-deduplication)
2. Play tracks: Click any track in the playlist
3. Select tracks: Check boxes on the left of each track
4. Remove tracks: Select multiple tracks → "Remove (X)" button appears
5. Seek: Drag slider or click to scrub through track
6. Volume: Slider + mute button (SVG icon changes based on level)
7. Repeat modes: None → Repeat All → Repeat One (cycle)
8. Shuffle: Random playback with history for "previous"
9. Context menu: Right-click tracks for move up/down/remove
10. Save/Load: "⋯" menu → Load or Save playlist (.jpl format)
11. Visual feedback: Animated gradient background during playback

Tuner Tab

1. Select a guitar tuning from the button grid
2. Click "Start Tuner" to begin pitch detection
3. Play a note on your guitar near the microphone
4. The tuner displays detected note, frequency, and cents deviation
5. String reference notes highlight when matched
6. Display dims when inactive (full opacity when listening)
7. A green dot on the Tuner tab indicates active listening

Chords Tab

1. Select tuning: Choose from 6 guitar tuning presets (button grid)
2. Select root note: Click one of 7 natural notes (C-B)
3. Select variant: Choose chord type (Major, Minor, 7, m7, Maj7)
4. View fretboard: Chord shape displays automatically
5. Flip orientation: Toggle vertical string order
6. Persistence: Chord selection preserved across tuning changes (resets only if chord doesn't exist in new tuning)

Technologies Used

• Tauri v1: Lightweight desktop application framework
• React 18: UI library with hooks
• TypeScript: Type-safe JavaScript
• Vite: Fast build tool and dev server
• Styled-Components: CSS-in-JS for component styling
• Web Audio API: Pitch detection and audio analysis
• Rust: Backend for file system and dialog operations
• Vercel: Web deployment platform

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.