Skip to content

Commit e4d34bb

Browse files
mike-lischkemike-lischke
committed
Update readme
Signed-off-by: Mike Lischke <mike@lischke-online.de>
1 parent 0fa7eb0 commit e4d34bb

1 file changed

Lines changed: 149 additions & 9 deletions

File tree

‎readme.md‎

Lines changed: 149 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,161 @@
22
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge&color=green)](./License.txt)
33

44
<p align="center">
5-
<img src="public/logo.svg" title="Animada Score Book" alt="Animada Score Book" style="height: 200px" /><br/>
5+
<img src="/public/logo.svg" title="Animada Score Book" alt="Animada Score Book" style="height: 200px" /><br/>
66
</p>
77

88
<hr />
99

1010
# Animada Score Book
1111

12-
Score management and arrangement app for our **Banda Animada de Samba** group – tailored for Samba ensembles.
12+
Animada Score Book is your ensemble's digital home for rhythm — a rich, browser-based score management and playback platform built from the ground up for Samba groups. Browse your entire score library in a beautiful tree view, listen to arrangements come alive with synchronized multi-track audio playback driven by a precision metronome, and export your work as MP3 files or crisp print-ready sheet music. A full sound library manager with waveform previews lets you organize and assign instrument samples, while the built-in backend with user accounts, groups, and fine-grained permissions keeps everything secure and collaborative. Whether you're rehearsing, arranging, or archiving, Animada Score Book puts the pulse of your bateria right in the browser.
1313

