Stacks4Stacks

PlayLister can be setup using one of three methods. You can construct your playlist within RapidWeaver and manually link to each MP3 file you want to include. Alternatively you can give PlayLister the link to a folder of audio files or a CSV file on your web server; and it will automatically generate the playlist for you. These two latter methods are perfect in instances where you or a client want to add or remove audio files remotely outside of RapidWeaver; without the need to constantly republish your website each time.

A common flaw with many audio addons available for RapidWeaver (and on the wider internet) is they tend to all look the same. Unlike preset 'skins' (which can drastically limit the creativity options you have for building bespoke audio players), the free-form style and colour settings we provide in PlayLister grant you unmatched ability to precisely customise PlayLister stacks to look like an integral part of your website. Plus you can toggle many interface elements on and off as they're needed, to build the perfect audio playlist solution for your website.

PlayLister has many potential uses. There is no limit on the number of MP3 files you can add to this stack and we impose no cap on the length of your individual audio files either. PlayLister would be fantastic to use for presenting samples of recorded music, narrations, religious sermons, podcasts and educational resources. Support for additional info added to each track facilitates the need to provide longer descriptions about each track, links and purchase buttons.

Example

This is a working example of the PlayLister stack. This example is using the default style and controller settings. We're just using some national anthem audio files and simple photographs for the album art work.

Setup

Audio files need to be encoded and saved in MP3 format. You can use the free Handbrake or Miro Converter apps to convert and prepare your audio files ready for use on the internet. MP3 is the most widely supported and compatible audio format; so therefore that is the one we use in this stack. PlayLister is capable of sourcing your audio files from four different locations. You choose the preferred location from the Setup Mode drop-down list of options, in the stack settings. The four setup modes available to you are as follows:

Stacks (default)
Click the blue '+' button shown in Stacks edit mode, to add and configure each audio track in the playlist. You can link to audio files stored in any public location; including RapidWeaver resources or audio files stored on your web server or a CDN (content delivery network) like Amazon S3. You configure the link, album, artist and cover artwork for each audio file, in the stack settings. Audio files of less-than 5MB should be safe to add as RapidWeaver resources - anything larger will probably benefit from being uploaded separately.

Podcast
You can link to an podcast (also sometimes referred to as a netcast) XML file. PlayLister will read the contents of the file and extract the MP3 links, titles, dates and other data to construct your playlist with. Configuration of this audio source requires the link to your XML file, the name of the podcast and optional artwork. The extension of the webpage requires changing to .php in the RapidWeaver Page Inspector. Please login to your web server via FTP to manually delete any older pages at the same location, that may have been published with other extensions. As new podcast episodes are published, these are automatically added to the PlayLister stack - there is no requirement to republish the website from RapidWeaver each time. The benefit fo this configuration is that it allows any website visitors to access your audio podcast content, without needing software like iTunes, Juice or gPodder.

Simple warehouse
In this instance you just give PlayLister the link to your directory (folder) of MP3 files, on the same domain where your website is published. All the MP3 files found in that directory will be converted into your playlist. When a playlist is generated, all audio files share the same album name, artist name and cover art; which can be optionally setup in the stack (if you wish to display this content). We generate the track titles from the audio file names, so for example a file found which is named 04-a-walk-in-the-park.mp3 will get shown in PlayLister as A Walk In The Park (we automatically strip numbers, hyphens, dashes and file extensions from the name). If new MP3 files are added to the directory, these will show in your playlist instantly, without any need to reconfigure or publish your website. So the simple warehouse is a sensible setup to use for instances like podcasts or sermons published on a regular basis.

Advanced warehouse
The advanced warehouse setup builds upon the simple warehouse. However a key difference is that instead of linking to a directory of MP3 files on your web server, you instead link to a single CSV (comma separated value) file. This CSV file contains more additional information about each MP3 file. Each row of the CSV file is presented in the following format:

Name,Album,Artist,MP3 Link,Cover Link,Additional Info

This CSV file gives PlayLister some more detailed information to construct your playlist with. In particular, you can link to MP3 files in different locations and specify unique titles, albums, artists, cover art and additional information (like purchase links) for each track. The data must be presented in this exact order. If surplus, the additional information can be left blank and disabled in the stack settings, in line with normal CSV protocols. If no track artwork is required, link to a bank image file and disable track artwork in the stack settings. This is an example of a complete CSV data file that PlayLister can use to construct a playlist with:

Name, Album,Artist,MP3 Link,Cover Link,Additional Info
Track One Name,Album Name,Artist Name,http://example.com/Summer-Skies.mp3,http://example.com/summer-skies.jpg,"Additional info, goes here"
Track Two Name,Album Name,Artist Name,http://example.com/Winter-Sun.mp3,http://example.com/winter-sun.jpg,"Additional info, goes here"
Track Three Name,Album Name,Artist Name,http://example.com/Country-Walk.mp3,http://example.com/country-walk.jpg,"Additional info, goes here"
Track Four Name,Album Name,Artist Name,http://example.com/Whispering-Wind.mp3,http://example.com/whispering-wind.jpg,"Additional info, goes here"
Track Five Name,Album Name,Artist Name,http://example.com/Dawn-Till-Dusk.mp3,http://example.com/dawn-till-dusk.jpg,"Additional info, goes here"

CSV files can be easily configured and managed in spreadsheet software like Excel, OpenOffice, LibreOffice or Numbers; or in any code editor. The advanced warehouse setup would be best to use if you are receiving MP3 files from multiple contributors, and you wish to maintain your playlist remotely, outside of RapidWeaver. If the .csv file is updated, these changes take immediate effect in PlayLister, without requiring a republish.

