====== ABC Plugin (for displaying sheet music) ====== ---- plugin ---- description: Displays sheet music (input ABC, output png, midi + pdf) author : Anika Henke email : anika@selfthinker.org type : syntax lastupdate : 2008-08-17 compatible : 2005-07-01 - 2008-05-05 depends : conflicts : similar : tags : abc, music, notation, midi, sheet ---- ===== What is ABC? ===== abc is a musical notation language and "designed to notate tunes in an ascii format." See http://abcnotation.org.uk/ 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]] * 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 its [[http://www.mediawiki.org/wiki/Extension:AbcMusic|AbcMusic extension for MediaWiki]] ===== Implementing in DokuWiki ===== ==== Requirements ==== * ''convert'' from [[http://www.imagemagick.org/|ImageMagick ]] (GPL-compatible license) * which should use [[http://www.cs.wisc.edu/~ghost/|Ghostscript]] (GPL or AFPL) -- see Andis tutorial on [[notes>ImageMagick]] for details * ''[[http://moinejf.free.fr/|abcm2ps]]'' (GPL 2) * ''abc2midi'' from [[http://abc.sourceforge.net/abcMIDI/|abcMIDI]] (GPL 2, 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) * [[http://www.cs.wisc.edu/~ghost/|Ghostscript]]'s ''ps2pdf'' (only needed if you want to have pdf files created instead of ps files) ==== Download and Install ==== * **{{plugin:abc_plugin.zip|Download latest version}} (2008-08-17)** for DokuWiki versions 2006-11-06 - 2008-05-05 (latest stable release) and devel versions * **{{plugin:plugin_abc_2006-02-27a.zip|Download version 2006-02-27a}}** for older DokuWiki versions (2005-07-01 - 2006-03-09) Either extract the downloaded zip file manually into ''./lib/plugins/'' or use the provided Download URL with the [[plugin]] manager. ==== Configuration ==== === For the latest plugin versions (2007-06-03, 2006-12-09 + 2006-07-23) === Please use the [[plugin:config|Configuration Manager]] to configure the needed variables! (If you want to change these manually, you can edit ''./lib/plugins/abc/conf/default.php'' instead.) ^config variable^description ^importance ^ ^''abc2ps'' |path where to find ''abcm2ps'' |**essential** | ^''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 == Since version 2006-12-09 a file icon for midi files was added. 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 my mid.png or any other) and comment out the last lines of ''style.css''. You can do the same with a possible abc icon ... === For older versions (2006-02-27a and earlier) === Please read the README that comes with the zip file! ==== 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 ===== X:42 T:Test M:4/4 K:C "C" C2 D2 E2 G2 |"C" c8 |] w:This is just a test 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 {{plugin:42_test.png}} ==== Transposition ==== Since version 2005-11-20 it is possible to let the plugin transpose for you by an extra parameter. This parameter has to be a number between -23 and 23, which is the amount of semitones the tune will be transposed up (if positive) or down (if negative). Since version 2006-02-21 it is possible to let the plugin transpose for you by extra parameters (seperated 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. X:42 T:Test M:4/4 K:C "C" C2 D2 E2 G2 |"C" c8 |] w:This is just a test 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). - There is an internal debug variable, which can be turned on for more detailed hints what could be wrong ("''var $_debug = 1;''" near the top of ''syntax.php''). - 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 ===== * I only just began to learn PHP, so please feel free to make improvements! * 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. * I have successfully tested on Windows2000 and Linux Debian. * You can test the plugin at this live wiki: http://abcwiki.selfthinker.org/ ===== Version history ===== * **2008-08-17**: * made abc media namespace configurable (if your wiki closed, this could fix a security issue) * added the option to display the error logs of abcm2ps and abc2midi (only once when the page is saved or previewed) * fixed browser caching for changed media files * fixed preview of a revision * improved error messages * **2007-06-03**: * support for (many) UTF-8 characters, which will be automatically converted into their equivalent escape sequence * formerly nothing was displayed when the image failed to be generated, now an error is displayed instead * two config options were added for the possibility of changing the abcm2ps parameters for the image and ps/pdf generation * **2006-12-09**: * support for PDF file creation * for the list of abc, midi, ps/pdf files corresponding file icons for different media types are used * when doing a "[[devel:caching#purging_the_cache|?purge=1]]", the behaviour for not parsing unchanged source again, is avoided * a simple (hidden) way to debug was added * the style.css was changed (so was a bit of the html output) * **2006-07-23**: * no more usage of the .trans file * if transposition parameters have changed, only the necessary files are parsed again * old transposed files will now be deleted * upgraded for ability to use the config manager for configuration * from now on the abc source is always in the html source (for search engine optimization) * rough error handling * **2006-02-27a**: bugfix for creation of ps file when no fmt file is used * **2006-02-27**: bugfix for preview and revisions (similar to [[bug>670]]) and reaction to deletion of $conf['dmask'] * **2006-02-21**: enhanced transposition functionality * **2005-11-21**: bugfix for handling file names (realpath) of more than 120 characters and changing the file base * **2005-11-20**: new transposition functionality * **2005-10-23**: first //functioning// version! * **2005-07-04**: first version ===== Feedback ===== >> 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// > 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// 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 plugin_abc:* @ALL 1 - 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): //line 177: $abcdir = $savedir.'/media/plugin_abc'; //line 354: $abcMediaUrl=DOKU_BASE."lib/exe/fetch.php?cache=cache&media=plugin_abc:"; to //line 177: $abcdir = $savedir.'/media'; //line 354: $abcMediaUrl=DOKU_BASE."lib/exe/fetch.php?cache=cache&media="; \\ --- //[[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//