Setlyst Web

A modern, stage-ready setlist management platform — built with Next.js and optimized for performance.

Setlyst Web is the frontend for the Setlyst ecosystem. It provides an intuitive dashboard for musicians to manage their song library, organize setlists, and access a high-performance Live Mode designed specifically for use on stage.

---

🎯 Motivation

Managing paper setlists or generic note apps during a concert is prone to error and lacks organization. Musicians need a dedicated tool that handles song structures, lyrics, and metadata, while providing a distraction-free interface when the lights go up.

Setlyst was built to be fast, responsive, and reliable enough for professional use.

---

✨ Features

⚠️ Setlyst is in active development.

• ✅ Dashboard — Centralized management of Artists, Songs, Bands, Setlists, and Gigs.
• ✅ Live Mode — High-contrast, distraction-free performance viewer with a built-in metronome and live transpose.
• ✅ Song versions — Keep a simplified chart, an acoustic arrangement or any other version of a song next to the original.
• ✅ Per-setlist keys — Set the key each song is played in per setlist (for a singer who takes it lower); Live Mode opens every song in that key and saves any change made on stage.
• ✅ ChordPro Support — Dynamic rendering and editing of lyrics and chords. Pasted charts with chords above the lyrics are aligned automatically, and section headings are recognised in English, Portuguese and Spanish.
• ✅ Chord diagrams — Tap any chord in a chart to see how to play it on guitar, keyboard, ukulele or cavaquinho, with every playable shape and the chord's notes and intervals. Brazilian chord symbols (7M, 7(9), m7(b5), °, 4/7…) are read as written; the instrument is a synced preference, with a left-handed option.
• ✅ Harmonic analysis — Write a manual analysis over a song's chart, the way Brazilian harmony books do: roman-numeral degrees (IIm7, V7/IV, SubV7/II), T/SD/D functions, AEM and diminished marks, solid and dashed resolution arrows, II–V brackets, key changes, numbered notes and highlighted passages. Autosaved with undo/redo, kept attached to the right chords when the chart is edited, and exported as a clean PNG. Nothing is guessed: every mark is the musician's.
• ✅ Setlist Analytics — Visualize a setlist's tempo/energy progression before you play it.
• ✅ Authentication — Secure access via NextAuth, with role-based access control.
• ✅ Band Collaboration — Multiple members share the same song library, setlists, and gigs.
• ✅ Public Sharing — Shareable, read-only links and QR codes for setlists and gigs.
• ✅ Offline Support — Setlists, songs, and Live Mode keep working with no signal.
• ✅ Installable (PWA) — Add Setlyst to your home screen like a native app.
• ✅ PDF & ChordPro Export — Generate printable setlists or export songs as .cho files.
• ✅ Backup & Restore — Export and import a full snapshot of your data.
• ✅ Responsive Design — Optimized for desktops, tablets, and mobile phones.
• ✅ Multi-language — Full support for English, Portuguese, and Spanish (i18n).
• ✅ Tags — Tag songs by vibe ("ballad", "opener"…), filter by tag and manage your tag vocabulary.
• ✅ Customizable PDF — Presets, compact and two-column layouts, text size, paper, margins, songbook with chords above the lyrics, optional watermark; save your favourite setup as the default.
• ✅ Synced preferences — Live Mode, list and PDF defaults follow you to every device.
• ✅ Staff console — Admins and moderators manage users (suspend, deactivate, temporary passwords, per-user limits, "view as"), bands, songs, setlists and public links, with a full audit log.
• ✅ Strong account security — Enforced password policy, username rules, instant sign-out on password change or suspension.
• ✅ What's new, status page and legal texts — Built in, in every language.

---

🛠️ Tech Stack

• Framework: Next.js (App Router)
• Styling: Tailwind CSS
• UI Components: Shadcn UI
• Authentication: NextAuth.js
• Icons: Lucide React

---

📥 Installation

Prerequisites: Node.js 20.9+ and a running instance of the Setlyst API.

