Ecoute is an awesome application for your Mac that allows you to play your music with a stunning UI and without all the weight of iTunes. It reads music directly from iTunes Music Library without having to launch it.
One of the most cool features of Ecoute is the super cool desktop controller. This desktop controller is fully customizable via HTML, CSS & Javascript and it's what we're going to talk about in this tutorial.
1 - Theme Bundles2 - Info.plist in detail
3 - Javascript Functions4 - WebKit is awesome
Ecoute is using folders with the .ecoute extension to identify theme files. When folder are named like this : "MyAwesomeTheme.ecoute" they will have a specific icon and a double click on them will install the theme in Ecoute.
Ecoute theme bundles must contain these files : (Red files are mandatory in order to have a working theme)
Info.plist
This file must contain some keys in order to let Ecoute identify the theme and correctly render it.
nameyouwant.html
This file is the main html file of your theme, it name is set into the Info.plist so you can name it with all the names you want.
preview.png
This preview image will be used in the Ecoute theme browser to show what the theme is looking like. The name of this file can be as for the html whatever you want but don't forget to set the matching name in the Info.plist
minipreview.png
This file will be used by the theme browser to show a little preview of your theme.
If you don't set this file in Info.plist the normal preview will be used to render a little image in the theme browser.
The Info.plist is a standard Apple Property List file that can be edited with Apple's Property List Editor wich is shipped with Apple Developer tools contained in your Mac OS X DVD.
Here's an example of a Info.plist file for an Ecoute Theme :
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>MainFile</key> <string>skin.html</string> <key>WindowWidth</key> <integer>390</integer> <key>WindowHeight</key> <integer>150</integer> <key>ThemeName</key> <string>ThemeName</string> <key>ThemeIdentifier</key> <string>me.fantattitude.ThemeName</string> <key>ThemeArtist</key> <string>Vivien Leroy</string> <key>ThemePreviewImage</key> <string>preview.png</string> <key>ThemeMiniPreviewImage</key> <string>minipreview.png</string> <key>ProgressBar</key> <true/> </dict> </plist>
Here are the key that you might put in your theme Info.plist : (Red are mandatory)
MainFile
This entry must be associated to a <string>. It is the name of the main file of the theme, the html file.
WindowWidth & ECWindowHeight
These entries are respectively the Width and the height of the theme, the unit is the pixel and the entry associated is of <integer> type.
ArtworkWidth & ArtworkHeight
These entries are respectively the Width and the height of the artwork that the theme will display, the unit is the pixel and the entry associated is of <integer> type.
It is not mandatory but if you want to have an artwork as smooth as possible use them because the default picture that will be communicated to your theme will be a 175x175 one.
ThemeName
A <string> entry to set the name of the theme.
ThemeIdentifier
A <string> entry to set the identifier of your theme, this identifier will allow Ecoute to identify the theme and like this you can have two theme with the same name if they have different Identifier.
The naming convention for identifier is to use your domain name reversed associated with the theme name.
Example : My website is http://fantattitude.me so the Identifier for the Ecoute theme I named "Matinal" is : me.fantattitude.Matinal
Obviously, if you don't own a domain you can invent a name like : com.vivienleroy.MyThemeName
ThemeArtist
Another <string> entry which is not mandatory. If it's not set no artist will be show on the Theme Browser.
ThemePreviewImage
<string> in which you have to put the name of the preview file, such as preview.png
ThemeMiniPreviewImage
<string> in which you have to put the name of the little preview file, such as minipreview.png .
If the key has not been set the Theme browser will create a little preview with the normal preview image.
ProgressBar
Boolean value. Optional but needed if your theme has a progress indicator. If "ProgressBar" is set to <true/>, Ecoute will automatically call JS function "playState()" in which you will be able to call "Ecoute.playerPosition" to get the current time elapsed from the beginning of the song.
Ecoute provides javascript methods that will allow you to control Ecoute & get informations. They are all bundled in the Ecoute object.
Here is all the stuff :
(void) Ecoute.play()
This method as it names says, launch the play in Ecoute.
(void) Ecoute.pause()
This method as it names says, pause the play in Ecoute.
(void) Ecoute.playPause()
This method as it names says, play or pause the play in Ecoute. This is better in order to make a Play/Pause button.
(void) Ecoute.stop()
This method as it names says, stop the play in Ecoute.
(void) Ecoute.previousTrack()
This method is the same than clicking on the previous button of the Ecoute interface. So if the song has been played for more than 3 seconds, it will return to the beginning of it instead of go to the previous song.
(void) Ecoute.nextTrack()
This method is the same than clicking on the next button of the Ecoute interface.
(integer) Ecoute.shuffle()
This method returns an integer which is 0 if shuffle is of or 1 if shuffle is on. Useful if you want to check the shuffle status of Ecoute (Especially in the Ecoute.playState() function).
(void) Ecoute.setShuffle(integer aNumber)
This method sets the shuffle state in Ecoute. aNumber can be 0 or 1, 0 means shuffle off and 1 means shuffle on.
(integer) Ecoute.repeat()
This method returns an integer which is 0 if repeat is of, 1 if repeat is on for all tracks or 2 if repeat is on for single track. Useful if you want to check the repeat status of Ecoute (Especially in the ECStatusFunction).
(void) Ecoute.setRepeat(integer aNumber)
This method sets the repeat state in Ecoute. aNumber can be 0, 1 or 2. 0 means repeat off, 1 means repeat on and 2 means repeat single track on.
(integer) Ecoute.rating()
This method returns the rating of the currently played song. The rating is represented by a number from 0 to 100, each stars has a value of 20 and half stars have a value of 10.
(string) Ecoute.ratingStars()
This method returns the rating of the currently played song as a String like this : ★★★☆☆. It's more convenient to put the rating in your theme.
(void) Ecoute.setRating(integer aNumber)
This method sets the rating of the currently played song. The rating is represented by aNumber, integer from 0 to 100, each stars has a value of 20 and half stars have a value of 10.
(integer) Ecoute.volume()
This method returns an integer from 0 to 100 which is the volume of Ecoute.
(integer) Ecoute.setVolume(integer aNumber)
This method sets the volume of Ecoute with aNumber, an integer from 0 to 100.
(integer) Ecoute.playState()
This method returns an integer indicating the play state of Ecoute.
0 is "stopped", 1 is "playing" and 2 is "paused". Use this in the status function to update the Play/pause button. Please notice that Ecoute.playState() is also called when the user click on play/pause from Ecoute.app
(integer) Ecoute.playerPosition()
This method returns an integer value which is the number of second since the beginning of the song. Useful for progress indicators.
(void) Ecoute.setPlayerPosition(integer aNumber)
This methods sets the player position to the number of second since the beginning of the song. Can be used to make a clickable progress indicator in your theme.
(Wrapper) Ecoute.trackInfos()
This method returns a Wrapper containing all the informations about the song currently played by Ecoute. If you want to get a variable from the wrapper, just use the following code :
function trackInfos(track)
{
var name = track.property('title');
}
You can get multiple informations about the track. Here's the parameters available for track.property:
- length : return the length of the track (Integer). Could be used if your theme has a progress bar.
- title : returns the title of the track (String)
- album : returns the album of the track (String)
- artist : returns the artist of the album (String)
- year : returns the year of the album (Integer) -- Available from v1.0.9
- trackNumber : returns the current track number of the album (Integer) -- Available from v1.0.9
- trackCount : returns the tracks count for the album (Integer) -- Available from v1.0.9
- albumArtist : returns the album artist for the album (String) -- Available from v1.0.9
- genre : returns the genre of the track (String) -- Available from v1.0.9
- composer : returns the current track composer (String) -- Available from v1.0.9
- discNumber : returns the disc number of the current track (for multiple CDs for the album) (Integer) -- Available from v1.0.9
- discCount : returns the total number of disc for the album (Integer) -- Available from v1.0.9
- radio : returns an Integer (0 or 1) that lets you know if the current track playing is a radio or not (radio = 1; local track = 0;). This can be useful if your theme has a progress bar because you could be able to hide the progress bar if the current track is a radio -- Available from v1.1
(string) Ecoute.artwork(url)
This method returns a string URL to the artwork of the song currently played, using the width and height in Info.plist.
(array) Ecoute.currentFrame()
This method returns the current frame of the window in an array :
[x-offset, y-offset, width, height]
X and Y offsets are the distances in pixel from the bottom left of the screen.
(void) Ecoute.setFrame(float x-offset, float y-offset, integer width, integer height)
This method allows you to change the frame position and size containing the theme. With it you can implement a window dragging system.
As Ecoute is using the default Mac Os X web html rendering, all your themes will be powered by the powerful WebKit engine.
It means that you'll be able to use all the super cool features included in it. Like CSS Animations, reflections, 3D rendering etc…
Be creative because WebKit gives you NO limits.
For more information about what is available on WebKit
don't hesitate to go here : WebKit official website
Here is an example theme that you can use to build your own theme with. This will help you to get your theme done quickly.