jcl2018/bass-tab

What does bass-tab do?

Turns what a source actually shows into a song data file, then renders a compact bass tab (.tab) and a print-ready play-along chart PDF (1-2 US-Letter pages). Needs python3 only; Pillow is needed too when a title or artist is non-Latin (e.g. Chinese). Without it chart2pdf.py and tab2pdf.py refuse rather than print ?; install it in a venv (python3 -m venv v && v/bin/pip install pillow) and run the script with that python, or pass --allow-lossy. Scripts live in scripts/ next to this file; run them from this skill's folder or give full paths.

The song file

One song, one directory, three files:

<slug>/
  <slug>.py     the source of truth: structured data, hand-editable (start from templates/song-template.py)
  <slug>.tab    generated by scripts/tabgen.py
  <slug>.pdf    the play-along chart, generated by scripts/chart2pdf.py straight from <slug>.py

<slug>.py supplies META / BARS / SECTIONS / CHORDS / LYRICS. A repeated figure is written ONCE and stamped wherever it is played, so a correction reaches every copy. Never expand a repeat into independent copies.

LYRICS maps a bar number to the words sung under that bar. They may come from the owner, or from what a source visibly shows (for example on-screen lyrics in a tab video). Never invent them or fill them from memory or from a web search; if no source shows words, leave LYRICS = {} and say the owner can add them. A song with no lyrics renders cleanly. Lyrics print verbatim and survive every regeneration.

Render

python3 scripts/chart2pdf.py <slug>/<slug>.py -o <slug>/<slug>.pdf [--paper letter|a4]
python3 scripts/tabgen.py <slug>/<slug>.py <slug>/<slug>.tab --bars <1 if META slots == 16 else 3> --cut compact

The PDF is a chart, in the style of an online tab player: several bars per line, a bold section label where each section starts, a repeated figure drawn once between repeat signs with its count (x4), a section that repeats an earlier one reduced to one line (Chorus 2 = Chorus (bars 13-16)), chord names over bars where CHORDS has them, and lyrics under the bar they belong to. It is US-Letter by default and at most 2 pages: tab digits stay at 9 pt or more, spacing tightens and repeats collapse before the font shrinks, and a song that still does not fit is refused with a line naming it. Report the page count. Needs Pillow for non-Latin lyrics or titles (see above). --collapse-sections forces the reference lines.

The long, one-bar-wide PDF is still available: tabgen.py ... --cut compact then tab2pdf.py <slug>.tab -o <slug>-long.pdf. --cut compact is the text sheet. It is the only cut that carries the repeat notation (a collapsed figure labelled A-B xN). --cut full is a debugging view (every bar, plus a beat-ruler row the format does not list), never the deliverable. Give outputs full paths.

The text format: header lines (title, artist, key, tempo, time, tuning, source, legend), then per section a [Name - bars a-b . m:ss] heading, a chord row, a bar-number row, a rhythm row R|, and four string rows G D A E; then caveats, then a [Checked] block. Stave lines are pinned at 77 characters so every song prints at the same scale; if a line is longer, use fewer bars per system.

Making a song file from sources

Follow this literally; it is the point of the skill.

1. Take only what a source actually shows. A screenshot or PDF of a tab can be read. A link to a recording cannot: you cannot hear audio. From a song URL take the title, tempo and section names if printed, nothing else. Never supply a bar from memory of the song. A visible gap beats a bar that looks right and is not.
2. Bass track only. If a source shows several instruments, take the bass and say which track. Two bass tracks, or bass doubled: ask, do not pick.
3. Cross-check every repeat, and encode it once. Read each occurrence and compare. Agreement is the strongest verification available; disagreement means at least one reading is wrong. Occurrences agree: encode once. They disagree: say so, give the count each way, mark the reading an estimate. A bar with no repeat anywhere cannot be cross-checked; say that on the sheet.
4. Never assert what you have not checked. Claims like "same as bars A-B" are generated from the data, not typed. Section bar ranges are computed from boundaries.
5. Structure, chords, tempo. Fill SECTIONS with the source's own labels. Give each bar its CHORDS entry: the chord fixes which string a fret is on (fret 7 is B on the E string, E on the A string), so tabgen.py derives the string and raises on a fret/chord pair that agree on no string. Put the tempo in META; section timestamps are computed from it.
6. Report what you did not do. Which bars are missing, which are estimates, which source gave what. End every transcription with that, not with a clean bill of health.

Rhythm read by eye and frets never measured are the known weak points; say so in CAVEATS.

Suggestions

After a transcription or on request, offer three kinds, clearly separated from the transcription: practice (what to drill first), musical (what the progression is doing), and arrangement (a simplification or addition). An arrangement suggestion is your invention; never let it read as what the source says.

Check

tests/bass-tab/run.sh in the repo renders a fixture song and compares it with the recorded baseline, and checks the chart on invented songs (section labels, collapsed repeats, lyric alignment, the 2-page limit).