DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== ABC Plugin (for displaying sheet music) ======

---- plugin ----
description: Displays sheet music (input ABC, output PNG, MIDI and PDF)
author     : Anika Henke
email      : anika@selfthinker.org
type       : syntax
lastupdate : 2016-04-03
compatible : 2005-07-01 - 2007-06-26, 2008-05-05, 2009-02-14, 2009-12-25 "Lemming", 2010-11-07 "Anteater", 2011-05-25 "Rincewind", 2012-01-25 "Angua", 2012-10-13 "Adora Belle", "Weatherwax", "Binky", "Ponder Stibbons", "Hrun"
depends    : 
conflicts  : 
similar    : 
tags       : music, markup_language, media, export

downloadurl: https://github.com/selfthinker/dokuwiki_plugin_abc/archive/master.zip
bugtracker : https://github.com/selfthinker/dokuwiki_plugin_abc/issues
sourcerepo : https://github.com/selfthinker/dokuwiki_plugin_abc/
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=11071728
----

===== What is ABC? =====

ABC is a musical notation language and "designed to notate tunes in plain text format."

See http://abcnotation.com/ for more information.

===== Attempts by other Wikis =====

* [[http://www.wikisophia.org/wiki/Wikitex#Music|WikiSophia]] does not use ABC but [[http://www.lilypond.org|lilypond]]
  * one attempt to implement ABC is the [[http://10pouces.homelinux.net/phpwiki/index.php/AbcPlugin|ABC plugin for  PhpWiki]] FIXME Link does not work
  * another attempt is an [[http://www.soe.ucsc.edu/cgi-bin/cgiwrap/nwhitehe/moin.cgi/MusicWiki|ABC plugin for MoinMoin]]
  * there is also the [[http://www.pmwiki.org/wiki/Cookbook/AbcMusic|AbcMusic recipe for PmWiki]]
  * and finally the "big one" got a [[http://www.mediawiki.org/wiki/Extension:Score|Score extension for MediaWiki]] (and an older [[http://www.mediawiki.org/wiki/Extension:ABC|ABC extension]] and an even older [[http://www.mediawiki.org/wiki/Extension:AbcMusic|AbcMusic extension]])
  * not a wiki, but another PHP implementation is the [[http://scorerender.abelcheung.org/|ScoreRender Plugin for WordPress]]

===== Implementing in DokuWiki =====

==== Requirements ====

* ''convert'', one of the tools from **[[http://www.imagemagick.org/|ImageMagick]]** (GPL-compatible license)
  * **[[http://www.ghostscript.com/|Ghostscript]]** (GPL or AFPL)
    * needed by ''convert'' for handling eps files, see [[notes>ImageMagick|Andi's tutorial on ImageMagick]] for details
    * ''ps2pdf'' from the same package (optional, only needed if you want to have PDF files created instead of PS files)
  * **''[[http://moinejf.free.fr/|abcm2ps]]''** (GPL 2)
  * ''abc2midi'' from [[http://abc.sourceforge.net/abcMIDI/|abcMIDI]] (GPL 2, optional, only needed if you want to have midi files created)
    * ''abc2abc'' from the same package (optional, only needed if you want to be able to transpose automatically)

==== Download and Install ====

Download and install the latest version of the plugin using the [[plugin:extension|Extension Manager]] using the URL given above. Refer to [[:Plugins]] on how to install plugins manually.

==== Configuration ====

Please use the [[plugin:config|Configuration Manager]] to configure the needed variables!

^config variable^description                                        ^importance ^
^''abc2ps''         |path where to find ''abcm2ps''                             |**essential**  |
^''[[config:im_convert]]'' |path where to find ''convert'' from ImageMagick **(from the main DokuWiki config!)**   |**essential**  |
^''displayType''    |how to display the output (image only; image linked to midi; image with list of abc, midi, PS/PDF) |recommended|
^''abc2midi''       |path where to find ''abc2midi'' (optional if you keep to the default displayType, needed with all other displayTypes)|recommended|
^''ps2pdf''         |path where to find ''ps2pdf'' (optional, only needed for displayType 2 (image with list of abc, midi, PS/PDF) and if you want pdf files to be created instead of ps files)|(optional, **new in version 2006-12-09**)|
^''abc2abc''        |path where to find ''abc2abc'' (only needed when ability to transposition is wanted, leave blank for disallowing transposition)|(optional)|
^''fmt''            |path where to find an ''abcm2ps'' format file (e.g. "foo.fmt") to format the PS/PDF file (leave blank for not using any)|(optional)|
^''mediaNS''        |namespace for media files; before version 2008-08-17 they were stored in a subfolder of the media directory 'plugin_abc', now this is configurable (leave blank for root and the acl mechanism to work on these files as well); please use only one valid namespace name          |(optional, **new in version 2008-08-17**)|
^''abcok''          |turn abc rendering on or off; when turned off, only the source is displayed        |(optional) |
^''displaySource''  |turn additional displaying of the abc source on or off               |(optional) |
^''displayErrorlog''|turn displaying of error logs (of abc2ps and abc2midi) on or off (they are only displayed **once** when page is saved or previewed)               |(optional, **new in version 2008-08-17**) |
^''params4img''     |parameters for generating the image                            |(optional, **new in version 2007-06-03**, only for experts!)|
^''params4ps''      |parameters for generating the ps/pdf file                      |(optional, **new in version 2007-06-03**, only for experts!)|

=== style.css and file icons ===

If you want to allow midi files to be uploaded by the media manager and want them to be automatically recognized by DokuWiki, you should take the steps [[:mime|described here]] (using the mid.png file icon in the root folder of the plugin or any other) and comment out the last lines of ''style.css''.

You can do the same with a possible abc icon ...

==== Probable alteration of ./inc/search.php ====

The plugin stores all needed media files automatically in the DokuWiki media directory in a subnamespace (configurable through ''mediaNS'', default: "plugin_abc"). If you do not want them to be displayed and made accessible through the media popup, you can alter ''./inc/search.php''. In the first function ''search()'' right after this
    if(preg_match('/^[\._]/',$file)) continue; //skip hidden files and upper dirs
just add the following line:
    if (substr($file,0,10)=='plugin_abc') continue; //skip plugin_abc dir
or substitute "plugin_abc" with your configured "mediaNS" accordingly.

===== Usage in DokuWiki =====

This code will lead to one of three possible outputs (set by ''$conf['abcDisplayType']''):

* output 1: image of the sheet music, linked to the corresponding midi file
  * output 2: image with a list of links to the corresponding abc, MIDI and PS (or PDF) file
  * output 0: image only

==== Transposition ====

It is possible to let the plugin transpose for you by extra parameters (separated by spaces; only 7 different values allowed). These parameters have to be numbers between -23 and 23, which is the amount of semitones that the tune will be transposed up (if positive) or down (if negative). E.g.

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

===== Debugging =====

If the plugin does not seem to work ...

- Make sure the involved programmes work properly (by testing e.g. "''/path/to/abcm2ps test.abc -O test.ps''" in the shell).
  - Enable the [[config:allowdebug|'allowdebug' config option]]. That will turn on more detailed hints about what could be wrong.
  - Add a [[devel:caching#purging_the_cache|purge parameter]] to the URL ("?purge=1" or "&purge=1") when testing - to force a recaching of the page and to recreate all abc plugin related files.

===== Important notes =====

* Any kind of error handling or other measures to provide security may not have been cared for satisfyingly. So any usage at your own risk.
  * You can test the plugin on http://abcwiki.selfthinker.org/

===== Version history =====

{{rss>https://github.com/selfthinker/dokuwiki_plugin_abc/commits/master.atom date}}

===== Feedback =====

==== Rendering ====
Please include http://code.google.com/p/abcjs/ for rendering.

==== Output tabs ====

>> Hey!! Congratulations for your plugin!!! It would be great if you could extend it to be able to output tabs besides music sheets. Is it possible? -- // [[gmail+dokuwiki@gmail.com|Jorge]] 2007-02-13 14:50 //
> Thanks. Yes, outputting tabs is possible by using ''[[http://www.lautengesellschaft.de/cdmm/|abctab2ps]]'' instead of ''abcm2ps''. And the plugin has to be tweaked a little, as well (most probably, maybe not!? I haven't tested). But I have no time to do it in the too near future. --- //[[anika@selfthinker.org|Anika Henke]] 2007-04-01 12:22//
I found out that tabs can be done with ''[[http://www.guitarnut.com/abc/|jaabc2ps]]'', as well. With the new release (2007-06-03) of the abc plugin, you could change the ''params4img'' config option to "''-s 1 -T1CeBGDA,E, -o''" or something similar. I don't know, if it will work right away, you might still be needing to tweak the plugin a bit more. But now it should be easier.  --- //[[anika@selfthinker.org|Anika Henke]] 2007-06-04 23:40//

==== Troubles getting plugin to run ====

> Hey Anika, I'm having an issue getting the plugin to run on my hosting service.  They've given me access to all the binaries (abc2*, ps2pdf and convert) and I've setup the config file.  Only issue I can think of is permissions.  My page that uses the plugin is [[http://www.thefreyers.net/doku.php?id=music:abcnotation|here]].  Got any tips for resolving this?  Thanks.  --- //[[chris@thefreyers.net|Chris Freyer]] 2007-12-07 00:50//
Hallo! 1. The ''im_convert'' config option is not part of the plugin config, but of the **main** DokuWiki config. So it should be set there. 2. The message "''(im_convert) is not executable''" indicates that there is no path set in ''$conf['im_convert']''. Otherwise it would read "''/path/to/convert (im_convert) is not executable''". --- //[[anika@selfthinker.org|Anika Henke]] 2007-12-07 16:43//

==== ACL issues ====

Hi Anika, \\
Here is reporting an ACL issue for the abc plugin on DokuWiki-2008-05-05 release version. \\
My wiki is set to be a closed wiki (@ALL default None), and set @ALL read to :stanley namespace and stanley page. \\
However, the abc tag on stanley:song page cannot show up PNG image file. You may see the URL - http://www.ichiayi.com/wiki/stanley/song \\
any idea?
 --- //[[tryweb@ichiayi.com|Jonathan Tsai]] 2008/05/17 14:55//
> Hallo! Sorry, all abc media files are stored in the namespace "plugin_abc". I did not want the "normal" media folders to be too cluttered. But unfortunately, this also means "normal" ACL rules will not apply. (In future releases I will make this namespace configurable!) You can either \\ - add an ACL rule <code>plugin_abc:*      @ALL    1</code> - or change the following lines in ''./lib/plugins/abc/syntax.php'' (in order to not store all files in "plugin_abc", but in their correct corresponding namespace): <code php>
//line 177:
$abcdir = $savedir.'/media/plugin_abc';
//line 354:
$abcMediaUrl=DOKU_BASE."lib/exe/fetch.php?cache=cache&amp;media=plugin_abc:";
</code> to <code php>
//line 177:
$abcdir = $savedir.'/media';
//line 354:
$abcMediaUrl=DOKU_BASE."lib/exe/fetch.php?cache=cache&amp;media=";
</code> \\ --- //[[anika@selfthinker.org|Anika Henke]] 2008/05/18 11:54//
>> Thanks Anika, \\
>> After comparing the adding an ACL rule method and the other method to modify './lib/plugins/abc/syntax.php' code , I would like to choose the last one to solve the issue. Because it can let all abc files following my ACL rules setting. Thank you again for your kindly and rapidly reply.
 --- //[[tryweb@ichiayi.com|Jonathan Tsai]] 2008/05/18 23:23//

==== Working with jcabc2ps ====

Hmmm, tried to get the plugin working with jcabc2ps but that directly writes to stdout and I haven't got a clue how to fix this and either change the plugin to do something like jcabc2ps filename.abc > filename.ps or alter jcabc2ps to directly dump to .ps. (The reason I'd like to use jcabc2ps is the more clever way of altering bass notes and such... [[http://trillian.mit.edu/~jc/music/abc/doc/ABCtut_Clefs.html]]
Anything anyone could fix? (I might try to fiddle around with it a bit myself, but I have very little knowledge of PHP...)
 --- //[[harmen@murf.nl|Harmen]] 2009/03/31 17:14//

==== Setting ps2pdf on Windows ====

I'm not too sure what to put when setting ps2pdf. I've tried putting ''c:\xxx\xxx\ghostscript\gs8.71\lib\ps2pdf14'' and I get the error message that it's not an executable. There's no .exe files that I can see in the ghostscript folder. Midi & ps conversion works fine. Dokuwiki on local install. Any help appreciated.
 --- ty //2011/08/29 10:13//

==== Understanding Transposition ====
I understood that I have to put the following in the plugin beginning to obtain a transposition:
<code><abc 7 -3></code>
Do I need to do something else to obtain a transposition? I copied your example in my page but it seems to not work. What did I missed?
//[[partenery ate gmail point com|Florin]]//

> You only need to make sure ''abc2abc'' (from the ''abc2midi'' package) is installed and working. The path to it then needs to be set in the ''abc2abc'' config option. --- [[user>ach|Anika Henke]] //2014/03/23 13:43//

==== Error messages ====

>I recive the folowing errors: abc2ps In tune\\
>Error : 'staffwidth' too big\\
>File C:/xampp/htdocs/dki/data/media/plugin_abc/kunde/2_zocharti_loch.abc
>Output written on C:/xampp/htdocs/dki/data/media/plugin_abc/kunde/2_zocharti_loch001.eps (26954 bytes)
>abc2ps\\
>File C:/xampp/htdocs/dki/data/media/plugin_abc/kunde/2_zocharti_loch.abc
>Output written on C:/xampp/htdocs/dki/data/media/plugin_abc/kunde/2_zocharti_loch.ps (1 page, 1 title, 27063 bytes) --- //[[partenery ate gmail point com|Florin]]//\\
>
>> That is just a feedback from abcm2ps which you can ignore or even turn off with the ''displayErrorlog'' config option. The messages will only be displayed the first time you save a page with ABC in it, after that they will disappear. --- [[user>ach|Anika Henke]] //2013/07/11 01:39//\\
>>
>>>''Error : 'staffwidth' too big''-it is a normal message? --- //[[partenery ate gmail point com|Florin]]//
>>>
>>>> Yes, I get that message all the time. That is nothing to worry about. --- [[user>ach|Anika Henke]] //2013/07/12 00:35//
>So, please tell me where exactly should I post this debugging code ''var $_debug = 1''?
>>There is only one syntax.php in the plugin and there is only one "var $_debug".\\
>>https://github.com/selfthinker/dokuwiki_plugin_abc/blob/master/syntax.php#L18.
>For test I made myself via notepad an ABC File with this content:\\
>test.abc:
> <abc 5>
>X:42
>T:Test
>M:4/4
>K:C
>"C" C2 D2 E2 G2 |"C" c8 |]
>w:This is just a test.
></abc>
>>ABC files shouldn't have <abc></abc> in them. That's only meant for DokuWiki to know that the content can be rendered by the ABC plugin.
>>>Good to know.\\

>**1.**This is my first manual testing steps:\\
>Win server 2003. Run, cmd:
>C:\Utile\abcm2ps>C:\Utile\abcm2ps\abcm2ps.exe test.abc -s 1 -w 600 -E -O test. 2>&1
>abcm2ps-6.6.22 (November 28, 2012)
>-In tune:
>Error: 'staffwidth' too big
>Output written on test001.eps

>**2.**C:\Utile\ImageMagick-6.8.6-Q8\convert.exe C:\Utile\abcm2ps\test001.eps -flatten test.png
>convert: Postscript delegate failed `rrr.eps': No such file or directory @ error/ps.c/ReadPSImage/837.
>convert: no images defined `rrr.png' @ error/convert.c/ConvertImageCommand/3106.
>>You are probably missing the Ghostscript delegate library. Install it from here: [[http://www.imagemagick.org/script/binary-releases.php]]  [[user>ach|Anika Henke]]
>>>It works! My advice is to open the **imdisplay.exe** inside ImageMagick folder and try to  open manually test001.eps. If you see the image the converter is working. (to me it did not work before installing GhostScript application!)\\
>>>Pay attention too to the apache error.log. It seems that for some reasons the path to im_converter (set in Configuration Manager DW) to not be recognized because of the space between C:\Program(space)files\path. For me it worked installing it outside the ''Program Files'' folder (I have Windows 2003 and I installed it in the ''C:\Util\''. //[[partenery ate gmail point com|Florin]]//\\

==== Multiple abc section on the same page ====

Hi Anika and thanks for this plugin.

I recently installed it on a 2014-09-29d "Hrun" and it works great.

Just one question, is there is a way to have multiple <abc> section on the same page?

When I'm doing it, I'm getting multiple image of the last section instead of 2 distinct section.

Thanks - Thomas.

> Yes, having multiple abc section on the same page is no problem. The problem you're having sounds like it's because your sections have the same titles and IDs/reference number (''X:''). The media files which get created all follow a pattern for the file name which first has the ID and then the title. So, when both are the same, the previous files get overwritten. Just make sure you use different reference numbers. --- [[user>ach|Anika Henke]] //2017-01-23 00:19//

Please fill all the letters into the box to prove you're human. Y P K U H Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International