ceol is an Irish traditional music practice tool with two interfaces:
- TUI — terminal player built with Babashka and charm.clj. Fetches ABC from thesession.org, converts to MIDI, plays via FluidSynth.
- Web — browser app built with ClojureScript, Replicant, abc.js, and Tone.js. Renders sheet music with chord annotations, plays melody (banjo) + rhythm guitar (sampled acoustic).
Both share code via .cljc files.
# TUI
./run.sh
# Web (dev)
cd web && ./node_modules/.bin/shadow-cljs watch app
# then open http://localhost:8280- notation.cljc — ABC tokenizer/parser, timeline builder with ms offsets
- tunes.cljc — static catalog (54 tunes), type filters, setlist resolution
- abc.cljc — pure ABC utils:
tempo-for-type,build-abc-string,adjust-abc-tempo,split-abc-parts
Elm architecture: init → update → view loop.
- state.clj —
init-state,update-state, key handlers, audio pipeline, count-in, setlists, set queue - view.clj — pure rendering (header, tune list, status bar, staff notation, help overlay)
- audio.clj — thesession.org API, MIDI conversion via abc2midi, FluidSynth playback. Delegates pure ABC fns to
ceol.abc - data.clj — file paths, cache read/write, soundfont discovery, local ABC, setlist loading
- staff.clj — terminal staff renderer (pitch→row grid, Unicode noteheads)
- core.clj — entry point, shutdown hook for orphan fluidsynth cleanup
Elm-like architecture: atom + watcher + Replicant render.
- core.cljs — entry point, init, keyboard shortcuts,
dispatch-action!router. Most actions delegate tohandlers/*; trivial one-liners (filter, tab, tempo) stay inline. - state.cljs — app-state atom, query functions, set/tune data model, malli schemas
- views.cljs — Replicant hiccup components (sidebar, sheet music, editor, playback bar, mobile layout)
- persist.cljs — localStorage I/O + remote data loading (custom tunes, sets, edits, notes, learned, ABC data); schema-validates at the boundary
- render.cljs — imperative abc.js sheet-music rendering, driven by a state watch
- handlers/ — action handlers split by domain:
tune.cljs,editor.cljs,set.cljs,playback.cljs,session.cljs - abc_bridge.cljs — abc.js interop (render SVG, synth play/stop, shared AudioContext)
- guitar.cljs — Tone.js Sampler with CDN acoustic guitar samples, strumming patterns per tune type
- metronome.cljs — standalone self-correcting metronome click
- beat_engine.cljc — shared pure beat math (beats-for-tune, ms-per-beat/bar)
- backup.cljs — export/import all user data as EDN
- gesture.cljs — mobile touch gestures (swipe-peek, full-swipe delete, swipe-right learned)
- chords.cljc — chord suggestion algorithm (bar-level, mode-based, pitch-class weighting)
- Async operations use
charm/cmd— runs fn on thread, delivers result as message toupdate-state - Audio pipeline: fetch ABC → convert MIDI → play. Each step returns a typed message
- State is a flat map — all mutation via
update-statereturning[new-state cmd-or-nil] - Count-in: optional woodblock click bar before tune playback
- Set queue: auto-advance through set tunes on playback finish
- Replicant dispatch: actions are vectors
[[:action/name arg1 arg2]], resolved viapostwalkfor:event/target.valueplaceholders - Imperative ABC rendering: abc.js called from state watcher (not during Replicant render) via
requestAnimationFrame - Guitar sync: always scheduled alongside melody, mute/unmute via gain node toggle
- abc.js quirks:
wrapoption causes missing barlines — use ABC newlines for line breaks instead.chordsOff: truesuppresses piano chord audio.program: 105for banjo. - Tone.js: lazy init via
Tone.start()on first user interaction. CDN samples from tonejs-instruments.
Cases where the app intentionally differs from design.pen, or a design-token
question was deliberately settled — do not "fix" these to match the mockups.
- Slim mobile playback bar — the mobile playback bar uses a 48px play button /
[0,16]padding, not the design's 64px / 16. Intentional redesign (commit "replace playback bar with slim mobile design"). - Inline notation editing kept — the full-screen ABC notation editor (
design.penframerT1yT) is rejected. The app keeps the inline.editor-paneltextarea so edits drive live sheet-music re-renders in place; a separate editor would break that. - Full-swipe-left → delete-confirm modal — a left swipe past the 140px threshold opens the styled delete-confirm modal directly. The design's intermediate "Release to delete" reveal (
qkOww) is not implemented; the confirm-modal flow is the chosen gesture. - Sidebar
gap= 20 —design.penframes disagree (d1p1says 24;d3p2/d4p1/d5p1say 20). The app's 20 matches the majority; thed1p1frame's 24 is the design-side bug. - Set editor is mobile-only — the full-screen new/edit set editor (
he1dM,:set-editorslot) clones the mobile-gated.te-overlay, so it renders only ≤720px. Desktop deliberately keeps the inline.set-creationsidebar wizard (:creating-set?). The two set-creation surfaces coexist by design; don't "unify" them onto the overlay without making it responsive first. .tune-namedefault colour#D4D2CC— settled value for the base/unselected tune-row name (active#F5F4F0, learned#A8A8A8). The earlier#aaawas a bug.- Session hero card is shared, not mobile-gated —
session-tab-pre's.session-hero-card(Wave 1 B, designJ8hkB) renders in both the 390px mobile layout and the 280px desktop sidebar, becausesession-tabis the single shared session view (no desktop variant). Verified the 56pxheroBignumber doesn't clip the sidebar. Don't gate it to mobile-only — the bold treatment is intentional on both surfaces. - Settings list rows take horizontal padding from the card — the Wave 1 E
.settings-list-row(export/import, designddeLd) usespadding: 12px 0; the.settings-cardsupplies the left/right inset (so the rows and.settings-list-dividerare content-box-wide, not edge-to-edge). The design putspadding:14on each row and zero on the card frame (full-bleed rows + divider). The shared-card-padding reuse is deliberate — it keeps the BACKUP/ABOUT/DATA cards consistent; don't refactor it to full-bleed without restructuring all three cards.
cache.edn— fetched ABC and session IDs (TUI)local-abc.edn— hand-written ABC notation, keyed by tune IDabc/— ABC notation files (TUI temp)midi/— MIDI files:{id}.mid,{id}_a.mid,{id}_t10.midsetlists/*.edn— named setlists (TUI)soundfont.sf2— SoundFont for FluidSynth
ceol-abc-edits— edited ABC per tune (with chord annotations)ceol-custom-tunes— user-added/edited tune metadataceol-sets— set definitionsceol-learned-tunes— set of learned tune IDsceol-tune-notes— practice notes per tuneceol-onboarded— first-launch coachmark dismissed flag
Fetched at startup by persist.cljs; localStorage overrides these.
local-abc.edn— hand-written ABC bodies, keyed by tune ID (see below)default-abc-edits.edn— seed ABC edits (with chord annotations) merged under any localStorage editsdefault-sets.edn— seed set definitions, used when noceol-setskey exists
Hand-written file at ~/.ceol/local-abc.edn, also copied to web/resources/public/data/. Maps tune IDs to ABC body strings (no headers). Both TUI and web read from this.
Add to catalog vector: :id, :name, :type, :time-sig, :key, :mode-name, :session-id.
Click "+" in sidebar → edit name/type/key inline in header → open editor to add ABC.
Add body to ~/.ceol/local-abc.edn keyed by tune ID. Copy to web/resources/public/data/local-abc.edn for web.
# TUI tests (Babashka)
bb -cp "src:test" -e "(require '[clojure.test :refer [run-tests]]) (require 'ceol.split-test) (run-tests 'ceol.split-test)"
# Web tests (CLJS via shadow-cljs)
cd web && ./node_modules/.bin/shadow-cljs compile test
# Web tests (pure .cljc via Babashka)
# beat-engine-test runs here too: only the JVM catches the parse-frac throw
# regression (issue #67) — the cljs runner exercises the NaN-silence half.
bb -cp "src:web/src:test" -e "(require '[clojure.test :refer [run-tests]]) (require 'ceol.web.abc-test 'ceol.web.chords-test 'ceol.web.beat-engine-test) (run-tests 'ceol.web.abc-test 'ceol.web.chords-test 'ceol.web.beat-engine-test)"95 tests, 7804 assertions (cljs total — most are generative) across chords, ABC, state, sets, beat engine, tempo, session, session-nav, actions, backup, and the mobile tune-editor / set-editor / session-summary.
For mobile flows (B-items in web/build-backlog.md), use the CDP harness at
web/scripts/verify/. Drives headless Chrome via DevTools Protocol — asserts
cljs state + screenshots at 390×844.
# Terminal 1: shadow-cljs watch app
# Terminal 2:
cd web/scripts
./verify.sh b1 # reference scenario: mobile tune-details editorSee web/scripts/verify/README.md for the helper API and gotchas
(coachmark, <select value> quirk, settle timing).
- Babashka (bb), abc2midi, fluidsynth, .sf2 soundfont
- Node.js, npm (shadow-cljs, abcjs, tone)
- Clojars: Replicant
2025.12.1
ceol/
src/ceol/
notation.cljc — ABC parser (shared)
tunes.cljc — tune catalog (shared)
abc.cljc — ABC utils (shared)
audio.clj — TUI: API, MIDI, playback
state.clj — TUI: state management
view.clj — TUI: rendering
staff.clj — TUI: staff notation
data.clj — TUI: file I/O, caching
core.clj — TUI: entry point
web/
shadow-cljs.edn
package.json
resources/public/
index.html
css/style.css — entry; imports css/modules/*
css/modules/ — split CSS modules
data/local-abc.edn — hand-written ABC bodies
data/default-abc-edits.edn — seed ABC edits
data/default-sets.edn — seed sets
src/ceol/web/
core.cljs — entry, init, keyboard shortcuts, dispatch router
state.cljs — app state, queries, schemas
views.cljs — UI components (desktop + mobile)
persist.cljs — localStorage I/O + remote data loading
render.cljs — imperative abc.js sheet rendering
abc_bridge.cljs — abc.js interop
guitar.cljs — Tone.js guitar
metronome.cljs — standalone metronome click
beat_engine.cljc — shared beat math
backup.cljs — export/import user data
gesture.cljs — mobile touch gestures
chords.cljc — chord algorithm
handlers/
tune.cljs — tune CRUD + mobile tune-editor wrappers
tune_editor.cljc — pure helpers behind mobile tune-editor
editor.cljs — ABC editor + inline-field actions
set.cljs — set actions + mobile set-editor wrappers
set_editor.cljc — pure helpers behind mobile set editor
playback.cljs — play/stop orchestration
session.cljs — practice-session actions
session_summary.cljc — pure session-complete summary helpers
scripts/
cdp.mjs — CDP harness (Node WebSocket → headless Chrome)
verify.sh — chrome launcher + scenario runner
verify/
README.md — verification process doc
b1.mjs — reference scenario (mobile tune-details editor)
test/
ceol/
split_test.clj — ABC splitting tests
web/
abc_test.cljc — ABC processing tests
chords_test.cljc — chord algorithm tests
state_test.cljc — state query tests
sets_test.cljc — set logic tests
beat_engine_test.cljc — beat math tests
session_test.cljc — session logic tests
actions_test.cljc — action dispatch tests
tune_editor_test.cljc — mobile tune-editor draft helpers
set_editor_test.cljc — mobile set-editor draft + reorder helpers
session_summary_test.cljc — session-complete count/format helpers
generative_test.cljc — generative/property tests
backup_test.cljs — backup export/import tests
runner.cljs — CLJS test runner
local-abc.edn — hand-written ABC (also at ~/.ceol/)
design.pen — UI mockups (Pencil)
Issues tracked as GitHub issues (gh CLI), repo Shakey-Bridge-Software/ceol. See docs/agents/issue-tracker.md.
Default canonical labels (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See docs/agents/triage-labels.md.
Single-context: CONTEXT.md + docs/adr/ at the repo root (created lazily by /domain-modeling). See docs/agents/domain.md.