1. Clone the repository:

   git clone [https://github.com/allansomensi/setlyst-web](https://github.com/allansomensi/setlyst-web)
   cd setlyst-web

2. Install dependencies:

   npm install

3. Configure environment:

   Create a .env.local file based on .env.example:

   NEXT_PUBLIC_API_URL=your_api_url
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=your_secret_of_at_least_32_characters
   # Optional
   NEXT_PUBLIC_WIKI_URL=https://github.com/allansomensi/setlyst-web/wiki
   NEXT_PUBLIC_SUPPORT_EMAIL=support@example.com
   NEXT_PUBLIC_PRIVACY_EMAIL=privacy@example.com   # LGPD privacy channel (small-scale agent, no encarregado), defaults to the support e-mail
   NEXT_PUBLIC_COPYRIGHT_EMAIL=copyright@example.com # copyright notices and content reports, defaults to the support e-mail
   NEXT_PUBLIC_BILLING_ENFORCED=false              # fallback when the API is down; the beta switch lives in the API
   NEXT_PUBLIC_CONTROLLER_NAME=                    # who runs Setlyst: footer, /contato and legal documents (required to build)
   NEXT_PUBLIC_CONTROLLER_TAX_ID=                  # CPF (individual) or CNPJ (company), detected by length, check digits validated
   NEXT_PUBLIC_CONTROLLER_ADDRESS=                 # postal address (Decreto 7.962/2013)
   ALLOW_PLACEHOLDER_CONTROLLER=false              # "true" only for CI builds never deployed
   INTERNAL_API_SECRET=                            # same value as the API's, see "Client address" below
   TRUSTED_PROXY_HOPS=1                            # reverse proxies in front of Next.js (self-hosted)
   TRUST_X_REAL_IP=false                           # "true" only if your proxy overwrites X-Real-IP
   NEXT_PUBLIC_ENABLE_SW_IN_DEV=false              # register the service worker in `npm run dev`

   Client address. With INTERNAL_API_SECRET set, the server tells the API who the visitor is so rate limits apply per visitor. On Vercel (VERCEL is set by the platform) the address comes from x-vercel-forwarded-for/x-real-ip. Self-hosted, it is the entry TRUSTED_PROXY_HOPS positions from the right of X-Forwarded-For (the address your closest reverse proxy appended; the default 0 disables it, and the server logs a warning at startup until one of these is set), or X-Real-IP when TRUST_X_REAL_IP=true. The leftmost X-Forwarded-For entry is written by the client and is never trusted; when nothing trustworthy is available no address is sent.

   Provider identification. Decreto 7.962/2013 (art. 2º) and the LGPD (art. 41) require the provider's name, CPF/CNPJ and address to be shown in plain view: they appear in the site footer, on /contato and in the legal documents. A production build (next build) fails while NEXT_PUBLIC_CONTROLLER_NAME, NEXT_PUBLIC_CONTROLLER_TAX_ID or NEXT_PUBLIC_CONTROLLER_ADDRESS is missing, or when the CPF/CNPJ check digits are invalid; a CI build that is never deployed can set ALLOW_PLACEHOLDER_CONTROLLER=true. Set NEXT_PUBLIC_PRIVACY_EMAIL (privacy channel) and NEXT_PUBLIC_COPYRIGHT_EMAIL (copyright notices) to real mailboxes before launch. Each legal document has its own version history in lib/legal-texts/versions.ts (rendered at the end of /legal/<doc>; superseded texts are served at /legal/<doc>/v/<version>).

4. Run the development server

   npm run dev

The application will be available at http://localhost:3000.

5. Checks

   npm run typecheck   # TypeScript
   npm run lint        # ESLint + Prettier
   npm test            # Unit tests (Vitest)

The legal texts (lib/legal-content.ts) describe how Setlyst stores and protects data. Review them for your jurisdiction (LGPD, GDPR…) before going to production. Release notes shown on the "What's new" page live in lib/whats-new.ts.

---

🎤 Live Mode

The Live Mode is the heart of Setlyst. It is designed to be used on tablets and smartphones mounted on mic stands. It features:

• Zero Layout Shift: Content remains stable during performance.
• High Contrast: Readable under stage lights or in dark venues.
• Stay Awake: Prevents the device from sleeping during use.
• Metronome: Per-song BPM, tap tempo, and an audible or visual click.
• Live Transpose: Shift the key on the fly, with capo suggestions.
• Auto-scroll: Hands-free lyric scrolling at an adjustable speed.
• Compact Mode: The whole song on one screen, in columns when there's room.
• Swipe Navigation: Swipe left/right on a phone to move through the setlist.
• Lyrics First: Chords and section headings can each be toggled, per device.
• Offline-ready: Works with no signal — nothing depends on a live connection once synced.

---

🤝 Contributing

Contributions are very welcome! Setlyst is a community-driven project, and we appreciate help with:

• 🐛 Bug Fixes: Identifying and fixing frontend or integration issues.
• ✨ Feature Requests: Suggesting and implementing new tools for musicians.
• 🎨 UI/UX: Improving the design, accessibility, and responsiveness.
• 🌍 Translations: Helping us reach more musicians by improving i18n support.

Please check our CONTRIBUTING.md for detailed guidelines on our development workflow and commit standards. 📜

---

⚖️ Legal

Setlyst is an open-source project created by musicians for musicians. 🎸

This project is not affiliated with, endorsed by, or sponsored by any instrument or software manufacturer. All product names, logos, and brands are property of their respective owners and are used here strictly for descriptive and nominative purposes.

Setlyst is released under the MIT License. 📜