utilitees

Listening to ... Documentation

• Requirements
• Installation of the module
• Configuration of the module
  • The “Settings” Tab
  • The “Manual Data entry” Tab
• Now Playing Plugin (by B. Fuller)
• Winamp Now Playing Plugin (by A.+L. Nevala)
• Template Tags
  • Display the latest track
  • Display history
  • Display arbitrary tracks
  • Variables

Requirements

• If you want to automatically update the song data on the website you either need an account at last.fm or the Now Playing plug-in by Antti & Lauri Nevala (website currently down) for Winamp (freeware) or the Now Playing plug-in by Brandon Fuller (shareware) for Winamp, iTunes for OS X, iTunes for Windows & Windows Media Player
• If you want to use any of the Amazon related features (show cover images, auto-create affiliate links) your server must allow HTTP-requests to external resources. The module supports file_get_contents(), CURL as well fsockopen() as means to connect to AWS. You’ll also need an AWS Access Key ID which you will get if you register at AWS.
• As of August 15, 2009 (and Listening to… version 1.2) requests to the Amazon API must be authenticated. For that you also need the Secret Access Key which can be obtained on the same page you get the Access Key ID. Also your server must run PHP 5 >= 5.1.2, PECL hash >= 1.1.

Installation of the module

1. Copy the folder named listening_to into the modules folder inside your system-directory.
2. Copy the file named lang.listening_to.php into the /language/english folder inside your system-directory.
3. Navigate to Modules in your EE CP and find the module named Listening to .... Click Install.
4. Now you have access to the Settings of your newly installed module.

Configuration of the module

Goto CP Home ›  Modules ›  Listening to ... to configure the module.

The “Settings” Tab

• Plug-in used: Which Player / Plugin you want to use to update the songdata for your webpage,
• Your last.fm user name (last.fm): The username of your last.fm account.
• Cache duration in minutes (last.fm): If you set a value here, last.fm will only be queried every x minutes for the updated tracklist. You should set this in order to speed up your site and be nice to the last.fm webservice.
• Password (Winamp): If anyone figures out the correct Action ID of your Listening to module, in theory he would be able to post his own songdata to it. To prevent this in the first place a password must be set here.
• Extra data (Winamp): This data is needed in the connection settings of the Now Playing Winamp Plug-in.
• Path to the uploaded XML-file (iTunes): The Now Playing Plug-in must be configured to upload its XML-file to your webspace. Enter the full path to the file’s location including the filename.
• Amazon Webservices Access Key ID: If you want the module to show images of the album covers and/or create Amazon affiliate links an Amazon webservice will be queried. In order to do so you need an AWS Access Key ID. You will get one if you register at AWS. It’s free of charge. Once you’ve signed up there you’ll find the key under “Your Account”  › “Access Identifiers”.
• Amazon Webservices Secret Access Key: Additionally you need the 40-digit Secret Access Key you get on the same page. Note: All the options below this point require that you have an AWS Access Key ID and Secret Access Key. If you don’t have one, you don’t need them.
• Connection method: The module offers several ways to internally connect to the AWS in case one of them is disabled in your host’s configuration. If you see a green success message there, the selected option works on your system. If not, you can try another.
• Cache duration in minutes: The results of your queries to AWS are cached by default. This keeps your site fast and is nice to AWS. Values of several hundred minutes are totally fine here.
• Amazon Locale: The Amazon locale you want to use. If you intend to create affiliate links, choose the locale you are registered with. If not, just choose the one that most likely has all the albums you usually listen to.
• Amazon Associates Tracking ID: If you take part in the Amazon affiliate program and want the module to create affiliate links for you, enter your Tracking ID here. Note: The options below this point require that you have an Amazon Associates Tracking ID. If you don’t have one, you don’t need them.
• Link album-name: If set to ‘yes’ the Album name (Variable: {album}) will automatically be output with a valid affiliate link using your Tracking ID.
• Link album cover: If set to ‘yes’ the Album cover images (Variables: {image_small}, {image_medium}, {image_large}) will automatically be output with a valid affiliate link using your Tracking ID.

The “Manual data entry” tab

In case you don’t use the Winamp-plug-in at all or just want to manually enter some songs in between you can use this entry form to manually enter up to 5 songs.

The form for the featured track has an additionla button labelled “Move down”. Pressing this will move all songs down by one position, freeing up the featured track and dropping the last.

Now Playing Plugin (by B. Fuller)

Download the latest version for your player / OS and follow the installation and configuration instructions:

• iTunes OS X
• iTunes Windows
• Winamp
• Windows Mediaplayer

Required settings:
XML: Specifiy an output file.
XML: Check CDATA
Upload: Protocol, Hostname, Username, Password, Filename

The rest is up to you.

Now Playing Winamp Plugin

The installation is pretty straightforward.
Run the NPSetup_2_1_2.exe. After you agreed to the license you are asked for the Winamp-folder on your system. If the folder is correct, you may hit “Install”. That’s it.

Configuration of the Winamp Plugin
After the plugin has been installed, launch Winamp and press Ctrl+P to open the Preferences. You’ll find the Now playing plugin under “Plug-ins” -> “General Purpose”. Select it and click “Configure selected plug-in”.

You may want to take a look at the “Options” first. Normally you can leave them at default settings.
You can safely ignore the “Web-services”-settings. In fact you should. Entering an Access Key ID there will probably lead to malfunctions.
Adjust “Proxy settings” if needed.

Now select “Connections” and click “New”.

Select “HTTP Post” as connection type and click “Accept”.

• Name: You may choose any name for your new connection.
• Url: This is the URL to the main index.php of your ExpressionEngine site.
• Extra data: Copy and paste the contents of the Extra data field from the bottom of the Module Settings page.
  
• Song history: If you plan to display songs you listened to before the actual song set this value to at least the number of songs you want to display.
• Update frequency: Usually set to 1 to update on every new song.
  
• Accepted file types: I use it only for mp3. Other formats untested.

After you’re done, click “Accept” and finish the configuration by hitting “Apply”.

Now you are ready to go. Fill up your playlist and start listenting to some music

Template Tags

There are two tags to display your song data in a template. One is exclusively used to display the last track you listened to to give you the opportunity to format it differently than the rest. The other loops over any songs you listened to before.

Display the latest track

This tag fetches the data of the last played track. It has no parameters.
Available variables are listed below.

Display history

This tag can be used to display data of all songs you listened to before the latest track. The maximum number of tracks it can display is determined by the Song history setting in the Now Playing plug-in’s connection configuration.

Parameters:

Limits the number of tracks shown to the specified value. Defaults to 3.

Available variables are listed below.

Display arbitrary tracks

This tag can be used to display data of anything you pass to it through the following three parameters:

Parameters:

Mandatory. Name of an artist / band / musician.

Optional. Name of a song.

Optional. Name of an album.

The variables {artist}, {title} and {album} will be available inside this tag-pair if you passed them through the respective parameters. Other than that you have access to the variables from the list below which show Amazon as their source.

Variables

Both tags share the same set of available variables.

Name of the album.
Source: ID3-tag.
If “Link album name” is set to “yes” in the module’s configuration the text will be linked using your Tracking ID.

Name of the artist.
Source: ID3-tag.

Title of the track.
Source: ID3-tag.

Track’s position on the album.
Source: ID3-tag. Empty on last.fm.

Release year.
Source: ID3-tag. Empty on last.fm.

Music genre.
Source: ID3-tag. Empty on last.fm.

Comment.
Source: ID3-tag.
When using last.fm as source the comment-variable will hold the URL to the track on last.fm.

Bitrate of the file.
Source: ID3-tag. Empty on last.fm.

Length of the track. 
Source: ID3-tag. Empty on last.fm.

Composer of the song. 
Source: ID3-tag. Empty on last.fm.

The time you played this song.
Source: Winamp / Now Playing plug-in / last.fm

Size of the file.
Source: Winamp / Now Playing plug-in / Empty on last.fm.

Cover image HTML code. Image size: 75 x 75 pixels.
Source: Amazon
If “Link album cover” is set to “yes” in the module’s configuration the image will be linked using your Tracking ID.

Cover image HTML code. Image size: 160 x 160 pixels.
Source: Amazon
If “Link album cover” is set to “yes” in the module’s configuration the image will be linked using your Tracking ID.

Cover image HTML code. Image size: 300 x 300 pixels.
Source: Amazon
If “Link album cover” is set to “yes” in the module’s configuration the image will be linked using your Tracking ID.

Amazon Standard Identification Number.
Source: Amazon

Amazon Associates Tracking ID.
Source: Module’s configuration settings

Link to the iTunes Store
Source: Now Playing for iTunes (available if you enabled ‘Lookup track information’ under the ‘Apple’ tab)

Whether all variables are filled with values or not depends on the source. The data that comes from ID3-Tags is obviously only available if the MP3-file is tagged respectively. The three image-variables and the ASIN-Code are only filled if a related product has been found at Amazon.

You can use simple conditionals to display something only if the variable has been set.

Example:

will output nothing unless the ID3-Tag YEAR was filled.

Questions / bug reports

For general comments, brickbats & bouquets please use the form over here.

Name:

Email:

URL:

	Remember my personal information
	Notify me of follow-up comments?

Page 1 of 3 pages  1 2 3 >

User Talk