Metadata-Version: 2.4
Name: couchguitar-web
Version: 0.1.0
Summary: Web-based song library and teleprompter for musicians
Author: Scott Peterman
License: MIT
Project-URL: Homepage, https://github.com/scottpeterman/couch-guitar-web
Project-URL: Repository, https://github.com/scottpeterman/couch-guitar-web
Project-URL: Issues, https://github.com/scottpeterman/couch-guitar-web/issues
Keywords: music,guitar,teleprompter,chordpro,songbook
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: python-multipart>=0.0.6

# CouchGuitar Web

A web-based song library and teleprompter for musicians. FastAPI, SQLite, no
cloud account, no subscription, no telemetry. Runs on your laptop or a spare
box on your home network; opens in any browser including your phone.

<p align="center">
  <img src="https://raw.githubusercontent.com/scottpeterman/couch-guitar-web/main/screenshots/desktop.gif" width="80%" alt="CouchGuitar Web on desktop" />
</p>

## Features

- **Song library** — title, artist, key, tempo, genre, difficulty, tags, notes
- **Teleprompter** — auto-scroll with adjustable speed and font size, per-song scroll-speed memory
- **Transpose** — shift chords by semitone, works with plain text and ChordPro
- **Setlists** — ordered song lists you can play through in sequence
- **ChordPro support** — import `.cho`/`.chordpro` files, auto-converts for display
- **Bulk import** — drop in a folder of `.txt`/ChordPro files
- **Search & filter** — full-text across titles, artists, lyrics; filter by genre/key/difficulty/artist/tag
- **Database management** — in-app backup download, restore from backup, location and stats display
- **Light/Dark theme** — toggle in the header

## Install

```bash
pip install couchguitar-web
cgw
```

Opens at [http://127.0.0.1:8880](http://127.0.0.1:8880) in your default browser.

## Where your data lives

Your song library is a single SQLite file. By default it lives at:

```
~/.cgw/couchguitar.db                        # Linux, macOS
%APPDATA%\cgw\couchguitar.db                 # Windows
$XDG_DATA_HOME/cgw/couchguitar.db            # Linux when XDG_DATA_HOME is set
```

To check the resolved path on your install without starting the server:

```bash
cgw --info
```

Returns JSON describing the data directory, current database path, file
existence, and any environment overrides in effect.

### Overriding the location

Three ways, highest precedence first:

```bash
cgw --db /path/to/songs.db            # CLI flag — per-invocation
COUCHGUITAR_DB=/path/to/songs.db cgw  # env var — per-shell
CGW_HOME=/path/to/datadir cgw         # env var — directory containing couchguitar.db
```

Useful if you keep your library on a synced folder (Dropbox, Syncthing) so the
same songs show up on multiple machines.

## Network access

By default `cgw` binds to `127.0.0.1` (loopback only). That means the server
is reachable from the machine running it, and from nowhere else — the most
common case, ideal for a single-laptop setup.

To open it up to your phone or another machine on your home network:

```bash
cgw --host 0.0.0.0
```

`0.0.0.0` tells the server to accept connections on every network interface
the machine has. Combined with your machine's LAN IP, that's the URL your
phone uses.

<p align="center">
  <img src="https://raw.githubusercontent.com/scottpeterman/couch-guitar-web/main/screenshots/mobile.gif" width="32%" alt="CouchGuitar Web on a phone" />
</p>

### Finding your machine's LAN IP

```bash
# Linux / macOS
ip addr | grep inet                # or `ifconfig` on older systems

# Windows
ipconfig
```

Look for an address like `10.0.0.27` or `192.168.1.42` — those are the private
ranges your home router hands out. Open `http://<that-address>:8880` from your
phone's browser and you'll see the same UI as on the laptop.

### Picking a port

The default `8880` is a deliberate high port — no root/admin privileges
required to bind it, and unlikely to collide with anything else running on
your machine. To pick a different one (running two instances side-by-side, or
working around a conflict):

```bash
cgw --port 9000
```

Anything in the 1024-65535 range is fair game for a non-root user. Ports below
1024 are privileged on Linux/macOS and not worth dealing with for this.

### Firewall

On a fresh Linux desktop you usually won't need to do anything — most distros
ship with no host firewall enabled. On Windows the first time you bind to
`0.0.0.0` the OS will pop a firewall dialog asking whether to allow access on
private networks; click "Allow." On macOS, System Settings → Network →
Firewall lets you whitelist Python if the firewall is on.

If you can `curl http://127.0.0.1:8880/` from the machine but not from your
phone, the firewall is the most likely culprit.

### Security model

There is no authentication. Anyone who can reach the server can read, edit,
and delete every song in your library, and can overwrite the database via
the restore endpoint. The intended trust model is *machines I trust on a
network I trust* — your laptop, your home WiFi.

Do not expose `cgw` to the public internet. Don't open the port through your
router's NAT. Don't run it on a hosted VPS bound to `0.0.0.0` without putting
a reverse proxy with auth in front. For a home LAN setup, you're fine; just
don't take the next step beyond that without thinking about it.

## Database management

Click **🗄️ Database** in the header to open the management modal:

<p align="center">
  <img src="https://raw.githubusercontent.com/scottpeterman/couch-guitar-web/main/screenshots/backup.gif" width="60%" alt="Database management modal — info, backup, restore flow" />
</p>

The modal shows:

- Database location (full path)
- File size
- Last modified timestamp
- Song / setlist / tag counts
- Schema version

Plus two actions:

- **Download backup** — saves a timestamped copy of the database to your
  Downloads folder.
- **Restore from backup** — replaces your current library with an uploaded
  `.db` file. The upload is validated as a real CouchGuitar database before
  any swap happens. Your existing database is renamed
  `couchguitar.db.before-restore-<UTC-timestamp>` in the same folder, so the
  swap is reversible if you uploaded the wrong file. Restart the server
  after restore to load the new data.

You can also back up at the filesystem level, since the entire library is one
file:

```bash
cp ~/.cgw/couchguitar.db ~/Dropbox/backups/couchguitar-$(date +%Y%m%d).db
```

## Command-line options

```
cgw --help
```

| Flag | Default |
|---|---|
| `--host` | `127.0.0.1` |
| `--port` | `8880` |
| `--db` | (see [Where your data lives](#where-your-data-lives)) |
| `--no-browser` | off |
| `--info` | — |
| `--version` | — |

## Keyboard shortcuts (teleprompter)

| Key | Action |
|---|---|
| Space | Toggle auto-scroll |
| ↑ / ↓ | Manual scroll |
| Home | Jump to top |
| + / = | Transpose up |
| − | Transpose down |
| ← / → | Previous / next song (setlist mode) |

## Song formats

**Plain text** — chords on a line above the lyrics they apply to:

```
 G            C          G
Amazing Grace, how sweet the sound,
```

**ChordPro** — inline chord markers and metadata directives:

```
{title: Amazing Grace}
{artist: Traditional}
[G]Amazing [C]Grace, how [G]sweet the sound,
```

On import, files with `.cho`/`.chordpro`/`.chopro` extensions are detected as
ChordPro. Files with ChordPro directives (`{title:}`, `{t:}`, `{subtitle:}`,
`{artist:}`) are detected even when saved as `.txt`. The display layer renders
ChordPro the same way as plain text — chords above lyrics — so you can edit
in either format and view comfortably.

## Building from source

```bash
git clone https://github.com/scottpeterman/couch-guitar-web.git
cd couch-guitar-web
pip install -e .
cgw
```

Or run without installing:

```bash
pip install -r requirements.txt
python -m cgw.app
```

## License

MIT
