Online Service Developer

From Winamp Developer Wiki
Jump to: navigation, search

Wiki Main : Skin Developer : Visual Developer : Plug-in Developer : Online Service Developer : SHOUTcast Broadcaster : SHOUTcast Developer : Articles Page : FAQ : Glossary

The What and Why of Online Services

What is a Winamp Online Service

A Winamp online service has several distinctive features. The first is that it is a web site that appears embedded within the Winamp client. The second, and more fun feature, is that the web pages so displayed are able to interact with the Winamp Client. The third is that access to the online services is presented to the large Winamp community as part of the Winamp client's Online Services Gallery.

Benefits to creating an Online Service

There are many benefits for developing an Online Service. Before we delve into the list, the most important benefit is distribution. Winamp is a great distribution platform as it has 77 million unique users every month!!

Hence,

  1. a) if your website needs page views and more monetization
  2. b) if your brand needs more eye balls
  3. c) if your blog needs more readers
  4. d) if you want to develop an web application which has something to do with music, video, photo, streaming, podcasts, music events, #e-commerce, games then you will never regret making an Online Service in Winamp.

Try it now!

Integrating Online Services with Winamp

The Online Services API is designed to allow web pages, hosted (displayed) within the embedded browser of the Winamp client, to leverage a series of APIs that can interact with the rest of the Winamp application. In order to make this happen you have to do the following:

  • Make sure you have the latest version of the Winamp client (v5.55 or above). You can download the client from winamp.com/player
  • Make sure you have the latest version of the Online Services developer plugin (ml_webdev.dll). Get the plugin from this link. This plugin will create a "WebDev Platform" node within the Medial Library pane. It has it's own special installer.

In order to change the starting web page for the online service, start the Winamp client and configure the plugin.

  1. Open the Winamp player
  2. Select Options->Preferences->Plug-ins->Media Library.
  3. Select "WebDev Test Platform v2.0" and press "Configure selected plugin".
  4. On the Web Dev Preferences dialog, set the URL field to the URL of the initial web page for the online service. For example, file://c:\myonlineservice\webdev.html
  5. Click on "Web Dev Test Platform" in the Media Library. You may have to right click and choose refresh to see the new web page.

You should now see the initial page of your online service in the Winamp embedded browser.

Registering an Account

While you can start developing an online service immediately, you will need to create a Winamp account before you can submit your service. To do this follow these steps:

  • Open your favorite web browser and go to http://www.winamp.com
  • Choose "Register" from the top of the page.
  • Complete the registration process

Submitting Your Service

The Submission Process

Once you have come up with an amazing idea for an Online Service that uses Winamp, how do you get it into the Winamp Online Services Gallery so that users can start visiting it? Glad you asked. First you must start by submitting the service to Winamp. After being submitted, the service will go through a Winamp internal review process. If the service passes the review it will then be automatically included in the Winamp Online Services Gallery.

The progress of your service through these steps can be seen through the use of the "My Profile" link at the top of the Winamp.com main page after logging in.

