The Rhymba Media Player (Beta)

The Rhymba Media Player is a ready-to-use, prebuilt JavaScript library that allows you to quickly add playback of Rhymba Streaming API-powered streams to your web application, designed to get audio from the Rhymba Content API and into your user's ears as directly as possible. We're continuously evolving its features & functionality, and have begun using it for all of our own projects, so it's constantly receiving QA, fixes, and updates. We're calling it "beta" for the time being even though it's being used in production, because we do have additional features we'd like to add, as well as test. You can of course "roll your own" solution, but for our customers looking to get up and running quickly with a minimum of development, the Rhymba Media Player is our recommended way to roll.

Let's take a look at getting a stream up and running quickly.

Playing a Stream - QuickStart

NOTE: right at the moment, the Rhymba Media Player is heavily optimized for RTMP streaming, and requires the Flash plugin. This will be changing soon, so check back for future updates!

Playing music from the Rhymba Content API in your browser is as simple as knowing the Media ID of the track you want to play.

First get yourself a current version of jQuery, because it's great, and also because the Rhymba javascript libraries need it to work.

Second, add the Rhymba Media Player script at this link to your page. We recommend adding it immediately before the end of your <body> tag so that it won't get in the way of your page's content.

Next, create a valid Content API token set using the process described in “Getting a Stream”.

Equipped with your Content API token, you can now create a Rhymba Media Player instance to play your stream with. In a new <script> tag, call the rhymba.media.Player() method, passing it your content API tokens in a configuration object like so:

Playing music is now as simple as calling the player's .play() method with the ID of the track you want to play. For instance:

myPlayer.play("[MediaID]");

But unless you only used the default parameters when you created your Content API Token, you'll probably want to do the sophisticated thing, and tell the Player exactly how you want to play that track:

Special Case: Preview Streams

For previews, things work only a little differently. Instead of needing to use a full Content API Token Set, you can get away with just your regular Rhymba Access Token (although a full set won't hurt matters). Then, when you want to preview your tracks, just make sure you add ".preview" to their media IDs.

More About the Rhymba Media Player

The Rhymba Media Player is a simple but flexible beast. The only required constructor option is your Content API Token Set. However, there are some additional options that can make getting your specific functionality simpler.

Options

Field Name

Type

Description

Example

tokens

object

A javascript object with string properties for the three parts of a Rhymba Content API token.

tokens: {
access_token: "",
access_hint: "",
access_req: ""
}

content

object

The Rhymba Media Player will use the properties of this object in the corresponding fields of a request to the Rhymba Content API when resolving the content stream url of any media assigned to it without one. While not required, we strongly suggest that you use values corresponding to the fields you used when requesting your Content API token.

The volume at which to play audio, with 0 being silent and 1 being maximum.

0.5

bufferTime

integer

The duration, in seconds, of playback time to load before an item begins to play. During playback, the player will always attempt to this many seconds of audio data in memory. See: the .bufferTime() method.

3

autoResolve

boolean

If true, the Rhymba Media Player instance will immediately attempt to use the Rhymba Content API to determine a content stream url for any media assigned to it without one. TODO: content object

true

autoLoad

boolean

If true, the Rhymba Media Player instance will immediately begin loading audio data for any media assigned to it, even before being told to play.

Configuration Methods

If invoked with an argument, assigns that media to the Rhymba Media Player instance. The currently assigned media is then loaded for playback.

volume

decimal

Gets/Sets the volume at which to play audio media.

decimal

position

integer

Gets/Sets the current playback position of the current media. If assigned a value greater than the duration of the media stream, playback will end as if the stream had played to completion.

integer

bufferTime

integer

Gets/Sets the time, in seconds, that media streams must have loaded in order to be considered playable. See: bufferTime option

integer

bufferLength

integer

Gets the time, in seconds, of playback content currently buffered for the assigned media

integer

autoResolve

boolean

Gets/Sets the autoResolve option. If autoResolve is true, then any media assigned to the Player without a content url will have one resolved for it using the Rhymba Content API, as configured in the content option.

If invoked with an argument, attempts to resolve a content url for that Media Object using the Rhymba Content API, as configured in the content option. If invoked without an argument, attempts to resolve a content url for the media currently assigned to the Player. Note: Media arguments to 'preResolve' are not immediately assigned as the current media for the Player instance, as with the .play() and .load() methods.

autoLoad

boolean

Gets/Sets the autoLoad option. If autoLoad is true, then any media assigned to the Player will immediately have a content url resolved for it using preResolve method. If a content url is resolved, playback data will be loaded from that url immediately.

If invoked with an argument, attempts to resolve a content url for that Media Object. If a content url is resolved, playback data will be loaded from that url in the background.Note: Media arguments to 'preLoad' are not immediately assigned as the current media for the Player instance, as with the .play() and .load() methods.

Status Methods

Name

Arguments

Description

Returns

Example

isReady

Returns true if the Player Instance has finished initializing and is ready to begin playing media.

boolean

isPlayable

Returns true if the currently assigned media has a content stream url and is able to begin playing.

boolean

isPlaying

Returns true if the player is currently playing.

boolean

isPaused

Returns true if the player is currently paused.

boolean

isStopped

Returns true of the player is current stopped.

boolean

isComplete

Returns true if the current media has been played to completion.

boolean

Event Handlers

The Rhymba Media Player emits a variety of events reflecting changes in the state of the Player or the media being played. Callback functions for these events are
assigned using the convenience methods listed here. You can assign as many callback functions to a given event as you need, and release them later using the .removeEventListener() method: all of the methods below return a numeric string identifying the particular callback-function + event-type pairing created, so when you don't need that callback any longer, you can use the token with .removeEventListener() to get rid of it.

Callback functions will be invoked with an event argument containing details about the related search. These details are stored in the event's .data property.

Name

Arguments

Description

Returns

Example

onReady

function( event )

Invoked once the Rhymba Media Player instance has initialized and is ready to begin playing media.

Add a new callback function for the named event, used internally by all of the convenience methods above. Check out available events using rhymba.media.Player.events()

string

myPlayer.addEventListener(
'change.ready',
myCallbackFunction
);

removeEventListener

string

Cancels an existing event handler callback based on its token.

myPlayer.removeEventListener("23")

Media Objects

Media Objects are any objects assigned to the Media Player to represent an item of Rhymba Content. The simplest form of Media Object is a string indicating the Rhymba Content item's ID, but any object with a 'mediaId' property will do. This is convenient if you already happen to have a lot of Rhymba Content as JSON objects, or if you want to play back a given track a little differently from others.

For example, all of the objects below are valid as javascript Media Objects: