# kit-signal/lyric-lantern

> Offline songwriting sparks, rhyme families, and lyric scan in Python.

- **Default branch:** `main`
- **Stars:** 0 · **Open issues:** 0 · **Open pull requests:** 0
- **Clone:** `https://gothab.io/kit-signal/lyric-lantern.git`

## README.md

# Lyric Lantern 🏮

A tiny, offline Python tool for songwriters: spark a few images, browse a hand-picked rhyme family, or get a gentle overview of a lyric draft. No dependencies, accounts, or network calls.

## Try it

```sh
python3 lyric_lantern.py spark --mood wistful --lines 4 --seed 22
python3 lyric_lantern.py rhyme ight
python3 lyric_lantern.py chords C --mode major --vibe bright --seed 8
python3 lyric_lantern.py chords Bb --mode minor --vibe wistful
python3 lyric_lantern.py jam G --vibe restless --feel shuffle --tempo 112 --seed 9
python3 lyric_lantern.py render practice.wav C --tempo 96 --repeats 2 --seed 9
python3 lyric_lantern.py midi practice.mid C --tempo 96 --repeats 2 --seed 9
python3 lyric_lantern.py melody verse.txt C --mode major --tempo 96 --contour arch --note-beats 1.25 --output vocal-sketch.mid
cat verse.txt | python3 lyric_lantern.py melody - Bb --mode minor --contour rise --output melody.mid
python3 lyric_lantern.py scan chorus.txt
python3 lyric_lantern.py meter --target 8 chorus.txt
python3 lyric_lantern.py hooks chorus.txt --min-words 2 --max-words 4
cat chorus.txt | python3 lyric_lantern.py scan -
```

Moods: `wistful`, `bright`, `restless`. Repeating a seed gives the same sparks, making it easy to save and remix a favorite batch. `scan` reports section counts for bracket labels such as `[Verse 1]`, `[Chorus]`, and `[Bridge]`, excluding labels from lyric word counts; it also summarizes how many lyric lines match an 8-syllable pulse and the draft's syllable range, alongside unique vocabulary, a rough average, and repeated exact line-ending words. It is a quick overview, not a rule for how a song should be structured. Scans also show an approximate end-rhyme scheme (A/B/C…) separately per labeled section, with end words alongside the labels. This is a deliberately gentle heuristic with common rhyme-family suggestions; English pronunciation, accents, and slant rhymes make vocal checking essential. `meter` estimates syllables in each nonblank line and shows how far it is from your target, preserving original line numbers. `hooks` spots exact repeated two-to-five-word phrases on separate lines, so you can find accidental repetitions or a hook taking shape; adjust the phrase length and result limit as needed. `chords` suggests a seedable four-chord loop in a requested major/minor key and vibe, with chord names and Roman-numeral degrees. `jam` combines that loop with a tempo and a beginner-friendly strum pattern (`straight`, `shuffle`, `pulse`, or `half-time`) as a one-chord-per-bar four-bar practice prompt. Tempo is limited to 40–220 BPM. In the strum pattern, `D` means downstroke, `U` upstroke, and `-` a rest; for straight/shuffle/pulse feels, the count shows eighth-note subdivisions. `render` writes a dependency-free mono 16-bit PCM WAV sketch with one softly synthesized arpeggiated chord per bar; set `--repeats` (1–8) and `--sample-rate` (8–48 kHz) to taste. `midi` exports the same kind of arpeggiated progression as a standard format-0 MIDI file, ready to import into a DAW and assign your own instrument. `melody` reads a lyric text file (or stdin with `-`) and sketches one scale note per estimated syllable, annotating line starts in the MIDI; edit the notes and phrasing to suit your voice. Choose a `--contour` (`wave`, `rise`, `fall`, `arch`, `skip`) and note length in beats with `--note-beats` (0.25–2); word-start syllables get a little extra velocity emphasis. Its vowel-group syllable estimate is rough and is not a prescribed melody. Both audio formats are writing guides, not finished production; the strum card and arpeggio are separate practice ideas.

## Tests

```sh
python3 -m unittest -v
```

## Remix note

Treat every generated line as raw material, not a finished lyric. Swap the nouns, sing it aloud, and keep only what feels like yours.