If providing additional information that contains commas, HTML code or other special characters, wrap the content within double quotes and avoid the use of double quotes within your content. So in the example of HTML code with attributes, you'd simply replace the double quotes with single quotes. This allows us to continue to parse your markup and convert it safely into HTML.

Important Both the simple and advanced warehousing setup modes depend on PHP code; which is special code that runs on your web server to process MP3 files and construct playlists. You must go into the RapidWeaver Page Inspector and change the page extension (of any pages hosting PlayLister) from .html to .php in the settings. Then you will need to publish your website to a web server which has a standard installation of PHP 7.1 or greater installed. Please note that with warehousing enabled, you will not be able to preview or test Playlister in RapidWeaver, because RapidWeaver lacks PHP support. If including HTML markup in the Additional Info cells, convert double quotes to single quotes.

Compatibility

The volume control does not take effect on some iOS and Android devices (these devices have physical volume controls on the device itself or on the audio output, like ear buds). Additionally these devices don't officially support autoplay, so multiple PlayLister items will not play sequentially (one after another). iOS and Android doesn't want to support autoplay audio or video, simply because of the high cost of data transfer over cellular networks. The same applies to just about any native HTML5 audio or video players. Android and iOS users will instead have to tap specific tracks they want to listen to.

Download button

This creates another link to the MP3 file, with a special HTML5 download attribute applied. In modern web browsers that support this attribute clicking the button will force the MP3 file to download onto a computer, instead of playing in the browser window. Please note that this will only work properly for MP3 files being hosted on the same domain that your PlayLister stack is on. Direct downloads do not work for MP3 files stored on Amazon S3 or at another location.

Can I use PlayLister to play a single track?

Yes, you can setup PlayLister stack to just play a single audio file. For best results, you'll want to edit the PlayLister settings slightly to turn-off skip buttons and toggle the display of the playlist to hidden. PlayLister is a pretty intelligent audio player, and unlike some other audio addons, it will not complain or fail to work if you only provide a single track.

Cover artwork

These are just simple square images displayed against each playing track; just like the artwork you might see displayed in software like iTunes or Amazon Music. You can use different images for each track or alternatively all tracks can share the same image. The size of the artwork images is configured in the stack settings. If you want to sharpen the display of images in retina screens, simply ensure the image file you provide is twice the size of the image size you specify in the settings (so if for example you have the artwork set to 300px, provide an image 600px square). Artwork should be saved at 72 dpi in either JPG, PNG or GIF format. Optional rounded corners can be applied to the artwork or you can toggle-off the display of artwork images, using settings in PlayLister. As always, the smaller the image file size, the quicker they will load.

Custom buttons

Any link added through additional info that has a class of playlisterButton will be converted to a button (matching the same style of existing buttons) and appended to the top right of the player. This feature would be especially useful in instances where you wish to display purchase buttons, links to other webpages or links to supplementary transcripts / song lyrics. These buttons can have additional attributes applied to them, like custom classes or data- attributes for triggering lightboxes etc. This is an example of the markup to use in your additional info, for a button that will link to a page on iTunes:

<a href='https://itunes.apple.com/gb/album/best-bond...-james-bond-deluxe/id1046148480' class='playlisterButton'><i class='fa fa-apple'></i></a>

You can also link to another website:

<a href='http://example.com' class='playlisterButton'><i class='fa fa-shopping-cart'></i></a>

This code basically comprises of a normal HTML anchor tag. Instead of putting text between the opening and closing tags, you can just insert the markup for a desired Font Awesome icon. Please be careful to ensure all double quote characters in your HTML markup are converted to single quote characters instead. This is because we pass additional information and HTML markup to PlayLister via data- attributes, and use of double quotes would otherwise corrupt the generated markup.

Hosting audio on AWS (Amazon Web Services)

The example audio and artwork in our PlayLister stack above are all hosted using the AWS service. 1 Signup for a free AWS account. You need to provide your contact and credit card details. Amazon automatically telephones you to verify your details and enter a secret PIN number. Accounts are typically setup within a matter of minutes.

1. Login to your AWS account by clicking the Launch Management Console button
2. In the Storage & Content Delivery section, click on the S3 (Scalable Storage In The Cloud) option
3. Create a new bucket. Think of a bucket as a folder stored on a web server. Give the bucket a name and choose a geographic region where you would like it stored. Click the Create button when done.
4. Click on the newly created bucket and then click the blue Upload button. Select the files or folders to upload (multiples are permitted), containing your media. Click the Start Upload button.
5. Once the files have uploaded, select them in the file viewer. Right click the files, and in the menu click Make Public.
6. From the services menu at the top of the AWS page, click on the CloudFront option. Create a new distribution, using the Create Distribution button.
7. When creating a new distribution choose the Web option and click Get Started.
8. In the Origin Domain Name box, select the new bucket you recently created.
9. All other settings can be left as they are, nothing else needs to be changed for the distribution. Click the Create Distribution button when done. It may take several minutes for the distribution to 'go live' on all the AWS servers world-wide.

The links to your audio or video files are shown in the Properties panel, when you select a file in the bucket file manager.

Services like AWS may appear tedious to setup. But it should be stressed that the instructions above are for a complete signup and setup of a new AWS account, buckets and distribution. Ordinarily you would just upload your files directly into an existing bucket, set their permissions and content type, and they will be ready for use. Incidentally you can use regular FTP software like Cyberduck to access and manage your S3 web disk really easily.