Skip to content

Commit f416829

Browse files
André DietrichAndré Dietrich
André Dietrich
authored and
André Dietrich
committed
templates documented
1 parent 48dcb1e commit f416829

5 files changed

Lines changed: 1409 additions & 0 deletions

‎content/english/blog/template_abcjs-music-notation-in-liascript.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
---
2+
title: "ABCjs for LiaScript: Embed and Play Music Notation in Open Courses"
3+
slug: "abcjs-music-notation-in-liascript"
4+
date: 2026-05-27
5+
draft: false
6+
author: "André Dietrich"
7+
image: "https://raw.githubusercontent.com/LiaTemplates/ABCjs/main/logo.png"
8+
categories:
9+
- Template
10+
- Tutorial
11+
tags:
12+
- Templates
13+
- Music
14+
- Visualization
15+
- OER
16+
- Interactive
17+
- No Server
18+
- Teachers
19+
20+
description: "Use the ABCjs template to write, render, and play music in ABC notation directly inside your LiaScript courses — no server, no extra tools, just text."
21+
---
22+
23+
Music belongs in open courses.
24+
Whether you teach music theory, introduce students to folk music traditions, document historical scores, or simply want to liven up a language lesson with a melody — the [ABCjs template](https://github.com/LiaTemplates/ABCjs) lets you write music in plain text and render it as interactive sheet music with a built-in audio player, directly in the browser.
25+
26+
No server, no MIDI files to upload, no external embedding.
27+
Just import the template, write [ABC notation](https://en.wikipedia.org/wiki/ABC_notation), and your course comes alive with sound.
28+
29+
---
30+
31+
## What is ABC Notation?
32+
33+
[ABC notation](https://abcnotation.com) is a text-based music notation system — simple enough to type in a plain text editor, expressive enough to describe melodies, chords, rhythms, lyrics, and multiple voices.
34+
It was originally created for folk and traditional music and is widely used in online score archives.
35+
36+
A short example:
37+
38+
``` text
39+
X: 1
40+
T: Ode an die Freude
41+
C: L. v. Beethoven
42+
M: 4/4
43+
L: 1/4
44+
K: D
45+
E E F G | G F E D | C C D E | E3/2 D/ D2 |
46+
```
47+
48+
The [ABCjs JavaScript library](https://www.abcjs.net) turns this text into rendered notation with a playback button — and the LiaScript template wraps it into a simple macro you can use directly in your course.
49+
50+
---
51+
52+
## Quick Start
53+
54+
Add a single line to your course header:
55+
56+
``` markdown
57+
<!--
58+
import: https://raw.githubusercontent.com/LiaTemplates/ABCjs/main/README.md
59+
-->
60+
```
61+
62+
For a version-stable import (recommended for published courses):
63+
64+
``` markdown
65+
<!--
66+
import: https://raw.githubusercontent.com/LiaTemplates/ABCjs/0.0.2/README.md
67+
-->
68+
```
69+
70+
That's it. All four macros are now available in your document.
71+
72+
---
73+
74+
## Rendering Notes: `@ABCJS.render`
75+
76+
The simplest macro renders your ABC code as sheet music with a play button:
77+
78+
```` markdown
79+
``` abc @ABCJS.render
80+
X: 1
81+
T: Ode an die Freude
82+
C: L. v. Beethoven
83+
M: 4/4
84+
L: 1/4
85+
K: D
86+
E E F G | G F E D | C C D E | E3/2 D/ D2 |
87+
E E F G | G F E D | C C D E | D3/2 C/ C2 |
88+
D D E C | D E/F/ E C | D E/F/ E D | C D G,2 |
89+
E E F G | G F E D | C C D E | D3/2 C/ C2 |
90+
```
91+
````
92+
93+
Try it directly in the LiveEditor:
94+
95+
{{< liascript mode="preview" >}}
96+
<!--
97+
import: https://raw.githubusercontent.com/LiaTemplates/ABCjs/main/README.md
98+
-->
99+
100+
# ABCjs Demo – Noten rendern
101+
102+
``` abc @ABCJS.render
103+
X: 1
104+
T: Ode an die Freude
105+
C: L. v. Beethoven
106+
M: 4/4
107+
L: 1/4
108+
K: D
109+
E E F G | G F E D | C C D E | E3/2 D/ D2 |
110+
E E F G | G F E D | C C D E | D3/2 C/ C2 |
111+
D D E C | D E/F/ E C | D E/F/ E D | C D G,2 |
112+
E E F G | G F E D | C C D E | D3/2 C/ C2 |
113+
```
114+
{{< /liascript >}}
115+
116+
---
117+
118+
## Live Editing: `@ABCJS.eval`
119+
120+
The real power comes with `@ABCJS.eval`.
121+
This turns the code block into an editable LiaScript editor — learners can modify the score, change notes, transpose melodies, and hear the result immediately.
122+
All changes are preserved in the course state.
123+
124+
```` markdown
125+
``` abc
126+
% audio: true
127+
% autoplay: false
128+
% notes: true
129+
X: 1
130+
T: Twinkle Twinkle Little Star
131+
M: 4/4
132+
L: 1/4
133+
K: C
134+
C C G G | A A G2 | F F E E | D D C2 |
135+
G G F F | E E D2 | G G F F | E E D2 |
136+
C C G G | A A G2 | F F E E | D D C2 |
137+
```
138+
@ABCJS.eval
139+
````
140+
141+
The comment lines (`% audio: true`, etc.) are settings that override the macro defaults — you can embed them directly in the ABC code.
142+
143+
Try the editable example live:
144+
145+
{{< liascript mode="preview" >}}
146+
<!--
147+
import: https://raw.githubusercontent.com/LiaTemplates/ABCjs/main/README.md
148+
-->
149+
150+
# ABCjs Demo – Live-Editor
151+
152+
``` abc
153+
% audio: true
154+
% autoplay: false
155+
% notes: true
156+
X: 1
157+
T: Twinkle Twinkle Little Star
158+
M: 4/4
159+
L: 1/4
160+
K: C
161+
C C G G | A A G2 | F F E E | D D C2 |
162+
G G F F | E E D2 | G G F F | E E D2 |
163+
C C G G | A A G2 | F F E E | D D C2 |
164+
```
165+
@ABCJS.eval
166+
{{< /liascript >}}
167+
168+
---
169+
170+
## Fine-grained Control: `@ABCJS.renderWith` and `@ABCJS.evalWith`
171+
172+
Both macros accept parameters to configure the output precisely:
173+
174+
```` markdown
175+
``` abc @ABCJS.renderWith(channel="10" audio="true" notes="false")
176+
X: 1
177+
T: Cooley's
178+
M: 4/4
179+
L: 1/8
180+
K: Emin
181+
|:D2|"Em"EBBA B2 EB|~B2 AB dBAG|"D"FDAD BDAD|FDAD dAFD|
182+
"Em"EBBA B2 EB|B2 AB defg|"D"afe^c dBAF|"Em"DEFD E2:|
183+
```
184+
````
185+
186+
Available options:
187+
188+
| Option | Description |
189+
|--------|-------------|
190+
| `audio` | Show audio controls (default: `true`) |
191+
| `autoplay` | Start playing automatically when visible (default: `false`) |
192+
| `channel` | MIDI channel — use `10` for percussion |
193+
| `notes` | Render sheet music or playback-only (default: `true`) |
194+
| `program` | MIDI instrument number |
195+
| `responsive` | Fit to screen width (default: `true`) |
196+
| `tablature` | Add instrument tablature (e.g., for guitar or violin) |
197+
| `stereo` | Stereo panning effect (default: `false`) |
198+
| `voicesOff` | Play accompaniment without melody |
199+
| `chordsOff` | Silence guitar chord symbols |
200+
201+
---
202+
203+
## Full Template Demo
204+
205+
The full ABCjs README is itself a self-documenting LiaScript course — you can explore all features live:
206+
207+
{{< liascript-show "https://raw.githubusercontent.com/LiaTemplates/ABCjs/main/README.md" >}}
208+
209+
---
210+
211+
## Use Cases
212+
213+
**Music education** — Render scales, intervals, sight-reading exercises, and harmonization tasks directly in the course text.
214+
Students can modify the notation and hear the result without leaving the page.
215+
216+
**Folk and traditional music** — ABC notation has a vast archive at [abcnotation.com](https://abcnotation.com).
217+
Paste any score directly into your course.
218+
219+
**Music theory** — Present chord progressions, voice-leading examples, or counterpoint exercises with playback.
220+
Use `@ABCJS.eval` to let students experiment with modifications.
221+
222+
**Language courses** — Embed songs and nursery rhymes to support pronunciation, rhythm, and vocabulary learning.
223+
224+
**OER and open archives** — Since ABC is plain text, your scores are fully version-controllable with Git, shareable without binaries, and independent of any proprietary format.
225+
226+
---
227+
228+
## Learning ABC Notation
229+
230+
ABC notation is easy to pick up.
231+
A good starting point is the official documentation at [abcnotation.com](https://abcnotation.com) and the following video series:
232+
233+
- [How to get started with ABC notation](https://www.youtube.com/watch?v=jwzzueA5siQ)
234+
- [ABC notation basics](https://www.youtube.com/watch?v=H8hWKP5cEXE)
235+
- [Next steps with ABC notation](https://www.youtube.com/watch?v=u6_tjcKE42A)
236+
- [Including lyrics in ABC notation](https://www.youtube.com/watch?v=RWNeCjid0zc)
237+
- [Polyphony and multiple voices](https://www.youtube.com/watch?v=HxLKo4HL19g)
238+
239+
---
240+
241+
## Technical Facts
242+
243+
| | |
244+
|---|---|
245+
| **Runs in browser** | Yes — no server, no backend |
246+
| **Audio playback** | Built-in via abcjs Web Audio synthesis |
247+
| **Interactive editing** | Yes, with `@ABCJS.eval` |
248+
| **External API** | No |
249+
| **Offline capable** | After first load (assets cached) |
250+
| **License** | CC0-1.0 |
251+
| **Maintained** | Yes (TypeScript, latest build 2024) |
252+
| **Version-stable import** | Yes (`0.0.2` tag available) |
253+
254+
---
255+
256+
## Try It
257+
258+
{{< button link="https://liascript.github.io/course/?https://raw.githubusercontent.com/LiaTemplates/ABCjs/main/README.md" label="Try in LiaScript" >}}
259+
260+
{{< button link="https://liascript.github.io/LiveEditor/?/show/file/https://raw.githubusercontent.com/LiaTemplates/ABCjs/main/README.md" label="Open in LiveEditor" >}}
261+
262+
{{< button link="https://github.com/LiaTemplates/ABCjs" label="View on GitHub" >}}
263+
264+
---
265+
266+
## Related Templates
267+
268+
- [**mermaid_template**](/blog/mermaid-diagrams-in-liascript) — text-based diagram notation (flowcharts, sequence diagrams, Gantt)
269+
- [**JSXGraph**](/blog/jsxgraph-and-liascript-a-perfect-match) — interactive mathematical visualizations
270+
- [**plantUML**](https://github.com/LiaTemplates/plantUML) — UML diagrams via PlantUML
271+
- [**Tikz-Jax**](https://github.com/LiaTemplates/Tikz-Jax) — render TikZ/LaTeX figures in the browser

0 commit comments

Comments
 (0)