1. Getting Started

Welcome to your digital practice companion. This app is designed specifically for classical guitarists to move away from messy notebooks and into a structured, data-driven practice routine.

• Authentication: Log in with your email to sync your data across devices. Guest mode is available for local-only storage.
• The Dashboard: Your screen is split into two main areas: Repertoire Library (Left) and Today's Session (Right).
• Session Persistence: The app remembers your last used repertoire list and automatically loads it when you return, ensuring a seamless transition between practice sessions.

2. Navigation & Header Controls

The top header provides quick access to global functions, cloud synchronization, and your practice history.

3. Internationalization & Languages

The application is localized to support a global community of classical guitarists. Our translation engine ensures that technical musical terms are accurate across all supported languages.

Changing Languages

You can switch languages at any time using the Globe/Flag icon in the top-right corner of the header. The dropdown menu provides instant access to several languages, including English, French, Spanish, German, and Russian.

Sync Policy

"Language preferences are securely stored in your user profile. If you switch to Spanish on your phone, the app will automatically present the Spanish interface when you log in on your tablet or desktop later."

4. Repertoire Management

Your library is the foundation of your practice. It stores every piece you are currently working on or have mastered.

5. Planning Your Session (Drag & Drop)

The right panel represents your plan for today. You can build it by pulling items from your library.

• Adding to Session (Drag & Drop): Simply click and drag a piece from the Repertoire Library and drop it into the Today's Session table. You will see a blue highlight indicating where the piece will land.
• Session Notes & Goals: At the top of the session table, you'll find a dedicated text field for Session Notes. Use this to record your specific focus for the day, technical reminders, or general goals. This note is saved to your practice diary when you finish the session.
• Removing from Session: If you decide you don't want to practice a piece today, you can drag it back from the session table and drop it over the library table. Alternatively, use the "X" icon next to the piece in the session.
• Editing Details: Double-click any piece in either the Repertoire or Today's Session table to quickly open the Edit Piece Details panel.
• Organized Layout: We've introduced dedicated columns for attachments. PDF, MusicXML, and MIDI files are displayed with distinct, colored icons for quick access.

Visual Reference: Attachment Icons

• Daily Grouping: All pieces practiced on a single day are automatically saved to the same practice session.
• Simple Timer & Alerts: A dedicated settable timer is available in the session header. You can set a specific duration (e.g., 20 minutes) and receive an alert when time is up.
• Tracking Progress: Mark a piece as "Done" once you've finished practicing it. When clicked, the circular indicator turns bright green.

6. Sheet Music (PDF) & Google Drive

Keep your scores organized and accessible directly within your practice environment. We now support both direct uploads and Google Drive integration.

• Attaching a Score: When adding or editing a piece, use the "Sheet Music (PDF)" field. You can upload a file directly or link a file from your Google Drive.
• Google Drive Integration (Optional): Click the Cloud icon next to the file input to open the Google Drive Picker. This allows you to link scores already stored in your Drive without duplicating them in our cloud storage. Note: Using Google Drive is entirely optional.
• Drag-and-Drop: For a faster workflow, you can drag a PDF file directly from your computer (e.g., macOS Finder) and drop it onto any piece in the Library or Today's Session table.
• Viewing Scores: Pieces with attached scores will display a red PDF icon in the Action column. Click this icon to open the immersive PDF viewer.
• The PDF Viewer: The integrated viewer provides a clean interface for reading your music. It includes support for Linked Google Drive files, which are rendered seamlessly.

7. Interactive MusicXML Playback & Looping

The application features a sophisticated MusicXML score viewer and playback engine powered by OpenSheetMusicDisplay (OSMD). This allows you to view interactive scores, listen to high-quality classical guitar synthesis, and practice specific sections using advanced looping controls.

8. MIDI Playback & Reference

Listen to a reference performance of your repertoire directly within the app. This is invaluable for checking rhythms, tempos, and overall musical flow.

