SetListBuilder

SetManager v1.0 - Official Release

Fearlessly Media Group

Version License Status JavaScript No Dependencies

Intelligent setlist generator for live musicians

Balance energy curves with physical effort • No backend • 100% offline • Multi-language • Production hardened

Quick Start · Features · Release Notes · Testing · Docs

Official Release v1.0

Production Ready — Data integrity, reliability, and performance optimizations.

See Full Release Notes →

Key Features

Quick Start

Online (No Installation)

→ Launch App (Coming Soon)

Local Development

git clone https://github.com/julesklord/SetListBuilder.git
cd SetListBuilder
python -m http.server 8000

Then open http://localhost:8000

Direct File

Double-click index.html (some features may be limited with file://)

Project Structure

SetListBuilder/
├── src/                                # Source code
│   ├── index.html                      # App shell
│   ├── style.css                       # All styles (dark/light theme)
│   └── js/
│       ├── songs.js                    # 336 songs database + validation
│       ├── i18n.js                     # Translations (EN/ES/PT/RU)
│       └── app.js                      # Core app logic (65+ functions)
│
├── docs/                               # Documentation
│   ├── QUICK_START.md                  # 5-minute onboarding
│   ├── GUIDE.md                        # Complete user guide
│   ├── FMG_Setlist_Builder_Docs.md     # Technical reference
│   ├── CHANGELOG_V1.md                 # v1.0 changelog
│   └── Other guides
│
├── tests/                              # Testing resources
│   ├── TESTING_GUIDE.md                # Manual test procedures (7 tests)
│   ├── TEST_RESULTS.md                 # Verification details
│   ├── TESTING_REPORT.md               # Executive summary
│   └── validation-script.js            # Automated validation tool
│
├── CHANGELOG.md                        # v2.0 changelog + history
├── RELEASE_NOTES.md                    # v2.0 release information
├── LICENSE                             # MIT License
├── README.md                           # This file
└── .github/                            # GitHub configuration

**Full tutorial:** [GUIDE.md](/SetListBuilder/docs/GUIDE.html)

---

## Algorithm

### Phase 1: Song Eligibility

- **Level 1** (preferred): Songs matching instruments AND genres
- **Level 2** (fallback): Only genres if not enough matches
- **Level 3** (last resort): Full pool

### Phase 2: Must-Play Distribution

- Locked songs are distributed evenly across sets
- Guaranteed to appear in every generated setlist

### Phase 3: Energy Curve

Early Sets: LOW (35%) → MID (40%) → HIGH (25%) Final Set: LOW (20%) → MID (40%) → HIGH (40%) ← Peak finish


Creates natural audience engagement arc

### Phase 4: Effort Balancing

- Evens physical effort across sets (drummer fatigue, vocalist strain, etc.)
- Conservative swaps: only reorders if it improves balance
- Never sacrifices energy curve for effort

---

## Song Pool (335 Songs)

### Curated Music Library

**Song Metadata per Track**:

- Title & Artist
- Genre classification (24 genres)
- Musical key (A–B, sharps/flats)
- BPM (beats per minute)
- Chord progression (Roman numeral notation)
- Energy level (1–5 scale)
- Instrument requirements
- Effort estimation

**Genre Distribution**:

| Category | Count | Details |
|----------|-------|---------|
| **Classic/Blues** | 99 | Blues, Soul, Ballad, Jazz |
| **Rock** | 93 | Rock, Rock Latino, R&B, Modern |
| **Pop/Dance** | 75 | Pop, Funk, Disco, Funk/Soul |
| **World Music** | 38 | Reggae, Latin, Cumbia |
| **Other** | 30 | Country, Ranchera, Ska, Merengue, etc. |

---

### Band Instruments (11 Total)

| Instrument | Weight | Effort Level | Notes |
|---|:---:|:---:|---|
| Electric Guitar | 1.0 | ⭐⭐ | Lead/rhythm primary |
| Acoustic Guitar | 0.8 | ⭐ | Fingerpicking |
| Bass | 1.2 | ⭐⭐ | Standing + focus |
| **Drums** | **1.8** | **⭐⭐⭐⭐** | Full-body exertion |
| Keys/Piano | 1.0 | ⭐⭐ | Seated play |
| Saxophone | 1.5 | ⭐⭐⭐ | Breath + stamina |
| Trumpet | 1.5 | ⭐⭐⭐ | Embouchure focus |
| Trombone | 1.5 | ⭐⭐⭐ | Breath + movement |
| **Lead Vocals** | **2.0** | **⭐⭐⭐⭐⭐** | Highest vocal strain |
| Backing Vocals | 1.5 | ⭐⭐⭐ | Less intensive |
| Latin Percussion | 1.2 | ⭐⭐ | Congas, bongos |

**All weights are fully configurable**—adjust to match your band's physical conditioning and performance style.

---

### Data & Persistence

**100% Browser-Based** — All data stored locally in `localStorage`

```javascript
{
  'fmg-pool': JSON.stringify(pool),           // Your song library
  'fmg-nights': JSON.stringify(nights),       // Saved setlists & shows
  'fmg-mustPlay': JSON.stringify([...ids]),   // Locked songs
  'fmg-instrs': JSON.stringify(codes),        // Active instruments
  'fmg-effort-weights': JSON.stringify(obj),  // Effort multipliers
  'fmg-lang': 'en|es|pt|ru',                  // Active language
  'fmg-theme': 'dark|light',                  // Theme preference
  'fmg-ai-count': '3|5|8|10'                  // AI suggestion count
}

Privacy First: No backend server · No cloud accounts · No tracking · Data never leaves your device

Customization & Extension

Add or Edit a Song

Edit js/songs.js and modify the DEFAULTS array:

{
  id: 336,
  title: "My Song",
  artist: "My Band",
  genre: "Blues",
  key: "Am",
  bpm: 100,
  prog: "i–IV–i–V",           // Roman numeral chord progression
  energy: 3,                    // 1 (chill) to 5 (explosive)
  instr: ['eg', 'b', 'dr', 'vo'],
  effort: 2                      // Estimated effort level
}

Import Songs via CSV

  1. Open Pool tab → click “CSV Template”
  2. Fill template with your songs (title, artist, BPM, key, etc.)
  3. Click “Import” and select file
  4. Songs automatically merge with existing pool

Add a New Language

  1. Edit js/i18n.js → Copy en:{...} block as new language (e.g., fr:{...})
  2. In index.html topbar, add button: <button class="lang-btn" data-lang="fr" onclick="setLang('fr')">FR</button>
  3. Translate all UI strings (keep genre names and numbers)
  4. See docs/GUIDE.md for complete instructions

Change Colors & Theme

Edit style.css CSS variables:

Fix or Update Translations

Edit js/i18n.js → Find language block → Update any key-value pair

Export Formats

Format Use Case Output
PDF Print-ready setlist Browser print dialog → save as PDF
HTML Email to bandmates Self-contained file (no internet needed)
Text Quick copy-paste Plain text for WhatsApp, email, chat
JSON Data backup/archive Raw JSON format for safe storage
Pool Export Share song library Entire database as JSON (import elsewhere)

AI Features (Optional)

Infrastructure for AI-powered song suggestions is present but disabled by default in the FOSS version.

To Activate (requires API key from service of choice):

  1. Open js/app.js → Find & remove return; in toggleAIPanel() function
  2. In index.css, change .ai-panel { display: none } to display: flex
  3. Provide API key from:

Security: API keys stored locally in your browser—never sent to FMG servers

Multi-Language Support (4 Languages)

Español 🇪🇸 ━ English 🇬🇧 ━ Português 🇧🇷 ━ Русский 🇷🇺

Complete translations for all UI elements, menus, and settings. Add more languages easily—see docs/GUIDE.md for instructions.

Responsive Design

Device Features
Desktop (1024px+) Sidebar navigation, drag-drop reordering, full controls
Tablet (768–1024px) Responsive sidebar, optimized touch controls
Mobile (<768px) Bottom nav bar, slide-up drawer, fully touch-optimized

Seamless Experience across all devices with optimized layouts

Feature Verification Checklist

Feature Status
335 curated songs ✅
11 instruments + weights ✅
24 genre categories ✅
Energy + Effort balancing ✅
Must-Play locking system ✅
Drag-to-reorder setlists ✅
Multi-format export (5 types) ✅
CSV import/export ✅
JSON backup/restore ✅
4 complete languages ✅
Dark/Light theme toggle ✅
Fully responsive design ✅
localStorage persistence ✅
Zero NPM dependencies ✅
100% offline capability ✅

Troubleshooting

Issue Solution
Data not saving Use http://localhost:8080 (not file://); check localStorage enabled in browser
Modal stuck/broken Reload page (F5); open console (F12) to check for JS errors
Drag-drop not on mobile Use “Add/Remove” buttons instead (drag is desktop-only for safety)
App layout broken Reset zoom: Ctrl+0 (Windows) or Cmd+0 (Mac)
Missing/fewer songs Scroll down in Pool tab—table displays 50 per page
Setlist too short Reduce event duration or enable more genres in filters

Performance

Operation Speed
App load < 1 sec
Setlist generation < 100ms
Drag-drop animation 60fps
PDF export < 2 sec
Pool search/filter < 10ms

Lightning-fast performance on all devices—no lag, no waiting

Documentation

Document Purpose
GUIDE.md Step-by-step tutorial + complete feature guide
QUICK_START.md 5-minute beginner’s guide
IMPROVEMENTS.md Feature roadmap + future enhancements
CHANGELOG_V1.md Release notes + version history
FMG_Setlist_Builder_Docs.md Technical reference + architecture

Privacy & Security

Version History

v1.0.0 - Production Launch (Current)

Major Enhancements

Core Features

Bugs Fixed

New Features

Getting Started in 5 Steps

  1. Open App → http://localhost:8080 (or double-click index.html)
  2. Generate → Create first setlist in 60 seconds
  3. Customize → Add your band’s songs to pool
  4. Share → Export to PDF and send to bandmates
  5. Save → Store favorited setlists in Shows tab

Full Tutorial → docs/QUICK_START.md

Contributing & Roadmap

Want to Contribute?

Planned Enhancements (See docs/IMPROVEMENTS.md for details)

License & Attribution

Open Source · Free to Use · Fully Modifiable

Built for musicians, by musicians

Built By

Fearlessly Media Group
Creating music tools for live performers worldwide

Questions? Ideas? Bug reports?
Open an issue or contact us directly.

Made with care for musicians

This site is open source. Improve this page.