DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:abc2

ABC 2.0 Plugin (for displaying sheet music)

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Displays sheet music (input ABC, output SVG and MIDI)

Last updated on
2024-01-21
Provides
Syntax, Action
Repository
Source
Conflicts with
abc

Similar to abc

Tagged with export, markup_language, media, music

This plugin lets you add ABC syntax (a musical notation language) to a wiki page and turns that into SVG images of sheet music and MIDI sounds. It uses abcjs, abc2svg and $ABC_UI for that. It is the successor of the ABC Plugin.

Installation

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Configuration and Settings

  • library: choose one of the different ABC libraries (they all have their pros and cons)
  • abcok: activate the library (deactivating is good for debugging)
  • showSource: show the original source (doesn't work with abc2svg)
  • stayLibre: only use Open Source components (abc2svg uses an external soundfont which is not Open Source, setting this will deactivate the sound for abc2svg so it won't be used)
  • abcuiConfig: configuration parameters for abc-ui (space separated numbers, first number is score width in cm, second number is zoom level)

Potential Template Changes

Two of the libraries (abc2svg and $ABC_UI) produce images which are not responsive. That means that when viewed on a mobile device or when zoomed in, they will break out of the page. That will look broken but is at least readable and won't cut off.

That only works when the template's styling allows that. There is a fix for the default 'dokuwiki' template in this plugin. But if you're using a different template, that fix might not work. You might need to override something that hides part of the image, e.g. changing overflow: hidden somewhere to overflow: visible via a user style.

The images also break out of the page in desktop view with a sidebar in the default template. That can be mitigated with the tempalate's __site_width__ style.ini setting, or the abcuiConfig setting specifically for the $ABC_UI library.

Usage and Syntax

<abc>
X:42
T:Test
M:4/4
K:C
"C" C2 D2 E2 G2 |"C" c8 |]
w:This is just a test
</abc>

This code will produce an SVG file which shows the sheet music and a MIDI file which you can play.

This is a screenshot of the output of all three libraries:

Transposition

You can transpose any ABC by adding extra parameters (separated by spaces, 8 different values allowed). These parameters have to be numbers between -12 and 12, which is the amount of semitones that the tune will be transposed up (if positive) or down (if negative).

<abc 7 -3>
X:42
T:Test
M:4/4
K:C
"C" C2 D2 E2 G2 |"C" c8 |]
w:This is just a test
</abc>

This will show the tune in the original key, as well as automatically transposed up to G major and down to A major.

Please note: Transposition does not work with abcjs.

Comparison between different libraries

You can choose between different ABC libraries. They all have their pros and cons.

abcjs abc2svg $ABC_UI
license MIT GPL2 or later (but it uses a resource which is not Open Source and can be switched off in the config) GPL2 or later (uses abc2svg)
responsiveness the score gets smaller on mobile but that also means it's more difficult to read the score doesn't get smaller and breaks out of the page on mobile but that also means it's easier to read the score doesn't get smaller and breaks out of the page on mobile but that also means it's easier to read
only works within plugin syntax ❌ no, the script grabs anything that looks like ABC and converts it ❌ no, the script grabs anything that looks like ABC and converts it ✅ yes
can show original source ✅ yes ❌ no 1) ✅ yes
works in edit preview ✅ yes ❌ no ✅ yes
can transpose ❌ no 2) ✅ yes ✅ yes
notes follow sound ❌ no 3) ✅ yes ✅ yes
sound includes chords ✅ yes ❌ no ❌ no
extra features ❌ no ✅ yes, lots of extra parameters and some differing features ✅ yes, same as abc2svg, plus can switch voices in the sound on and off and can switch between different tempos (via %%tempo)
how the sound starts player underneath, play/pause plays from start when clicking on sheet, or plays from specific point when clicking on single notes player button on the top, play/stop
pitfalls if ABC is used outside of the <abc> syntax, needs no space after “X:” or it won't render 4) better to use Q (or else the sound is super slow)
bugs or missing features gets some broken rhythm wrong 5), missing support for octave modifier breaks some of DokuWiki's JavaScript (TOC toggle) loading soundfont before playing any sound means it takes about 2 seconds longer to load than the other libraries, no repo makes it unclear when and how the code gets updated, missing some glyphs for decorations (e.g. !slide!)
accessibility issues cannot play sound with keyboard only no accessible names for interactive elements (player button, checkboxes and tempo dots), uses layout tables

Differences to old ABC Plugin

The predecessor of this plugin is the ABC Plugin. It still works but cannot be used alongside the ABC2 Plugin because they both use the same syntax. Here are the differences between the two plugins and the reason why there is a new plugin…

The ABC2 Plugin is much easier to install than the old ABC Plugin. You don't have to build and install different backend programmes outside of the wiki anymore. Everything you need is now included in the plugin and is run with JavaScript.

The old ABC Plugin gave admins the choice between different output types: image, image and sound, or image, sound and PDF, and those could be downloaded. The successor now has less choices, it only creates image and sound, no PDFs and no downloads.

But the image quality of the new plugin is much better. It produces SVGs which are always much clearer and sharper than PNGs which don't scale well and can look grainy on retina devices. SVGs also look much better when printed and scores can easily be printed via the browser's print functionality.

Version history

Discussion

Add questions here…

  • got no github accound, so: after the latest DokuWiki update (rc2022-06-26 “Igor” RC2) the SVG output is tiny, next to invisible… Maybe any ideas, how to fix it? Great Plugin, btw. 2022-07-08 14:12
    • This has been fixed now (in version 2024-01-20).
  • Congratulations! This is a huge update. Thanks for your dedication and consistent commitment for this difficult task (and I know the level of dificulty). I am not sure you done this for the sake of music or for DokuWiki :-); but anyhow, nice and serious job. — Florin 2021-02-22 14:12
  • Awesome plugin. The default grand piano voice (MIDI program number one) becomes marimba above high 'F' on the great stave Austvergine 2022-10-24 11:50
  • Am I the only one who has trouble with uploading media files with ABC2 active? (the Media Manager still works fine) wun 2022-12-27 12:50
1)
that means the 'showSource' config has no effect
2)
abcjs has the ability to transponse, but not through the way it is implemented in this plugin
3)
abcjs has the ability for this, but not in this version of the library
4)
this is fixed and will be in a future version
5)
this was fixed upstream and will be fixed in a future release
plugin/abc2.txt · Last modified: 2024-01-21 17:01 by ach

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki