New Sheet Music Library: The Story

After nearly two years of planning, false starts, and development, I finally launched a new sheet music library. In this post, I’ll discuss the development and implementation process, design decisions, and how I created this project in a way that the source code will be available for anyone to use for free.

History

I started posting my cello ensemble compositions and arrangements online in early 2012, when I first set up celloexpressions.com as the website for my high school cello quartet, Cello Expressions. When I transitioned the site to be the home for my projects in August of that year, I created a series of separate WordPress installs for my different sites, moving the original site to the music subdirectory and building a new system to display sheet music in a more structured way. Because I had spent the summer developing Euclid’s Muse, basing the code off of a horribly-written BuddyPress plugin, I thought that the best approach would be to create a custom database table, querying it directly. I didn’t have the time to build a posting or editing UI, so I decided I would just make edits directly in the database with PHPMyAdmin. That worked for a few months, and in November 2012, I redesigned the site’s theme (poorly). But I would last post a new piece in January 2013. It was clear that I needed an entirely different system, and that I would probably need to migrate all of my existing content (now 60 pieces) manually.

Cello Expressions Sheet Music Library, from January 2013 to December 2014.
Cello Expressions Sheet Music Library, from January 2013 to December 2014.

Goals

My primary goal for the sheet music library is to make free music, primarily for cello-oriented ensembles, widely available and accessible. I also want to get my works out there for people to play.

But my goals for making the sheet music library easy to use were much harder to accomplish with the old system. All pieces needed to have PDF downloads, preferably with the ability to have separate score and parts PDFs. I needed to display previews of the PDFs in a browser-agnostic way, rather than hoping that it would work to put a PDF in an iframe. Pieces needed to have a way to upload and display recordings, both via MP3s and via YouTube videos. Pieces needed to have fields for composers, difficulties, genres, and instrumentations, and values should cross-link between different pieces. And most importantly, I needed everything to be searchable, both internally and via search engines.

A Plugin

One of my first decisions was to build the sheet music library functionality in a plugin. That way I could use an existing WordPress theme and redesign much more easily. Over time, additional benefits became clear – others could use this plugin as well. The Boulder Cello Project will be using it, plus an add-on plugin, to power their internal members site, where they post sheet music for their meetups for members to practice in advance. The plugin will be released on WordPress.org once the initial implementation for the Cello Expressions Sheet Music Library is complete.

Custom Post Type & Taxonomies

It also became clear that I should create a sheet music custom post type, with custom taxonomies providing relationships between pieces. Composers, instrumentations, difficulties, and genres are each custom taxonomies for the sheet_music post type. PDFs for the score and parts and audio file uploads would be stored as attachments, with the attachment post ids stored as post meta in sheet_music posts. YouTube videos are stored by their URLs as post meta as well.

PDFs to Images

The solution to displaying PDF previews in a reusable way ended up being surprisingly simple. By converting the first page of the score PDF to an image, the front-end and admin can display an image preview of the PDF pretty easily. Converting PDFs to images is actually pretty simple in most modern server environments with WordPress’ image editor.

Diving briefly into code, WP_Image_Editor’s ImageMagick implementation makes it incredibly easy to convert PDFs to Images:

/**
 * When a PDF is uploaded, generate a thumbnail image and save it in the attachment meta.
 */
add_filter( 'wp_generate_attachment_metadata', 'prefix_generate_pdf_thumbnail_metadata', 10, 2 );
function prefix_generate_pdf_thumbnail_metadata( $metadata, $attachment_id ) {
	$attachment = get_post( $attachment_id );
	if ( 'application/pdf' === get_post_mime_type( $attachment ) ) {
		// Create a png from the pdf.
		$file = get_attached_file( $attachment_id );
		$pdf = wp_get_image_editor( $file );
		if ( ! is_wp_error( $pdf ) ) { // Most likely cause for error is that ImageMagick is not available.
			$filename = $pdf->generate_filename( 'image', null, 'png' );
			$uploaded = $pdf->save( $filename, 'image/png' );
			if ( ! is_wp_error( $uploaded ) ) {
				$upload_dir = wp_upload_dir();
				update_post_meta( $attachment_id, 'pdf_thumbnail_url', $upload_dir['url'] . '/' . $uploaded['file'] );
			}
		}
	}
	return $metadata;
}

Unfortunately, not all servers have ImageMagick installed. I don’t have it installed locally, and when I went to test on the celloexpressions.com server (hosted by GoDaddy for historical reasons), it wasn’t there. I contacted support and they said I had to upgrade to a newer account, which would involve manually migrating everything (or they could do it for a fee). I’d been wanting to get off of that server for a while anyway, so I took to opportunity to move everything onto one of my existing Bluehost accounts, cleaning up some old stuff that was living on celloexpressions.com in the process. Once I switched the domain over to the new server, everything worked exactly how I had wanted.

Realizing how straightforward it is to create images from PDFs in PHP, and how much room for improvement WordPress has with regards to PDF uploads (both in terms of administration and presentation), I’m going to propose some improvements there for core once I finish this project.