• Attaching MIDI Files: When adding or editing a piece, use the "MIDI File" upload field. We support standard .mid and .midi files. The app validates the file header to ensure it's a valid MIDI sequence.
• Drag-and-Drop: You can also drag a MIDI file from your file explorer and drop it directly onto a piece in either table to instantly attach it.
• Accessing the Player: Pieces with attached MIDI data will display a blue Music Note icon in the Action column. Click this icon to open the immersive MIDI player modal. We've consolidated the interface to show a single, clickable icon for better clarity.
• Interactive Progress Bar: The progress bar is fully interactive. You can click or drag the slider to seek to any point in the performance. The time indicator updates in real-time as you drag, allowing for precise navigation.
• Playback Controls:
  • Play/Pause: Start or pause the performance. The icon toggles between a triangle (Play) and double bars (Pause).
  • Stop: Ends playback and resets the position to the start.
  • Rewind: A dedicated button (|◀) to instantly jump back to the beginning of the piece without stopping.
• Volume Control: Adjust the output level using the volume slider. This setting is independent of your system volume, allowing for fine-tuned balancing during practice.
• Sound Check: If you don't hear any sound, click the "Sound Check" button. This plays a short test tone and ensures the browser's audio engine is active and ready for playback.
• Immersive Experience: The player is designed to be distraction-free, focusing on the music and your progress through the piece.

9. Spaced Repetition System (SRS)

The Spaced Repetition System (SRS) is a powerful tool designed to help you master difficult musical excerpts. Instead of practicing everything every day, the system intelligently schedules excerpts based on your previous reviews.

Library View Modes

You can now toggle between two distinct view modes in the SRS Library. The app remembers your preference for future sessions.

• Grid View: A visual gallery of cards, perfect for scanning thumbnails of your musical excerpts.
• List View: A compact, text-based list that displays the Title, Composer, and Description. This is ideal when you have a large library of excerpts to navigate.

Editing Excerpts

Click the Pencil icon on any card or list item to update its metadata. You can now modify the Title, Composer, and the detailed Description fields.

Simplified Workflow

We have removed complex grading tiers. Simply practice the excerpt, and click "Complete" to log it. The next review will be scheduled for the following day by default.

10. The Practice Diary & Data Export

The Diary tracks your progress over time. Every time you "Finish Session", your work is logged here.

• Saving a Session: Click "Save Session" to log all completed pieces to your diary. This clears them from your active session.
• Viewing History: Click the "History" icon in the header. You can expand previous dates to see exactly what you practiced, including tempos and notes.
• Session Notes History: Your session notes are displayed prominently alongside the date in your diary. You can edit these notes directly in the history panel at any time—just click on the note text to enter editing mode and press Enter or click away to save.
• Fuzzy Search: Use the search bar at the top of the History panel to find specific pieces or composers. The app will display a chronological list of every day you practiced that piece, along with the specific tempos, measure ranges, and notes recorded for those sessions. The search is optimized for precision, ensuring that numbered pieces (e.g., "Prelude No. 5") are correctly distinguished from similar works.
• Measure Practice Summary: When you filter the diary down to a single piece (by typing its name in the search box), a smart summary appears at the top. This summary automatically merges all the measure ranges you've practiced over time, showing you exactly which parts of the piece you've covered and where the gaps are.
  • Example: If you practiced "1-10" on Monday and "15-20" on Tuesday, the summary will show "1-10, 15-20". If you then practice "11-14" on Wednesday, it will automatically merge into "1-20".
• Exporting Data: You can now export your practice history for external review or archival. Click the "Export" icon in the History panel.
  • Formats: Choose between Plain Text, PDF Report, or CSV Spreadsheet.
  • Date Range: Select a specific start and end date to export only the relevant portion of your history.
• Piece History: Right-click any piece in your library and select "View Practice History" to see every time you've worked on that specific work.

11. Saved Repertoire Lists & Favorites

Organize your repertoire into distinct sets for different contexts, such as solo performances, guitar quartet sessions, or orchestral work.

