Skip to content
joshdougallPublic

About

Playback-synced chord sheets and guitar tabs with auto-scroll

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

223 Commits

Folders and files

Repository files navigation

Chordplay

Shows chord sheets and guitar tabs for your currently playing track, with playback-synced auto-scroll. Chord sheets are fetched automatically from Ultimate Guitar, Chordie, and other sources, or you can add your own files.

Features

  • Auto-fetches chord sheets when a song starts playing
  • ChordPro, ASCII tab, and Guitar Pro file support
  • Chord diagrams with correct voicings (including slash chord inversions like D/C, G/B)
  • Transpose + capo suggestions
  • Per-user library with multi-version support
  • Playlist browser with batch chord import
  • Auto-scroll with speed control
  • Multi-user (each user connects their own streaming account)

Prerequisites

  • Node.js 22+
  • Developer API credentials for your music streaming service (for example, a Spotify Developer app)

Local development

git clone <repo-url>
cd chordplay
npm install
cp .env.example .env.local

Edit .env.local:

# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
APP_SECRET=<32-byte base64 string>

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:3000/api/auth/callback

# Created automatically on first run
LIBRARY_PATH=./data/library
DATA_PATH=./data/app
npm run dev
# open http://localhost:3000

Required environment variables

Variable Purpose
APP_SECRET 32 bytes of randomness, base64-encoded. openssl rand -base64 32
SPOTIFY_CLIENT_ID From your streaming service developer dashboard
SPOTIFY_CLIENT_SECRET From your streaming service developer dashboard
SPOTIFY_REDIRECT_URI Must exactly match what's registered in your app
LIBRARY_PATH Directory where chord/tab files are stored
DATA_PATH Directory for user tokens, prefs, and cache

Optional

Variable Default Description
LOG_LEVEL info debug / info / warn / error
CHORDPLAY_ADMIN_USERS (none) Comma-separated user IDs with access to /settings/admin

Docker

Pre-built images for linux/amd64 and linux/arm64 are published to GitHub Container Registry on every release.

Quick start:

cp .env.example .env
# fill in .env, then:

# docker run
docker run -d \
  --name chordplay \
  -p 3000:3000 \
  --env-file .env \
  -e HOSTNAME=0.0.0.0 \
  -v ./library:/data/library \
  -v ./appdata:/data/app \
  ghcr.io/joshdougall/chordplay:latest

# or docker compose (docker-compose.yml included)
docker compose up -d

Pin to a specific version:

ghcr.io/joshdougall/chordplay:1.0.0

To build from source, replace image: in docker-compose.yml with build: . and run docker compose up -d --build.

Library

Drop files anywhere under LIBRARY_PATH. Nested subdirectories are fine. Supported formats:

  • ChordPro (.pro, .cho) — rendered with inline chord diagrams
  • ASCII tab (.txt) — rendered as monospace text
  • Guitar Pro (.gp, .gpx, .gp5) — rendered via alphaTab

Metadata is read from:

  1. ChordPro directives: {title: ...}, {artist: ...}, {spotify_track_id: ...}
  2. Filename pattern: Artist - Title.ext

Adding a {spotify_track_id: ...} directive gives an exact, unambiguous match. Without it the app uses fuzzy title + artist matching.

Testing

npm test           # unit + integration (Vitest)
npm run test:e2e   # end-to-end (Playwright)
npm run lint
npx tsc            # type check

License

MIT. See LICENSE. Before running a public instance, read the copyright note below — the license covers the code, not the chord sheet content it fetches.

A note on copyright and usage

Chord sheets from external sources (Ultimate Guitar, Chordie, etc.) are covered by music publishing rights. This app is intended for personal use — the same category as printing out a tab for practice. Running a public instance that serves chord sheets to arbitrary users would create copyright exposure.

About

Playback-synced chord sheets and guitar tabs with auto-scroll

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages