LyricMachine

A full-stack web application for live musical performance, setlist management, and dynamic lyrics display. Built to be used during live jam sessions.

Overview

LyricMachine combines a robust library management system with a high-performance, responsive lyrics and chords display. It deeply integrates with the Spotify Web API and Ultimate Guitar to automate data aggregation, allowing musicians to focus on the music.

Key Features

Performance Display

• Zero-Reflow Lyrics Engine: Custom DOM-based renderer utilizing binary-search font sizing and pretext arithmetic for zero-reflow, responsive text layouts across devices.
• Dynamic Formatting: Smart line merging for shorter phrases, repeat collapsing (e.g., "[Chorus] x3"), and alternating tint colors for repeated sections or specific vocal parts.
• Teleprompter & Karaoke Modes: Smooth, auto-scrolling teleprompter view and a dedicated Karaoke mode with synchronized lyric highlighting.
• Intelligent Pagination: Multi-column auto-layout and multi-page pagination that perfectly fits your screen size.
• Chord Integration: Import from Ultimate Guitar, instant transposition by semitone (including slash chords), and Capo auto-detection.

Spotify Integration

• Bi-Directional Sync: Robust synchronization engine with mutex guards and parallel fetching to keep your local library in sync with a Spotify source playlist.
• Web Playback SDK: Full track playback directly in the browser for Spotify Premium users, with an intelligent fallback to 30-second preview clips.
• Automated Metadata: Auto-imports songs, backfills album art, and fetches lyrics automatically via Lrclib.net.

Library & Setlist Management

• Interactive Kanban Board: Drag-and-drop songs across customizable progress states (e.g., Ignored, Fresh, Getting There, In Setlist).
• Advanced Library View: Paginated multi-column grid with robust right-click context menus, multi-filtering, and sorting capabilities.
• Song Randomizer: Slot-machine style random song picker with celebration effects and Spotify autoplay integration.

Quick Start

1. Install dependencies:

npm install

2. Configure environment variables. Copy .env.example to .env and fill in your Spotify credentials from the Spotify Developer Dashboard.

   • SPOTIFY_CLIENT_ID: Your client ID
   • SPOTIFY_CLIENT_SECRET: Your client secret
   • SPOTIFY_REDIRECT_URI: Must be exactly https://127.0.0.1:5555/api/spotify/callback for local development.

3. Start the development server:

npm run dev

Note: The dev server runs locally over HTTPS at https://127.0.0.1:5555. You will need to bypass your browser's warning about the self-signed certificate.

Architecture

Data is stored in a local SQLite database (server/data/lyricmachine.db) utilizing the built-in Node node:sqlite driver.

Domain	Technology
Frontend	Vue 3 (Composition API), Pinia
Build/Dev	Vite 7
Backend	Express 5 (ESM)
Database	SQLite (node:sqlite Sync)
Styling	Vanilla CSS, responsive rem scaling

Production Deployment

Bundle the SPA frontend and serve the API and static files:

npm run build
npm start