Player Options

 

Below are quick examples for how to define options with HTML 5 or Javascript.

HTML Player Instance Example

Player Instance options are prefixed with "data-".

<div data-wimpyplayer data-random data-media="track.mp3"></div>

 

Javascript Example

No prefix needed, just use the option name.

new wimpyPlayer({random:1, media:"track.mp3"});

 

NOTES
• Default values can be re-established as described in "Defining Global Options"
• Please review "Value Types" for important info regarding "type" (string, number, boolean)

Option Description Example Default Type

allowOthers

By default, wimpy turns off all other players and buttons (places them into a "pause" state) so only one button/player can possibly make a noise at one time.

This option allows other players to play at the same time.

0

1

boolean

autoAdvance

Automatically advance to the next track. Used to prevent a playlist from being mindlessly played, and consuming bandwidth.

0

1

boolean

autoPlay

Start to play as soon as possible.

On some devices this option may not work as expected because the device may require "human interaction" to start media playback.

1

0

boolean

coverArt

URL to image file. may be a JPG or PNG file. See "Cover Art" for more info on using cover art + the logic employed within Wimpy to display cover art.

"image.png"

null

string

coverArtFit

1 = fit (default)
Image will stretch or shrink to fit precisely within the boundaries of the coverart container.

2 = contain
Image will shrink or enlarge (but not stretch) to fit within the coverart container boundaries. Image may have black bars along edges.

3 = center
Image will be "original size" and centered within the coverart container. The image will not be stretched.

1
or
2
or
3

1

integer

disableControls

Disables specific controls within the player.

When a controls is disabled, the pointer (mouse) will have no affect, however the control will display and/or animate normally..

See also:
- enableControls (Javascript API)
- Available Controls

The enableControls Javascript API describes the names and spelling to use for the comma-delimited list.

"scrubber, playlist"

null

string

disableFlash

When 1, forcefully prevents Flash from being used for media playback.

When set to 0 (the default), Wimpy will automatically determine if the browser needs to use Flash or not.

To extend the widest possible coverage for browsers, devices and platforms, leave this option alone and let Wimpy determine the best possible scenerio.

1

0

boolean

downloadEnable

Enables (1) or disables (0) items to be downloaded.

See "Enabling Downloads" for more information.

0

1

boolean

downloadTip

Sets the tooltip when user's mouse hovers over the icon.

See "Links and Downloads" for more information. Related to linkTip.

"Download Track"

"download"

string

downloadWindow

Set's the window for downloads to be opened into when browsers are not capable of handling a "save as" dialog to prompt the user to save the file directly to their PC.

See "Enabling Downloads" for more information.

"myWindow"

"_blank"

string

getid3 1,2

Instructs wimpy.php to read the embedded ID3 meta information from the media file.

Requires PHP and the getid3 library. See notes 1 & 2 below.

1

0

boolean

getid3image 1,2

Instructs wimpy.php to read the embedded cover art image from the media file.

Requires PHP and the getid3 library. See notes 1 & 2 below.

1

0

boolean

glyphDownload

Changes the icon displayed in the playlist when downloads are eneabled.

See "Wimpy Player Glyphs" for more info.

"d"

"D"

string

glyphFile

Changes the icon displayed in the playlist for media items.

See "Wimpy Player Glyphs" for more info.

"a"

"f"

string

glyphLink