Media & Embeds

In addition to digging into the intricacies of WordPress’ handling of PDFs, I spent some time working on my JavaScript skills to implement previews of uploaded audio and linked videos in the admin. Since I knew I’d be using the plugin at large scale, it was important that the admin UI was as functional and efficient as possible. Audio and video previewing was implemented based on the media wpviews in the main editor. While the result is somewhat hacky and buggy, most of the integration relies on core functions rather than extensive custom logic, and I rarely encountered the bugs in my workflows.

On the front-end, wp_audio|video_shortcode( array( ‘src’ => $url ) ); gives browser-compatible HTML5 audio and video via MediaElement.js. That also gives us a skinned player for YouTube videos that matches the audio player, can be customized with CSS, and seems to reduce the volume of ads. WordPress 4.2 will also add support for skinned Vimeo embeds, and the sheet music library plugin won’t require any changes to support Vimeo and YouTube equally.

In a future update, I plan to explore the possibilities with creating a “collection” of PDFs with the media library, similarly to galleries, audio playlists, and video playlists. If I’m successful with that, it could be used to offer separate files for each part of a piece, instead of requiring all of the parts to be in one PDF (which I manually merge the separate parts into before upload). That could also concievably provide an automated merged PDF file that’s created in PHP, if ImageMagick supports something like that.

Templates

While a custom post type with several custom fields and taxonomies would normally work best with custom theme templates, I wanted the sheet music library to be as theme-compatible as possible. So I implemented default templates for single and archive views by filtering the_content. It works pretty well on a lot of themes, and could look just fine on pretty much any theme with a little custom CSS. For more advanced implementations, custom templates and adding theme support for ‘sheet_music_library’ will do the trick. I also created a shortcode that outputs the table view that I use on the homepage.

Search, taxonomies, archives, etc. all work well with the content filtering. The sheet music post type also supports featured images, so using the theme’s templates ensures that images are still used as intended. In my case, I only use images on a few pieces, and they really stand out in search, taxonomies, and post navigation.

Themes & Design

The plan all along was to go with a WordPress.org theme for the initial roll-out, then come back and do a custom theme specifically for use with the sheet music library plugin. But after exploring tons of potential theme options (while testing the theme compatibility of the plugin), I ended up going with Twenty Fifteen. And I’m liking it so much that I may not even do a child theme (I currently have some custom CSS, but that’s it). While I’m not happy with every component of the theme, the biggest things that made it my choice are its strong, scalable typography and its sticky sidebar functionality. CelloExpressions.com has a global header that’s displayed on all sites in the network, and by having no header and a minimal sidebar for the theme, I was able to keep things simple while still providing means for navigating throughout the site. In fact, I ended up with no menu for the music library, leaving navigation and discovery to search and a widget for each custom taxonomy.

My biggest problems with Twenty Fifteen were lack of color contrast, and excessive whitespace/inefficient use of space in places. For a while I had planned to use Twenty Fourteen, since it provides so much space for navigation and is very space-efficient. But upon further investigation, the only part of the sheet music library requiring more horizontal space is the table view on the homepage, so I just dropped some margins there. The contrast issues were a quick fix with Twenty Fifteen’s custom color options, combined with the dark “global” Cello Expressions header.

I also designed a new logo for myself and Cello Expressions as part of this process. I started out on paper, from doodles that had been done while trying to stay awake during class. As I learn more about graphic design, I’m pleased with my final result, and it works great in vector format. Currently, I’m using it in the header and as the site icon. I’ll use it elsewhere as opportunities arise.

Cello Expressions Logo

Migration & New Content

Once the new plugin was finally complete and I’d settled on using Twenty Fifteen at least initially, I was ready to migrate the 60+ pieces from the old site to the new site and add all of the music from the past two years that never made it into the old system.

Because the old implementation was so bad, and most of the old fields wouldn’t translate cleanly to the new taxonomies for composers, instruments, difficulties, and genres, I had to manually migrate all of the content. This also gave me the opportunity to remove some pieces that weren’t up to my current standards.

I started by moving the entire contents of my old server to the new Bluehost server, renaming the /music/ directory to /music-archive/. Then, once I moved the nameservers, I created a new site in the celloexpressions.com multisite network, at /music/. After putting some text in the homepage and setting up my plugins, I started migrating content.

In the end it took nearly two weeks and countless hours, but I now have 104 pieces in my new sheet music library. About half were migrated from the old library, and the other half are newly-published. At a rough estimate, two-thirds have an audio or video recording, or both. They all have scores, terms in four taxonomies, and publication dates back-dated to when they were created. While it required a colossal effort that’s still not quite complete, this project was very much worth it. And the best part is that all of the work, from the software powering it to the music it contains, is free for anyone to use, in the spirit of open source.

One thought on “New Sheet Music Library: The Story

Leave a Reply

Your email address will not be published. Required fields are marked *