Winamp Browser Support

From Winamp Developer Wiki
Revision as of 18:57, 29 September 2009 by Blo (Talk | contribs)

Jump to: navigation, search

This wiki page has been created to help Web developers and QA engineers optimize their web pages to be rendered within the Winamp client application.

Where are web pages loaded within Winamp?

Winamp has 2 primary areas that allow external web sites to be loaded within the client experience -- Online Services and the Bento Skin Browser

1) Online Services

Online Services is a feature within the Winamp Media library that allows 3rd parties to submit their web site to appear as an integrated service within the client. An Online Service is distinct in that the web pages displayed are able to interact with the Winamp Client by leveraging the Online Services APIs. Check out the Online Services Developer section of this wiki for more information.

File:Online Services Screenshot.png

2) Bento Skin Browser

Winamp's default skin, named "Bento", has a built in web browser that allows users to freely surf the web, create bookmarks, etc. The Bento browser DOES NOT have access to the Online Services APIs and acts very much like a stand alone IE browser session.

File:Bento Browser Screenshot.png

What browser engine is embedded within Winamp?

The Winamp Browser is powered by leveraging the version of Internet Explorer that is resident on the users local machine (IE only). As such, the browser support matrix for the Winamp client is shown in the image below.

File:Winamp Browser Support Matrix.png

How can I detect that my page Is being loaded inside Winamp?

1) Online Services: The easiest way to determine if the web page is being loaded within the Winamp online services is by checking for Winamp specific strings in the user agent (see below).

Example: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322; .NET CLR 2.0.50727; .NET CLR 3.0.04506.30; .NET CLR 3.0.04506.648) omBrowser/1.3 (Winamp 5.57 build 2596 Beta, JSAPI2)

2) Bento Browser: As stated earlier, the Bento Browser acts very much like a stand alone IE browser session and does not have convey any Winamp specific hooks (e.g, no Winamp strings in user agent, no access to Winamp API's).

The remainder of this documentation page will be focused on web pages loaded within Online Services

What unique conditions exist as compared to a stand alone browser?

Screen Size:

The biggest difference is the available screen real estate. The browser window that loads within Winamp is significantly smaller than a fullscreen stand alone browser window. To avoid horizontal scroll bars from appearing by default, the page grid size that designers and web page creators should target for is 660p wide (see image below).

Once a web page detects that its being loaded within Winamp, its recommended that the page modifies its CSS to accommodate the smaller dimensions (or redirect to a alternate web page that is specifically optimized to render in Winamp).

File:Winamp Client Browser Default Page Grid.png

Default omBrowser Settings:

By default, the following omBrowser settings are unchecked:

  • Disable context menu filtering
  • Show a notification for every script error
  • Enable script debugging

To turn on any of these features you'll need to download the web_dev plug-in.

Access to Online Services API's:

Your web page is now inside of the Winamp media player, make the experience contextually relevant to Winamp's media centric users by leveraging the Online Servcies API's.

For example, you might want to use the Skins API to adjust the colors of your service to blend with active color palatte of the users client. If you have on-demand media, you can use the Transport API to have Winamp natively control the playback of streaming audio/video.

The screenshot below is highlighting an example of a website using the Transport API to fetch metadata for the users currently playing asset and automatically programming a relevant experience based on that metadata.

File:Example Use of Online Serivces API.png

How can I unit test how my web page looks and performs within Winamp?

1) Online Services

Winamp provides a web developer plugin to help you unit test your web page inside of the Winamp client. You can download it here.

Basically this plugin works very similarly to the Online Services node in Media library, but allows you to create "test services" with parameters you specify. The plugin also makes available a test page for our Online Services APIs.

To use it, you'd just install the latest publically available Winamp Client, version 5.56+ ( if you don't have it already), then run the installer for the web developer plugin (wa_webdev.exe) (note: Winamp.exe should be closed when you install).

The installer should detect the correct location of your current winamp installation, or you can point it to an alternative install.

Once you've installed it, launch Winamp and you'll see a "WebDev Platform" item in your Media Library on the bottom left. The area to the right has the embedded browsing experience, where the online service would be loaded, When you click on the WebDev Platform Selection, you'll see a web page that has links to both "JSAPI2 Test Page" which shows simple examples of available Winamp Javascript API calls, and a "Create Your Own Service" link, which allows you to enter a URL and title, and create a sub-node under the WebDev Platform Item, which would behave as your online service would (you can enter the url to load a local file or hosted web page).

File:Wa webdev.png