Track Dataset

 

When a request is made to launch a track, Wimpy examines the request and looks for specific "fields" beyond just the media file URL. If additional info is available, Wimpy will update the player to present the info accordingly.

In order to include additional information we use a Track Dataset, which is a collection of "value pairs", said another way: each kind of data is labeled.

A playlist is a collection of Track Datasets. Each playlist format (XML, JSON, and Javascript Object) simply structures the data differently.

For example, below shows how each language represents file, title and image data:

Javascript Object

{
	file  : "foo.mp3",
	title : "My Track",
	image : "foo.jpg"
}					

JSON

{"file":"foo.mp3","title":"My Track","image":"foo.jpg"}

XML

<item>
    <file>foo.mp3</file>
<title>My Track</title>
<image>foo.jpg</image>
<item>

 

Flexible

The minimum requirement for a Track Dataset is the "file" field.

# Javascript 
{ file : "foo.mp3" }

# JSON
{"file":"foo.mp3"}

# XML
<item><file>foo.mp3</file></item>

Any other information provided within the dataset is optional. You may include additional custom fields that are not part of wimpy's "recognized" or "special" fields.

For example, you may wish to include a field named "whatever" as:

{
	file  : "foo.mp3",
	title : "My Track",
	image : "foo.jpg"
  whatever : "something"
}					

Custom field data will remain accessible when using any API method to retreive track or playlist info.

Each "item" does not have to have an identical set of fields. For example, one item may only include the "file" field, whereas another may include "file" and "title".

Fields Wimpy Recognizes

Below is a list of the fields Wimpy recognizes.

Field Description
file

A URL to a playlist or media file.

File URLs should only contain alpha-numeric characters. Using anything other than alpha-numeric characters poses potential problems that may prevent files from loading.

kind

Used to specify the type of media file or playlist.

This field is optional, but speeds up Wimpy's ability to determine kinds of files. When this field doesn't exist, Wimpy determines the kind of file based on the file's "extension".

If you're using a backend system that uses weird or complicated URLs to files Wimpy may not be able to parse the URL correctly. setting "kind" appropriately will cause wimpy to rely on the value you've set.

The "kind" field can be any of the following values:

Audio Kinds

  • mp3
  • wav
  • aac
  • m4a
  • mpa
  • oga
  • ogg

Video Kinds

  • m4v
  • m4p
  • mp4
  • webm
  • ogx
  • ogv

Playlist Kinds

  • xml
  • rss
  • txt
  • json
  • m3u
  • pls
image URL to an image file to display as cover art. Can be a URL to a remote file, or a "Data URI".
date An integer representing Epoch time (seconds since 1/1/1970), which is a long integer like 1798274622.
link

The playlist will display a special "info" icon if this field contains a value.

By default, when clicked the Wimpy will open a new window with the URL defined for this field. You can define the window name using the "infoWindow" Player Option (or global option). You can also use a custom handler to deal with the link -- see "setLinkHandler" for more info.

linktip

Sets the text to display when hovering over the link icon.
- Default values can also be configured using the linkTip player option.
- linktip defined in the playlist over-rides the default value

downloadable

The playlist will display a special "download" icon if this field is set to 1 (true). When set to 0 (false) the icon isn't displayed and over-rides the global enable downloads option.

By default, when clicked the Wimpy will open a new window with the URL defined for this field. You can define the window name using the "infoWindow" Player Option (or global option). You can also use a custom handler to deal with the link -- see "setLinkHandler" for more info.

downloadtip

Sets the text to display when hovering over the link icon.
- Default values can also be configured using the downloadTip player option.
- downloadtip defined in the playlist over-rides the default value

title du
artist du
album du
genre du
index The track number. For example, the order that the tracks appear on a traditional Compact Disc. Used during sorting.

Special Fields

The following fields are inserted into each playlist item by Wimpy. Wimpy creates and/or overwrites these fields. These fields will be incorporated into each item, so if you use the getPlaylist API method, you will notice the presence of these fields.

i

The array indice. A direct relationship to the order in which the item is listed. For example when a playlist is sorted, or shuffled, the value for "i" will refer to the items position in the list as defined by the sorting mechanism -- not by the original order, but by how the item is listed in the actual view.

The values start at zero, because javascript arrays start counting from zero. In other words the first item is "0", the second is "1" and so on.

If the playlist has been removed, but a track is still playing, "i" will be set to -1 to indecate that there isn't an actual index for this track.

amPlaylist Used internally by Wimpy to quickly determine what kind of entity the item is -- either a playable media file or a playlist item.