• Creating a List: Click "Save as List" in the Library section to save your current repertoire table. You can give it a name like "Solo Recital 2026" or "Quartet Repertoire".
• Favorite Lists: You can mark any saved list as a Favorite by clicking the Star icon in the list menu or the Saved Lists manager.
  • Tabbed Access: Favorite lists appear as dedicated tabs at the top of your Repertoire section, allowing for instant switching.
  • Draggable Reordering: You can click and drag these tabs to reorder them. Your custom order is automatically saved and remembered for your next session.
• Accordion Navigation: The Saved Lists modal uses an accordion behavior to keep your view organized. Expanding one list will automatically collapse any others, ensuring you only see the details for the list you're currently focused on.
• Structured Data Table: When a list is expanded, its contents are displayed in a professional, compact table showing both the Composer and the Title for every piece. The table is automatically sorted by Composer for easy scanning.
• Edit List Name: Click the "Pencil" icon next to any saved list to rename it.
• Full State Preservation: Saved lists capture the entire state of every piece, including attached PDFs, last practiced dates, specific measure ranges, and notes.
• Loading a List: Click the "Folder" icon in the header or the green folder icon next to a list name to load it. Loading a list will replace your current library view with the saved pieces.
• Active List Header: When a list is loaded, its name is prominently displayed at the top of the Library table in blue.
• Automatic Saving: While a list is active, any changes you make (editing a piece, adding a new one, or removing one) are automatically saved to that list.
• Exporting Lists: Click the "Download" icon next to any saved list to export it as a .txt file. This icon is conveniently located in the same row as the Edit and Delete actions.

12. Integrated Tools

The app includes a professional-grade metronome designed for precision and auditory clarity.

Interface Reference: Metronome

The metronome is located at the bottom-right of your practice dashboard.

• Core Controls: Located at the bottom-right of the screen by default. You can drag the metronome to any position on the screen that works best for your layout. You can adjust BPM using the slider, +/- buttons, or by typing directly. The visualizer shows the current beat within the measure.
• Subdivisions: Use the note icons next to the time signature to choose between Quarter Notes, Eighth Notes, Eighth Note Triplets, and Sixteenth Notes. Subdivisions are played at a slightly lower volume to help you maintain the main beat.
• Auto-Sync Tempo: Clicking the "Play" icon next to a piece's tempo in the session table will automatically set the metronome to that BPM.
• Metronome Presets: Click the "List" icon to manage your metronome presets.
  • Saving: Save your current BPM, subdivision, time signature, sound type, and accent settings as a named preset.
  • Loading: Quickly switch between practice configurations by selecting a preset from the list. The list displays key details like BPM, sound type, and accent status for each entry.
  • Persistence: Presets are saved to your account and synced across devices, ensuring your favorite practice tempos are always available.
• Sound Customization: Click the "Music Note" icon to open the Sound Settings.
  • Sound Type: Choose between Electronic (sine), Woodblock (triangle), or Cowbell (square).
  • Independent Pitch: Set different frequencies (Hz) for the accented downbeat and regular beats to create the perfect auditory "pocket".
  • Independent Volume: Balance the relative volume of the accent vs. normal beats.
• Auto-Increment Tempo: Click the "Rising Graph" icon to open the Auto-Increment settings.
  • Mode: Choose between incrementing every X Bars or every X Minutes.
  • Interval: Set how often the increment should occur (e.g., every 4 bars).
  • Amount: Set how many BPM to add at each interval (e.g., +2 BPM).
  • Tip: This is essential for "speed bursts" or gradual tempo building in technical studies.

13. Practice Tools

The Practice Tools section provides specialized utilities for technical development and musical visualization. Access these tools by clicking the "Puzzle Piece" icon in the header.

Chromatic Tuner

Stay in tune without leaving the app. Uses your device's microphone to detect pitch in real-time.

• Visual Dial: High-precision needle meter for accurate tuning. The needle responds in real-time to your instrument's pitch.
• Color Coding: Instant feedback via intuitive color shifts—Red when flat, Blue when sharp, and Bright Green when perfectly in tune (within ±3 cents).
• In-Tune Indicator: A dedicated check-mark and glowing halo appear when you reach the target pitch.
• Tuning Presets: Use the dropdown menu to select between Standard, Drop D, G Tuning (Renaissance), DADGAD, or Open D.
• Reference Tones: Includes reference tones for each string in the selected tuning for tuning by ear.