Changes the icon displayed in the playlist when links are eneabled (or a media item contains a "link" field in the Track Dataset.

See "Wimpy Player Glyphs" for more info.

"?"

"i"

string

glyphList

Changes the icon displayed in the playlist for folders and playlists.

See "Wimpy Player Glyphs" for more info.

"A"

"F"

string

height 3

A number representing the pixel dimension.

Width and height defined as an option take presidence over style-based width and height definitions.  See Player Sizing for more info.

100

null

number

id

A unique identifier for each player.

IMPORTANT
When establishing a player via HTML, do not use a "data-" prefix for this "id", just use "id".

Good:
<div id="foo" ..  />

Bad:
<div data-id="foo" ... />

See "Player Handles & IDs" for more info.

"myPlayer1"

null

string

infoFormat

Specifies how the "Info Display" control displays track title, artist and album information.

See "Formatting Info and Time" for more information on how to define this value.

If a track only has a title, infoFormat will be ignored and will only display the title in the info control.

"1 by 2, on: 3"

"1 - 2 - 3"

string

infoScroll

Turns info scrolling on (1) or off (0). This is NOT a boolean value.

0

1

integer

infoSpeed

How fast to scroll the info scroll control. The value is based on "pixels per second".  Higher values cause faster scrolling.

20

12

number

inline

Causes the player to render using the CSS "inline-block" +" float:left" rules.

When this option is enabled (true or 1), text, images and other HTML elements will wrap around the player.

When false (0) the player will take on the standard CSS "block" display rule.

0

1

boolean

limitPlayTime

The total number of seconds each track can play.

10

-

number

linkEnable

Enables (1) or disables (0) items to display the link icon.

See "Links and Downloads" for more information.

0

1

boolean

linkTip

Sets the tooltip when user's mouse hovers over the icon.

See "Links and Downloads" for more information. Related to downloadTip.

"Link to page"

"link"

string

linkWindow

Set's the target window that links will be directed to (or opened into).

See "Links and Downloads" for more information.

"myWindow"

"_blank"

string

loop

1 = loop track, 2 = loop playlist

Users can control this option if the loop icon is available in the skin.

1

0

int

media

This option is used to specify the playlist to load.

See "Playlists" section for details on how to write and create playlists.

When this option is not defined, Wimpy goes into "automatic mode" and defaults to using wimpy.php located wherever wimpy is installed (specifically, the same folder where the wimpy.js script is located. )

To specify an empty playlist, use "none" as the value for the media option.

"playlist.xml"
or
"track.mp3"
or
See "Playlists" section.

Automatic 
(the wimpy.php file in the wimpy installation folder)

string

name

A label developers can assign to a player in order to assist in identifying and differentiating players.

You may use any characters or symbols See "Characters" for more info.

See "Player Handle, ID and Name" for more info.

"My Player"

null

string

numberTracks

Items in a visible playlist will show numbers next to each item instead of an icon.

1

0

boolean

onReady

A function to "ping" when the player is ready.

This option is only available when creating a player with Javascript. It is NOT available within HTML

See:
- Ready Overview
- Javascript API > onReady

someFunction

null

function

plugPlaylist

Allows for an alternate playlist to be intertwined with the normal playlist.

Used to place advertisements or "plugs" (such as radio identification notices) in-between regular playlist tracks.

The playlists can be any of the traditional playlists used by Wimpy. (e.g. same as the "media" option above).

"playlist.xml"
or
"track.mp3"
or
See "Playlists" section.

null

string

plugDisables

When true, if a plugPlaylist item is playing, the controls will be disabled, preventing the user from skipping over the plug.

1

0

boolean

plugEvery

A number that represents how many regular playlist items will play in-between each plug.

The built-in default is 5, so you don't really have to define this option unless you want plugs to play more often or less often.

3

5

boolean

plugFirst

When true, a plug will play first, before a regular playlist item.

When false, X number of regular playlist items will play based on the plugEvery option, then a plug will play.

1

0

boolean

random

Next track is a randomly selected from list.

See Also: Random, Shuffle and Start On Track

Users can control this option if the random icon is available in the skin.

1

0

boolean

responsive

Enables player to respond to changes in size.

Causes the player to conform to the size of the Player Instance DIV (or Target Element) in response to media-queries or when used in a fluid layout.

This option is only honored a Player Instance DIV (or Target Element) has a style or class attribute assignment.

See also:
- Responsive Design with Wimpy
- Sizing a Player

 

1

0

boolean

skin

URL to skin file

"skin.json"

null

string

size

An alternative way to set the width and height of the player.

A comma-delimited string where the first item refers to the width, and the second the height.

width & height take precedence.

If width & height options are set, they will be used instad of the size option.

"300,200"

null

string

sort

Sort the playlist by specified field. See Track Dataset for a complete list of fields you can sort on.

Shuffle
To shuffle the playlist, set this value to "shuffle".

See Also: Random, Shuffle and Start On Track

If you need to sort manually, and you're using automatic playlists, take a look at the quirksmode feature.

"title"
or
"artist"
or
"shuffle"
or
"none"
or
...more...

not sorted

string

sortReverse

Reverses the sort order.

When set to true (1), sort order will be reversed as Z-A, 9-1.

By default Wimpy sorts A-Z, 0-9

1

0

boolean

startOnTrack

Start playing playlist from N track. Where N is the track number from the top.

For example if set to 3, Wimpy will start playing from the 3rd track on the list.

Nerds: Unlike an array that is zero-based, this option is one-based.

See Also: Random, Shuffle and Start On Track

3

0

int

startUpText

Text to display in the "Title" text field or the "Info" text control when the player has not yet launched a track and awaiting user to activate.

When this option is set as a simple string, the text will appear in the "title" field, or in the "info display control".

You can set up start up text to appear in the "artist" and "album" fields if you use a JSON string. Or you can use the Customizer tool :)

"Click to Play"

"Click to Play"

string

target

An HTML DIV tag's "id" attribute to render the player into. See "Javascript Target" for more info.

"myTargetId"

null

string

timeFormat

Specifies how the "Formatted Time" control displays time signatures.

See "Controls - Formatted Time" for more information on this control.

See "Formatting Info and Time" for more information on how to define this value.

"1 / 2 / 3"

"1 / 3"

string

volume

Startup volume.

Some browsers do not support automated volume control. For example, volume can not be controlled programatically on the iPhone because Apple requires the user to control volume using the physical switch.

 

0.8

1.0

number

width3

A number representing the pixel dimension.

Width and height defined as an option take presidence over style-based width and height definitions.  See Player Sizing for more info.

300

null

number

1 Requires the player to be running in "Automatic Mode" (or the media option is pointing to a wimpy.php file).

2 Requires the getid3 library to be located in the same folder as the wimpy.php file.

3 Width and height defined as an option take presidence over style-based width and height definitions.  See Player Sizing for more info.