14-
Originally based on [BananaDrum](https://github.com/mooseling/BananaDrum).
14+
## Features
1515

16-
## Development Setup
16+
- **Desktop & Mobile.** Full support for desktops, tablets, and phones with automatic and manual zoom to make the
17+
most of your screen real estate.
18+
- **Dual Display Modes.** Switch on the fly between a grid-based view — perfect for learning — and a true notation
19+
view for seasoned players. Toggle anytime, even during playback.
20+
- **Samba-First Notation.** Purpose-built for percussion and Samba music with a simplified notation system.
21+
Special note heads and markings distinguish playing techniques at a glance.
22+
- **Flexible Playback.** Play the entire song or a selected bar range, once or on loop. Adjust tempo and overall
23+
volume on the fly.
24+
- **Metronome & Count-In.** Toggle the built-in metronome on and off, with an optional count-in to lead you in.
25+
- **Multi-Track.** View and play back multiple tracks simultaneously — one instrument per track.
26+
- **Per-Track Mixer.** Fine-tune each track's volume independently with a continuous slider mixer.
27+
- **Minimap.** A bird's-eye overview for navigating long scores quickly.
28+
- **Horizontal Bar Layout.** Bars flow horizontally with smooth automatic scrolling during playback.
29+
- **MP3 Export.** Export the full arrangement as an MP3 file, respecting all playback settings — tempo, volume,
30+
count-in, and more (loop excluded).
31+
- **Print.** Print the loaded score in either grid or notation view — crisp, rehearsal-ready sheets.
32+
- **Customizable Theme.** Choose from a range of color schemes to suit your taste and lighting conditions.
33+
- **Score Management.** A database-backed score library with fine-grained access control: private, group-shared,
34+
or world-readable. Full user and group administration included.
35+
- **BananaDrum Import.** Import scores from BananaDrum URLs to bring your existing repertoire on board.
1736

18-
- Base API URL: Configure the backend base path used in development.
19-
- Create a `.env.local` (preferred) or edit `.env` and set `VITE_BASE_URL`.
20-
- Example: `VITE_BASE_URL="http://samba.<your-domain>.net"`
21-
- This value is read by the app via `import.meta.env.VITE_BASE_URL` when running on `localhost` or `127.0.0.1`.
22-
- In production builds, the app uses the same origin as the served app (empty base).
37+
> [!IMPORTANT]
38+
> **Editing is not yet implemented.** The current version focuses on score library browsing, arrangement playback,
39+
> printing, and sound management. Full score and arrangement editing capabilities are planned for a future release.
40+
41+
## Getting Started
42+
43+
Animada Score Book consists of two parts that work together: a **backend server** that stores your scores and manages users, and a **frontend** that runs in the browser. The setup is the same whether you install on your own laptop or on a web server — both need Node.js and a database.
44+
45+
### What You Need
46+
47+
- **[Node.js](https://nodejs.org/)** version 20 or later. This powers the backend server — it's required on every machine that runs Animada Score Book, including hosted servers. Download the LTS version from the website and run the installer.
48+
- **A database** — **MySQL**, **MariaDB**, or **PostgreSQL**. The backend connects to it to store scores, users, and permissions. Most hosting packages include a database; if you're setting up locally, [MariaDB](https://mariadb.org/download/) is a good lightweight choice.
49+
50+
### Step-by-Step Setup
51+
52+
#### 1. Get the Code
53+
54+
[Download the latest release](../../releases) and unzip it, or clone the repository:
55+
56+
```bash
57+
git clone https://github.com/mike-lischke/animada-score-book.git
58+
cd animada-score-book
59+
```
60+
61+
#### 2. Install Dependencies
62+
63+
```bash
64+
npm install
65+
```
66+
67+
#### 3. Configure the Backend
68+
69+
This is the central step. Create a file named `backend-config.json` in the project folder with the following content — adjust the values to match your database:
70+
71+
```json
72+
{
73+
"host": "127.0.0.1",
74+
"port": 3100,
75+
"database": {
76+
"engine": "mysql",
77+
"host": "127.0.0.1",
78+
"port": 3306,
79+
"database": "animada_score_book",
80+
"user": "root",
81+
"password": "your-password-here"
82+
},
83+
"soundLibPath": "public/sounds"
84+
}
85+
```
86+
87+
- **`host` / `port`** — the address and port the backend listens on. `3100` is the default; change it if that port is already in use.
88+
- **`database.engine`** — `"mysql"`, `"mariadb"`, or `"postgres"`. For PostgreSQL, also change `"port"` to `5432`.
89+
- **`database.host` / `port`** — where your database server is reachable. On the same machine this is `127.0.0.1`; your hosting provider will give you the address for remote databases.
90+
- **`database.database`** — the name of the database. The server creates the database automatically if it doesn't exist yet, so all you need to provide is a name.
91+
- **`database.user` / `password`** — the login credentials for the database.
92+
- **`soundLibPath`** — where the server looks for instrument sound files. The default `public/sounds` points to the built-in sound library that ships with the repository. Only change this if you store your sounds elsewhere.
93+
94+
The backend also needs a secret key to secure user logins. Set it before starting:
95+
96+
```bash
97+
# macOS / Linux:
98+
export JWT_SECRET="pick-a-long-random-string-here"
99+
100+
# Windows (PowerShell):
101+
$env:JWT_SECRET = "pick-a-long-random-string-here"
102+
```
103+
104+
Pick a long, random string and keep it safe — this key is what keeps your users' accounts secure.
105+
106+
#### 4. Start the Backend
107+
108+
```bash
109+
npm run start
110+
```
111+
112+
Keep this terminal open. The server will confirm it's running — you'll see something like `Server running on http://0.0.0.0:3100`.
113+
114+
#### 5. Build and Serve the Frontend
115+
116+
```bash
117+
npm run build
118+
```
119+
120+
This creates a `dist/` folder with everything the browser needs. Serve that folder with any static web server — nginx, Apache, Caddy, or even a simple file server. The frontend automatically talks to the backend on the same domain, so point both to the same address and you're done.
121+
122+
> **First run:** When you open the app in your browser for the first time, a setup wizard will guide you through creating an admin account and connecting to the backend. No further manual steps needed.
123+
124+
## Contributing & Development
125+
126+
### Reporting Bugs
127+
128+
Found a problem? Please [open an issue](../../issues) on GitHub. Include as much detail as you can: what you were doing, what you expected to happen, and what happened instead. Screenshots and browser console logs are incredibly helpful.
129+
130+
### Development Setup
131+
132+
To work on the code itself, you need the same basics as a regular installation — Node.js 20+, a database, and the `backend-config.json` file. Once that's in place, here's what a development session looks like:
133+
134+
**Terminal 1 — Backend:**
135+
136+
```bash
137+
npm run start-with-dummy-secret
138+
```
139+
140+
which uses a simple secret just for development. Don't use that in production (on your hosting server).
141+
142+
**Terminal 2 — Frontend dev server** (with hot reload):
143+
144+
```bash
145+
npm run dev
146+
```
147+
148+
This opens the app at `http://localhost:5173` and updates automatically as you edit files.
149+
150+
**Useful commands while developing:**
151+
152+
| Command | What it does |
153+
|---|---|
154+
| `npm run check` | Type-checks all TypeScript source and test files |
155+
| `npm run lint` | Runs ESLint across the codebase |
156+
| `npm run test` | Runs the unit test suite (Vitest) |
157+
| `npm run test:e2e` | Runs end-to-end browser tests (Playwright) |
158+
159+
The project is written in **TypeScript** with **Preact** for the UI, **SCSS** and **Tailwind** for styling, and **DaisyUI** for components. The backend is a plain Node.js HTTP server with MySQL/MariaDB/PostgreSQL adapters.
160+
161+
### VS Code ###
162+
This project ist developed in VS Code and already has a launch configuration you can use to start a debugging session.

0 commit comments

Comments
 (0)