AbcTunebook

Summary: add and edit abc music using Fox and rendered as score and midi by abcjs javascript abc editor
Version: 2016-01-08
Prerequisites: PmWiki 2.2.56 (compatible with PHP 5.5)
Status: stable
Maintainer: HansB
Discussion: AbcTunebook-Talk
Users: (View / Edit)
Categories: Markup Editing CMS Fox PHP55
Discussion: AbcTunebook-Talk

Questions answered by this recipe

How can I create abc tune collections and have tunes displayed as score and midi player?
How can I edit abc tunes with an instant preview of the score, seeing the score changes as I type the changes?
How can I create tune lists and special searches using the fields of the abc notation?
How can I add custom fields?

Description

This recipe is for creating and editing tunes in abc notation, organised in groups as tune books. It uses Fox and FoxEdit for posting and editing abc tunes, and the amazing javascript abc editor abcjs from Gregory Dyke and Paul Rosen (http://drawthedots.com/abcjs) for rendering the abc notation as a musical score and midi in a player for instant preview..

The enclosed templates and system pages will give you the possibility to create multiple tune books. Much can be done to enhance the system so far developed. I am looking for other developers to join me in this project.

Installation

Download abctunebook.zipΔ, unpack the files to the associated directories, and add to config.php:

include_once("$FarmD/cookbook/abctunebook.php");

Install Fox and FoxEdit if you have not done already, and set $FoxPagePermissions for 'add,edit' for the tunebook wiki group(s) you want to use.

The zip file contains three wiki pages set up already for a group 'Tunebook'. Each wiki group destined to become a tunebook needs these three pages, so copy and rename as necessary. The page Site.FoxAbcTemplates is included and serves the form templates for the three tunebook system pages (NewTune, HomePage, GroupHeader).

If the javascript score rendering is not happening when viewing or editing a tune page check that the javascript is loading: check that your browser can use javascript; check the page HTML source; check the directory and file names of the abcjs scripts used; try to open the url of the script as found in the HTML source; make sure the skin you use supports the $HTMLFooterFmt (many if not most skins do).

Usage

Once the files and pages are set up go to the tunebook HomePage (default Tunebook.HomePage). This page will list the tunes of the group once you added some, and it contains a link to the NewTune page, with which you can add a new abc tune. Write it or paste a complete tune into the textarea. The abcjs javascript should immediately show you a preview of the tune in form of a musical score (dots) and a midi player which will play a midi version of the score when clicked. If you change the abc notation in the edit area the score shown will instantly adjust, so you have a constantly updated preview.

Once satisfied, click the 'Save' button, and the tune gets saved on a new page in the group. The tune's title is used to create the page name. The tune will show up in the index on the group HomePage.

When going to a tune page to browse, the abcjs javascript will show the score and a player to play a midi version of it, as well as the abc notation. An edit link is provided (via the GroupHeader) to edit the abc notation. Clicking this will open the notation in an edit area, and again you will get an instant preview of score and midi.

Each tune is saved on a separate page as abc notation. The score image and midi version is not stored, not even temporarily. Each tune page holds the tune abc in an anchored section #abc to #abcend. This can be accessed as a PTV named {$:abc}. The abc fields like T:, M:, R:, K: etc can also be accessed as PTVs named {$:T}, {$:M}, {$:R}, {$:K} etc. The original author/contributor's name is stored as PTV and can be accessed by {$:author}. This may be useful in special pagelists and searches.

Adding more Tunebook groups

Wiki page groups can be created as tunebooks: Copy the contents of Tunebook/HomePage Tunebook/NewTune and Tunebook/GroupHeader to pages with same name in each the additional tunebook group. Add the group name to config as an item of $AbcTunebooks array, like for instance for a group named 'ScottishTunes':

$AbcTunebooks[] = 'ScottishTunes';

Importing abc tune collections

You can import raw text abc tune collections using the form on the ImportAbc page. Paste the raw text into the edit window, add a title for the page, and save it. The tunes will be re-indexed, and anchors added surrounding each tune. These make it possible to later open individual tunes for editing and instant abcjs preview. Text between tunes will be preserved.

You can also copy and paste the raw text into a wiki page using the standard edit window. The raw text will not be changed, but you cannot edit individual tunes.

If the page is in a tunebook group, it will display the tunes. If there are more than twenty tunes you'll see a list of links you can click to see the notation. If the collection gets pasted in a page which is not part of a tunebook group, add the directive (:abcjs:) to the page in order to get tunes displayed as score and midi.

Printing tunes

The rendering is pretty good for printing. The print display is set up so that only the score will get printed, and not the abc text or links in the page. If the skin is smart enough to suppress sidebar and site header the print output is good enough for use in your paper tune collections.

Customisations

The forms and templates used by Fox and FoxEdit are located in Site.FoxAbcTemplates. The pagelist template for the index listing is stored on the tunebook HomePage. Edit the templates if you wish to add more custom fields to be stored alongside the abc notation, or want to modify the form layout etc.

Notes

Care has been taken to only load the abcjs javascript files when necessary (for the right page and action).

The abcjs editor and plugin script could be used independently from using Fox or FoxEdit. In fact browsing a page with an abc tune in it does just that. The abctunebook.php script defines a markup for

[[#abc]] ..... [[#abcend]]

which loads the abcjs plugin script, and puts the abc notation enclosed in it into a HTML 'pre' section, and avoiding PmWiki rendering of the notation.

To get the abcjs editor script to instantly show changes the abc notation needs to be in a textarea of id "abc", and empty divs need to be in the page with id's "midi", "warning", "music" and "canvas", which get filled with content by the javascript.

Release notes

  • 2016-01-08: updated markup definitions for PHP 5.5 compatibility.
  • 2010-06-02: updated abcjs_base-min.js script, which fixes timing error when midi playing triplets.
  • 2010-05-25: added import of abc tune collections. Added edit of tunes in imported collection. Modified pages Site/FoxAbcTemplates, Tunebook/HomePage. Added Tunebook/ImportAbc.
  • 2010-05-24: code rewrite. repackaged abcjs. Added $AbcTunebooks array to set wiki groups as tunebooks. Added $Abcjs array for abcjs options. Added speedform to change default speeds. Added rhythm default speeds for various ITM rythms. Added markup to display raw abc tune collections pasted into a wiki page, i.e. multiple tunes can be shown without extra markup.
  • 2010-05-16: initial release.

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

Comments

See discussion at AbcTunebook-Talk

User notes : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.