Submitting an Online Service

  • Login to www.winamp.com
    • Navigate to www.winamp.com
    • Select "Winamp.com: Login" from the top of the page
    • Enter the email address and password specified when you registered your account.
    • Mouse over the gold "Online Services" button at the top of the screen.
    • Choose "submit an online service" from the buttons in the drop down
    • Make sure you follow the guidelines specified and press "Proceed".
    • Enter the following information on the form:
      • Service Name (15 characters max) - This name will be displayed on the first line for the service in the Winamp Gallery.
      • Description (750 characters max) - Enter text describing your online service.
      • Online Service URL - Enter the URL to launch your service.
      • Categories - Select two categories so your service can be grouped with other services.
      • Tags - Enter tags so that users can find your service by searching
      • Thumbnail Image (optional, .gif, .jpg, .png, max size 178x75 pixels) - Displayed in the Winamp Gallery.
      • Installer Image (optional, .gif, .jpg, .png, max size, 64x64 pixels - Displayed by Winamp Installer
      • List Icon Image (optional, .gif, .jpg, .pgn, max size: 16x16 pixels - Displayed in the Winamp "Media Library" pane.
      • Country - Select the countries which your online service supports.
      • Language - Select the languages which your online service supports.
      • Customer Support Email Id - An email address where user comments/complaints will be sent.
      • Click and read the Terms and Conditions
      • Check "Agree to Terms and Conditions
      • Click "Finish"
Categories/Types of Online Services
  • Events
  • Streaming
  • Podcasts
  • Photo
  • Music
  • Video
  • Radio
  • E-Commerce
  • Artists
  • Games
  • Internet TV
  • Others
Tags Vs. Categories

You can tag/categorize a piece of information in your site and allows this piece of information to be searched and indexed.

So what are categories? Categories help you organize your content under a more familiar taxonomy. By familiar, we mean non-unique and non-personal words; thereby allowing a user to navigate your content with ease knowing what they want. That's the reason why we have fixed the categories. They are Music, Video, Radio, E-Commerce, Photo, Artists, Streaming, Podcast, Games, Internet TV, Events and Other. This will also give you a clear indication on what you can actually create. And if you think you can create something else, there is always the 'Other' category.

Then why do we need tags? Well, you can personalize your Online Service with your own tags. For e.g. for a hypothetical online service Music Shoppe (Let's say) tags can be 'music shoppe', 'music shop', 'purchase music', 'music shop', 'music store' whereas categories can be broader like 'music' & 'e-commerce'. All you have to do is make them short, crisp, relevant (search compatible) and small in numbers so that they are relevant.

Tags will be introduced shortly. Till then, please use categories :)

Monitoring the Status of your Submission with "My Profile"

After you have successfully submitted an online service, Winamp will put it through a review process. You can check the status of your online service by examining the "My Profile" link in the upper right of the screen after logging in to www.winamp.com.

Note that once you go to your profile, there are three links, one for each of the types of submissions you may have made. Choose "Online Services" to see that type.

The online service will proceed thru the following stages:

  1. Online Services in Review - The online service has been submitted and is awaiting review
  2. Approved Online Services - The service has been reviewed and is waiting to be either published or rejected. An online service should only stay in this state for a short time.
  3. Published Online Services - The online service was found to be acceptable and is now available in the Winamp Gallery.
  4. Rejected Online Services - The online service was found to be un-acceptable and is not available in the Winamp Gallery.

Managing your Online Service with "My Profile"

Once your online service has been published, there are several things you can do to manage it through the My Profile page.

Viewing Service Information

Each published online service will show the following:

  • Unique ID - A ID that uniquely identifies your online service.
  • Version # - The current version number of your online service.
  • Description - The description you typed when submitting the service.
  • First Published on - Date on which this online service was first published.
  • Last Edited on - Last date this online services was edited.
  • Last Approved on - Last date this online service was approved.
  • Reporting On - A section showing the following statistics
    • Service has been added - The service is available in the gallery.
    • Service has been removed - The service is not available and has been deleted.
    • Service has been accessed - The number of times users have accessed the site through the Winamp Client.
    • Unique Users - The number of views by unique (i.e., new ip addresses) users.
    • Ratings - Average user rating.
    • Number of Ratings - How many users have rated the online service
    • Abuse Reports - How many abuse reports have been sent against this service.

Editing your Online Service Info

My Profile contains an EDIT button so you can change the details that you entered when you first submitted the online service for review. This button will take you to a form where you can change these values. Changing the values will increase the version number of the online service and submit the service for review.

Removing your Online Service

My Profile also has a REMOVE button so the author can delete the online service. To reinstate the service you will have to resubmit it.

Hiding your Online Service

Hide from Gallery will prevent the online service from appearing in the Winamp client online services gallery. This can be used to temporarily prevent users from subscribing to the service.

Style Guide

Please reference this wiki page for optimizing how your online service looks/performs inside of Winamp

Winamp Browser Support

JavaScript APIs

Here is a summary of the API methods that can be called from an online service.

For more details on the methods available check out the complete JavaScript API technology framework

  • Transport API
    • Play
    • Stop
    • Pause
    • Advance to next track
    • Back up to previous track
    • Shuffle
    • Repeat
    • Event Notifications - so the web page can tell when the events happen
      • When the player starts playing
      • When the player is stopped
      • When the player is paused
      • When the player reaches the end of a file
    • Metadata - get metadata for currently playing song
    • position - change the playback position of currently playing song
  • Playqueue API
    • The ability to alter the Winamp Queue of songs about to be played.
      • Play - clear the queue and play a song.
      • Enqueue - add a song to the queue
      • Insert - add a song to the queue at a position
      • Clear - clear the queue
      • Metadata - get metadata for a song in the queue
  • Playlists API
    • Get a list of all playlists
    • Open a playlist for alteration
    • Save a modified playlist
  • Playlist methods - once a playlist is opened these are available.
    • Get and set info about individual items in the playlist
    • Swap two songs
    • Randomize the order of songs
    • Reverse the order of songs
    • Sort By Filename
    • Sort By Title
    • Clear (empty) the playlist
  • Bookmarks API
    • Add a bookmark
    • TBD
  • Podcasts API
    • Subscribe to a Podcast
    • More TBD
  • Secuirty API
    • In place, but not fully ready
    • TBD
  • LocalMedia API
    • TBD
  • History API
    • Query the History DB - retrieve info about songs played previously
  • Config API
    • The ability to store JavaScript properties persistantly.
  • Application API
    • Launch the internal Winamp browser.
    • Launch an external browser.
    • Get the version of the internal browser.
    • Get the language pack info
  • Skins API
    • Retrieve color and font information regarding the currently assigned Winamp client skin.
  • MediaCore API
    • Retrieve metadata for a specified file
    • Determine whether a specific file format (file extension) is supported by the Winamp Client.

User Feedback

There are several methods by which users can provide feedback on your online service.

Ratings by Users

The Winamp client allows users to rate your online service. You can see the average rating and the number of times that your service has been rated using the "My Profile" link on winamp.com after logging in. This way you can tell whether thousands of people adore your service, or perhaps it was a single rating from your best friend.

Abuse Reporting

Users can also complain if they find something objectionable. These "abuse reports" may be forwarded to the online service developer to be resolved. So don't do bad things. And no, SlyHawk, parcour will not help you here.

Additional Considerations

Security

In order to help protect users from potential abuse by online services, Winamp has implemented a strategy to notify users that a web service is about to issue one of the online service api methods. The warning message will ask the user whether the method should proceed. Each security prompt will be applied to the action being requested as well as certain related actions of the same API. There is also a way to indicate that the selection should be used for ALL other security prompts for the current online service. This prevents the user from being bombarded with what may sound like repetitive requests. If the author of the online service upgrades their service, these choices will be carried forward to the new release.

For a more in depth discussion of the security prompts go to Online Service Security Prompts. [link title]