Fretboard Visualizer

Visualize and play scales across the neck. Now includes the integrated Scale Generator.

• Scale Challenges: Generate random Key/Type/Pattern combinations for practice.
• Interactive Playback: Hear the scales with high-quality nylon guitar samples.

String Change Tracker

Maintain your guitar's tone by tracking string age and maintenance history.

• Change History: Log the date, brand/type, and notes for every string change.
• Maintenance Logs: View a chronological list of past changes to identify your preferred string life.
• Quick Add: Easily log new changes directly from the Tools panel.

Fretboard Visualizer & Scale Challenges

The Fretboard Visualizer is now the primary engine for scale practice, incorporating the functionality of the previous Scale Generator tool.

Interface Reference: Fretboard Visualizer

• Scale Challenges: Click "New Challenge" to generate a randomized practice goal. The system will select a Key, Scale Type (e.g., Harmonic Minor), technical Pattern (e.g., "In 3rds"), and Fretboard Position. This helps prevent technical stagnation.
• Interactive Playback: Click "Play Scale" to hear the currently selected scale played with a high-quality nylon guitar sound. The button toggles to "Stop Playback" during performance.
• Rhythmic Precision: Playback is perfectly synchronized with the internal tempo. The system uses a high-precision scheduler to ensure every note falls exactly on the beat.
• Intelligent Looping: Enable "Loop" for continuous practice.
  • Seamless Transitions: The timing between loop iterations is perfectly maintained.
  • No Root Repetition: When playing in Descending mode with Loop enabled, the system intelligently skips the repeated root note at the turnaround.
• Position Focus Mode: Enable "Position Focus" to only display notes within the selected fretboard position (e.g., 5th Position), helping you master specific scale shapes.
• Visual Feedback: As the scale plays, the current note is highlighted with a glowing blue marker on the fretboard.

14. PDF Annotation & Score Viewer

Mark up your scores directly within the app to highlight difficult passages or fingerings.

Tip: Use a tablet and stylus for the most natural annotation experience on your music stand.

15. Bluetooth Foot Pedal Support

The PDF Viewer supports standard Bluetooth foot pedals (like AirTurn, PageFlip, or Donner) for hands-free page turning while playing.

16. Cloud Manager & Troubleshooting

The Cloud Manager (located in the Admin Panel) provides a comprehensive overview of your application's resource usage and document management.

Note: Deleting a document from the Cloud Manager is permanent and will remove the score/MIDI from all associated repertoire items.

17. Settings & Preferences

The Settings panel allows you to tailor the application's behavior and appearance. Access it via the Admin/Gear icon.

18. Customization & Themes

Practice in an environment that suits your mood.

Open the "Settings" (Admin Panel) to choose from several themes: Midnight (Dark), Nord (Cool), Solarized (Warm), Paper (Light), or Gruvbox (Retro). You can also toggle "Skip Save Confirmations" for a faster workflow.

19. Interface & Dialogs

The app uses a custom dialog and notification system to provide a consistent visual experience across all interactions.

• Consistent Branding: All alerts, confirmations, and prompts are branded with the app's name, "Classical Guitar Practice Planner".
• Toast Notifications: For non-critical confirmations (like "Session Saved", "Data Exported", or "PDF Deleted"), the app uses subtle "toast" notifications that appear briefly at the bottom of the screen and disappear automatically, ensuring your workflow remains uninterrupted.
• Responsive Design: Dialogs are designed to work seamlessly on both desktop and mobile devices.
• Keyboard Support: You can use the Enter key to confirm and Escape to cancel most dialogs.

20. PWA Installation & Refresh

The Classical Guitar Practice Planner is built as a Progressive Web App (PWA), allowing you to install it on your device for a native-like experience.

21. Version History