Songchart

cloud-based choir repertoire (no more paper records).
Explore the docs »

View Live · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

Songchart is a web app built for the youth choir at Saint Alphonsa Cathedral Mississauga. It gives every member instant access to the full repertoire (song metadata, BPM, key, capo, and inline chord sheets or lyrics rendered directly in the browser) from any device.

Key capabilities: Song database

• title, key, BPM, capo, and transposition stored in Convex, browsable from any phone, tablet, or desktop with real-time sync across all connected clients Inline document viewer
• chord sheets and lyrics are stored as .docx files in Convex file storage and rendered in-browser via mammoth, with no download required Weighted setlist generator
• builds randomised rehearsal and performance setlists, with configurable song weights so frequently-needed songs appear more often Protected write access
• JWT-based authentication gates song creation and deletion, keeping the database clean

(back to top)

Built With

layer	tools
frontend
backend
language
deployment

(back to top)

Getting Started

Prerequisites

• Node.js 18+
• A Convex account (free tier works)

npm install npm@latest -g

Installation

1. Clone the repo

   git clone https://github.com/teddycitrus/songchart.git
   cd songchart

2. Install dependencies

   npm install

3. Initialise Convex — this will prompt a GitHub login, create a project, and write NEXT_PUBLIC_CONVEX_URL to .env.local automatically

   npx convex dev

4. Add the remaining values to .env.local

   NEXT_PUBLIC_CONVEX_URL="https://your-deployment.convex.cloud"
   
   JWT_SECRET="a-long-random-secret"

5. Start the development server in a second terminal

   npm run dev

   Open http://localhost:3000 to see the app.

(back to top)

Usage

Browse the repertoire

the home dashboard lists all songs with their key, BPM, and capo. Click any song to open a detail view with the chord sheet rendered inline from the .docx file stored in Convex file storage. The list updates in real time across all connected clients.

Setlist generator

open the setlist picker, configure song weights if needed, and generate a randomised set. Songs with higher weights appear more frequently in the output.

Add or remove songs

authenticated users can create new entries or delete outdated ones. The song schema looks like this:

{
  "name": "10,000 Reasons",
  "key": "G Major",
  "transpose": 0,
  "capo": "none",
  "bpm": 77,
  "beat": "4/4",
  "storageId": "<convex storage id>"
}

Backend functions — all data operations are handled by Convex functions in convex/:

function	type	description
songs.list	query	Fetch all songs — reactive, auto-updates on change
songs.create	mutation	Create a new song entry
songs.remove	mutation	Delete a song and its stored file
songs.generateUploadUrl	mutation	Get a short-lived URL for .docx file upload
songs.saveStorageId	mutation	Persist a file's storage ID onto a song document

(back to top)

Roadmap

• Song database with full metadata and inline .docx viewer powered by Convex file storage and mammoth
• Weighted setlist generator for randomised rehearsal and performance sets
• Full CRUD; update and delete operations exposed in the UI for authorised members
• Multiple repertoire support for managing separate song lists across special masses and performances

See the open issues for a full list of proposed features and known bugs.

(back to top)

Contributing

Contributions are welcome. If you have a suggestion, please fork the repo and open a pull request, or file an issue with the enhancement label.

1. Fork the project
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a pull request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Project Link: https://github.com/teddycitrus/songchart

Live App: https://sacmchoir.vercel.app

(back to top)