# Vocal Stage Kit — Full Technical Documentation & LLM Specification
> Your Entire Stage, In Perfect Sync.
> The all-in-one digital toolkit for sheets, lyrics, tuning, and real-time band sync—right from your Tablet.

## System Overview
Vocal Stage Kit (https://www.vocalstagekit.com) is an enterprise-grade SaaS web platform engineered specifically for stage musicians, lead vocalists, bands, orchestras, sound engineers, and stage managers. It replaces paper setlist binders and static PDF score files with an intelligent, dynamic stage portal offering synchronized multi-device screen control, real-time 1-click chord key transposition, synchronized neon scrolling lyrics, sheet music rendering, and integrated pro-musician tools.

---

## Complete Technical Architecture & Specifications

### 1. Live Orchestra Band Sync Protocol
- **Master/Client Architecture**: Band leaders operate as the Master controller; band members connect as Client receivers.
- **Session Handshake**: 6-digit room code validation (e.g., `STAGE1`).
- **Low-Latency Screen Control**: Master device broadcasts active song index, lyric scroll offset, and key transposition. Client devices auto-scroll and sync in under 100ms.
- **Role-Based Views**: Lead singers view large neon lyrics; guitarists/bassists view transposed chord charts; drummers view backing tracks and metronome tempos.

### 2. Real-Time Chord Engine & Transposition Algorithm
- **Format Support**: ChordPro syntax, bracketed inline chords (`[Am]`, `[C#m7]`, `[Fmaj7/G]`), and plain text chord sheets.
- **Transposition**: Pitch shift algorithm from -12 to +12 semitones.
- **Enharmonic Accidental Normalization**: Configurable Sharp (♯), Flat (♭), or Smart Enharmonic key notation.

### 3. Karaoke Mode & Dynamic Vocal Teleprompter
- **Full-Screen Karaoke Display**: High-contrast, distraction-free karaoke view with large neon typography, contrast options, and stage background illumination.
- **Time-Aligned Neon Lyric Scroll**: Variable-speed auto-scroll synchronized with audio backing tracks or manual tempo triggers for lead singers and backing vocalists.
- **Vocal Pitch & Key Controls**: Integrated 1-click transposition allowing singers to adjust song key to their vocal range.

### 4. Personal Playlist & Custom Setlist Builder
- **User-Scoped Playlists**: Create, edit, and manage private setlists, gig playlists, and custom song collections.
- **Custom Reordering & Notes**: Drag-and-drop song arrangement, custom performance notes per song (e.g., "Capo 2", "Solo Sax"), and total duration calculation.
- **Venue Tagging**: Categorize playlists by venue (Concert, Bar/Pub, Wedding, Festival, Rehearsal, Karaoke Event).

### 5. Digital Sheet Music & Score Visualization
- **OpenSheetMusicDisplay (OSMD)**: Renders MusicXML / MXL vector music scores natively on touchscreens.
- **ABC Notation Engine**: Translates ABC music notation into SVG staves with key transposition support.
- **PDF & Image Viewer**: High-definition zoomable chord sheet and score viewer with dark stage mode background.

### 6. Professional Musician Utility Suite
- **Web Audio Metronome**: High-precision Web Audio API audio-context pulse generator with 30-280 BPM range, tap tempo, sub-beat visual pulses, and accent beats.
- **Chromatic Tuner**: Real-time microphone audio input analysis using Autocorrelation pitch detection algorithm for guitar, vocal, bass, and brass calibration.
- **Chord Finder**: Visual piano keyboard and guitar fretboard chord diagram generator.

### 7. Multi-Tenant Data Isolation & Security
- **Authentication**: Laravel Sanctum bearer token authentication.
- **User Isolation**: Setlists, custom repertoire, appearance settings, and musician roles are strictly user-scoped.
- **Admin Control**: User role management, impersonation token generation, brand logo studio, and audit logging.

### 8. Dynamic Multi-Language Architecture (i18n Engine & Locale Auto-Discovery)
- **Build-Time Glob Import**: `src/locales/index.ts` uses Turbopack `import.meta.glob("./*.json", { eager: true })` to auto-discover and register any `.json` language file dropped into `src/locales/` — no code changes, no import lists.
- **Currently Active Locales (10)**: Deutsch (`de`), English (`en`), Español (`es`), Français (`fr`), हिन्दी (Hindi) (`hi`), Italiano (`it`), 日本語 (`ja`), Русский (`ru`), Türkçe (`tr`), 简体中文 (`zh`).
- **Self-Describing Files**: Each locale JSON carries a `_meta` block (native name + flag emoji); a fallback metadata table covers 50+ world languages by ISO code.
- **Master Fallback**: `en.json` — `t(key)` resolves active locale → English → raw key.
- **Admin Locale Creator**: 1-click admin interface for generating, cloning, translating, and exporting new language JSON packages.

---

## Canonical Routes & Endpoints
- **GET `https://www.vocalstagekit.com/`**: Public Landing Page with feature highlights, store badges, and brand showcase.
- **GET `https://www.vocalstagekit.com/songs`**: Repertoire search and public song score directory.
- **GET `https://www.vocalstagekit.com/songs/[id]`**: Song score detail, chord transposer, and lyric scroll viewer.
- **GET `https://www.vocalstagekit.com/tools`**: Integrated musician tools (Metronome, Chromatic Tuner, Chord Transposer).
- **GET `https://www.vocalstagekit.com/dashboard`**: Private user setlist dashboard & playlist manager.
- **GET `https://www.vocalstagekit.com/stage/[setlistId]`**: Live band orchestra sync portal.
- **GET `https://www.vocalstagekit.com/settings`**: Personal stage settings, themes, and 27 instrument position roles.
- **GET `https://www.vocalstagekit.com/admin`**: Super Admin suite (Users, Payments, SEO & Logo Studio, i18n Manager, Audit Logs, SMTP).
- **GET `https://www.vocalstagekit.com/sitemap.xml`**: Multi-lingual XML Sitemap with hreflang alternates and XSL browser stylesheet.
- **GET `https://www.vocalstagekit.com/robots.txt`**: Bot crawling policy rules for search engines and AI crawlers.
- **GET `https://www.vocalstagekit.com/llms.txt`**: AI search engine summary specification.
- **GET `https://www.vocalstagekit.com/llms-full.txt`**: Comprehensive technical specification for Large Language Models.